anbaric 1.23.2 → 1.25.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
@@ -39,6 +40,7 @@ How to put the features together to build something real.
 - [Human-in-the-loop](patterns/human-in-the-loop.md) — approvals, forms and hand-offs
 - [Integrating external systems](patterns/integrating-external-systems.md) — waiting on callbacks and webhooks
 - [Authorization with actors and roles](patterns/authorization.md) — who is allowed to do what
+- [UX practices](patterns/ux-practices.md) — feedback and polling for an asynchronous UI
 - [Testing your app](patterns/testing.md) — driving a machine in memory
 
 ## API reference

package/docs/api/cli.md

@@ -25,9 +25,20 @@ project — they walk up to the nearest `package.json`.
 | `anbaric app configure` | Create or update `.anbaric/app-config.json` (`name`, `internalPort`). |
 | `anbaric app deploy` | Deploy the app and wait until it is live (prompts before replacing a running one). |
 | `anbaric app update` | Deploy, replacing a running app **without** prompting. |
-| `anbaric app status <name>` | Show deploy state, liveness, and recent logs. |
-| `anbaric app tail <name>` | Stream the app's runtime logs. |
-| `anbaric app tear-down <name>` | Stop and remove the app (prompts unless `--yes`). |
+| `anbaric app status [name]` | Show deploy state, liveness, and recent logs. |
+| `anbaric app tail [name]` | Stream the app's runtime logs. |
+| `anbaric app tear-down [name]` | Stop and remove the app (prompts unless `--yes`). |
+
+The name is optional, because an `app` command is normally about the app you
+are standing in: the CLI walks up from the working directory to the nearest
+`package.json` and takes the name from that project's
+`.anbaric/app-config.json`, falling back to the package's own `name`. Pass a
+name to act on a different app, or to work from outside a project entirely.
+
+```bash
+cd ~/work/crm && anbaric app tail       # the app you are in
+anbaric app status link-media-brief     # a different app, from anywhere
+```
 
 ## State machines and jobs
 

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

@@ -217,15 +217,20 @@ transition whose predicate holds moves the job to `to`.
 
 ```ts
 to : string
-predicate : (job : Job) => boolean
+predicate : (job : Job) => boolean          // default: () => true
 
-constructor(to : string, predicate : (job : Job) => boolean)
+constructor(to : string, predicate? : (job : Job) => boolean)
 ```
 
 ```ts
 new Transition("active", (job) => job.properties.get("welcomeSent") === true)
+new Transition("scoring")   // unguarded: the actions run, then the job moves on
 ```
 
+The predicate is optional. Omit it when a state's actions simply run and the job
+should move on, rather than inventing a sentinel property for the transition to
+read. Guard a transition only when the move is conditional.
+
 ---
 
 ## `Job`
@@ -243,18 +248,26 @@ readonly startedAt : Date
 readonly startedBy : string
 readonly lastUpdated : Date
 readonly killed : boolean
-status : string                  // "active" or "Awaiting input"
+status : string                  // "active", "Awaiting input" or "Failed"
 waitingFor? : string
 awaitMetadata? : WaitForInput     // present while parked on an Await
 
 namespace Job {
-    const Status = { ACTIVE: "active", AWAITING_INPUT: "Awaiting input" } as const
+    const Status = {
+        ACTIVE: "active",
+        AWAITING_INPUT: "Awaiting input",
+        FAILED: "Failed",
+    } as const
 }
 ```
 
 Check whether a job is parked with `job.status === Job.Status.AWAITING_INPUT`;
 read what it's waiting for from `job.awaitMetadata`.
 
+A job whose action threw is `FAILED`, with the reason in its audit trail. It
+stays in its state rather than transitioning, and an update that moves it on
+returns it to `ACTIVE` — so a failure is recoverable, not terminal.
+
 ---
 
 ## `PropertyDefinition`
@@ -265,6 +278,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 +289,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/docs/features/state-machines.md

@@ -61,6 +61,34 @@ Each time a job is processed, the machine:
 Because actions only *propose* changes and the machine *applies* them, a job's
 data is always schema-valid, whoever wrote it.
 
+A state's actions run **every time** the job is processed in that state, not
+once on entry. That is deliberate — it lets a predicate be time-based
+(`(job) => Date.now() > retryAfter(job)`) or wait on something external. For
+work that must happen only once, guard it:
+
+```ts
+fetchReport.predicate = (job) => !job.properties.has("report");
+```
+
+## Failing a job
+
+If an action throws, the job is marked **failed** (`Job.Status.FAILED`) and the
+reason is recorded against it in the audit trail. You don't need to catch
+errors yourself to stop a job getting stuck — throwing *is* how you say "this
+job cannot proceed":
+
+```ts
+chargeCard.run = async (job) => {
+    const outcome = await payments.charge(job.properties.get("amount"));
+    if (!outcome.ok) throw new Error(`Card declined for job ${job.id}: ${outcome.reason}`);
+    return new Map([["charged", true]]);
+};
+```
+
+A failed job stays where it is rather than transitioning, but it isn't dead: an
+update that moves it on clears the status, so correcting the data and calling
+`updateJob` retries it.
+
 ## Terminal states
 
 Mark the end of a process with `Terminal`, which carries an outcome:
@@ -77,6 +105,21 @@ new Terminal("cancelled", Terminal.Outcome.FAILURE),
 
 A job that reaches a terminal state stops and is never processed again.
 
+## Moving on unconditionally
+
+A transition's predicate is optional. If a state's actions simply run and the
+job should then move on, leave the guard off — there is no need to invent a
+sentinel property for the transition to test:
+
+```ts
+new State("enriching", [lookUpCompany], [new Transition("scoring")]),
+```
+
+Guard a transition when the move is genuinely conditional — branching, or
+waiting for something to become true. If the concern is "what if the action
+fails?", throw from the action instead (see [Failing a job](#failing-a-job));
+you don't need an error property and a guard that reads it.
+
 ## Branching
 
 A state can have several transitions; the first satisfied one wins. Put the more

package/docs/patterns/ux-practices.md

@@ -0,0 +1,62 @@
+# UX practices for Anbaric apps
+
+Anbaric apps are asynchronous by nature: submitting a form doesn't finish the
+work, it hands a job to a state machine that then moves on its own. A UI that
+ignores that feels broken even when everything is working. These are the
+practices to follow when you build a human-facing interface on Anbaric.
+
+## Acknowledge a submission immediately
+
+**Always give feedback the moment a job update is submitted.** `updateJob` and
+`startJob` return once the change is *stored and queued* — not once the job has
+progressed. If the page sits silent, the person cannot tell whether their click
+registered, and will click again.
+
+Say what happened and what is happening next:
+
+```
+✓ Approval submitted — the job is being processed…
+```
+
+Disable the button while the request is in flight so the same update can't be
+sent twice.
+
+## Then follow the job until it settles
+
+After acknowledging, watch the job so the page reflects reality rather than a
+guess. Poll it and re-render as the state changes:
+
+- **Poll at most once per second.** Anything faster adds load without telling
+  the user anything new; a job that transitions immediately is still only
+  observable per processing pass.
+- **Stop when there is nothing left to wait for** — the job reached a terminal
+  state, parked on an `Await`, or failed. Don't poll a settled job forever.
+- **Show the state, not just a spinner.** "Awaiting approval", "Charging card",
+  "Failed — card declined" tells someone far more than an endless whirl.
+- **Back off or stop after a reasonable period**, and say so, rather than
+  spinning indefinitely if nothing changes.
+
+A job that has parked on an `Await` is waiting for a *person*, possibly not the
+one at the screen. Say what it is waiting for rather than implying the page is
+still loading.
+
+## Surface failures honestly
+
+A job whose action threw is `Job.Status.FAILED`, with the reason in its audit
+trail. Show that the work stopped and why. Silently leaving the last-known state
+on screen turns a failure into a mystery.
+
+## Styling (optional)
+
+If the user hasn't asked for a particular look, you may use the **Anbaric design
+system** — design tokens, brand assets and React components:
+<https://github.com/anbaric-ai/anbaric-cloud/tree/main/anbaric-design-system>.
+It isn't published to npm, so copy in `tokens.css` and the components you need
+rather than adding a dependency. If the user asked for something specific —
+Tailwind, MUI, plain CSS, their own kit — use that instead; their choice wins.
+
+## See also
+
+- [Awaiting input](../features/awaiting-input.md) — pausing a job for a human
+- [Human-in-the-loop](human-in-the-loop.md) — approvals, forms and hand-offs
+- [Serving a web UI](../features/serving-a-web-ui.md) — putting data on a page

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anbaric",
-  "version": "1.23.2",
+  "version": "1.25.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.25.0",
+    "anbaric-data-store": "^1.25.0",
+    "anbaric-state-machine": "^1.25.0",
+    "anbaric-tsapi": "^1.25.0"
   }
 }