anbaric 1.56.8 → 1.57.0

package/docs/api/cli.md

@@ -46,7 +46,7 @@ anbaric app status link-media-brief     # a different app, from anywhere
 | --- | --- |
 | `anbaric state-machines` | List registered state machines. |
 | `anbaric jobs create <sm-id> <start-state> [k=v …]` | Create a job and queue it for processing. |
-| `anbaric jobs list [state-machine-id]` | List jobs, optionally filtered by workflow. |
+| `anbaric jobs list [state-machine-id]` | List jobs, newest first, a page at a time (100 by default — `--page 1` for the next). Narrow with `--state`, `--status`, `--app`; `--oldest` flips the order. Filters apply on the platform, across every job, before paging. |
 | `anbaric jobs stats` | Job counts per state and the queue size. |
 | `anbaric jobs watch <job-id>` | Follow a job's state and property changes live. |
 | `anbaric jobs set-state <job-id> <state>` | Move a job to a state and re-queue it. |
@@ -67,6 +67,9 @@ ask for, so the CLI runs unattended in scripts and CI.
 | `--name <name>` | `app configure`/`deploy`/`update` | App name; prompts if omitted (suggested from `package.json`). |
 | `--port <port>` | `app configure`/`deploy`/`update` | Internal port (1–65535); prompts if omitted. |
 | `--yes` | `app deploy`, `app tear-down`, `jobs kill-old` | Skip confirmation. (`app update` implies it.) |
+| `--state <state>`, `--status <status>`, `--app <app>` | `jobs list` | Only jobs in that state / with that status (`active`, `Awaiting input`, `Failed`) / belonging to that app. |
+| `--page <n>`, `--page-size <n>` | `jobs list` | Which page (from 0) and how many per page (default 100). |
+| `--oldest` | `jobs list` | Oldest first instead of newest. |
 | `--help`, `-h` | all | Print usage. |
 
 ## Configuration and storage

package/docs/api/state-machine.md

@@ -136,20 +136,46 @@ actor : Actor
 constructor(name : string, actor : Actor, description : string = "", id? : string)
 
 // Replaceable function fields — assign your own:
+reads : Reads                                  // default: Reads.everything
 predicate : (job : Job) => boolean            // default: () => true
 run : (job : Job) => Promise<Map<string, any>> // default: async () => new Map()
 ```
 
-You configure an action by assigning `predicate` and `run`:
+You configure an action by assigning `predicate` and `run`, and `reads` when
+the job holds more than the action needs:
 
 ```ts
 const sendWelcome = new Action("Send welcome email", new Code("welcome"));
+sendWelcome.reads = Reads.only("email", "name");
 sendWelcome.run = async (job) => new Map([["welcomeSent", true]]);
 ```
 
+- **`reads`** — which properties are loaded for the job before `predicate` and
+  `run` see it. Given the machine's property definitions, so it can be written
+  once and follow the schema. See [`Reads`](#reads).
 - **`predicate`** — return `false` to skip this action for a given job.
 - **`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.
+
+### `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
+```
+
+A job is loaded with the union of what the current state's actions, awaits and
+transitions read, and nothing else: a property that wasn't declared is simply
+absent from `job.properties`. A step that reads everything loads everything, so
+nothing changes until you declare. Declaring matters for jobs that carry a lot
+— a workflow holding hundreds of article summaries stops moving all of them
+for a step that scores one — and for [agentic actions](../features/ai-agents.md),
+whose prompt carries the loaded properties and nothing more.
 
 See [Actions and actors](../features/actions-and-actors.md).
 
@@ -172,6 +198,7 @@ waitingFor? : AwaitParty
 fields : Array<string> = []
 resolveUrl : string | ((job : Job) => string) = ""
 metadata : (job : Job) => Map<string, any>    // default: () => new Map()
+reads : Reads                                 // what resolveUrl and metadata read; default: Reads.everything
 
 constructor(name : string, waitingFor? : AwaitParty, description : string = "", id? : string)
 
@@ -218,18 +245,20 @@ transition whose predicate holds moves the job to `to`.
 ```ts
 to : string
 predicate : (job : Job) => boolean          // default: () => true
+reads : Reads                               // default: everything if guarded, nothing if not
 
-constructor(to : string, predicate? : (job : Job) => boolean)
+constructor(to : string, predicate? : (job : Job) => boolean, reads? : Reads)
 ```
 
 ```ts
-new Transition("active", (job) => job.properties.get("welcomeSent") === true)
+new Transition("active", (job) => job.properties.get("welcomeSent") === true, Reads.only("welcomeSent"))
 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, and say what the
+guard reads so the job is loaded with only that.
 
 ---
 
@@ -268,6 +297,45 @@ 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.
 
+### Reading a job
+
+```ts
+persistence.retrieve(id, actor) : Promise<Job>                  // every property
+persistence.retrieve(id, actor, ["summary", "score"]) : Promise<Job>   // only those
+```
+
+Properties are stored one by one, so a job can be read with only the keys
+wanted — that's what the machine does for every step, from what the step
+[declares it reads](#reads) — and a save writes only the properties that
+changed. A property absent from a partial read is never touched by a save of
+that job, 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
+const persistence = JobPersistenceFactory.instance();
+
+persistence.list(actor) : Promise<Array<Job>>                                  // first 100, oldest first
+persistence.list(actor, pageSize, page, query?) : Promise<Array<Job>>
+
+type JobPersistence.Query = {
+    workflowId? : string,
+    appId? : string,
+    state? : string,
+    status? : string,            // "active", "Awaiting input", "Failed"
+    killed? : boolean,
+    order? : "oldest" | "newest" // by when the job was started; oldest by default
+}
+```
+
+A listing is a **page**, never a cap: `pageSize` jobs (default 100) at `page`
+(from 0), and every job the store holds is reachable by asking for the next
+page until one comes back short. The query narrows the set on the store before
+paging — a filter sees every job, and page numbers count matching jobs only.
+Deployed, the store holds every job on the tenant across all apps and machines.
+
 ---
 
 ## `PropertyDefinition`

package/docs/api/web.md

@@ -94,10 +94,43 @@ GET /api/v2/whoami   →   { "id": "user-123", "roles": ["admin"] }
 
 Returns the authenticated user for the current request.
 
+### Jobs
+
+```
+GET /api/v2/jobs?page=0&pageSize=100&order=newest&workflowId=…&appId=…&state=…&status=…&killed=false
+```
+
+Every job on the tenant, across all apps and state machines, **paged**: the
+response is one page of at most `pageSize` jobs (default 100) at page `page`
+(from 0). The page size is not a cap — keep asking for the next page until one
+comes back shorter than `pageSize`, which is the last. `order` is by when the
+job was started: `oldest` (the default, for compatibility) or `newest`.
+
+The other parameters are filters, applied on the platform **before** paging, so
+a filter sees every job and page numbers count matching jobs only. All are
+optional and combine with AND: `workflowId` (the state machine), `appId`,
+`state`, `status` (`active`, `Awaiting input`, `Failed`) and `killed`
+(`true`/`false`).
+
+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:
-`jobs`, `state-machines`, `queue`, `consumers`, and (when enabled) `documents`,
+`state-machines`, `queue`, `consumers`, and (when enabled) `documents`,
 `secrets`, `audits`. Prefer the typed clients and factories over calling these by
 hand.
 

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

@@ -32,6 +32,32 @@ 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.
 
+### Declare what an action reads
+
+A job can hold a lot — hundreds of article summaries, say — while a given
+action needs one property of it. Declare that, and only that is loaded:
+
+```ts
+import {Reads} from "anbaric";
+
+chargeCard.reads = Reads.only("total", "paid");
+```
+
+`reads` is a function of the machine's property definitions, so a mapping can
+be written once and keep up as the schema grows: `Reads.everything` (the
+default — nothing changes until you declare), `Reads.nothing`,
+`Reads.only(...keys)`, or `Reads.where(definition => …)` to pick by name. A
+transition's guard takes a `reads` too, and an `Await`'s `resolveUrl` and
+`metadata` have one.
+
+Before a job is processed in a state, the machine loads the union of what that
+state's actions, awaits and transitions read; a property that wasn't declared
+is simply absent from `job.properties`, so declare honestly. Afterwards it
+writes back only the properties that changed — never the ones it read, and
+never the ones it didn't load. For an [agentic action](ai-agents.md) the
+declaration also decides what reaches the model: the prompt carries the loaded
+properties and nothing more.
+
 ## 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

@@ -45,7 +45,11 @@ 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.
+model sees the data it's reasoning about — the properties the action
+[declares it reads](actions-and-actors.md#declare-what-an-action-reads), which
+is all of them until you say otherwise. On a job that holds a lot, declare
+them: `triage.reads = Reads.only("subject")` keeps a ticket's attachments,
+history and everything else out of every call.
 
 ## The output schema
 

package/docs/features/core-concepts.md

@@ -43,6 +43,12 @@ 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 a step is given only the ones it
+[declares it reads](actions-and-actors.md#declare-what-an-action-reads) — by
+default all of them. So a job can carry a great deal of data without every
+step paying for all of it: 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anbaric",
-  "version": "1.56.8",
+  "version": "1.57.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.8",
-    "anbaric-data-store": "^1.56.8",
-    "anbaric-state-machine": "^1.56.8",
-    "anbaric-tsapi": "^1.56.8"
+    "anbaric-impl-cloud": "^1.57.0",
+    "anbaric-data-store": "^1.57.0",
+    "anbaric-state-machine": "^1.57.0",
+    "anbaric-tsapi": "^1.57.0"
   }
 }