anbaric 1.56.9 → 1.58.0

package/docs/api/state-machine.md

@@ -84,6 +84,7 @@ readonly id : string
 actions : Array<Action | Await>
 transitions : Array<Transition>
 readonly isTerminal : boolean
+prewarm : Reads                              // default: Reads.everything
 
 constructor(
     id : string,
@@ -98,6 +99,29 @@ subscribe(action : Action | Await) : void   // append an action after constructi
 A state's `actions` may mix `Action`s and `Await`s; they are considered in order
 when a job is processed.
 
+### `prewarm` and `Reads`
+
+```ts
+type Reads = (definitions : Array<PropertyDefinition>) => Array<string>
+
+Reads.everything                       // every property (the default)
+Reads.nothing                          // none
+Reads.only("summary", "articles")      // a fixed few
+Reads.where(definition => definition.id.startsWith("article"))   // whatever matches
+
+scoring.prewarm = Reads.only("summary");
+```
+
+Before a job is processed in a state, the properties the state `prewarm`s are
+loaded in one fetch. Anything a step reads that wasn't prewarmed still loads,
+on demand, the moment it's asked for — so `prewarm` is never something a step
+depends on for correctness, only what keeps a pass to one round trip. Given the
+machine's definitions, so a mapping written once follows the schema. Narrow it
+for a state that needs a little of a job that holds a lot: a workflow carrying
+hundreds of article summaries stops moving all of them for a step that scores
+one, and an [agentic action](../features/ai-agents.md) in that state sends the
+model only what was loaded.
+
 ---
 
 ## `Terminal`
@@ -136,20 +160,23 @@ actor : Actor
 constructor(name : string, actor : Actor, description : string = "", id? : string)
 
 // Replaceable function fields — assign your own:
-predicate : (job : Job) => boolean            // default: () => true
-run : (job : Job) => Promise<Map<string, any>> // default: async () => new Map()
+predicate : (job : Job) => boolean | Promise<boolean>   // default: () => true
+run : (job : Job) => Promise<Map<string, any>>          // default: async () => new Map()
 ```
 
 You configure an action by assigning `predicate` and `run`:
 
 ```ts
 const sendWelcome = new Action("Send welcome email", new Code("welcome"));
+sendWelcome.predicate = async (job) => ! await job.properties.has("welcomeSent");
 sendWelcome.run = async (job) => new Map([["welcomeSent", true]]);
 ```
 
-- **`predicate`** — return `false` to skip this action for a given job.
+- **`predicate`** — return `false` to skip this action for a given job. May be
+  `async`, since [reading a property](#jobproperties) is.
 - **`run`** — return a `Map` of the properties to change. Only properties in the
-  machine's schema are applied; others are ignored with a warning.
+  machine's schema are applied; others are ignored with a warning. Only the
+  properties that actually changed are written back.
 
 See [Actions and actors](../features/actions-and-actors.md).
 
@@ -170,12 +197,12 @@ name : string
 description : string
 waitingFor? : AwaitParty
 fields : Array<string> = []
-resolveUrl : string | ((job : Job) => string) = ""
-metadata : (job : Job) => Map<string, any>    // default: () => new Map()
+resolveUrl : string | ((job : Job) => string | Promise<string>) = ""
+metadata : (job : Job) => Map<string, any> | Promise<Map<string, any>>    // default: () => new Map()
 
 constructor(name : string, waitingFor? : AwaitParty, description : string = "", id? : string)
 
-waitForInput(job : Job) : WaitForInput
+waitForInput(job : Job) : Promise<WaitForInput>
 ```
 
 - **`fields`** — the input you expect back (property names).
@@ -217,19 +244,20 @@ transition whose predicate holds moves the job to `to`.
 
 ```ts
 to : string
-predicate : (job : Job) => boolean          // default: () => true
+predicate : (job : Job) => boolean | Promise<boolean>   // default: () => true
 
-constructor(to : string, predicate? : (job : Job) => boolean)
+constructor(to : string, predicate? : (job : Job) => boolean | Promise<boolean>)
 ```
 
 ```ts
-new Transition("active", (job) => job.properties.get("welcomeSent") === true)
+new Transition("active", async (job) => await 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.
+read. Guard a transition only when the move is conditional. A guard may be
+`async`, since reading a property is.
 
 ---
 
@@ -268,6 +296,37 @@ 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.
 
+### `JobProperties`
+
+`job.properties` is not a `Map`: it reads on demand, so a job may hold a great
+deal while a step pays only for what it asks for.
+
+```ts
+await job.properties.get(key) : Promise<any>
+await job.properties.has(key) : Promise<boolean>
+await job.properties.getMany(keys) : Promise<Map<string, any>>
+await job.properties.prewarm(keys?) : Promise<void>     // fetch these (or everything) in one go
+await job.properties.toMap() : Promise<Map<string, any>> // everything, loading what isn't held
+job.properties.snapshot() : Map<string, any>            // what is held right now, loading nothing
+```
+
+The first read of a property not yet held fetches it; the state's
+[`prewarm`](#prewarm-and-reads) fetches a set up front. Reads are cached for
+the pass. `snapshot()` is what serialisation and an agentic prompt use.
+
+### Reading a job
+
+```ts
+persistence.retrieve(id, actor) : Promise<Job>                  // holding every property
+persistence.retrieve(id, actor, ["summary", "score"]) : Promise<Job>   // holding those; the rest on demand
+```
+
+Properties are stored one by one, and a save writes only the properties that
+changed — never the ones a pass read, let alone the ones it never loaded — and
+no save ever removes a property. Over HTTP the same read is
+`GET /api/v2/jobs/<id>?keys=summary,score`, and the properties in a `PUT` body
+are the ones written.
+
 ### Listing jobs
 
 ```ts

package/docs/api/web.md

@@ -116,6 +116,17 @@ In code the same listing is `JobPersistenceFactory.instance().list(actor,
 pageSize, page, query)`; the CLI's `anbaric jobs list` and the MCP tool
 `anbaric_jobs_list` take the same filters.
 
+```
+GET /api/v2/jobs/<id>                       every property
+GET /api/v2/jobs/<id>?keys=summary,score    only those
+PUT /api/v2/jobs/<id>                       body: a serialised job
+```
+
+A job's properties are stored one by one. A `GET` with `keys` returns only
+those; the properties in a `PUT` body are **upserted** — written if given,
+left alone if not — so a caller that read a few keys can write a few keys
+without disturbing the rest, and no `PUT` ever removes a property.
+
 ### Other resources
 
 Also under `/api/v2`, reached through the cloud clients rather than raw HTTP:

package/docs/features/actions-and-actors.md

@@ -13,9 +13,9 @@ import {Action, Code} from "anbaric";
 
 const chargeCard = new Action("Charge the card", new Code("billing"));
 
-chargeCard.predicate = (job) => job.properties.get("paid") !== true;   // skip if already paid
+chargeCard.predicate = async (job) => await job.properties.get("paid") !== true;   // skip if already paid
 chargeCard.run = async (job) => {
-    const amount = job.properties.get("total");
+    const amount = await job.properties.get("total");
     // ... call your payment provider ...
     return new Map([["paid", true], ["chargedAmount", amount]]);
 };
@@ -32,6 +32,36 @@ Actions in a state run **in order** each time a job is processed. An action that
 returns an unchanged value doesn't churn the job — the machine only advances (or
 schedules a re-check) when something actually changes.
 
+### Reading properties is asynchronous
+
+`job.properties` reads on demand — `await job.properties.get("total")` — so a
+job can hold a lot (hundreds of article summaries, say) while an action that
+needs one property pays for one. That's why `predicate` may be `async`, as in
+the example above, and why a transition's guard may be too. Afterwards the
+machine writes back only the properties that changed — never the ones the pass
+read, let alone the ones it never loaded.
+
+### Prewarm what a state needs
+
+Each property read that wasn't already held is a fetch. A state can name what
+to load up front, in one go:
+
+```ts
+import {Reads} from "anbaric";
+
+const scoring = new State("scoring", [score], [new Transition("grouped")]);
+scoring.prewarm = Reads.only("summary");
+```
+
+By default a state prewarms everything, so nothing changes until you narrow it;
+anything a step reads beyond the prewarm still loads on demand, so a narrow
+prewarm can never break a step, only cost it a fetch. `Reads` is a function of
+the machine's property definitions — `Reads.everything`, `Reads.nothing`,
+`Reads.only(...keys)`, `Reads.where(definition => …)` — so a mapping written
+once keeps up as the schema grows. For an [agentic action](ai-agents.md) the
+prewarm also decides what reaches the model: the prompt carries the properties
+the job holds when the action runs.
+
 ## Actors: who does the work
 
 An actor is a small identity object — `type`, `id`, and `roles`. There are four

package/docs/features/ai-agents.md

@@ -34,7 +34,7 @@ const triage = new RemoteLLMAgenticAction(
 
 const support = new StateMachine("support", [
     new State("open", [triage], [
-        new Transition("prioritised", (job) => job.properties.has("priority")),
+        new Transition("prioritised", async (job) => await job.properties.has("priority")),
     ]),
     new State("prioritised"),
 ]);
@@ -44,8 +44,12 @@ When a job is processed in `open`, the agent is asked to produce a `priority`
 constrained to the schema; the result is applied to the job, and the transition
 advances it. The decision is recorded against `triager`.
 
-The job's current properties are appended to the prompt automatically, so the
-model sees the data it's reasoning about.
+The job's properties are appended to the prompt automatically, so the model
+sees the data it's reasoning about — the properties the job holds when the
+action runs, which is all of them until the state says otherwise. On a job
+that holds a lot, [prewarm](actions-and-actors.md#prewarm-what-a-state-needs)
+just what the model needs: `open.prewarm = Reads.only("subject")` keeps a
+ticket's attachments, history and everything else out of every call.
 
 ## The output schema
 

package/docs/features/awaiting-input.md

@@ -22,7 +22,7 @@ approve.resolveUrl = (job) => `/approve?job=${job.id}`;   // where a person prov
 
 const fulfilment = new StateMachine("fulfilment", [
     new State("review", [approve], [
-        new Transition("approved", (job) => job.properties.get("approved") === true),
+        new Transition("approved", async (job) => await job.properties.get("approved") === true),
     ]),
     new State("approved"),
 ]);
@@ -52,7 +52,7 @@ of the job** so you can build a per-job link — for example putting the job id
 the query string so your form knows which job it's resolving:
 
 ```ts
-approve.resolveUrl = (job) => `/approve?job=${job.id}&total=${job.properties.get("total")}`;
+approve.resolveUrl = async (job) => `/approve?job=${job.id}&total=${await job.properties.get("total")}`;
 ```
 
 Write it **app-relative** (an absolute path like `/approve`, as above) — it's a

package/docs/features/core-concepts.md

@@ -43,6 +43,13 @@ against your schema before applying them. Every property a job holds must have a
 `PropertyDefinition`, or the change is rejected. This is what keeps a job's data
 trustworthy no matter who or what wrote it.
 
+Properties are stored one by one and read on demand — `await
+job.properties.get("name")` — so a job can carry a great deal of data without
+every step paying for all of it. A state can
+[prewarm](actions-and-actors.md#prewarm-what-a-state-needs) what it needs in
+one fetch; a step that scores one summary loads one summary, and writes back
+only what it changed.
+
 ## Nothing is hard-wired
 
 Persistence, queueing, document/secret/SQL stores — all of them come from

package/docs/features/scheduled-runs.md

@@ -66,7 +66,7 @@ Every scheduled job carries the run it belongs to:
 
 ```ts
 processRun.run = async (job) => {
-    const scheduledFor = new Date(job.properties.get("scheduledFor"));
+    const scheduledFor = new Date(await job.properties.get("scheduledFor"));
     // …reconcile everything up to scheduledFor
 };
 ```

package/docs/features/state-machines.md

@@ -13,7 +13,7 @@ import {Action, Code, PropertyDefinition, State, StateMachine, Transition} from
 
 const sendWelcome = new Action("Send welcome email", new Code("welcome"));
 sendWelcome.run = async (job) => {
-    const email = job.properties.get("email");
+    const email = await job.properties.get("email");
     console.log(`Sending welcome email to ${email}`);
     return new Map([["welcomeSent", true]]);   // properties to add to the job
 };
@@ -25,7 +25,7 @@ const onboarding = new StateMachine(
     "onboarding",
     [
         new State("new", [sendWelcome], [
-            new Transition("active", (job) => job.properties.get("welcomeSent") === true),
+            new Transition("active", async (job) => await job.properties.get("welcomeSent") === true),
         ]),
         new State("active"),
     ],
@@ -67,7 +67,7 @@ once on entry. That is deliberate — it lets a predicate be time-based
 work that must happen only once, guard it:
 
 ```ts
-fetchReport.predicate = (job) => !job.properties.has("report");
+fetchReport.predicate = async (job) => ! await job.properties.has("report");
 ```
 
 ## Failing a job
@@ -79,7 +79,7 @@ job cannot proceed":
 
 ```ts
 chargeCard.run = async (job) => {
-    const outcome = await payments.charge(job.properties.get("amount"));
+    const outcome = await payments.charge(await job.properties.get("amount"));
     if (!outcome.ok) throw new Error(`Card declined for job ${job.id}: ${outcome.reason}`);
     return new Map([["charged", true]]);
 };
@@ -97,7 +97,7 @@ Mark the end of a process with `Terminal`, which carries an outcome:
 import {Terminal, Transition} from "anbaric";
 
 new State("packing", [packItems], [
-    new Transition("shipped", (job) => job.properties.get("packed") === true),
+    new Transition("shipped", async (job) => await job.properties.get("packed") === true),
 ]),
 new Terminal("shipped", Terminal.Outcome.SUCCESS),
 new Terminal("cancelled", Terminal.Outcome.FAILURE),
@@ -127,8 +127,8 @@ specific conditions first.
 
 ```ts
 new State("placed", [], [
-    new Transition("cancelled", (job) => job.properties.get("cancelled") === true),
-    new Transition("packing",   (job) => job.properties.get("paid") === true),
+    new Transition("cancelled", async (job) => await job.properties.get("cancelled") === true),
+    new Transition("packing",   async (job) => await job.properties.get("paid") === true),
 ]),
 ```
 

package/docs/patterns/first-app.md

@@ -45,17 +45,17 @@ review.resolveUrl = (job) => `/review?job=${job.id}`;
 // An automated payment step.
 const payOut = new Action("Pay the expense", new Code("payments"));
 payOut.run = async (job) => {
-    // ... call your payment provider with job.properties.get("amount") ...
+    // ... call your payment provider with await job.properties.get("amount") ...
     return new Map([["paid", true]]);
 };
 
 const expenses = new StateMachine("expenses", [
     new State("submitted", [review], [
-        new Transition("approved", (job) => job.properties.get("approved") === true),
-        new Transition("rejected", (job) => job.properties.get("approved") === false),
+        new Transition("approved", async (job) => await job.properties.get("approved") === true),
+        new Transition("rejected", async (job) => await job.properties.get("approved") === false),
     ]),
     new State("approved", [payOut], [
-        new Transition("paid", (job) => job.properties.get("paid") === true),
+        new Transition("paid", async (job) => await job.properties.get("paid") === true),
     ]),
     new Terminal("paid", Terminal.Outcome.SUCCESS),
     new Terminal("rejected", Terminal.Outcome.FAILURE),

package/docs/patterns/human-in-the-loop.md

@@ -18,8 +18,8 @@ approve.fields = ["approved", "note"];
 approve.resolveUrl = (job) => `/approve?job=${job.id}`;
 
 new State("review", [approve], [
-    new Transition("approved", (job) => job.properties.get("approved") === true),
-    new Transition("rejected", (job) => job.properties.get("approved") === false),
+    new Transition("approved", async (job) => await job.properties.get("approved") === true),
+    new Transition("rejected", async (job) => await job.properties.get("approved") === false),
 ]),
 ```
 
@@ -29,8 +29,8 @@ Because `resolveUrl` is a function of the job, you can encode everything the pag
 needs in the link — most importantly the **job id**:
 
 ```ts
-approve.resolveUrl = (job) =>
-    `/approve?job=${job.id}&amount=${job.properties.get("amount")}`;
+approve.resolveUrl = async (job) =>
+    `/approve?job=${job.id}&amount=${await job.properties.get("amount")}`;
 ```
 
 The admin console lists every job **awaiting a human** and turns this
@@ -57,9 +57,9 @@ matching `approved` fires. The decision is recorded against the user in the
 Use `metadata` to carry extra context with the wait (shown alongside the task):
 
 ```ts
-approve.metadata = (job) => new Map([
-    ["submittedBy", job.properties.get("submitter")],
-    ["amount", job.properties.get("amount")],
+approve.metadata = async (job) => new Map([
+    ["submittedBy", await job.properties.get("submitter")],
+    ["amount", await job.properties.get("amount")],
 ]);
 ```
 
@@ -72,10 +72,10 @@ Chain approvals by giving each its own state and `Await`. Because actions after
 
 ```ts
 new State("manager-review", [managerApprove], [
-    new Transition("finance-review", (job) => job.properties.get("managerApproved") === true),
+    new Transition("finance-review", async (job) => await job.properties.get("managerApproved") === true),
 ]),
 new State("finance-review", [financeApprove], [
-    new Transition("approved", (job) => job.properties.get("financeApproved") === true),
+    new Transition("approved", async (job) => await job.properties.get("financeApproved") === true),
 ]),
 ```
 

package/docs/patterns/integrating-external-systems.md

@@ -13,7 +13,7 @@ job park until the system reports back:
 ```ts
 const startSigning = new Action("Send for signature", new Code("esign"));
 startSigning.run = async (job) => {
-    const ref = await eSignProvider.createEnvelope(job.properties.get("documentUrl"));
+    const ref = await eSignProvider.createEnvelope(await job.properties.get("documentUrl"));
     return new Map([["envelopeRef", ref]]);
 };
 
@@ -21,7 +21,7 @@ const awaitSignature = new Await("Await signature", "EXTERNAL_SYSTEM");
 awaitSignature.fields = ["signed"];
 
 new State("signing", [startSigning, awaitSignature], [
-    new Transition("signed", (job) => job.properties.get("signed") === true),
+    new Transition("signed", async (job) => await job.properties.get("signed") === true),
 ]),
 ```
 
@@ -59,12 +59,12 @@ re-checks after a back-off until the status flips:
 ```ts
 const checkStatus = new Action("Poll payment status", new Code("payments"));
 checkStatus.run = async (job) => {
-    const status = await gateway.status(job.properties.get("paymentRef"));
+    const status = await gateway.status(await job.properties.get("paymentRef"));
     return status === "settled" ? new Map([["settled", true]]) : new Map();
 };
 
 new State("charging", [checkStatus], [
-    new Transition("settled", (job) => job.properties.get("settled") === true),
+    new Transition("settled", async (job) => await job.properties.get("settled") === true),
 ]),
 ```
 

package/docs/patterns/modelling-workflows.md

@@ -28,7 +28,7 @@ transition reacts. This keeps each piece testable and the flow visible.
 
 ```ts
 new State("packing", [packItems], [
-    new Transition("shipped", (job) => job.properties.get("packed") === true),
+    new Transition("shipped", async (job) => await job.properties.get("packed") === true),
 ]),
 ```
 
@@ -39,8 +39,8 @@ transition wins. Put more specific transitions first:
 
 ```ts
 new State("placed", [], [
-    new Transition("cancelled", (job) => job.properties.get("cancelled") === true),
-    new Transition("packing",   (job) => job.properties.get("paid") === true),
+    new Transition("cancelled", async (job) => await job.properties.get("cancelled") === true),
+    new Transition("packing",   async (job) => await job.properties.get("paid") === true),
 ]),
 ```
 
@@ -51,10 +51,10 @@ routes work without extra states:
 
 ```ts
 const autoTriage = new Action("Auto triage", new Code("triage-bot"));
-autoTriage.predicate = (job) => job.properties.get("priority") === "low";
+autoTriage.predicate = async (job) => await job.properties.get("priority") === "low";
 
 const escalate = new Action("Escalate", new Code("rules"));
-escalate.predicate = (job) => job.properties.get("priority") === "high";
+escalate.predicate = async (job) => await job.properties.get("priority") === "high";
 
 new State("open", [autoTriage, escalate], [/* transitions */]);
 ```
@@ -67,7 +67,7 @@ parks cleanly and resumes when the input arrives:
 
 ```ts
 new State("review", [new Await("Approve", "HUMAN")], [
-    new Transition("approved", (job) => job.properties.get("approved") === true),
+    new Transition("approved", async (job) => await job.properties.get("approved") === true),
 ]),
 ```
 
@@ -81,7 +81,7 @@ after a back-off — so a state can gently poll without a busy loop.
 ```ts
 const poll = new Action("Check delivery status", new Code("carrier"));
 poll.run = async (job) => {
-    const status = await fetchStatus(job.properties.get("tracking"));
+    const status = await fetchStatus(await job.properties.get("tracking"));
     return status === "delivered" ? new Map([["delivered", true]]) : new Map();
 };
 ```
@@ -109,7 +109,7 @@ const companies = new PropertyDefinition("companies");
 companies.example = [{ slug: "acme", companyName: "Acme Corp" }];
 
 // in an action
-const companies = job.properties.get("companies") ?? [];
+const companies = await job.properties.get("companies") ?? [];
 ```
 
 ## See also

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anbaric",
-  "version": "1.56.9",
+  "version": "1.58.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.56.9",
-    "anbaric-data-store": "^1.56.9",
-    "anbaric-state-machine": "^1.56.9",
-    "anbaric-tsapi": "^1.56.9"
+    "anbaric-impl-cloud": "^1.58.0",
+    "anbaric-data-store": "^1.58.0",
+    "anbaric-state-machine": "^1.58.0",
+    "anbaric-tsapi": "^1.58.0"
   }
 }