@lotics/app-sdk 0.90.3 → 0.91.1

package/AGENTS.md

@@ -16,15 +16,15 @@ signature; open the file.**
 |---|---|
 | [docs/recipes.md](./docs/recipes.md) | Task-shaped how-tos for the actions whose mechanism is not guessable from the hooks — returning a generated file, returning structured data, parameterized lookups, composable optional filters, cell decoding, testing an AI action without spending credits. |
 | [docs/queries.md](./docs/queries.md) | **The query engine authoring reference** — AST node kinds, per-field-type operator support, filters/params/pruning, free-text search, combining tables (join/union/link/`unnest`/`record_id`), shaping (aggregates, date buckets, windows), runtime refinement bounds, limits & the efficiency playbook. |
-| [docs/data_fetching.md](./docs/data_fetching.md) | The four read hooks (`useQuery`/`useInfiniteQuery`/`usePaginatedQuery`/`useCount` — the last for a number with no rows, sharing the `(alias, params, filter)` count key the paginated hook uses, so a list and a badge over one set buy one count; a count is a full scan and stays its OWN request so rows paint without waiting for it, and `rows.length` is never a count since rows truncate silently at 10,000), the `QueryRow` shape (projected columns `unknown`; `__source_record_id`/`__source_table_id` typed but optional), runtime `sort`/`filter` keys typed against the query's own projection (`AppQueryColumns`, `ColumnKeyOf`), cell readers (`row.*`, `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`), `useFieldOptions`, caching — **arrival revalidates** (a re-mount renders cache *and* refreshes it in the background, `loading` never flips) — **realtime push** (a table one of your queries reads changes and that query refetches within about a second, alias-precise, records-only, host-embedded apps only) — and the fourth source, **this app's own successful write**, which re-reads every mounted query immediately rather than waiting on that push (→ [mutations](./docs/mutations.md)), data discipline, the pagination count as a second full execution (and `total` to suppress it), the search-as-you-type + record-picker patterns. |
-| [docs/mutations.md](./docs/mutations.md) | `useWorkflow` (the ONLY write path), the `WorkflowResult` resolve-never-throw contract, typed inputs, the automatic re-read a SUCCESSFUL write triggers over every mounted query (so a screen never waits on the host push to see its own write), diff-before-update, locked records, `useOptimistic`, `useNewRecord` (client-minted `rec_*` id so a new-record surface never remounts on its first save), read-after-write ordering (a re-read must not overtake an in-flight write). |
+| [docs/data_fetching.md](./docs/data_fetching.md) | The four read hooks (`useQuery`/`useInfiniteQuery`/`usePaginatedQuery`/`useCount` — the last for a number with no rows, sharing the `(alias, params, filter)` count key the paginated hook uses, so a list and a badge over one set buy one count; a count is a full scan and stays its OWN request so rows paint without waiting for it, and `rows.length` is never a count since rows truncate at 10,000 — `useQuery` says so with `truncated`), the `QueryRow` shape (projected columns `unknown`; `__source_record_id`/`__source_table_id` typed but optional), runtime `sort`/`filter` keys typed against the query's own projection (`AppQueryColumns`, `ColumnKeyOf`), cell readers (`row.*` — `row.num` answers `null` for an EMPTY cell, so none is distinguishable from zero — `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`, and `readCreatedAt`/`readUpdatedAt` for the record timestamps every row-level result carries), `useFieldOptions`, caching — **arrival revalidates** (a re-mount renders cache *and* refreshes it in the background, `loading` never flips) — **realtime push** (a table one of your queries reads changes and that query refetches within about a second, alias-precise, records-only, host-embedded apps only) — and the fourth source, **this app's own successful write**, which re-reads every mounted query immediately rather than waiting on that push (→ [mutations](./docs/mutations.md)), data discipline, the pagination count as a second full execution (and `total` to suppress it), the search-as-you-type + record-picker patterns. |
+| [docs/mutations.md](./docs/mutations.md) | `useWorkflow` (the ONLY write path), the `WorkflowResult` resolve-never-throw contract (`field_errors` locates a refusal on the control it belongs to, where `message` can only say it at the dialog's scope), typed inputs, the automatic re-read a SUCCESSFUL write triggers over every mounted query (so a screen never waits on the host push to see its own write), diff-before-update, locked records, `useOptimistic`, `useNewRecord` (client-minted `rec_*` id so a new-record surface never remounts on its first save), read-after-write ordering (a re-read must not overtake an in-flight write). |
 | [docs/workflows.md](./docs/workflows.md) | **The workflow-BODY authoring reference** — the JS subset a `src/workflows/<alias>.ts` body may use: the parse-at-save/never-execute model, opaque `fld_*`/`opt_*` keys, expression sources + explicit `linked()` descent, every step form (tool call, `agent`, waits, `validate`, `return`), the accepted sugar and its canonical lowering, helpers + callback rules, record-write surfaces, the traps, the bright line, and the verify loop — `check` (the only local gate: the app's own `npm run typecheck` never sees a body) → `dry_run_workflow` (static green is not a run) → `set`. |
 | [docs/files.md](./docs/files.md) | Files end to end — `useFileUpload`, `useAttachments`, `readFiles`/presigned URLs (**a bearer credential for the bytes** — never logged, reported, or persisted), workflow-generated files, **naming a zip's entries** (`{ id, name }` per file — a file name, never a path), preview pairing, filter operators, the server-side delivery bounds. **Uploads declare a `fidelity`** (`standard` / `high` / `original`) — the app picks how much of the image survives storage; use `high` whenever text must stay legible. |
-| [docs/members_and_options.md](./docs/members_and_options.md) | People + select options + comments — `useMembers`, `useFieldOptions`, `useViewer`, `useComments`, and the `@lotics/ui` components they feed. |
+| [docs/members_and_options.md](./docs/members_and_options.md) | People + select options + comments — `useMembers`, `useFieldOptions`, `useViewer`, `useComments` (each comment carries its own resolved `author`, so a thread crossing a role boundary is legible without declaring member access), and the `@lotics/ui` components they feed. |
 | [docs/navigation_and_state.md](./docs/navigation_and_state.md) | `AppRouter` (embedded/standalone URL model), `useUrlState` + `urlParam` codecs, `useRecents`. |
 | [docs/ai.md](./docs/ai.md) | `useAgentRun` (structured vs free-text, streaming ai-sdk `parts` → `AgentRun`, the agent's ask-back — `pendingChoice`/`answerChoice` over the parked `awaiting_input` state — and the `AgentRunLanding` every leg resolves), `askAi` — plus the fields-vs-file razor for choosing between them — and `useAiContext` (push the current screen's view state to the member's ambient chat agent; caps, push-only semantics; a chat mutation refetches your queries through the realtime channel, not a separate poke). **A `file` input carries its own content** — no reader tool to declare. **An agent reaches record DATA only through its declared `query_aliases` / `workflow_aliases`.** Also **what the member's own chat agent can do with your app while it is open** — the alias catalog it reads and how to shape a mutating alias for it. |
 | [docs/security.md](./docs/security.md) | **Read before shipping** — the owner-principal model, `is_current_member` scoping, write attribution, group gates, public-app bounds, what runtime refinement cannot widen, and why a per-input bound is a tenancy floor rather than an authorization check (a caller-supplied id must be intersected with the record server-side). |
-| [docs/runtime.md](./docs/runtime.md) | `mount()`, the two transports, **the API address a standalone bundle reads out of its own page** (`<meta name="lotics-api-base">`, declared by whatever serves the app — no address is compiled into the SDK, so one bundle runs on any instance and a page without it refuses rather than guessing), `rpc()`, the design-time mock harness (`fixture` + `?__mock=1` — queries AND workflows, so an AI screen's in-flight/done/error states are reviewable without running or paying for anything), `openExternal`/`openApp`/`downloadFile`, geofencing, and the publish chain for SDK contributors. |
+| [docs/runtime.md](./docs/runtime.md) | `mount()`, the two transports, **the API address a standalone bundle reads out of its own page** (`<meta name="lotics-api-base">`, declared by whatever serves the app — no address is compiled into the SDK, so one bundle runs on any instance and a page without it refuses rather than guessing), `rpc()`, the design-time mock harness (`fixture` + `?__mock=1` — queries AND workflows, so an AI screen's in-flight/done/error states are reviewable without running or paying for anything; a fixture is rows or a FUNCTION of the call, and only the function form reproduces a per-call `filter`), `openExternal`/`openApp`/`downloadFile`, geofencing, and the publish chain for SDK contributors. |
 
 ## Non-negotiables (each detailed in its doc)
 

package/dist/src/comments.d.ts

@@ -7,6 +7,14 @@ export interface AppCommentFile {
     thumbnail_url?: string;
     preview_url?: string;
 }
+/** A comment author's display identity, resolved server-side. */
+export interface AppCommentAuthor {
+    /** The member's display name. Null when the id no longer resolves in the org
+     *  (a removed member) — fall back explicitly, as with `readMembers`. */
+    name: string | null;
+    /** Presigned avatar URL, when the member has one. */
+    image?: string | null;
+}
 /** One record comment, as returned by the list op. */
 export interface AppComment {
     id: string;
@@ -14,6 +22,19 @@ export interface AppComment {
     table_id: string;
     /** The author's member id. */
     member_id: string;
+    /**
+     * The author's display identity, resolved server-side on EVERY comment the
+     * server returns — list, create and update alike — including one written from
+     * another app by someone the record references nowhere. A thread crossing a
+     * role boundary is legible without the app declaring member access it does not
+     * otherwise need.
+     *
+     * Optional for one reason only: the optimistic row `createComment` renders is
+     * built HERE, from a context that carries the viewer's id and not their name,
+     * and inventing a display identity for it would render as somebody. It is
+     * replaced by the server's row when the refetch lands.
+     */
+    author?: AppCommentAuthor;
     content: string;
     files: AppCommentFile[] | null;
     workspace_id: string;

package/dist/src/hooks.d.ts

@@ -62,6 +62,16 @@ interface QueryStateBase {
 /** Return value of `useQuery` — a single fetch, no pagination. */
 interface QueryState<R> extends QueryStateBase {
     rows: R[];
+    /**
+     * True when the limit cut the result — more rows matched than arrived, so
+     * `rows` is SHORT and anything folded from it (a total, a ratio, a KPI strip)
+     * is under-reported. Without it the cap is invisible: no error, no empty
+     * state, just numbers that look right.
+     *
+     * The limit is your `pageSize` when you set one and the server's row cap
+     * otherwise. False while loading and under a fixture.
+     */
+    truncated: boolean;
 }
 /** Return value of `useInfiniteQuery` — append/load-more. */
 interface InfiniteQueryState<R> extends QueryStateBase {
@@ -300,6 +310,14 @@ export interface WorkflowResult<TData = unknown> {
     message?: string;
     files?: UploadedFile[];
     data?: TData;
+    /**
+     * Per-input refusals the workflow returned via `return({ field_errors })`,
+     * keyed by the INPUT name it declares — what a form wires straight onto the
+     * control that is wrong (`<FormField error={result.field_errors?.ly_do}>`),
+     * where `message` can only say it at the dialog's scope. Absent when the
+     * workflow returned none.
+     */
+    field_errors?: Record<string, string>;
 }
 /**
  * The (params, opts) tail of a query hook for alias `K`: `params` optional when

package/dist/src/hooks.js

@@ -81,6 +81,25 @@ function swrConfig(revalidateOnFocus) {
         keepPreviousData: true,
     };
 }
+/**
+ * The fixture rows for this alias and this call, held STABLE across renders.
+ *
+ * A function fixture returns a fresh array each time it is called, and `rows` is
+ * handed straight to consumers — so without memoizing, a screen that derives
+ * anything from `rows` (a `useMemo`, an effect) re-runs on every render, and one
+ * that sets state from them never settles. Keyed exactly the way the real read
+ * is keyed, so a changed param/filter/sort re-asks the fixture and nothing else
+ * does.
+ */
+function useMockRows(alias, call) {
+    const key = JSON.stringify([call.params, call.filter ?? null, call.sort ?? null, call.limit ?? null]);
+    const { params, filter, sort, limit } = call;
+    return useMemo(() => getMockRows(alias, { params, filter, sort, limit }), 
+    // The KEY, not the object literal the caller rebuilt this render — a memo on
+    // the literal would be no memo at all.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [alias, key]);
+}
 /**
  * Refetch this query when the host reports that ITS tables changed — whoever
  * wrote them: another member, a workflow, the chat agent, or an external agent
@@ -140,7 +159,7 @@ export function useQuery(alias, params, opts) {
     const revalidateOnFocus = opts?.revalidateOnFocus ?? true;
     const sort = opts?.sort && opts.sort.length > 0 ? opts.sort : undefined;
     const filter = opts?.filter;
-    const mockRows = getMockRows(alias);
+    const mockRows = useMockRows(alias, { params: params ?? {}, filter, sort, limit: pageSize });
     // A `null` key disables the fetch (mock / disabled). SWR canonicalizes the
     // params/sort/filter objects via its stable hash, so identical reads dedupe to
     // one request + one cache entry that survives unmount/remount.
@@ -161,6 +180,9 @@ export function useQuery(alias, params, opts) {
     useHostRefetch(alias, refetch, mockRows);
     return {
         rows: mockRows ?? swr.data?.rows ?? [],
+        // A fixture IS the whole set, so it is never short; before the first
+        // response there is nothing to be short of.
+        truncated: mockRows || !swr.data ? false : swr.data.truncated,
         loading: mockRows ? false : swr.isLoading,
         isValidating: mockRows ? false : swr.isValidating,
         error: swr.error ? swr.error.message : null,
@@ -200,7 +222,7 @@ export function useInfiniteQuery(alias, params, opts) {
     const revalidateOnFocus = opts?.revalidateOnFocus ?? true;
     const sort = opts?.sort && opts.sort.length > 0 ? opts.sort : undefined;
     const filter = opts?.filter;
-    const mockRows = getMockRows(alias);
+    const mockRows = useMockRows(alias, { params: params ?? {}, filter, sort, limit: pageSize });
     // Keyset (seek) pagination: each page seeks past the previous page's
     // `next_cursor` instead of an increasing OFFSET, so deep scrolls stay O(page)
     // and never skip/duplicate a row as the set shifts. The cursor is opaque; the
@@ -244,7 +266,7 @@ export function useInfiniteQuery(alias, params, opts) {
     // operate on resolved pages only so a page being appended never crashes the
     // flatten or skews the counts.
     const pages = (swr.data ?? []).filter((p) => p != null);
-    const rows = mockRows ?? pages.flatMap((p) => p.rows ?? []);
+    const rows = mockRows ?? pages.flatMap((p) => p.rows);
     const lastPage = pages.length > 0 ? pages[pages.length - 1] : undefined;
     // A non-null next_cursor means another page exists; null/absent = the end.
     const hasMore = lastPage != null && lastPage.next_cursor != null;
@@ -275,7 +297,7 @@ export function usePaginatedQuery(alias, params, opts) {
     const revalidateOnFocus = opts?.revalidateOnFocus ?? true;
     const sort = opts?.sort && opts.sort.length > 0 ? opts.sort : undefined;
     const filter = opts?.filter;
-    const mockRows = getMockRows(alias);
+    const mockRows = useMockRows(alias, { params: params ?? {}, filter, sort, limit: pageSize });
     // `null` = the caller owns the total and it hasn't resolved; `undefined`
     // (or omitted) = the hook counts. See `PaginatedQueryOptions.total`.
     const suppliedTotal = opts?.total;
@@ -334,7 +356,7 @@ export function useCount(alias, params, opts) {
     const enabled = opts?.enabled ?? true;
     const revalidateOnFocus = opts?.revalidateOnFocus ?? true;
     const filter = opts?.filter;
-    const mockRows = getMockRows(alias);
+    const mockRows = useMockRows(alias, { params: params ?? {}, filter });
     // The SAME read `usePaginatedQuery` uses for its total — one definition, so a
     // list and a badge over one set can never drift into two scans.
     const countSwr = useCountRead(alias, params, filter, !mockRows && enabled, revalidateOnFocus);

package/dist/src/index.d.ts

@@ -18,7 +18,7 @@ export type { MountOptions } from "./mount.js";
 export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useCount, useFieldOptions, useFileUpload, useAttachments, useMembers, useAgentRun, useAgentRuns, useAiContext, buildChoiceOutput, } from "./hooks.js";
 export type { QueryRow, UploadedFile, AttachedFile, BaseQueryOptions, QueryOptions, InfiniteQueryOptions, PaginatedQueryOptions, CountOptions, ColumnKeyOf, QuerySortKey, QueryFilter, QueryFilterCondition, QueryFilterFieldCondition, QueryFilterRecordIdCondition, QueryFilterGroup, WorkflowResult, MembersOptions, AgentRunOptions, UseAgentRun, AgentRunLanding, AgentRunRecord, AgentRunState, AgentUIPart, PendingChoice, ChoiceQuestion, ChoiceOption, AskUserChoiceOutput, FieldOptions, FieldOptionsState, FieldOptionsOptions, } from "./hooks.js";
 export { useComments, useCommentCounts } from "./comments.js";
-export type { AppComment, AppCommentFile, CommentsState, UseCommentsArgs, CommentCountsState, UseCommentCountsArgs, } from "./comments.js";
+export type { AppComment, AppCommentAuthor, AppCommentFile, CommentsState, UseCommentsArgs, CommentCountsState, UseCommentCountsArgs, } from "./comments.js";
 export { useViewer } from "./viewer.js";
 export { requestGeofencedLocation, isWithinZone } from "./geolocation.js";
 export type { GeofenceZone, GeoCoords, GeofenceOutcome, GeofenceOptions } from "./geolocation.js";
@@ -32,9 +32,9 @@ export { readMembers } from "./members.js";
 export type { ResolvedMember } from "./members.js";
 export { readSelect } from "./select.js";
 export type { ResolvedOption } from "./select.js";
-export type { AppFixture } from "./mock.js";
+export type { AppFixture, MockQuery, MockQueryCall, MockWorkflow } from "./mock.js";
 export type { AppWorkflows, AppWorkflowResults, AppQueries, AppQueryColumns, AppAgents, AppAgentResults } from "./types.js";
-export { row, readLinks, readFiles, readLocked } from "./row.js";
+export { row, readLinks, readFiles, readLocked, readCreatedAt, readUpdatedAt } from "./row.js";
 export type { ResolvedLink, AppFile } from "./row.js";
 export { useOptimistic } from "./use_optimistic.js";
 export type { OptimisticApi } from "./use_optimistic.js";

package/dist/src/index.js

@@ -25,7 +25,7 @@ export { askAi } from "./ask_ai.js";
 export { downloadFile } from "./download.js";
 export { readMembers } from "./members.js";
 export { readSelect } from "./select.js";
-export { row, readLinks, readFiles, readLocked } from "./row.js";
+export { row, readLinks, readFiles, readLocked, readCreatedAt, readUpdatedAt } from "./row.js";
 export { useOptimistic } from "./use_optimistic.js";
 export { useNewRecord, newRecordId } from "./new_record.js";
 export { useRecents } from "./use_recents.js";

package/dist/src/mock.d.ts

@@ -4,8 +4,8 @@
  * Activation contract:
  *
  *   1. App passes `{ fixture }` to `mount(<App />, { fixture })`. The fixture
- *      is a `{ queries: { alias: Row[] }, workflows: { alias: Result } }` map
- *      keyed by the same aliases the app declared in
+ *      is a `{ queries: { alias: MockQuery }, workflows: { alias: MockWorkflow } }`
+ *      map keyed by the same aliases the app declared in
  *      `package.json#lotics.queries` / `#lotics.workflows`.
  *   2. At runtime, the user (or a screenshot script) loads the app with the
  *      `?__mock=1` URL search param. Without that param the SDK ignores the
@@ -26,11 +26,14 @@
  * non-billing path to its own in-flight / done / error states at all, so those
  * three screens could not be reviewed without spending on a live workspace.
  *
- * A fixture entry may be the RESULT, or a FUNCTION of the inputs. The function
- * form is what makes the in-flight state reachable: resolve on a timer and the
- * app renders the pending branch it otherwise never shows. It also lets one
- * alias answer differently per input, which is how an error branch is reviewed
- * beside a success one.
+ * A fixture entry may be the RESULT, or a FUNCTION of the call. For a workflow
+ * the function form is what makes the in-flight state reachable: resolve on a
+ * timer and the app renders the pending branch it otherwise never shows. It also
+ * lets one alias answer differently per input, which is how an error branch is
+ * reviewed beside a success one. For a query it is what reproduces a NARROWED
+ * surface: the server applies `filter`/`sort`/`limit` after the named query, and
+ * a static row array cannot, so a master/detail drawer under `?__mock=1` would
+ * otherwise show every parent's children under every parent.
  *
  * What's deliberately *not* mocked: `useFileUpload`. Bytes and progress are a
  * different shape from a request/response pair, and nothing has needed it.
@@ -42,9 +45,30 @@ import type { WorkflowResult } from "./hooks.js";
  * caller in its pending state for as long as the review needs.
  */
 export type MockWorkflow = WorkflowResult | ((inputs: Record<string, unknown>) => WorkflowResult | Promise<WorkflowResult>);
+/** The call a mocked query is answering: the alias's params plus the per-call
+ *  refinement the screen passed. A master/detail surface narrows by `filter`,
+ *  so a fixture that ignores it renders every parent's children under every
+ *  parent — right-looking and wrong. */
+export interface MockQueryCall {
+    params: Record<string, unknown>;
+    filter?: unknown;
+    sort?: unknown;
+    limit?: number;
+}
+/**
+ * What a mocked query answers with: fixed rows, or a function of the call.
+ *
+ * The function form is the one that reproduces a FILTERED surface. The server
+ * applies `filter`/`sort`/`limit` after the named query; the fixture path has no
+ * query engine, and re-implementing the filter grammar here would ship a second,
+ * divergent copy of it — so the fixture decides, from the call it was handed,
+ * which rows that call returns.
+ */
+export type MockQuery = Array<Record<string, unknown>> | ((call: MockQueryCall) => Array<Record<string, unknown>>);
 export interface AppFixture {
-    /** Map of query alias → rows the hook should return when mock mode is on. */
-    queries?: Record<string, Array<Record<string, unknown>>>;
+    /** Map of query alias → the rows the hook returns when mock mode is on, or a
+     *  function of the call for a surface that narrows per call. */
+    queries?: Record<string, MockQuery>;
     /** Map of workflow alias → the result it resolves with when mock mode is on.
      *  The workflow never executes, so nothing it would have written is written. */
     workflows?: Record<string, MockWorkflow>;
@@ -70,7 +94,7 @@ export declare function hasMockFlag(): boolean;
  * through to the real RPC path. The distinction matters: an app may mock
  * only some queries and let the rest flow through to real data.
  */
-export declare function getMockRows(alias: string): Array<Record<string, unknown>> | null;
+export declare function getMockRows(alias: string, call: MockQueryCall): Array<Record<string, unknown>> | null;
 /**
  * The fixture entry for a workflow alias when mock mode is active *and* the
  * fixture has an entry for it. Otherwise null — the hook falls through to the

package/dist/src/mock.js

@@ -4,8 +4,8 @@
  * Activation contract:
  *
  *   1. App passes `{ fixture }` to `mount(<App />, { fixture })`. The fixture
- *      is a `{ queries: { alias: Row[] }, workflows: { alias: Result } }` map
- *      keyed by the same aliases the app declared in
+ *      is a `{ queries: { alias: MockQuery }, workflows: { alias: MockWorkflow } }`
+ *      map keyed by the same aliases the app declared in
  *      `package.json#lotics.queries` / `#lotics.workflows`.
  *   2. At runtime, the user (or a screenshot script) loads the app with the
  *      `?__mock=1` URL search param. Without that param the SDK ignores the
@@ -26,16 +26,21 @@
  * non-billing path to its own in-flight / done / error states at all, so those
  * three screens could not be reviewed without spending on a live workspace.
  *
- * A fixture entry may be the RESULT, or a FUNCTION of the inputs. The function
- * form is what makes the in-flight state reachable: resolve on a timer and the
- * app renders the pending branch it otherwise never shows. It also lets one
- * alias answer differently per input, which is how an error branch is reviewed
- * beside a success one.
+ * A fixture entry may be the RESULT, or a FUNCTION of the call. For a workflow
+ * the function form is what makes the in-flight state reachable: resolve on a
+ * timer and the app renders the pending branch it otherwise never shows. It also
+ * lets one alias answer differently per input, which is how an error branch is
+ * reviewed beside a success one. For a query it is what reproduces a NARROWED
+ * surface: the server applies `filter`/`sort`/`limit` after the named query, and
+ * a static row array cannot, so a master/detail drawer under `?__mock=1` would
+ * otherwise show every parent's children under every parent.
  *
  * What's deliberately *not* mocked: `useFileUpload`. Bytes and progress are a
  * different shape from a request/response pair, and nothing has needed it.
  */
 let registeredFixture;
+/** Aliases already warned about a static fixture under a filtered call. */
+const warnedStaticFilter = new Set();
 /**
  * Called by `mount({ fixture })`. Module-level state because the SDK has no
  * React context boundary around the iframe — every hook resolves against the
@@ -74,11 +79,24 @@ function isMockMode() {
  * through to the real RPC path. The distinction matters: an app may mock
  * only some queries and let the rest flow through to real data.
  */
-export function getMockRows(alias) {
+export function getMockRows(alias, call) {
     if (!isMockMode())
         return null;
-    const rows = registeredFixture?.queries?.[alias];
-    return rows ?? null;
+    const fixture = registeredFixture?.queries?.[alias];
+    if (fixture === undefined)
+        return null;
+    if (typeof fixture === "function")
+        return fixture(call);
+    // A static fixture cannot honour the call's narrowing, and the divergence is
+    // otherwise invisible — a drawer showing four rows where production shows two
+    // reads as a correct render. Said once per alias, at the first call that asks.
+    if (call.filter !== undefined && !warnedStaticFilter.has(alias)) {
+        warnedStaticFilter.add(alias);
+        console.warn(`Mock fixture for query "${alias}" is a static row array, so the filter passed to this call ` +
+            `is not applied — the mocked screen shows rows production would exclude. Make ` +
+            `fixture.queries.${alias} a function of the call to narrow it.`);
+    }
+    return fixture;
 }
 /**
  * The fixture entry for a workflow alias when mock mode is active *and* the

package/dist/src/router.d.ts

@@ -1,4 +1,17 @@
 import { type RouteObject } from "react-router";
-export declare function AppRouter({ routes }: {
+/**
+ * The not-found screen's words. The SDK ships no locale, so an app whose reader
+ * does not read English passes its own — from `@lotics/ui`'s locale where the app
+ * uses the kit, from its own strings otherwise.
+ */
+export interface NotFoundWords {
+    /** Names the address that has no screen. Takes the path so the words may put
+     *  it anywhere the language needs it. */
+    message: (path: string) => string;
+    /** The label of the link back to the first screen. */
+    firstScreen: string;
+}
+export declare function AppRouter({ routes, notFound }: {
     routes: RouteObject[];
+    notFound?: NotFoundWords;
 }): import("react").JSX.Element;

package/dist/src/router.js

@@ -35,9 +35,14 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  *       { path: "/item/:id", element: <Detail /> },
  *     ]} />;
  *   }
+ *
+ * An address none of the routes claim renders the SDK's not-found screen rather
+ * than nothing — see {@link NotFoundScreen} and {@link withNotFound}. Its words
+ * are the `notFound` prop ({@link NotFoundWords}), because an app's reader reads
+ * the app's language and the SDK ships no locale.
  */
 import { useEffect } from "react";
-import { BrowserRouter, useLocation, useRoutes, } from "react-router";
+import { BrowserRouter, Link, useLocation, useRoutes, } from "react-router";
 import { isEmbedded, setUrlParams } from "./rpc.js";
 /** Host query key carrying the app's current screen, so it's shareable and the
  *  host can restore it on refresh. */
@@ -70,10 +75,70 @@ function HostScreenMirror() {
 function RoutedRoutes({ routes }) {
     return useRoutes(routes);
 }
-export function AppRouter({ routes }) {
+/*
+ * Shaped like the kit's `RegionState` — a centred message and one destination —
+ * and written in its tokens with literal fallbacks, so it takes the app's theme
+ * where `@lotics/ui/styles.css` is loaded and stays legible where it is not. It
+ * cannot BE `RegionState`: the SDK ships no kit component.
+ */
+const NOT_FOUND_ROOT = {
+    display: "flex",
+    flexDirection: "column",
+    alignItems: "center",
+    justifyContent: "center",
+    gap: "var(--lotics-space-8, 8px)",
+    paddingBlock: "var(--lotics-space-48, 48px)",
+    paddingInline: "var(--lotics-space-16, 16px)",
+    textAlign: "center",
+    fontFamily: "var(--font-sans, system-ui, sans-serif)",
+};
+const NOT_FOUND_MESSAGE = {
+    margin: 0,
+    fontSize: "var(--lotics-text-sm, 14px)",
+    color: "var(--lotics-ink-muted, #71717a)",
+};
+const NOT_FOUND_LINK = {
+    fontSize: "var(--lotics-text-sm, 14px)",
+    color: "var(--lotics-accent, #2563eb)",
+};
+const NOT_FOUND_ENGLISH = {
+    message: (path) => `No screen at ${path}`,
+    firstScreen: "Go to the first screen",
+};
+/**
+ * What an app shows at an address none of its routes claim. Without it
+ * `useRoutes` matches nothing and the page renders EMPTY — no message and no
+ * console error — so a stale link or a typo reads as a crash.
+ */
+function NotFoundScreen({ home, words }) {
+    const { pathname } = useLocation();
+    return (_jsxs("div", { style: NOT_FOUND_ROOT, children: [
+            _jsx("p", { style: NOT_FOUND_MESSAGE, children: words.message(pathname) }), _jsx(Link, { to: home, style: NOT_FOUND_LINK, children: words.firstScreen })
+        ] }));
+}
+/**
+ * The catch-all, appended at EVERY level of the tree: a route with `children`
+ * is a layout, and a catch-all among those children is what keeps that layout's
+ * shell on screen instead of swapping the whole page for the message. An app
+ * that declares its own `*` still wins — react-router ranks equal matches by
+ * declaration order and ours is appended last.
+ */
+function withNotFound(routes, element) {
+    return [
+        ...routes.map((route) => route.children === undefined
+            ? route
+            : { ...route, children: withNotFound(route.children, element) }),
+        { path: "*", element },
+    ];
+}
+/** The screen the not-found sends the reader back to — the first one declared. */
+function firstScreenPath(routes) {
+    const first = routes.find((route) => route.path !== undefined && route.path !== "*");
+    return first?.path ?? "/";
+}
+export function AppRouter({ routes, notFound = NOT_FOUND_ENGLISH, }) {
     // `isEmbedded()` reads the `?lotics_host=` the host puts on the iframe src, so
     // it's known synchronously at first render.
     const embedded = isEmbedded();
-    return (_jsxs(BrowserRouter, { children: [embedded ? _jsx(HostScreenMirror, {}) : null, _jsx(RoutedRoutes, { routes: routes })
-        ] }));
+    return (_jsxs(BrowserRouter, { children: [embedded ? _jsx(HostScreenMirror, {}) : null, _jsx(RoutedRoutes, { routes: withNotFound(routes, _jsx(NotFoundScreen, { home: firstScreenPath(routes), words: notFound })) })] }));
 }

package/dist/src/row.d.ts

@@ -17,8 +17,14 @@
 declare function opt(v: unknown): string | null;
 /** Text/markdown/autonumber → string (numbers stringified; everything else ""). */
 declare function text(v: unknown): string;
-/** Number → number (NaN/Infinity and unparseable strings → 0). */
-declare function num(v: unknown): number;
+/**
+ * Number → number, or `null` when the cell holds no number — an empty cell, a
+ * NaN/Infinity, an unparseable string. Empty and zero usually mean opposite
+ * things ("not priced yet" vs "free", "no reading" vs "a reading of 0"), so the
+ * absence is preserved the way `date` preserves it. Write `?? 0` where 0 IS the
+ * correct reading of an empty cell (a sum, a count).
+ */
+declare function num(v: unknown): number | null;
 /** Checkbox/boolean → boolean (accepts the string "true"). */
 declare function bool(v: unknown): boolean;
 /**
@@ -100,6 +106,17 @@ export declare function readFiles(v: unknown): AppFile[];
  * non-object / absent flag.
  */
 export declare function readLocked(rowValue: unknown): boolean;
+/**
+ * When the record behind this row was created — the row-level `__created_at`
+ * column the compiler emits on every row-level query result. It is a DISPLAY
+ * value, so a table with no date field of its own still has a chronological
+ * anchor (a kardex date, an "as of" caption) with no schema change. Absent on a
+ * grouped/aggregated row, which has no originating record.
+ */
+export declare function readCreatedAt(rowValue: unknown): Date | null;
+/** When the record behind this row was last updated — the `__updated_at`
+ *  sibling of {@link readCreatedAt}. */
+export declare function readUpdatedAt(rowValue: unknown): Date | null;
 export declare const row: {
     opt: typeof opt;
     text: typeof text;

package/dist/src/row.js

@@ -36,15 +36,21 @@ function text(v) {
         return String(v);
     return "";
 }
-/** Number → number (NaN/Infinity and unparseable strings → 0). */
+/**
+ * Number → number, or `null` when the cell holds no number — an empty cell, a
+ * NaN/Infinity, an unparseable string. Empty and zero usually mean opposite
+ * things ("not priced yet" vs "free", "no reading" vs "a reading of 0"), so the
+ * absence is preserved the way `date` preserves it. Write `?? 0` where 0 IS the
+ * correct reading of an empty cell (a sum, a count).
+ */
 function num(v) {
     if (typeof v === "number")
-        return Number.isFinite(v) ? v : 0;
+        return Number.isFinite(v) ? v : null;
     if (typeof v === "string" && v.trim()) {
         const n = Number(v);
-        return Number.isFinite(n) ? n : 0;
+        return Number.isFinite(n) ? n : null;
     }
-    return 0;
+    return null;
 }
 /** Checkbox/boolean → boolean (accepts the string "true"). */
 function bool(v) {
@@ -158,4 +164,35 @@ export function readLocked(rowValue) {
         return false;
     return bool(rowValue["__source_locked"]);
 }
+/**
+ * The stored record's timestamp on a `useQuery` row, read off the addressing
+ * column named. Unlike a `date`/`datetime` CELL — a timezone-less workspace
+ * wall-clock at minute precision — these are true INSTANTS (ISO-8601 with an
+ * offset), so they are parsed as such and render in the viewer's zone. Pass the
+ * whole row (not a cell). Null for any non-object / absent / unparseable value.
+ */
+function rowInstant(rowValue, column) {
+    if (!rowValue || typeof rowValue !== "object")
+        return null;
+    const raw = rowValue[column];
+    if (typeof raw !== "string" || !raw)
+        return null;
+    const d = new Date(raw);
+    return Number.isNaN(d.getTime()) ? null : d;
+}
+/**
+ * When the record behind this row was created — the row-level `__created_at`
+ * column the compiler emits on every row-level query result. It is a DISPLAY
+ * value, so a table with no date field of its own still has a chronological
+ * anchor (a kardex date, an "as of" caption) with no schema change. Absent on a
+ * grouped/aggregated row, which has no originating record.
+ */
+export function readCreatedAt(rowValue) {
+    return rowInstant(rowValue, "__created_at");
+}
+/** When the record behind this row was last updated — the `__updated_at`
+ *  sibling of {@link readCreatedAt}. */
+export function readUpdatedAt(rowValue) {
+    return rowInstant(rowValue, "__updated_at");
+}
 export const row = { opt, text, num, bool, date, datetime, link };

package/dist/src/rpc.js

@@ -767,10 +767,16 @@ async function standaloneContext() {
         comments_enabled: info.comments_enabled,
     };
 }
-async function standaloneQuery(p) {
+/**
+ * The op payload IS the endpoint's body, and the endpoint's answer IS the op's
+ * result: both pass through untouched, so `sort`/`filter`/`count`/`keyset` on
+ * the way out and `total`/`truncated`/`next_cursor` on the way back reach a
+ * standalone app exactly as they reach a bridged one. Naming fields here is
+ * what once made `truncated` a host-only field.
+ */
+async function standaloneQuery(payload) {
     const { app_id } = await boot();
-    const r = (await apiCall("POST", `/v1/apps/${app_id}/query`, { alias: p.alias, params: p.params, limit: p.limit, offset: p.offset }, { appId: app_id }));
-    return { rows: r.rows ?? [] };
+    return apiCall("POST", `/v1/apps/${app_id}/query`, payload, { appId: app_id });
 }
 async function standaloneFieldOptions(p) {
     const { app_id } = await boot();

package/docs/ai.md

@@ -13,7 +13,7 @@ Don't run a structured extraction through `askAi` (the result is stranded in a c
 
 ## Declared agents — what `useAgentRun` runs
 
-An agent is **declared on the app server-side, by alias**, with the `set_app_agent` tool (removed with `remove_app_agent`). `lotics app deploy` ships code and queries only — it never binds agents. The `lotics.agents` map in `package.json` is a **read-only reflection** written by `lotics app pull`; hand-editing it does nothing. Invoking an alias that isn't bound fails with a "no agent alias" error naming `set_app_agent`. (After a deploy, the CLI warns about any manifest alias not bound on the server.)
+An agent is **declared on the app server-side, by alias**, with the `set_app_agent` tool (removed with `remove_app_agent`) — the only verb that creates a binding, so no deploy binds an alias the app does not already have. A deploy does push an alias it has: the prose in `src/agents/<alias>.md` and the authored `inputs`/`outputs` in `package.json#lotics.agents.<alias>` go through `set_app_agent` whenever either differs from the live row, before the bundle ships. Every other key of that map is a reflection `lotics app pull` refreshes and no verb sends, so replaying a stale snapshot cannot revert a grant bound elsewhere. Invoking an alias that isn't bound fails with a "no agent alias" error naming `set_app_agent`. (After a deploy, the CLI warns about any manifest alias not bound on the server.)
 
 A declaration carries:
 

package/docs/data_fetching.md

@@ -2,7 +2,7 @@
 
 How an app reads data: the three read hooks (`useQuery`, `useInfiniteQuery`, `usePaginatedQuery`),
 their caching/revalidation and pagination contracts, the typed cell readers that decode query rows
-(`row.*`, `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`), `useFieldOptions`
+(`row.*`, `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`, `readCreatedAt`/`readUpdatedAt`), `useFieldOptions`
 for complete select option sets, the data-discipline rules, and the two load-bearing read patterns
 (search-as-you-type, browse/record-picker). Authoring the named queries these hooks invoke — the
 AST, params, filter operators, aggregation, performance contract — is [./queries.md](./queries.md);
@@ -69,8 +69,9 @@ moved while everything around it updates — and a count that is quietly wrong c
 count that costs a request.
 
 And never count client-side from `useQuery(...).rows.length`: rows are capped at 10,000 per
-response and truncation is **silent**, so the number is right in development and wrong in
-production with no error ([queries](./queries.md) §10).
+response, so the number is right in development and wrong in production ([queries](./queries.md)
+§10). `useQuery` reports `truncated` when the cap cut the result — read it wherever a figure is
+folded from the rows (below) — but a count over the whole set is `useCount`'s answer, not a length.
 
 ## Shared option surface
 
@@ -246,7 +247,8 @@ Shared by both:
 
 - **Row cap: 10,000.** No single query response returns more than 10,000 rows; a larger `limit`
   (or an omitted `pageSize` on `useQuery`) is clamped to it. To read a bigger result set, page
-  through it.
+  through it. `useQuery` reports `truncated: true` when the limit cut the result, so a screen can
+  say so instead of quietly under-reporting.
 - **Always give a paginated query a deterministic order.** With no `ORDER BY` (neither in the
   template nor runtime `sort`), row order is unspecified — offset pages may overlap or skip rows
   even without concurrent writes, and keyset falls back to the record-id order. Sort by a stable
@@ -275,8 +277,22 @@ const { rows, loading, error, refetch } = useQuery("openOrders", { status: "open
 ```
 
 One fetch. `params` is required when the alias declares params, optional otherwise. Returns
-`{ rows, loading, isValidating, error, refetch }`. `rows` is `Array<Record<string, unknown>>` —
-decode cells with the readers below.
+`{ rows, truncated, loading, isValidating, error, refetch }`. `rows` is
+`Array<Record<string, unknown>>` — decode cells with the readers below.
+
+**`truncated` — the one thing a short result cannot tell you itself.** It is `true` when more rows
+matched than arrived, so `rows` is short and anything folded off it (a grouped period × site table,
+a per-carrier ratio, a KPI strip) is under-reported. The limit is your `pageSize` when you set one
+and the server's 10,000-row cap otherwise. Nothing else says so — there is no error, no empty state
+and no visual tell — so read it wherever the screen computes a figure from the whole result, and
+say the report is short rather than printing a number that is quietly wrong:
+
+```tsx
+const { rows, truncated } = useQuery("movements", { from, to });
+const total = rows.reduce((n, r) => n + (row.num(r.amount) ?? 0), 0);
+return <>{truncated && <Callout tone="warning">Số liệu chưa đủ — thu hẹp khoảng thời gian.</Callout>}
+        <Stat value={total} /></>;
+```
 
 ### `useInfiniteQuery`
 
@@ -406,7 +422,7 @@ emits none of these" is a fact the type states rather than one you have to remem
 |---|---|---|
 | `row.opt(cell)` | select cell → `string \| null` | first option **key** (accepts the legacy bare-string / `{ id }` shapes); `null` when empty |
 | `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.num(cell)` | any → `number \| null` | finite numbers pass, parseable strings parse, everything else (empty cell, NaN/Infinity, unparseable string) → `null` |
 | `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; 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** |
@@ -416,11 +432,18 @@ emits none of these" is a fact the type states rather than one you have to remem
 | `readMembers(cell)` | member cell → `ResolvedMember[]` | `{ id, name, email?, image?, groups? }[]` (`[]` when empty) |
 | `readFiles(cell)` | files cell → `AppFile[]` | attached files with presigned URLs (`[]` when empty) |
 | `readLocked(rowObj)` | the whole **row** → `boolean` | the record's lock state from `__source_locked` |
+| `readCreatedAt(rowObj)` | the whole **row** → `Date \| null` | when the record was created, from `__created_at` |
+| `readUpdatedAt(rowObj)` | the whole **row** → `Date \| null` | when the record was last updated, from `__updated_at` |
 
 All readers are pure (`unknown` in, value out), never throw, and return their empty value
-(`null` / `""` / `0` / `false` / `[]`) for absent or malformed input — so callers iterate and
+(`null` / `""` / `false` / `[]`) for absent or malformed input — so callers iterate and
 render without null-check pyramids.
 
+**`row.num` and the empty cell.** `null` means the cell holds no number; `0` means it holds zero.
+The two usually mean opposite things ("not priced yet" vs "free", "no reading" vs "a reading of 0"),
+so the reader keeps them apart instead of collapsing both to `0`. Write `?? 0` where zero IS the
+correct reading of an empty cell (a sum, a count, a running total).
+
 **`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
@@ -471,6 +494,13 @@ columns **only in the query that renders them**, narrow with a filter, or pagina
 show the locked state and route edits through the locked-change request flow
 ([./mutations.md](./mutations.md)).
 
+**`readCreatedAt` / `readUpdatedAt`.** Take the whole row object, not a cell. They give a table with
+no date field of its own a chronological anchor — a kardex/statement date, an "as of" caption —
+without adding a field or a stamping workflow. Unlike a `date`/`datetime` CELL (a timezone-less
+workspace wall-clock at minute precision), these are true **instants**: ISO-8601 with an offset on
+the wire, parsed as instants, rendered in the viewer's zone. `null` on a grouped row, which has no
+originating record.
+
 ## Complete select option sets
 
 A query cell carries only the options a record actually holds (key + label, no color). For the

package/docs/members_and_options.md

@@ -278,7 +278,7 @@ updateComment, deleteComment, refetch }`.
 
 - `comments` — newest first on the wire (server order). Pass the array as-is to `@lotics/ui`'s
   `CommentThread`, which re-sorts oldest-first for display. Each `AppComment`: `{ id, record_id,
-  table_id, member_id, content, files, workspace_id, created_at, updated_at }`. Attachments
+  table_id, member_id, author, content, files, workspace_id, created_at, updated_at }`. Attachments
   (`AppCommentFile`) carry `id` / `filename` / `mime_type` — a file's identity is its `id`, and
   the server re-reads every attachment from storage by that id, so nothing else you hold about a
   file can affect what is stored. The `url` / `thumbnail_url` / `preview_url` fields exist on the type
@@ -294,10 +294,14 @@ updateComment, deleteComment, refetch }`.
   server. **Limitation:** an optimistic create renders a placeholder row (temporary id, empty
   `table_id`/`workspace_id`, `files: null`) until the refetch lands — don't persist anything keyed
   on it.
-- **Limitation:** a comment carries `member_id` only — resolving the author's display name needs a
-  member source: the `useMembers` roster (requires the member-access declaration above) or member
-  cells in your own data. An unresolvable id should render a fallback (`CommentThread` has an
-  `unknownMember` label for exactly this).
+- **The author names itself.** `author` carries `{ name, image? }`, resolved server-side on every
+  comment the server returns — list, create and update alike — including one written from another
+  app by someone the record references nowhere. So a thread that crosses a role boundary is legible without the app declaring member
+  access it does not otherwise need, and a per-viewer app never widens its reach for a display
+  string. `name` is `null` when the id no longer resolves in the org (a removed member) — render a
+  fallback (`CommentThread` has an `unknownMember` label for exactly this). The one comment with no
+  `author` is the optimistic row `createComment` renders locally: the SDK knows the viewer's id and
+  not their name, and it will not invent one. The server's row replaces it when the refetch lands.
 - **Freshness:** SWR-cached, revalidates on focus/reconnect, so another viewer's comment appears on
   the next focus or explicit `refetch()` — not on its own. Comments are the one read that does not
   keep itself current, and not because apps lack realtime: the channel carries **record** changes,
@@ -323,7 +327,7 @@ directly (full props: `node_modules/@lotics/ui/AGENTS.md` and its `docs/`):
 | A select value (stored or picker option) | `Status` | A `useFieldOptions` option, or `byKey(readSelect(cell)[0]?.key)`; accepts a single option, an array (multi → one badge each), or null (renders nothing). Missing/unknown color → neutral. |
 | A person, inline | `MemberChip` | `name` / `image` from a roster or a cell — both carry it; no image → initials |
 | A member picker | `MemberSelect` | `members={useMembers().members}` — renders each option as a `MemberChip`; `MEMBER_UNASSIGNED` marks its optional "unassigned" option |
-| A comment thread | `CommentThread` + `CommentComposer` | `useComments` state; `resolveMember` bridges `member_id` → your member source |
+| A comment thread | `CommentThread` + `CommentComposer` | `useComments` state; `resolveMember` reads each comment's own `author` (`{ name, image }`) — no roster needed |
 
 The SDK never imports `@lotics/ui` — the app owns the (thin) data→UI adapter in each row above.
 

package/docs/mutations.md

@@ -29,10 +29,9 @@ const result = await createOrder({ customer_id, quantity: 3 });
   owner's** authority (never the viewer's — see [security](./security.md) for attribution,
   privilege gates, and public-app semantics).
 - Binding is server-side (`set_app_workflow`, or `lotics app workflow set <alias>` from the
-  app project). `lotics app deploy` ships code, queries, and capabilities — it never binds
-  workflows.
-  The `package.json#lotics.workflows` map is a *pulled reflection* of the live bindings, used
-  purely to type `useWorkflow` (below); hand-editing it changes nothing on the server.
+  app project), and `lotics app deploy` calls it: `package.json#lotics.workflows.<alias>` plus
+  `src/workflows/<alias>.ts` ARE the source of a binding, so an alias committed to the repo is
+  one the next clone ships. The declaration also types `useWorkflow` (below).
 - Invoking an alias that is not bound resolves with `status: "error"` and a message naming
   the missing binding.
 - Anonymous visitors to a publicly shared app can invoke workflows too; the triggering
@@ -66,6 +65,7 @@ Every call resolves to a `WorkflowResult<TData>` (type exported from the package
 | `message` | `string?` | The workflow's `return({ message })` text, a validation/binding error, or a body-free transport message |
 | `files` | `UploadedFile[]?` | Files generated during the run (auto-collected — below). Absent when the run generated none |
 | `data` | `TData?` | Structured data from `return({ data })`. Absent when no return step ran |
+| `field_errors` | `Record<string, string>?` | Per-input refusals from `return({ field_errors })`, keyed by the INPUT name the alias declares. Absent when the workflow returned none |
 
 ### The failure model: check `status`, never just try/catch
 
@@ -104,6 +104,29 @@ the app must branch on failure kinds, make the workflow return them:
 `return({ status: "error", data: { code: "OUT_OF_STOCK" } })` (an *error* return's `data`
 passes through unvalidated).
 
+### Locating a refusal: `field_errors`
+
+A workflow that validates its own inputs refuses with both halves — a message for the dialog and a
+map for the controls:
+
+```ts
+return({ status: "error", message: "Thiếu lý do.",
+         field_errors: { ly_do: "Nhập vì sao ngoại lệ này chấp nhận được." } });
+```
+
+The map arrives on the result keyed by the INPUT name, so a form wires it straight onto the control
+that is wrong instead of making the reader hunt across a six-field dialog:
+
+```tsx
+const [errs, setErrs] = useState<Record<string, string>>({});
+const result = await submit(values);
+setErrs(result.field_errors ?? {});
+// <FormField error={errs.ly_do}> … </FormField>
+```
+
+Keep `message` too — it is what a refusal with no field to blame says, and the two are shown
+together (a `Callout` at the dialog's scope plus the per-field text).
+
 ### Generated files come back in `files[]`
 
 Any step in the run whose tool output carries a `file_id` (most commonly the
@@ -119,6 +142,10 @@ const url = files?.[0]?.url;
 if (status === "success" && url) await openExternal(url);
 ```
 
+The same run reached through the `run_app_workflow` tool — from chat, from MCP, from an app
+agent — lists those files as `file_id`. It is the same value `useWorkflow` gives you as `id`,
+so a file an agent produced and a file the app produced are addressed identically.
+
 Files travel **only** via `files[]` — never hand a `file_id`/`url` back through
 `return({ data })`, and never `update_records` a file onto a record solely to make it
 downloadable. A download-only workflow generates and returns; attaching to a record is a
@@ -158,6 +185,9 @@ envelope's grammar — `message` is required, `field_errors` never reaches the a
   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.
+- **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.
 - **`data` is optional even when typed.** A workflow that completes without hitting a
   `return` step resolves `status: "success"` with no `data` (and no validation). If the app
   depends on `data`, make every success path in the body end in `return({ data })` — and
@@ -173,11 +203,13 @@ if (r.status === "success" && r.data) {
 
 ## Declaring workflow inputs
 
-An alias's declaration is `{ workflow_id, inputs?, outputs? }`. `inputs` maps each input name
-to a typed declaration; it is authored when the workflow is bound (`set_app_workflow` /
-`lotics app workflow set` reads it from `package.json#lotics.workflows.<alias>`), and the
-schema the body was verified against is canonical — the manifest reflection cannot silently
-weaken it. It drives three things at once: compile-time typing of the `useWorkflow` payload,
+An alias's declaration is `{ inputs?, outputs?, workflow_id? }` — `workflow_id` is the server's
+half, stamped by the first bind, so an alias an author has only just written carries none.
+`inputs` maps each input name to a typed declaration; it is authored beside the body and
+travels with it (`set_app_workflow` / `lotics app workflow set` reads it from
+`package.json#lotics.workflows.<alias>`, and a deploy pushes a declaration that has moved), and
+the schema the body was verified against is canonical — a manifest edit that reaches no push
+weakens nothing. It drives three things at once: compile-time typing of the `useWorkflow` payload,
 compile-time typing of `trigger.app_workflow.inputs.*` inside the body, and runtime payload
 validation at the execute boundary.
 
@@ -247,7 +279,7 @@ When the alias declares `inputs`, the server validates the payload before the wo
   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
+  (`lotics app workflow set` / `set_app_workflow`, which a deploy calls for a declaration it holds) 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. Populate pickers from `useFieldOptions`

package/docs/navigation_and_state.md

@@ -63,6 +63,28 @@ routes, and splats all work. Inside the tree, use react-router normally:
   (`^7 || ^8` — the canonical package; the `react-router-dom` shim's tree also
   satisfies it) is an **optional peer dependency** — an app that imports the
   router entry must install it itself; nothing else in the SDK needs it.
+- **An address no route claims says so.** `AppRouter` appends a catch-all at
+  every level of the tree, so such a path renders a not-found screen — a
+  message naming the path and a link to the first route — instead of an empty
+  page, and a layout route keeps its shell around that message. Declaring your
+  own `{ path: "*" }` replaces it.
+- **The not-found screen speaks the app's language.** Its two strings default
+  to English; an app whose reader reads another language passes them as
+  `notFound`, next to `routes`:
+
+  ```tsx
+  <AppRouter
+    routes={routes}
+    notFound={{
+      message: (path) => `Không có màn hình ở ${path}`,
+      firstScreen: "Về màn hình đầu tiên",
+    }}
+  />
+  ```
+
+  `message` takes the path so the words may place it where the language needs
+  it. Where the app uses `@lotics/ui`, read both from the kit's locale — the
+  SDK ships none of its own.
 - **Limitation: element routing only.** `AppRouter` mounts a plain browser
   router, not a react-router *data* router — route `loader`/`action` fields
   are ignored, and `useLoaderData` **throws** ("must be used within a data

package/docs/queries.md

@@ -161,6 +161,12 @@ declare these; output names starting with `__source_` / `__src_field_`, or equal
 drops addressing (grouped results can't be written through or matched by `record_id`); a `join`
 keeps the **left** side's addressing.
 
+`__created_at` / `__updated_at` are DISPLAY values, not just reserved names: a table with no date
+field of its own still has a chronological anchor. They arrive as ISO-8601 **instants** with an
+offset (`"2026-07-05T09:00:00.000Z"`) — not the timezone-less wall-clock a `date`/`datetime` cell
+carries — so read them with `readCreatedAt(row)` / `readUpdatedAt(row)`, which parse them as
+instants ([./data_fetching.md](./data_fetching.md)).
+
 ---
 
 ## 2. The AST node reference
@@ -850,7 +856,7 @@ runtime refinement.
 
 | Limit | Value | On violation |
 | --- | --- | --- |
-| Rows per response | **10,000** (caller `limit` is clamped; the cap is the default) | silent truncation at the cap — paginate |
+| Rows per response | **10,000** (caller `limit` is clamped; the cap is the default) | truncation at the cap — `useQuery` reports `truncated`; paginate, or say the report is short |
 | Statement timeout | **15 s** per query execution | 400: `query timed out after 15s — narrow the filter or simplify the query` |
 | Concurrent query executions | server-configured bulkhead (bounded slots + bounded queue wait) | **503**: `The app is handling too many requests right now. Please retry in a moment.` — a distinct busy-retry outcome; back off and retry |
 | Signed file URLs per response | server-configured, default **2,000 file entries** | 400 naming the alias, the count, and the ceiling — project files columns only where rendered, narrow, or paginate |

package/docs/recipes.md

@@ -118,6 +118,7 @@ A query cell is `unknown` with a per-type serialized shape:
 
 - `row.opt` / `row.text` / `row.num` / `row.bool` / `row.date` — scalars and the first value of a
   select. `row.date` keeps only the calendar day; use **`row.datetime`** when the time matters.
+  `row.num` answers `null` for an empty cell — write `?? 0` only where zero is its correct reading.
 - `readSelect` — the full `{ key, label }[]` of a multi-select.
 - `readMembers` — `select_member` cells.
 - `row.link` / `readLinks` — `select_record_link` → `{ id, display }`. Read `.display` to render,

package/docs/runtime.md

@@ -43,6 +43,10 @@ mount(<App />, {
     queries: {
       orders: MOCK_ORDERS,       // alias → rows, same aliases as package.json#lotics.queries
       customers: MOCK_CUSTOMERS,
+      // Or a FUNCTION of the call — how a surface that narrows per call
+      // (a master/detail drawer) renders what production would.
+      orderLines: ({ filter }) =>
+        MOCK_LINES.filter((l) => matchesOpenOrder(l, filter)),
     },
     workflows: {
       // A fixed result, for the settled state.
@@ -75,6 +79,17 @@ transport. Calling `mount` again (HMR) replaces the registration last-write-wins
   as fetched rows, so shape them exactly like the query's real output — the same
   serialized cells your `row.*` / `readSelect` / `readFiles` readers decode —
   or the readers will decode nothing.
+- **A ROW ARRAY answers every call to its alias identically.** The server applies
+  the per-call `filter` / `sort` / `pageSize` *after* the named query; a static
+  array cannot, so a drawer narrowed with
+  `useQuery("orderLines", {}, { filter: byOpenOrder })` shows every parent's
+  children under every parent — a screen that looks right and is wrong, which
+  defeats the review the mock path exists for. **Make such a fixture a function
+  of the call** (`({ params, filter, sort, limit }) => rows`) and narrow it
+  there; a filtered call against a row array warns once per alias in the
+  console. Do NOT compensate with a client-side re-filter in the app — that
+  ships a second, divergent copy of the filter to production to make a mock
+  look right.
 - **A mocked workflow does not RUN.** `useWorkflow(alias)` resolves the fixture
   entry and sends nothing, so there is no notification, no audit trail and no
   spend — the side-effect argument is the reason to mock it, not a reason not

package/docs/workflows.md

@@ -430,7 +430,7 @@ full menu by category, so a miss is one informed retry.
 | **Type / null** | `isNull`, `isNotNull`, `isEmpty`, `isString`, `isNumber`, `isBoolean`, `isArray`, `isObject`, `coalesce`, `toNumber`, `toString`, `typeOf`, `parseJson`, `toJson` |
 | **Array** | `size`, `first`, `requireFirst`, `last`, `nth`, `at`, `slice`, `includes`, `filter`, `find`, `some`, `every`, `pluck`, `sortBy`, `groupBy`, `countBy`, `unique`, `uniqueBy`, `compact`, `flatten`, `reverse`, `concat`, `difference`, `differenceBy`, `intersection`, `intersectionBy`, `list`, `range`, `reduce` |
 | **Number** | `sum`, `sumBy`, `mean`, `meanBy`, `min`, `max`, `minBy`, `maxBy`, `round`, `ceil`, `floor`, `abs`, `mod`, `pow`, `sqrt`, `clamp`, `percentage` |
-| **String** | `upper`, `lower`, `capitalize`, `trim`, `contains`, `startsWith`, `endsWith`, `replace`, `replaceAll`, `substring`, `length`, `split`, `join`, `padStart`, `padEnd`, `formatNumber`, `numberToWords` |
+| **String** | `upper`, `lower`, `capitalize`, `trim`, `contains`, `startsWith`, `endsWith`, `replace`, `replaceAll`, `substring`, `length`, `split`, `join`, `padStart`, `padEnd`, `formatNumber(value, decimals)` (fixed-decimal, ungrouped), `formatDecimal(value, decimals, locale)` (grouped for a reader — `formatDecimal(151000, 0, "vi-VN")` → `151.000`), `numberToWords` |
 | **Object** | `keys`, `values`, `entries`, `get`, `pick`, `omit`, `merge`, `nonNullKeys` |
 | **Date** | `now`, `formatDate`, `parseDate`, `addDays`, `subDays`, `addHours`, `subHours`, `addMinutes`, `subMinutes`, `startOfDay`, `endOfDay`, `differenceInCalendarDays`, `differenceInHours`, `differenceInMinutes`, `isBefore`, `isAfter`, `isSameDay`, `isToday`, `isWithinRange` |
 | **Other** | `formatCurrency(amount, locale, currency)`, `randomNumber(len)`, `randomAlphaNumeric(len)`, `sample(items)`, `current_member_in_any_group(["grp_…"])` |

package/package.json

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