anbaric 1.24.0 → 1.26.0

package/docs/README.md

@@ -40,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/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`

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.24.0",
+  "version": "1.26.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.24.0",
-    "anbaric-data-store": "^1.24.0",
-    "anbaric-state-machine": "^1.24.0",
-    "anbaric-tsapi": "^1.24.0"
+    "anbaric-impl-cloud": "^1.26.0",
+    "anbaric-data-store": "^1.26.0",
+    "anbaric-state-machine": "^1.26.0",
+    "anbaric-tsapi": "^1.26.0"
   }
 }