@lotics/app-sdk 0.64.1 → 0.66.0

package/AGENTS.md

@@ -33,7 +33,9 @@ signature; open the file.**
   A client-supplied member id is an IDOR. → [security](./docs/security.md)
 - **Server data is never copied into `useState`** — hooks are the source of truth; derive with
   `useMemo`. → [data_fetching](./docs/data_fetching.md)
-- **Update writes are diffs** — send only changed fields. → [mutations](./docs/mutations.md)
+- **Update writes are diffs** — send only changed fields, and *cleared* is a change: an optional
+  input clears with `null` (never `""`), which `set_skip_null` drops and `set` performs.
+  → [mutations](./docs/mutations.md)
 - **`project` only what you render; filter server-side.** A bare `from_table` over-ships every
   column, including files. → [queries](./docs/queries.md)
 - **Never hand-roll the serialization contract** — decode cells with the typed readers.

package/docs/mutations.md

@@ -202,10 +202,17 @@ When the alias declares `inputs`, the server validates the payload before the wo
 - **Strict object** — a payload key not in the schema is rejected. Want forward-compatible
   payloads? Declare a `json` input.
 - **Missing required input** — rejected. `required` defaults to true.
-- **Optional inputs and `""`** — a top-level optional input whose value is the empty string
-  is treated as *omitted* (HTML form controls emit `""` for "left blank"). Nested optional
-  object fields are plain-optional: omit the key. A required `text` input does accept `""` —
-  emptiness is not a type error; validate non-emptiness in the workflow body if it matters.
+- **Optional inputs carry THREE caller states** — omitted means *leave unchanged*, a value means
+  *write it*, and **`null` means CLEAR**. The generated type says so: a top-level optional input
+  is `T | null`. Sending `null` is how an inline editor blanks a phone number or unassigns an
+  owner; the body forwards it to `update_records.set`, where `null` clears.
+- **`""` is NOT a clear** — a top-level optional input whose value is the empty string is treated
+  as *omitted* (HTML form controls emit `""` for "left blank", never for "blank this out"), so the
+  write reports success and the old value stays. Reaching for `""` to clear is the natural first
+  guess and it fails silently; send `null`. Nested optional object fields are plain-optional and
+  **reject `null`** — only a top-level input clears; omit the key. A required `text` input does
+  accept `""` — emptiness is not a type error; validate non-emptiness in the workflow body if it
+  matters.
 - **Required reference inputs reject empty** — a required `record_link` / `member` / `file`
   must resolve to at least one real id: the single form rejects `""`, and the multi form
   rejects `[]` (an empty array is the multi-analog of an empty value — it would otherwise slip
@@ -261,14 +268,18 @@ see [members_and_options](./members_and_options.md).
 
 ### What the body sees
 
-Inside the workflow body, the payload is `trigger.app_workflow.inputs.<name>`, typed per the
-declaration (optional inputs may be absent). The triggering member is
-`runtime.triggered_by_member_id` (`null` for an anonymous public caller). An omitted optional
-input should mean "don't write that field" — guard each write:
+Inside the workflow body, the payload is `trigger.app_workflow.inputs.<name>`, typed
+`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:
 
 ```js
 const i = trigger.app_workflow.inputs;
-if (i.title != null) {
+if (i.title !== undefined) {
+  // 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 } });
 }
 ```
@@ -277,7 +288,9 @@ When several optional inputs each map to a field, per-field guards become noise.
 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
 (untouched fields keep their lock / `before_update` / concurrent-edit safety — the diff-write
-discipline below, done in the body):
+discipline below, done in the body). **It drops `null` as well as `undefined`, so it cannot
+CLEAR** — a field the screen must be able to blank belongs in `set` with the guard above, whatever
+the rest of the bag does:
 
 ```js
 const i = trigger.app_workflow.inputs;

package/docs/workflows.md

@@ -492,6 +492,31 @@ all-dropped `set_skip_null` with no other surface is a no-op (no records touched
 `before_update` hooks). 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
+— omitted (leave unchanged), a value (write it), `null` (clear) — and they arrive in the body
+intact as `T | null | undefined`; the caller side is
+[mutations](./mutations.md#validation-at-the-execute-boundary). Which of them actually reaches the
+record is the body's decision, and the two write surfaces answer differently:
+
+| Body writes | a `null` input |
+|---|---|
+| `set_skip_null: { fld_x: i.x }` | **dropped — the clear does not happen** |
+| `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:
+
+```js
+if (i.phone !== undefined) {   // NOT `!= null` — that swallows the clear
+  await update_records({ table_id: "tbl_x", record_ids: [i.id], set: { fld_phone: i.phone } });
+}
+```
+
+`""` 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`.
+
 Value shapes, which the generated types enforce exactly:
 
 | Field | Read | Write |
@@ -641,10 +666,18 @@ rejects, or read a path that is null on real data. The rehearsal for that is `dr
 hands back `planned_calls` (every tool call in order, with its fully-resolved input),
 `return_value`, `validation_failures`, `evaluation_errors`, and `tool_input_errors` — inputs the
 target tool would reject, which can only surface once the values are computed. **Write tools are
-recorded, never dispatched**, and nothing is persisted. For a table-triggered body, pass
-`record_id` + `table_id` instead of `trigger_payload` and the read-only tools (`query_records`,
-`get_record`, `aggregate_records`) dispatch for real, so data-dependent gates are exercised
-against actual rows. Do this before the first live run of anything that writes.
+recorded, never dispatched**, and nothing is persisted.
+
+**Add `live_reads: true` whenever the body READS.** By default the read-only tools
+(`query_records`, `get_record`, `aggregate_records`) return stubs — an empty result set, a blank
+record — so any branch gated on stored data takes the empty path and the rehearsal quietly proves
+nothing about the branch that matters. A duplicate check finds no duplicate; a lookup that should
+skip because a field is already set doesn't skip. With `live_reads: true` those three dispatch
+against the real workspace under YOUR authority, so the gates are exercised against actual rows
+while writes stay recorded-only. (A table-triggered body gets this from `record_id` + `table_id`,
+which supply the real record as the payload AND turn live reads on; an app workflow has no trigger
+record — its payload is its inputs — so it asks for the reads directly.) Do this before the first
+live run of anything that writes.
 
 ## A worked body
 
@@ -676,7 +709,7 @@ await create_records({
     fld_customer: [i.customer_id],
     fld_status: "opt_open",
     fld_opened_on: formatDate(now(), "yyyy-MM-dd"),
-    fld_note: i.note,          // omitted optional input → undefined → key dropped
+    fld_note: i.note,          // optional input: omitted → dropped; null → cleared
   }],
 });
 

package/package.json

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