@lotics/app-sdk 0.64.0 → 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/queries.md

@@ -431,7 +431,7 @@ derived surfaces share one implementation.
 
 | Field type | Column type | Source-layer operators | Derived-layer differences | Sort / group / aggregate notes |
 | --- | --- | --- | --- | --- |
-| text | `text` | `equals`, `not_equals`, `contains`, `does_not_contain`, `starts_with`, `ends_with`, `is_empty`, `is_not_empty`, `is_any_of`, `is_none_of` | same set | Sort is lexicographic in the database's default collation — no locale control. Text comparisons normalize both sides (trim + case-insensitive). |
+| text | `text` | `equals`, `not_equals`, `contains`, `does_not_contain`, `starts_with`, `ends_with`, `is_empty`, `is_not_empty`, `is_any_of`, `is_none_of` | same set | Sort is lexicographic in the database's default collation — no locale control. Text comparisons normalize both sides (trim + case-insensitive). The LIKE family (`contains`, `does_not_contain`, `starts_with`, `ends_with`) additionally folds **diacritics**, so `contains "ha noi"` matches `"Hà Nội"`; the identity operators (`equals`, `not_equals`, `is_any_of`, `is_none_of`) do **not** — they compare a stored value, and `mã` is not `ma`. |
 | number | `number` | `equals`, `not_equals`, `greater_than`, `less_than`, `greater_than_or_equal_to`, `less_than_or_equal_to`, `is_empty`, `is_not_empty` | same set | Full numeric aggregate set (§8). |
 | date / datetime | `date` / `datetime` (datetime when the field's format includes time) | `on`, `before`, `after`, `on_or_before`, `on_or_after`, `between`, `time_of_day`, `is_empty`, `is_not_empty` — values are `DateTimePoint`s (below) | same set | Day-level filters on datetime values expand to the full-day window. Sortable; bucketable in `group.by` (§8); `earliest`/`latest`/`min`/`max`/`date_range` aggregate. |
 | boolean | `boolean` | `equals` (value `true`/`false`; `false` matches NULL/missing) | same | `checked`/`unchecked`/`percent_*` aggregate (`unchecked` counts false **or** empty). |
@@ -596,11 +596,20 @@ It AND-s with `filter` (search *within* a scope) and is templatable
 (`"search": "{{params.q}}"`). An empty or whitespace-only term matches everything; an
 unresolved optional token prunes to match-all (§6).
 
-**Search-as-you-type uses `search`, never a `contains` OR-group.** Per-field `contains` is
-accent-*sensitive* and unindexed — a zero-match keystroke forces a full-partition scan that
-hangs the picker. Reserve an OR-group of `contains` for when you must bound exactly *which*
-fields match. Gate the fetch on a non-empty term client-side (`enabled`), or first paint dumps
-the table.
+**Search-as-you-type over a LARGE table uses `search`, never a `contains` OR-group.** Per-field
+`contains` is unindexed — a zero-match keystroke forces a full-partition scan that hangs the
+picker. (It is not accent-sensitive; the LIKE family folds diacritics, §5.) Gate the fetch on a
+non-empty term client-side (`enabled`), or first paint dumps the table.
+
+**But `search` matches the WHOLE record, and on an identity box that is usually wrong.** The
+search document indexes select option labels, member names, dates in three formats, and each
+linked record's cached display text — including the `Field=True/False` pill a boolean renders
+into. A box captioned "find a person" then matches rows that merely share a stage label or an
+owner, and folding makes near-homographs collide (`tiến` ≡ `tiền`). Measured on a real 88-row
+customer book, one such term returned **every row**. When the box means *find this person*, bound
+it: an OR-group of `contains` over the two or three identity fields (name, national id, phone),
+with the term param `required: false` so an empty box prunes the group to match-all. Use `search`
+when the box genuinely means *find this anywhere in the record*.
 
 ---
 
@@ -872,7 +881,9 @@ and is not — and a playbook rule applied to the wrong query costs effort while
 ### The authoring rules
 
 1. **Filter at the source.** Push every static predicate into `from_table.filter`.
-2. **Prefer `search`** for any free-text box; `contains` OR-groups only to bound the fields.
+2. **Match the operator to what the box MEANS.** *Find this anywhere in the record* → `search`.
+   *Find this person/order* → a `contains` OR-group over the identity fields (§7) — the
+   whole-record index will surface rows that only share an owner or a status.
 3. **Aggregate and bucket server-side.** A dashboard reads grouped rows, never raw rows it
    reduces in JS — raw-row shipping burns the 10k cap, the timeout, and bandwidth at once.
 4. **Project narrow.** Every un-rendered column is wasted bytes; every un-rendered `files`

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.0",
-  "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": {
     ".": {