@lotics/app-sdk 0.52.4 → 0.53.0

package/dist/src/row.d.ts

@@ -24,7 +24,9 @@ declare function bool(v: unknown): boolean;
 /**
  * Date/datetime field → a LOCAL-midnight Date for the stored calendar day, so
  * calendar/gantt placement never shifts across timezones. Parses the leading
- * `YYYY-MM-DD` of the serialized string; null if absent or unparseable. (Range
+ * `YYYY[-MM[-DD]]` of the serialized string — a reduced-precision `date` value
+ * ("2026-05" / "2026") decodes to its PERIOD START (missing month/day → 1)
+ * rather than vanishing to null. Null only if absent or unparseable. (Range
  * fields are not handled here — they have no consumer yet.)
  */
 declare function date(v: unknown): Date | null;
@@ -34,8 +36,10 @@ declare function date(v: unknown): Date | null;
  * value is a timezone-less workspace wall-clock (see the serialization note
  * above), so it is read verbatim — no UTC conversion. Use this when the time
  * matters (a check-in time, an appointment); `date` keeps only the calendar day.
- * Parses `YYYY-MM-DD` with an optional `T`-or-space `HH:mm[:ss]`; a missing time
- * is midnight. Null if absent or unparseable.
+ * Parses `YYYY[-MM[-DD]]` with an optional `T`-or-space `HH:mm[:ss]`; a missing
+ * month/day is the period start (1) and a missing time is midnight — a
+ * reduced-precision value decodes rather than vanishing. Null if absent or
+ * unparseable.
  */
 declare function datetime(v: unknown): Date | null;
 /** A linked record cell entry — the target record's id + its display text. */

package/dist/src/row.js

@@ -53,12 +53,16 @@ function bool(v) {
 /**
  * Date/datetime field → a LOCAL-midnight Date for the stored calendar day, so
  * calendar/gantt placement never shifts across timezones. Parses the leading
- * `YYYY-MM-DD` of the serialized string; null if absent or unparseable. (Range
+ * `YYYY[-MM[-DD]]` of the serialized string — a reduced-precision `date` value
+ * ("2026-05" / "2026") decodes to its PERIOD START (missing month/day → 1)
+ * rather than vanishing to null. Null only if absent or unparseable. (Range
  * fields are not handled here — they have no consumer yet.)
  */
 function date(v) {
-    const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(text(v));
-    return m ? new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3])) : null;
+    const m = /^(\d{4})(?:-(\d{2}))?(?:-(\d{2}))?/.exec(text(v));
+    if (!m)
+        return null;
+    return new Date(Number(m[1]), (m[2] ? Number(m[2]) : 1) - 1, m[3] ? Number(m[3]) : 1);
 }
 /**
  * Date/datetime field → a LOCAL Date that KEEPS the stored wall-clock time, so
@@ -66,14 +70,16 @@ function date(v) {
  * value is a timezone-less workspace wall-clock (see the serialization note
  * above), so it is read verbatim — no UTC conversion. Use this when the time
  * matters (a check-in time, an appointment); `date` keeps only the calendar day.
- * Parses `YYYY-MM-DD` with an optional `T`-or-space `HH:mm[:ss]`; a missing time
- * is midnight. Null if absent or unparseable.
+ * Parses `YYYY[-MM[-DD]]` with an optional `T`-or-space `HH:mm[:ss]`; a missing
+ * month/day is the period start (1) and a missing time is midnight — a
+ * reduced-precision value decodes rather than vanishing. Null if absent or
+ * unparseable.
  */
 function datetime(v) {
-    const m = /^(\d{4})-(\d{2})-(\d{2})(?:[ T](\d{2}):(\d{2}))?/.exec(text(v));
+    const m = /^(\d{4})(?:-(\d{2}))?(?:-(\d{2}))?(?:[ T](\d{2}):(\d{2}))?/.exec(text(v));
     if (!m)
         return null;
-    return new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3]), m[4] ? Number(m[4]) : 0, m[5] ? Number(m[5]) : 0);
+    return new Date(Number(m[1]), (m[2] ? Number(m[2]) : 1) - 1, m[3] ? Number(m[3]) : 1, m[4] ? Number(m[4]) : 0, m[5] ? Number(m[5]) : 0);
 }
 /** One `{ id, display }` object → ResolvedLink, or null if absent/malformed. */
 function asLink(v) {

package/docs/ai.md

@@ -130,7 +130,7 @@ Both truncation shapes emit the `app_agent_stream_truncated` analytics event (`k
 
 The poll is bounded at 22 minutes — deliberately PAST the server's 20-minute hard run cap, so a live run always settles before the client gives up. A row still `running` at the deadline means the run's process died mid-flight (e.g. a crash that skipped the server's shutdown drain); the poll surfaces an error and the server's reaper repairs the row. Only when no run id was ever received (the run never started) does the failure reject before any polling.
 
-On recovery, `output` adopts the row's output **only when it is an object** (a structured result) — the "`output` is never a stray string" rule holds on every path. A **free-text** run recovered from truncation keeps only the streamed prefix in `text`; read the full settled answer via `useAgentRuns(sessionId)` if you need it.
+On recovery, `output` adopts the row's output **only when it is an object** (a structured result) — the "`output` is never a stray string" rule holds on every path. A **free-text** run recovered from truncation keeps only the streamed prefix in `text`; the full settled answer is persisted server-side but is not currently client-readable (`useAgentRuns` can't reach it on any transport — see the limitation below), so treat the streamed prefix as terminal for now.
 
 ### Sessions
 

package/docs/data_fetching.md

@@ -228,7 +228,7 @@ Wire shapes per output column type:
 | `text` | `string` |
 | `number` | `number` (numeric database strings are normalized server-side; a rare decimal too precise for float64 stays a string — `row.num` parses both) |
 | `boolean` | `boolean` |
-| `date` | `"YYYY-MM-DD"` — a calendar day, no time component |
+| `date` | `"YYYY-MM-DD"` — a calendar day, no time component (a reduced-precision date field may also carry `"YYYY-MM"` or `"YYYY"`; see below) |
 | `datetime` | `"YYYY-MM-DDTHH:mm"` — workspace wall-clock, minute precision |
 | `select` | `Array<{ key, label }>` — one entry per selected option |
 | `select_member` | `Array<{ id, name, email? }>` — `email` only for authenticated viewers of the app's own org |
@@ -249,8 +249,8 @@ metadata. A grouped query collapses rows and emits none of these. Details:
 | `row.text(cell)` | any → `string` | strings pass through, finite numbers stringify, everything else → `""` |
 | `row.num(cell)` | any → `number` | numbers pass (NaN/Infinity → 0), parseable strings parse, everything else → `0` |
 | `row.bool(cell)` | any → `boolean` | `true` or the string `"true"`; everything else `false` |
-| `row.date(cell)` | date/datetime cell → `Date \| null` | the stored **calendar day** at LOCAL midnight — time stripped |
-| `row.datetime(cell)` | date/datetime cell → `Date \| null` | local `Date` **keeping the stored wall-clock** (minute precision; seconds are dropped); missing time = midnight |
+| `row.date(cell)` | date/datetime cell → `Date \| null` | the stored **calendar day** at LOCAL midnight — time stripped; a reduced-precision value decodes to its **period start** |
+| `row.datetime(cell)` | date/datetime cell → `Date \| null` | local `Date` **keeping the stored wall-clock** (minute precision; seconds are dropped); missing time = midnight; a reduced-precision value decodes to its **period start** |
 | `row.link(cell)` | link cell → `{ id, display } \| null` | the FIRST linked record |
 | `readLinks(cell)` | link cell → `{ id, display }[]` | ALL linked records (`[]` when empty) |
 | `readSelect(cell)` | select cell → `ResolvedOption[]` | all selected options as `{ key, label }` (`[]` when empty) |
@@ -262,7 +262,7 @@ All readers are pure (`unknown` in, value out), never throw, and return their em
 (`null` / `""` / `0` / `false` / `[]`) for absent or malformed input — so callers iterate and
 render without null-check pyramids.
 
-**`row.date` vs `row.datetime`.** `row.date` parses only the leading `YYYY-MM-DD` and builds a
+**`row.date` vs `row.datetime`.** `row.date` parses the leading `YYYY[-MM[-DD]]` and builds a
 LOCAL-midnight `Date` — calendar/gantt placement never shifts across viewer timezones. `row.datetime`
 keeps the stored wall-clock verbatim (no UTC conversion — the stored value is a timezone-less
 workspace wall-clock), so `getHours()` / `toLocaleTimeString()` render the time as written. A
@@ -270,6 +270,14 @@ workspace wall-clock), so `getHours()` / `toLocaleTimeString()` render the time
 and the UI prints `00:00`. When you need the time, the query must output the column as `datetime`
 (the type-override rules are in [./queries.md](./queries.md)).
 
+**Reduced-precision date values.** A `date` field may store an ISO 8601 truncated value —
+`"2026-05"` (month) or `"2026"` (year) — when a document carries only that precision. Both decoders
+resolve it to its **period start** (missing month/day → 1): `row.date("2026-05")` →
+May 1 2026 at local midnight, `row.date("2026")` → Jan 1 2026 — never `null`. For DISPLAY that
+respects the precision (show "05/2026", not "01/05/2026"), format with `@lotics/ui`'s `formatDate`
+on the raw cell string rather than the decoded `Date`. Sorting/filtering server-side already treats
+a partial as its period start.
+
 **`readSelect`.** A query **cell** carries `key` + `label` only — `color` comes from
 `useFieldOptions`, not the cell. An option deleted after the cell was written surfaces as
 `label === key` (the stale state is explicit, never hidden). Render with `@lotics/ui` `OptionBadge`

package/docs/mutations.md

@@ -128,12 +128,16 @@ A workflow body ends with `return({ status, message?, data? })`. `data` is arbit
 structured data (computed totals, row lists, status objects) the app reads back as
 `result.data`:
 
-- **Typed for free.** The alias's `outputs` schema is derived at save time from the inferred
-  TypeScript type of the body's `return({ data })` — the return *is* the declaration. Codegen
-  then types `result.data` per alias. Declare an explicit `outputs` on the alias (same
-  recursive vocabulary as inputs: scalars plus nested `object`/`array`, no member/file/
-  date_range) only to narrow beyond what's inferred; a shape the checker can't pin down
-  degrades to untyped `json`, never to a wrong schema.
+- **Typed for free — persisted at `set`.** The alias's `outputs` schema is derived at save
+  time from the inferred TypeScript type of the body's `return({ data })` — the return *is*
+  the declaration. When the manifest declared **no** `outputs`, `lotics app workflow set`
+  writes the server-derived schema into `package.json#lotics.workflows.<alias>.outputs` and
+  refreshes that alias's generated types in the same command, so `result.data` is typed
+  immediately — no hand-copy of the echoed schema, no second `lotics app codegen`. An
+  **explicitly declared** `outputs` is authoritative and never overwritten. Declare an explicit
+  `outputs` (same recursive vocabulary as inputs: scalars plus nested `object`/`array`, no
+  member/file/date_range) only to narrow beyond what's inferred; a shape the checker can't pin
+  down degrades to untyped `json`, never to a wrong schema.
 - **Validated at run.** On a success return, the returned `data` is validated against the
   schema at the app boundary — a mismatch resolves as `status: "error"` with a field-level
   message, so a declared output is a real contract. An *error* return's `data` passes through
@@ -173,7 +177,7 @@ Every declaration takes optional `description` and `required` (default **true**)
 | `date` | — | `"YYYY-MM-DD"`, or a TZ-bearing ISO datetime (projected to the workspace day) | `string` |
 | `datetime` | — | `"YYYY-MM-DDTHH:mm"` naive workspace wall-clock (what the platform DatePicker emits), or TZ-bearing ISO | `string` |
 | `email` | — | a valid email | `string` |
-| `select` | `options: [{label, value}]` (min 1), `multi?` | an option key (array when `multi`) | union of declared `value` literals; `ReadonlyArray<…>` when `multi` |
+| `select` | exactly one of `options: [{label, value}]` (min 1) **or** `field: "fld_…"`; `multi?` | an option key (array when `multi`) | union of the option `value`s (inline) or the field's current option keys (`field`); `ReadonlyArray<…>` when `multi` |
 | `record_link` | `table_id` (required), `multi?` | a record id — must exist **in the declared table** | `string` / `ReadonlyArray<string>` |
 | `member` | `group?`, `multi?` | a member id — with `group`, must belong to that group | `string` / `ReadonlyArray<string>` |
 | `file` | `multi?` | a file id from an upload — must live in the app's workspace | `string` / `ReadonlyArray<string>` |
@@ -209,12 +213,24 @@ When the alias declares `inputs`, the server validates the payload before the wo
   declared group; every `file` id must live in the app's workspace. These are real write-time
   constraints, not picker cosmetics — a hand-crafted request can't redirect the workflow.
   Rationale and the full caller-boundary model: [security](./security.md).
-- **`select` accepts any well-formed option key at runtime**, not only the deploy-declared
-  `options`. **Limitation:** the declared options are frozen into the codegen literal union,
-  so an option added to the live field after deploy is valid at runtime but fails the
-  compile-time type. Populate pickers from `useFieldOptions` (the live option set — see
-  [members_and_options](./members_and_options.md)) and widen or redeploy the declaration when
-  the type gets in the way.
+- **`select` names its option set one of two ways — declare exactly one (both or neither is a
+  set-time error).** *Inline* `options: [{label, value}]` freezes the set into the codegen
+  literal union and is **format-only at run time**: any well-formed key is accepted, and an
+  option added to the live field after deploy is valid at run time but fails the compile-time
+  type (widen or redeploy the declaration when the frozen union gets in the way).
+  *Field-referenced* `field: "fld_…"` (a select field's global key — `fld_…`, no table prefix)
+  is **drift-proof**: the union is resolved from the field's *current* options at type-gen, and
+  the submitted value is validated against the field's *current* options at run time — an option
+  added after authoring is accepted, a removed one rejected
+  (`select input "<path>" value "<v>" is not one of field "<key>"'s current options`) with no
+  redeploy. A `field` that doesn't exist or names a non-select field is rejected at bind time
+  (`lotics app workflow set` / `set_app_workflow`; `lotics app deploy` never binds workflows) with
+  `select input references field "<key>", which does not exist in this workspace` /
+  `… which is a <type> field, not a select`. Prefer `field` for any select backed by a real
+  field; keep `options` for a fixed enum the app owns or a select you plan to **package** — a
+  `field`-form select can't ride a package contract (it carries a concrete field id), so inline
+  the options before publishing. Populate pickers from `useFieldOptions` either way (the live
+  option set — see [members_and_options](./members_and_options.md)).
 
 If the alias declares **no** `inputs`, the payload passes through opaquely — no validation,
 no typing, no reference binding. Fine for a zero-input action; declare inputs for anything
@@ -254,6 +270,27 @@ if (i.title != null) {
 }
 ```
 
+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
+(untouched fields keep their lock / `before_update` / concurrent-edit safety — the diff-write
+discipline below, done in the body):
+
+```js
+const i = trigger.app_workflow.inputs;
+await update_records({
+  table_id: "tbl_items",
+  record_ids: [i.record_id],
+  set_skip_null: { fld_title: i.title, fld_status: i.status, fld_due: i.due }, // absent inputs drop out
+});
+```
+
+`set` still writes every key it carries — `null` in `set` **clears** the field; `null`/absent in
+`set_skip_null` **skips** it. That is the per-field "clear vs. leave unchanged" choice, so a field
+may appear in **at most one** of `set` / `set_skip_null` (naming it in both is rejected at run
+time). An all-absent `set_skip_null` with no other write surface is a no-op — no records touched,
+no `before_update` hooks.
+
 ## Refetch after a mutation
 
 Query hooks cache through SWR and know nothing about your workflows — a successful mutation
@@ -281,9 +318,9 @@ in place of an explicit refetch after a write the user is watching for.
 
 An edit form snapshots the record's values when it loads, and on save sends **only the fields
 the user actually changed** to its update workflow. Declare each updatable input
-`required: false`; an omitted input means "not written" (the body guards each write as shown
-above). "Changed" is decided at the edit surface that loaded the before-state — compare
-against the load-time snapshot, not against a re-fetch.
+`required: false`; an omitted input means "not written" (the body guards each write — or hands
+them to `set_skip_null` — as shown above). "Changed" is decided at the edit surface that loaded
+the before-state — compare against the load-time snapshot, not against a re-fetch.
 
 Why a full-form snapshot save is a bug, not a style choice — three independent mechanisms:
 

package/package.json

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