State cell

Read or write a durable state cell, or settle a race between runs.

Without entity the cell belongs to this run and goes with it. With entity: <name>, every run in the project that names the same entity reaches the same cell.

• Kind: state
• Palette: Flow
• Run it on its own: no, only as part of a graph

When to use

• Memory between runs: a poll cursor, a last-seen id, a counter (get, set, incr).
• Doing something once even when the trigger arrives twice: op: add claims a key and says whether this run was first.
• A read-modify-write that two runs can’t interleave: get, then cas with the version you read.

Configuration

Field	Type	Required	Description
key	string	yes	Cell key.
op	string	yes	get, set, delete, or the atomic ones: add (claim a key), cas (write if unchanged), incr (count). One of "get", "set", "delete", "add", "cas", "incr".
by	integer	no	incr: how much to add (default 1; may be negative).
entity	string	no	Optional entity the cell is scoped to.
expected	integer	no	cas: the version the write requires; absent means “only if absent”.
value	any	no	Value to write (set, add, cas).

Output

Depends on op: get/incr set value+version, set/add/cas set version, add sets claimed, cas sets swapped, delete sets existed.

Field	Type	Description
claimed	boolean	add: whether this run took the key.
existed	boolean	delete: whether a cell was there.
swapped	boolean	cas: whether the write landed.
value	any	get, incr: the cell’s value.
version	integer	The cell’s version after the operation.

Example

version: hyperspool-graph/v1
nodes:
  - id: claim
    type: state
    config:
      op: add
      key: { $template: "order-{{ input.order_id }}" }
      value: true
      entity: ledger
  - id: process
    type: shell
    if: nodes.claim.output.claimed
    config:
      run: { $template: "./process-order.sh {{ input.order_id }}" }
  - id: count
    type: state
    config: { op: incr, key: processed, entity: counters }
edges:
  - { from: claim, to: process }
  - { from: process, to: count }

A second delivery of the same order finds the key taken, so claimed is false and process is skipped. Keys starting _spool/ are the engine’s own and can’t be written. See Durable state.

See the node reference for every other node.