@lotics/app-sdk 0.82.1 → 0.82.3

package/docs/mutations.md

@@ -272,18 +272,22 @@ Inside the workflow body, the payload is `trigger.app_workflow.inputs.<name>`, t
 `T | null | undefined` for an optional input. The triggering member is
 `runtime.triggered_by_member_id` (`null` for an anonymous public caller).
 
-**Guard on `undefined`, not on nullish.** The three caller states arrive intact, and the loose
-`!= null` collapses two of them — it skips a clear as well as an omission, which is how a Clear
-button ends up doing nothing:
+**Guard on the KEY, not on the value.** The three caller states arrive intact — an omitted input
+has no key at all, a cleared one has the key with `null` — so a value test cannot tell them apart:
+`!= null` and `isNull(…)` both skip a clear as well as an omission, which is how a Clear button
+ends up doing nothing. Ask whether the key was sent:
 
 ```js
 const i = trigger.app_workflow.inputs;
-if (i.title !== undefined) {
+if (includes(keys(i), "title")) {
   // i.title may be null here — that is the CLEAR, and `set` writes it as one.
   await update_records({ table_id: "tbl_items", record_ids: [i.record_id], set: { fld_title: i.title } });
 }
 ```
 
+`undefined` is not spellable in a workflow body — the expression subset has no such identifier, and
+a body naming it fails to save with `Unknown identifier "undefined"`. `keys` is the presence test.
+
 When several optional inputs each map to a field, per-field guards become noise. Hand the whole
 bag to `update_records`' **`set_skip_null`** instead — same object shape as `set`, but entries
 whose value is `null`/`undefined` are dropped, so only the fields actually provided get written

package/docs/workflows.md

@@ -504,15 +504,20 @@ record is the body's decision, and the two write surfaces answer differently:
 | `set: { fld_x: i.x }` | **clears the field** |
 
 So `set_skip_null` is the right default for a bag of optional inputs, and the wrong choice for any
-field the screen must be able to blank — put those in `set`, and guard on `undefined` so an input
-the caller never sent is not written:
+field the screen must be able to blank — put those in `set`, and test whether the KEY was sent so
+an input the caller never sent is not written:
 
 ```js
-if (i.phone !== undefined) {   // NOT `!= null` — that swallows the clear
+if (includes(keys(i), "phone")) {   // NOT `isNull(i.phone)` — that swallows the clear
   await update_records({ table_id: "tbl_x", record_ids: [i.id], set: { fld_phone: i.phone } });
 }
 ```
 
+An omitted input carries no key at all and a cleared one carries the key with `null`, so presence
+is the only test that separates them. It has to be `keys` rather than a comparison against
+`undefined`: the expression subset has no `undefined` identifier, and a body naming it fails to
+save with `Unknown identifier "undefined"`.
+
 `""` is never a clear on any surface: an HTML input emits it for "the user skipped this", so the
 validator coerces it to omitted before the body runs. Reaching for `""` to blank a field fails
 silently — the write reports success and the old value stays. Send `null`.
@@ -627,9 +632,14 @@ The rules that are easy to get wrong because the failing code looks correct.
   spelling. Start that binding from the first array instead of seeding it `[]`. Appending single
   **items** (`xs.push(item)`) works on a bare `[]` seed.
 - **A mutation on the trigger table of an `after_*` workflow can re-trigger itself** — a lint
-  warning, not an error. Gate it on `trigger.change_origin.type == "member"` (the originating
-  write's origin). Not `runtime.change_origin`: that is the execution's own origin, always
-  `table_workflow` here, so it discriminates nothing.
+  warning, not an error. Gate it on `trigger.change_origin` — the originating write's origin —
+  and name every origin you mean to let through, rather than testing for one. `member` is a
+  person in the browser and **only** that: the same edit made over MCP, the CLI, or a direct API
+  call arrives as `api_client`, and one made by the chat agent as `chat_agent`. A gate meaning
+  "someone did this by hand" is
+  `includes(["member", "chat_agent", "api_client"], trigger.change_origin.type)`. Not
+  `runtime.change_origin`: that is the execution's own origin, always `table_workflow` here, so
+  it discriminates nothing.
 
 ## The bright line
 

package/package.json

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