@lotics/app-sdk 0.111.4 → 0.112.0

package/dist/mock.d.ts

@@ -7,8 +7,9 @@
  * `useFileUpload` is not mocked.
  */
 import type { QueryAggregate } from "./shared_types.js";
-import type { UploadedFile, WorkflowResult } from "./hooks.js";
+import type { WorkflowResult } from "./hooks.js";
 import type { MockAgent } from "./mock_agent_run.js";
+import type { ExportedFile } from "./shared_types.js";
 import type { ExportCall, QuerySortKey } from "./queries.js";
 import type { RecordingState } from "./recording_state.js";
 /** A result, or a function of the inputs — return a slow promise to review the pending state. */
@@ -27,7 +28,7 @@ export type MockQuery = Array<Record<string, unknown>> | ((call: MockQueryCall)
 /** The file an export of a query makes, as a function of the call — return a slow promise to review the pending state. */
 export type MockExport = (call: ExportCall & {
     alias: string;
-}) => UploadedFile | Promise<UploadedFile>;
+}) => ExportedFile | Promise<ExportedFile>;
 export interface AppFixture {
     queries?: Record<string, MockQuery>;
     workflows?: Record<string, MockWorkflow>;

package/dist/queries.d.ts

@@ -1,8 +1,8 @@
 import type { QueryAggregate } from "./shared_types.js";
 import type { AppQueries, AppQueryColumns } from "./types.js";
 import type { ResolvedOption } from "./select.js";
-import type { UploadedFile } from "./hooks.js";
 import type { ReportLanguage } from "./shared_types.js";
+import type { ExportedFile } from "./shared_types.js";
 import type { ReportColumn, ReportReading } from "./shared_types.js";
 /**
  * One row of a query whose columns codegen could not read (a dynamic alias, a
@@ -234,9 +234,9 @@ export interface ExportCall {
 /**
  * Every row a declared query matches — narrowed by `filter` and ordered by `sort` as a page of it is — made into one
  * file by the server, so no row reaches the browser. Past the most rows one export holds it is refused, never cut.
- * Resolves the stored file, its URL signed for the caller.
+ * Resolves a link to download the file, signed for at most an hour.
  */
-export declare function exportQuery(alias: string, call: ExportCall): Promise<UploadedFile>;
+export declare function exportQuery(alias: string, call: ExportCall): Promise<ExportedFile>;
 /** One select column's full option set. */
 export interface FieldOptions {
     /** The source field's display name. */

package/dist/shared_types.d.ts

@@ -3,17 +3,81 @@
  * `scripts/build_sdk.mjs`, because that package is private and ships in no
  * tarball. Written at every build, never edited.
  */
-export type QueryAggregate = { by?: readonly string[]; day?: string; sum?: string; };
-export type ReportColumn = { key: string; header: string; type: "number" | "text" | "date"; labels?: { readonly [x: string]: string; }; };
+/** The file an app export made, as a link to download it: no workspace file, so no id, and kept a day. */
+export type ExportedFile = {
+  filename: string;
+  mime_type: string;
+  /** Signed for at most an hour, for the caller who exported. */
+  url: string;
+  /** Bytes. */
+  size: number;
+  /** When the server made it, ISO 8601. */
+  created_at: string;
+};
+/** What an aggregate asks: output columns to group by, an output date grouped by its day, an output number summed. */
+export type QueryAggregate = {
+  by?: readonly string[];
+  day?: string;
+  sum?: string;
+};
+export type ReportColumn = {
+  /** Each row's cell by it. */
+  key: string;
+  header: string;
+  /** A `date` cell is an ISO day or moment. */
+  type: "number" | "text" | "date";
+  /** A select whose cells hold bare option keys, no field of the query naming them: the words each key prints as. */
+  labels?: { readonly [x: string]: string; };
+};
 export type ReportLanguage = "vi" | "en";
-export type ReportPart = { label: string; value: number; share: number | null; };
-export type ReportPivotColumn = { label: string; total: number | null; };
-export type ReportPivotRow = { label: string; values: number[]; total: number | null; };
-export type ReportPoint = { label: string; value: number; partial: boolean; };
+export type ReportPart = {
+  label: string;
+  value: number;
+  /** Its share of the whole, 0–1; none where the whole is unknown or nothing. */
+  share: number | null;
+};
+export type ReportPivotColumn = {
+  label: string;
+  total: number | null;
+};
+export type ReportPivotRow = {
+  label: string;
+  /** Its figure under every column, in their order. */
+  values: number[];
+  total: number | null;
+};
+export type ReportPoint = {
+  /** The period as its axis names it. */
+  label: string;
+  value: number;
+  /** Still running, or cut by the window's edge. */
+  partial: boolean;
+};
 export type ReportReading = (ReportReadingHead & { kind: "metric"; value: number | null; }) | (ReportReadingHead & { kind: "breakdown"; byLabel: string; parts: ReportPart[]; total: number | null; }) | (ReportReadingHead & { kind: "trend"; points: ReportPoint[]; }) | (ReportReadingHead & { kind: "pivot"; rowsLabel: string; columnsLabel: string; columns: ReportPivotColumn[]; rows: ReportPivotRow[]; total: number | null; }) | { kind: "failed"; label: string; };
-export type ReportReadingHead = { label: string; valueLabel: string; unit: string | null; truncated: boolean; };
+/** What every reading of numbers states beside its figures. */
+export type ReportReadingHead = {
+  label: string;
+  /** What its figures are: the summed field's name, or a count's word. */
+  valueLabel: string;
+  /** The unit or currency its figures read in; none for a count or a plain number. */
+  unit: string | null;
+  /** The read behind it was cut: its figures stand, every total over them is left out (`null`). */
+  truncated: boolean;
+};
 export type TableField = { key: string; name: string; description: string; type: "number"; format: "number" | "currency" | "percentage"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; currency?: string | null | undefined; unit?: string | null | undefined; unit_field?: string | null | undefined; currency_field?: string | null | undefined; default_value?: number | null | undefined; } | { key: string; name: string; description: string; type: "text"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; unique?: boolean | undefined; format?: "text" | "link" | "markdown" | undefined; default_value?: string | null | undefined; } | { key: string; name: string; description: string; type: "date"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; format?: "date" | "datetime" | "date_range" | "datetime_range" | undefined; timezone?: string | undefined; derive_from?: "created_at" | "updated_at" | undefined; default_value?: string | null | undefined; } | { key: string; name: string; description: string; type: "boolean"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; default_value?: boolean | null | undefined; } | { key: string; name: string; description: string; type: "select"; options: { key: string; name: string; color: "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone"; mark?: { kind: string; name: string; } | undefined; }[]; confirm_before_update?: boolean | undefined; required?: boolean | undefined; multi?: boolean | undefined; default_value?: string[] | null | undefined; } | { key: string; name: string; description: string; type: "select_member"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; multi?: boolean | undefined; default_value?: string[] | null | undefined; } | { key: string; name: string; description: string; type: "select_record_link"; table_id: string; display_field_keys: string[]; confirm_before_update?: boolean | undefined; required?: boolean | undefined; display_field_widths?: Record<string, number> | undefined; paired_field_key?: string | undefined; cardinality?: "one" | "many" | undefined; } | { key: string; name: string; description: string; type: "rollup"; source_field_key: string; aggregate_option: { operation: "count"; field_key?: string | undefined; } | { operation: "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique"; field_key: string; } | { operation: "min" | "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "sum" | "avg" | "median" | "max" | "range"; field_key: string; } | { operation: "unique" | "date_range" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "earliest" | "latest"; field_key: string; } | { operation: "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "selected"; field_key: string; } | { operation: "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "selected"; field_key: string; } | { operation: "empty" | "filled" | "percent_empty" | "percent_filled" | "selected"; field_key: string; } | { operation: "checked" | "unchecked" | "percent_checked" | "percent_unchecked"; field_key: string; } | { operation: "empty" | "filled" | "percent_empty" | "percent_filled" | "selected"; field_key: string; } | { operation: "min" | "unique" | "date_range" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "sum" | "avg" | "median" | "max" | "range" | "earliest" | "latest" | "checked" | "unchecked" | "percent_checked" | "percent_unchecked"; field_key: string; } | { operation: "min" | "unique" | "date_range" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "sum" | "avg" | "median" | "max" | "range" | "earliest" | "latest"; field_key: string; }; confirm_before_update?: boolean | undefined; required?: boolean | undefined; filter?: TableRecordFiltersGroupNode | undefined; aggregate_field_type?: "number" | "boolean" | "text" | "date" | "select" | "select_member" | "select_record_link" | "rollup" | "files" | "formula" | "lookup" | "button" | "autonumber" | undefined; aggregate_field_format?: string | undefined; aggregate_field_currency?: string | undefined; aggregate_field_unit?: string | undefined; aggregate_field_unit_field?: string | undefined; aggregate_field_currency_field?: string | undefined; } | { key: string; name: string; description: string; type: "lookup"; source_field_key: string; lookup_field_key: string; confirm_before_update?: boolean | undefined; required?: boolean | undefined; lookup_field_type?: "number" | "boolean" | "text" | "date" | "select" | "select_member" | "select_record_link" | "rollup" | "files" | "formula" | "lookup" | "button" | "autonumber" | undefined; lookup_field_format?: string | undefined; lookup_field_currency?: string | undefined; lookup_field_unit?: string | undefined; lookup_field_options?: { key: string; name: string; color?: string | undefined; mark?: { kind: string; name: string; } | undefined; }[] | undefined; order_by?: { field_key: string; direction: "asc" | "desc"; } | undefined; } | { key: string; name: string; description: string; type: "files"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; } | { key: string; name: string; description: string; type: "formula"; formula: { expression: string; format?: "number" | "currency" | "percentage" | "link" | undefined; currency?: string | undefined; unit?: string | undefined; unit_field?: string | undefined; currency_field?: string | undefined; options?: { key: string; name: string; color: "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone"; mark?: { kind: string; name: string; } | undefined; }[] | undefined; output_type?: "number" | "boolean" | "text" | "date" | "datetime" | "select" | undefined; volatile?: boolean | undefined; }; confirm_before_update?: boolean | undefined; required?: boolean | undefined; } | { key: string; name: string; description: string; type: "button"; text: string; confirm_before_update?: boolean | undefined; required?: boolean | undefined; workflow_id?: string | null | undefined; } | { key: string; name: string; description: string; type: "autonumber"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; prefix?: string | undefined; padding?: number | undefined; template?: string | undefined; };
 export type TableRecordFilters = TableRecordFiltersConditionNode | TableRecordFiltersTraversalNode | TableRecordFiltersGroupNode;
 export type TableRecordFiltersConditionNode = { node_type: "condition"; field_key?: string | undefined; type?: string | undefined; operator: string; value?: unknown; unit_option?: string | undefined; };
 export type TableRecordFiltersGroupNode = { node_type: "group"; logic: "and" | "or"; children: (TableRecordFilters)[]; };
+/**
+ * Traversal node — filter the current table by a field on a record reachable
+ * through one or more `select_record_link` hops. ANY semantics: a row matches
+ * if at least one reachable record satisfies the inner condition.
+ *
+ * - `path`: the link field keys to walk, in order. Last entry must be a
+ *   `select_record_link` field; all entries must be link fields.
+ * - `condition`: the standard field-condition shape, evaluated on the FINAL
+ *   table reached by the path.
+ *
+ * Max path depth and inner-condition syntax are validated by `validateFilters`.
+ */
 export type TableRecordFiltersTraversalNode = { node_type: "traversal"; path: string[]; condition: TableRecordFiltersConditionNode; };

package/docs/data_fetching.md

@@ -24,7 +24,7 @@ untyped. It is written from the app's live bindings by `lotics app create --cust
 | `useQuery(alias, params?, { rows: false, total: true })` | `total` only, no rows (`total: { by: column }` or `total: { where: { name: filter } }` adds `counts`) | a facet chip, a queue badge, an "N awaiting approval" tile — the size of a set you are not listing |
 | `useQueries(calls, opts?)` | one state per `{ alias, params?, filter?, sort?, aggregate?, total?, rows? }`, in order — a `sort` orders that call's rows before the cap cuts them | reads that are DATA — a list known only at render, one read per item, or one count per stage (`rows: false, total: true`, each state's `.total`); the deploy's alias scan reads a list as dynamic, so every alias in it is still declared. With `aggregate` a call answers the groups of its filtered rows instead of the rows ([queries](./queries.md)) |
 | `queryAll(alias, params?, { filter, sort })` | a promise of every row | outside React, for a job that must hold the whole narrowed set in the browser (the ids an act runs on): it asks page after page until the server says the set ended, never stopping at the 10,000-row cap. The server's rows as stored — no write of this app is drawn over them |
-| `exportQuery(alias, { params, filter, sort, tabs?, report, file })` | a promise of the file | every row the narrowed set holds, made into one file by the server — no row reaches the browser. `tabs` (2 to 5, each `{ tab, label, filter?, sort? }`) are each read as the export's own rows are — same query and params, under the tab's own filter and sort (absent, the declared order) — and a template reads each one's rows under its `tab`, a name none of the report's keys nor the template's `rows` key holds. `report` is `{ title, lines, readings, dates?, period?, per?, filename? }` — `dates` each date filter's `{ from?, to? }` by field alias, each bound a day (`yyyy-MM-dd`) or a minute of one (`yyyy-MM-ddTHH:mm`) with no zone; `period` the tabs' `{ from, to }`, bounds of the same form; `per` the value the report was picked for, in the reader's words; `filename` the file's name in the template grammar over one value each — `title`, `at` (the moment the server made the file), `dates.<field>.from` or `.to`, `period.from` or `.to`, `per`, `lines | lookup:<n>` — at most 200 bytes once filled (absent, the template's name, or `title`); `file` is `{ kind: "workbook", language, sheet, columns }` (the default report workbook, its head closing with the moment the server made it, each column `{ key, header, type, labels? }` an output column of the query — a `number` one on a number column, a `date` one on a date or datetime; `labels` the words each bare option key of a `select` column no field names prints as, refused on any other column and for a key it lacks; with `tabs`, one sheet per tab named by its `label` in place of `sheet`) or `{ kind: "template", template }`, one the query declares under `templates` by name ([queries](./queries.md)). Past 20,000 rows, in any tab, it rejects, never cuts; each caller makes at most 60 exports a minute. The file's `url` is signed for the caller: open it with `openExternal` |
+| `exportQuery(alias, { params, filter, sort, tabs?, report, file })` | a promise of an `ExportedFile`: `{ filename, mime_type, url, size, created_at }` | every row the narrowed set holds, made into one file by the server — no row reaches the browser. `tabs` (2 to 5, each `{ tab, label, filter?, sort? }`) are each read as the export's own rows are — same query and params, under the tab's own filter and sort (absent, the declared order) — and a template reads each one's rows under its `tab`, a name none of the report's keys nor the template's `rows` key holds. `report` is `{ title, lines, readings, dates?, period?, per?, filename? }` — `dates` each date filter's `{ from?, to? }` by field alias, each bound a day (`yyyy-MM-dd`) or a minute of one (`yyyy-MM-ddTHH:mm`) with no zone; `period` the tabs' `{ from, to }`, bounds of the same form; `per` the value the report was picked for, in the reader's words; `filename` the file's name in the template grammar over one value each — `title`, `at` (the moment the server made the file), `dates.<field>.from` or `.to`, `period.from` or `.to`, `per`, `lines | lookup:<n>` — at most 200 bytes once filled (absent, the template's name, or `title`); `file` is `{ kind: "workbook", language, sheet, columns }` (the default report workbook, its head closing with the moment the server made it, each column `{ key, header, type, labels? }` an output column of the query — a `number` one on a number column, a `date` one on a date or datetime; `labels` the words each bare option key of a `select` column no field names prints as, refused on any other column and for a key it lacks; with `tabs`, one sheet per tab named by its `label` in place of `sheet`) or `{ kind: "template", template }`, one the query declares under `templates` by name ([queries](./queries.md)). Past 20,000 rows, in any tab, it rejects, never cuts; each caller makes at most 60 exports a minute. The file has no `id` — it is a download, not a workspace file a workflow or a field takes: its `url` is signed for the caller for at most an hour, so open it with `openExternal` when the promise resolves; the server deletes the file a day after it is made |
 
 Every hook answers the same `QueryState`: `rows`, `truncated`, `total`, `counts`, `loading`,
 `isValidating`, `error`, `pending`, `refetch`, `page`, `setPage`, `pageCount`, `hasMore`,
@@ -151,7 +151,8 @@ write it as `{ node_type: "condition", type: "record_id", operator, value }`.
   `refetch()` covers what none of those can know about.
 - **This app's own writes show from the press.** Every read draws each write this app has made
   over its rows before the server answers — cells, membership, new rows, `total`, `counts` and
-  groups — and says **`pending`** while what one changes is not all drawn. Nothing to wire: [./mutations.md](./mutations.md)
+  groups — and says **`pending`** while what one changes is not all drawn. A visitor from outside
+  your organization sees each write when the server answers instead. Nothing to wire: [./mutations.md](./mutations.md)
   § A write shows from the press.
 - **Realtime push keeps an already-open screen current.** When a table one of your queries reads
   changes — another member, a workflow, the chat agent, or an external agent writing over the CLI or

package/docs/files.md

@@ -32,7 +32,9 @@ storage, size and upload day), which is inert like an upload until a save puts i
 place. A save carrying `_added` and `_removed` of one field puts the added file where the removed
 one stood, so a rename or a replace keeps its position. The name keeps the file's extension
 exactly — `"scan.pdf"` → `"Invoice 9.pdf"`; `.html` is refused — and holds no `/`, `\` or control
-character. Offer it only where the app writes that field: the save is what may be refused.
+character. Offer it only where the app writes that field: the save is what may be refused. A
+visitor from outside your organization may rename only a file uploaded through this app, within
+twenty minutes of that upload starting; any other file answers as a missing one.
 
 ## Uploading — `useFileUpload`
 
@@ -96,9 +98,10 @@ to object storage → finalize. The API server never proxies the bytes.
 - **Transport resilience.** The storage `PUT` has a 5-minute per-request timeout and retries
   network errors / timeouts / 5xx up to 3 attempts with 1 s → 2 s backoff between attempts. 4xx
   responses are terminal (no retry). The presigned upload URL itself is valid for 10 minutes.
-- **Server-side verification.** The finalize step verifies the actually-stored object: an object
-  larger than the limit (or of unverifiable size) is rejected **and its bytes deleted** — the
-  file record is never created.
+- **Server-side verification.** The finalize step takes only the upload this app minted the URL
+  for, and verifies the actually-stored object: an object larger than the size declared when its
+  URL was minted (or of unverifiable size) is rejected **and its bytes deleted** — the file record
+  is never created.
 
 ### Upload limits
 

package/docs/mutations.md

@@ -188,8 +188,9 @@ envelope's grammar — `message` is required, `field_errors` never reaches the a
   redeploy); use inline `options` for a fixed enum the app owns.
 - **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
-  unvalidated.
+  message, so a declared output is a real contract. A visitor from outside your organization reads
+  the generic sentence a failed run gives them instead, since the message names the keys the body
+  returned. An *error* return's `data` passes through unvalidated.
 - **An output field marked `required: false` types as `key?: T | null`.** The derivation
   collapses "may be absent" and "may be null" into that one flag, so the generated type admits
   both — narrow with `!= null`, never with a bare truthiness check on a number or a string.
@@ -327,8 +328,9 @@ const onClose = async (recordId: string) => {
 ```
 
 Only on **success**: a refused write changed nothing. A body that names a table only at run time,
-a run whose writes could not be predicted, a run before the app's write model has loaded, and a
-`useAgentRun` leg that lands, re-read every mounted query. A comment written or deleted re-reads
+a run whose writes could not be predicted, a run before the app's write model has loaded, a run
+by a visitor from outside your organization, and a `useAgentRun` leg that lands, re-read every
+mounted query. A comment written or deleted re-reads
 every `useCommentCounts`. Under a design-time
 fixture every mounted read re-reads, since a fixture has no body to read tables from. The host's
 realtime push is separate: it carries changes **other** people make, and is far too slow for your
@@ -554,8 +556,11 @@ What the steps cannot tell before they run is never guessed:
   delete: every read over the tables it may touch (every read, where it names none) is `pending`
   until the answer lands.
 - A guard (`validate`, a `return` with `status: "error"`) it can decide over held rows: a refused
-  write draws nothing. One it cannot decide is assumed to pass — the server is the authority, and
-  a refusal takes the drawing back.
+  write draws nothing, and neither does one whose `validate` check throws on those rows, since the
+  server refuses that write too. One over a value the app does not hold is assumed to pass — the
+  server is the authority, and a refusal takes the drawing back.
+- A prediction that takes more than a second: the run is sent without it, and its writes wait for
+  the answer — predicting never holds a press back longer than that.
 - A guard or branch comparing an input with a constant (`i.code == "VIP"`) never reaches the app:
   the constant would be shown to everyone who can open it. The guard is assumed to pass, and the
   branch's writes wait for the answer. A comparison with a held row's cell reaches it.
@@ -564,6 +569,11 @@ Every read hook returns **`pending`**: a write this app made is in flight over i
 landed with part of what it changes not yet read back. The rows already show what is known; use it
 for a quiet "saving" cue, never to hide the rows.
 
+**A visitor from outside your organization sees a write when the server answers.** For anyone who
+opens the app through its public link rather than access of their own, nothing is drawn ahead and
+no read's `pending` turns on: each write shows once its run answers, so a press that needs a cue
+before then takes it from the awaited result.
+
 **A create gets its id before the server answers.** Every row a `create_records` makes without
 `ids` is drawn under a `rec_*` the SDK mints, and the run carries those ids to the server, which
 stores each row under the one drawn for it — so the row drawn from the press is the row the server

package/docs/queries.md

@@ -477,7 +477,7 @@ derived surfaces share one implementation.
 | select_member | `select_member` | select ops + `is_current_member`, `is_not_current_member` (field-scoped, no value; `is_not_current_member` matches every cell not holding the requester, an empty one included) | same — `is_current_member` **works at the runtime layer** too | `unnest` fans member ids. Anonymous public request: current-member binds the app owner (§1). |
 | select_record_link | `select_record_link` | membership by linked-record **id**: `has_any_of`, `has_none_of`, `has_all_of`; text over the cached **display**: `contains`, `not_contains`, `starts_with`, `ends_with`; `is_empty`, `is_not_empty` | same — id-membership works at the runtime layer (converged `[{id}]` containment) | Sorting orders by raw JSON, not display text — project the display (link extraction / `display_output`) and sort that. `unnest` fans link ids (+ display). |
 | files | `files` | `has_filename`, `has_mime_type` (substring), `has_file_count` (exact count), `is_empty`, `is_not_empty` | same | Presign-enriched at delivery (§1); `unnest` fans file ids. Only presence-counting aggregates. |
-| formula | its declared output type (`number`/`text`/`boolean`/`date`/`datetime`, or `select` for one stating its own options, its cell a single select's; `json` until inferred) | filtered by the output type's operators; `#ERROR:` cells are guarded — they count as empty and never match value operators | same | Extracted as a real scalar, so numeric formulas feed `sum`/`avg`/sorts. A **datetime-output** formula matches day-level date filters (full-day expansion). |
+| formula | its declared output type (`number`/`text`/`boolean`/`date`/`datetime`, or `select` for one stating its own options, its cell a single select's; `json` until inferred) | filtered by the output type's operators; a cell holding an error (`#ERROR: …`) holds no value — it projects as `null` whatever the output type, and matches what an empty cell matches (`is_empty`, a negation such as `not_equals`) and nothing that needs a value | same | Extracted as a real scalar, so numeric formulas feed `sum`/`avg`/sorts. A **datetime-output** formula matches day-level date filters (full-day expansion). |
 | rollup | decided by the OPERATION, never by the aggregated field: `earliest`/`latest` → `date`/`datetime` per that field's format; **every** other op → `number` | number or date operators per output type; text operators route as text | same | Datetime-format rollups match day-level date filters. `date_range` counts DAYS between the extremes, so it is a number despite its date input. A presence count (`filled`/`empty`/`percent_*`) is a number whatever it counts — including over `files`. |
 | lookup | the type of the VALUE the looked-up field yields — a formula's output type, a rollup's operation result, an autonumber's display string (`text`); never the word `formula`/`rollup` | operators of that type, evaluated with ANY-element semantics over the linked values (a row matches if *any* linked value matches) | array-typed lookups follow their column type's rules | **Projection returns the first element only.** Emptiness on a files-lookup checks the inner file arrays (a linked record with zero files counts empty). For all values across links: unnest the link column + join (§8). |
 | autonumber | `text` | text operators — filter by the visible composed string (`"ORD-0042"`) | same | Sorts numerically when the stored value is a bare integer, lexicographically otherwise — so `"ORD-0042"` orders by its padding and an unprefixed `"124"` orders after `"99"`, not before it. |
@@ -569,8 +569,10 @@ axes from ONE named query — don't shard into a query-per-combination. Mark eac
 `required: false`; the server **prunes every filter condition (or traversal) whose
 `{{params.x}}` the caller didn't pass** — then collapses emptied groups — so an unset axis
 stops constraining instead of erroring. A param passed empty (`""`, `[]`, `null`) counts as not
-passed. A REQUIRED param passed empty is refused (400, naming the condition it feeds) when a
-filter reads it.
+passed, and so does one that leaves a search with no word once trimmed and accent-folded (`" "`,
+a lone accent): the condition or `from_table.search` it fills prunes. A REQUIRED param passed
+either way is refused (400, naming the condition or the search it feeds — to a caller outside the
+app's organization, the param alone).
 
 ```jsonc
 "search": {
@@ -633,8 +635,9 @@ index that is:
 - multi-term: the query splits on whitespace (max 10 terms), all terms must match (AND).
 
 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": "{{params.q}}"`). A term with no word once trimmed and accent-folded matches
+everything: an optional param that leaves one, or is not passed, prunes the search to match-all;
+a required one is refused (§6).
 
 **Search-as-you-type over a LARGE table uses `search`, never a `contains` OR-group alone.** Per-field
 `contains` is unindexed — a zero-match keystroke forces a full-table scan that hangs the

package/docs/runtime.md

@@ -78,7 +78,7 @@ returns a promise: the read stays loading until it settles, to review a pending
 the fixture nothing, as it asks the server nothing. **Partial mocking is
 supported**: an alias absent from the fixture still flows through the real
 transport. `fixture.exports[alias]` answers `exportQuery(alias, call)` — a
-function of the call returning the file, or a promise of it to review the
+function of the call returning an `ExportedFile`, or a promise of one to review the
 pending state. Calling `mount` again (HMR) replaces the registration last-write-wins.
 
 - **Fixture rows stand in for wire rows.** They pass through the same code path

package/docs/workflows.md

@@ -245,7 +245,9 @@ validate({ checks: [{
 
 `fail_when` rejects when truthy. A failing check ends the run as `status: "error"` with the
 failing messages joined — cleanly, not as a crash: it is control flow, so **`try`/`catch` does
-not catch it** (nor `return`).
+not catch it** (nor `return`). A check that throws instead of answering — its `fail_when` or its
+`message` — refuses the write too: the run fails with a message naming the step and the check's
+index and nothing the check read, and `try`/`catch` does not catch that either.
 
 `field_key` is optional, a string literal, and carries the same key `return({ field_errors })`
 does: **the control the message belongs to, on the surface that renders it**. Each failing check
@@ -341,10 +343,11 @@ try {
 ```
 
 `e` is shaped `{ message, type, step_id?, detail? }`. Caught: tool errors and expression errors
-thrown inside the body. **Not caught:** `validate` failures and `return` (control flow), and
-errors from steps that run on *resume* after a `wait` inside the body — the wrapper spans one
-execution pass. There is no `finally`: put always-run steps after the `try`, always-on-failure
-steps in the `catch`.
+thrown inside the body. **Not caught:** `validate` failures — a check that throws included — and
+`return` (control flow), the run's own bounds (its time, its step count, and the node and 512 MB
+bounds in *Traps*), and errors from steps that run on *resume* after a `wait` inside the body —
+the wrapper spans one execution pass. There is no `finally`: put always-run steps after the `try`,
+always-on-failure steps in the `catch`.
 
 ### Loops
 
@@ -819,6 +822,16 @@ The rules that are easy to get wrong because the failing code looks correct.
   `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.
+- **Expressions are bounded.** A helper that builds an array — `range`, `list`, `flatten`,
+  `concat` of arrays, `split`'s parts — makes at most 100,000 elements, and a callback helper
+  takes an array of at most 100,000. `join`, `replaceAll`, `padStart`, `padEnd`, `toString`,
+  `toJson` and a template string write at most 10,000,000 characters; `randomNumber` /
+  `randomAlphaNumeric` take a length of at most 1,000. Past one of those the call throws an
+  expression error, which `try`/`catch` catches, and so does a step whose result would take what
+  the run keeps past 67,108,864 characters of JSON. One evaluation runs at most 20,000,000 nodes —
+  a callback nested in another runs once per pair of elements — and the run's expressions build at
+  most 512 MB of arrays, objects and text in all, every temporary counted: past either, the run
+  fails whatever catches it. Build long text with `join`, never a fold of `+`.
 
 ## The bright line
 
@@ -886,7 +899,10 @@ check's message joined with `"; "`, and one `field_errors` entry per failing che
 **A rehearsal can stop early, and it says so in `evaluation_errors`.** Four bounds apply — 1 000
 iterations of a `while` / `do_while` / `c_for`, 10 000 steps, 50 live reads, and 20 seconds — and
 tripping any of them appends an entry naming the bound and ending "the plan below is incomplete",
-then stops. So read `evaluation_errors` before reading `planned_calls`: an entry there may be a
+then stops. It also stops, with an entry saying why, where the live run would fail: at a
+`validate` check that throws, an evaluation past the run's node or 512 MB bound (*Traps*), or a
+return too long to write.
+So read `evaluation_errors` before reading `planned_calls`: an entry there may be a
 truncated plan rather than a bug in your body. A `foreach` is deliberately NOT capped at 1 000 —
 its length is known before the first iteration, so the rehearsal walks every item and instead
 refuses, up front, exactly the lists a live run refuses (over 10 000 items). The 50-live-read bound

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.111.4",
+  "version": "0.112.0",
   "description": "The SDK a Lotics custom-code app reads and writes through \u2014 typed hooks over the host bridge, cell readers, mount() and AppRouter",
   "type": "module",
   "exports": {