@lotics/app-sdk 0.87.3 → 0.87.4

package/docs/mutations.md

@@ -321,7 +321,8 @@ await update_records({
 
 `set` still writes every key it carries — `null` in `set` **clears** the field; `null`/absent in
 `set_skip_null` **skips** it. The full write surface (`set`, `set_skip_null`, the surgical
-`add_to`/`remove_from`/`replace` ops, `field_edits`, and the exact value shape per field type)
+`add_to`/`remove_from`/`replace` ops, `increment`, `field_edits`, and the exact value shape per
+field type)
 is [workflows](./workflows.md#writing-records).
 
 ## Refetch after a mutation
@@ -446,7 +447,9 @@ Why a full-form snapshot save is a bug, not a style choice — three independent
    append is the system's rather than a person's — an upload settling, a workflow attaching a
    generated document — name the ITEMS with `add_to` / `remove_from`
    ([workflows](./workflows.md#writing-records)) and the write path resolves them against the
-   record as it stands.
+   record as it stands. A running total is the scalar form of the same defect: two writers both
+   read 100, both subtract 10, both write 90, and one sale is gone with no error anywhere. Name
+   the DELTA with `increment`.
 
 ```tsx
 // load: snapshot the editable fields from the row

package/docs/workflows.md

@@ -482,31 +482,38 @@ differ from `<` / `>` (code-unit order) and from the database's collation.
 
 ## Writing records
 
-`update_records` carries four composable surfaces. A field may appear in **at most one** of them.
+`update_records` carries five composable surfaces. A field may appear in **at most one** of them.
 
 | Surface | Shape | Effect |
 |---|---|---|
 | `set` | `{ fld_x: value }` | write the whole value. `null` **clears** the field |
 | `set_skip_null` | `{ fld_x: value }` | same shape, but `null`/`undefined` entries are **dropped** — absent means "leave unchanged" |
 | `add_to` / `remove_from` / `replace` | `{ fld_x: [items] }` | surgical edits on multi-value fields (files, multi select, multi member, record links) |
-| `field_edits` | `[{ field, op, value }]` | the same surgical ops with the field named by a **string expression** — the only way to target a field chosen at run time |
-
-`add_to` / `remove_from` are RELATIVE: the server resolves them against the record as it stands
-when the write lands, inside the lock it already takes. Two runs appending to one field at the
-same time therefore each keep their item — which reading the field and writing the whole array
-back through `set` does not, since both fold onto the array they read and the later write drops
-the earlier, both reporting success. Parallel runs are ordinary (a trigger firing twice, an agent
-emitting two calls in one step), so reach for the ops rather than a read-modify-write whenever
-the workflow is ADDING to a field rather than stating it.
+| `increment` | `{ fld_x: delta }` | move a **number** field by a signed amount. Negative decrements; there is no separate decrement op |
+| `field_edits` | `[{ field, op, value }]` | the multi-value ops with the field named by a **string expression** — the only way to target a field chosen at run time. `increment` has no value-form: its payload is a scalar, not an item list |
+
+`add_to`, `remove_from` and `increment` are RELATIVE: the server resolves them against the record
+as it stands when the write lands, inside the lock it already takes. Two runs changing one field at
+the same time therefore each keep their effect — which reading the field and writing the result back
+through `set` does not, since both fold onto the value they read and the later write drops the
+earlier, both reporting success. On a stock count that is a sale that vanishes. Parallel runs are
+ordinary (a trigger firing twice, an agent emitting two calls in one step), so reach for the ops
+rather than a read-modify-write whenever the workflow is CHANGING a field by an amount rather than
+stating its value.
+
+`increment` counts an empty or unset field as 0, so a first decrement leaves a negative — oversold,
+and visibly so. It is rejected on formula, rollup, lookup and autonumber fields: those come from
+their own definition, so change what they aggregate instead.
 
 Inside `set` and `create_records.records`: `null` clears (persisted), `undefined` or an omitted
 key preserves. So passing a possibly-null read straight through is safe. Use
 `coalesce(x, fallback)` only when you want a real fallback, never to "strip" null.
 
 `set_skip_null` is what turns a bag of optional workflow inputs into a diff-write without a guard
-per field; naming the same field in both `set` and `set_skip_null` is an error, and an
-all-dropped `set_skip_null` with no other surface is a no-op (no records touched, no
-`before_update` hooks). Why diffs and not snapshots, plus locked records and the
+per field; naming the same field in both `set` and `set_skip_null` is an error. A call whose
+surfaces all resolve to nothing — an all-dropped `set_skip_null`, an op object with no entries —
+is a no-op: no records touched, no `before_update` hooks. So a conditionally-built op object needs
+no guard around the call. Why diffs and not snapshots, plus locked records and the
 `request_locked_record_change` path: [mutations](./mutations.md#diff-before-update--send-only-what-changed).
 
 **A `null` optional input is a CLEAR, and `set_skip_null` drops it.** The caller has three states

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.87.3",
+  "version": "0.87.4",
   "description": "Runtime SDK for Lotics custom-code apps \u2014 typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {