@lotics/app-sdk 0.91.1 → 0.94.0

package/AGENTS.md

@@ -16,11 +16,11 @@ 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 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/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 ROW type (`RowOf` — the alias's projected columns and nothing else, values `unknown`; `__source_record_id`/`__source_table_id` typed but optional), runtime `sort`/`filter` keys AND the `useFieldOptions` map keyed against that same 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), 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` (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/members_and_options.md](./docs/members_and_options.md) | People + select options + comments — `useMembers`, `useFieldOptions` (keyed by the alias's OWN columns, every key optional), `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). |
@@ -44,6 +44,9 @@ signature; open the file.**
   column, including files. → [queries](./docs/queries.md)
 - **Never hand-roll the serialization contract** — decode cells with the typed readers.
   → [data_fetching](./docs/data_fetching.md)
+- **Read only the columns the alias projects** — its option sets too, from the alias that CARRIES
+  the column. Anything else is `undefined`, which every reader draws as a blank cell, so the row
+  type and the option map are bounded to the projection. → [data_fetching](./docs/data_fetching.md)
 - **Narrow `__source_record_id` / `__source_table_id` before use** — a grouped query emits neither,
   so an unchecked read hands a workflow (or an AI record ref) `undefined`.
   → [data_fetching](./docs/data_fetching.md)

package/dist/src/hooks.d.ts

@@ -7,12 +7,14 @@ import type { ResolvedOption } from "./select.js";
 export type { AgentRunState, AgentUIPart, PendingChoice, ChoiceQuestion, ChoiceOption, AskUserChoiceOutput, AgentRunLanding } from "./agent_stream.js";
 export { buildChoiceOutput } from "./agent_stream.js";
 /**
- * One row of a query result: the projected columns, plus the platform's
- * ADDRESSING columns.
+ * One row of a query result whose COLUMNS are not known: a dynamic alias, or a
+ * query whose AST names no projection (a bare `from_table`). Where codegen could
+ * read them, `RowOf` states them instead and there is no index signature — see
+ * that type, which is where the reason lives.
  *
- * The projected values stay `unknown` — which columns a row carries is fixed by
- * the query's manifest declaration, not by this type, so the cell readers
- * (`row.text`, `readLinks`, `readFiles`, …) are what narrow them.
+ * The projected values stay `unknown` either way: a column's TYPE is the field's
+ * and the manifest does not carry it, so the cell readers (`row.text`,
+ * `readLinks`, `readFiles`, …) are what narrow them.
  *
  * The `__source_*` columns are different in kind: the compiler injects them at
  * every layer, and they are the only way to address the RECORD a row came from
@@ -41,6 +43,27 @@ export interface QueryRow {
     /** The table that record lives in. Absent on a grouped/aggregated row. */
     __source_table_id?: string;
 }
+/**
+ * The row type of alias `K`: the columns that alias PROJECTS, plus the two
+ * addressing columns, and nothing else.
+ *
+ * `.lotics/app_queries.d.ts` already names every projected column
+ * (`AppQueryColumns`), read off the query's AST by the same rule the server
+ * names them by. A read is bounded to that union for the same reason a
+ * `filter`/`sort` key is — except the failure is quieter. A key the query does
+ * not carry is refused by the server; a COLUMN it does not carry comes back
+ * `undefined`, which every cell reader answers with its empty value, so a
+ * misspelt column, a renamed field and a projection moved to another alias all
+ * render as a blank cell in a member's browser with no error anywhere. Removing
+ * the index signature is what turns that silence into a `tsc` error, which is
+ * what `lotics app check` refuses to ship.
+ *
+ * An alias with no `AppQueryColumns` entry keeps `QueryRow` — a union that could
+ * be wrong is worse than none, the rule `ColumnKeyOf` already follows.
+ */
+export type RowOf<K extends string> = K extends keyof AppQueryColumns ? {
+    [C in AppQueryColumns[K] & string]: unknown;
+} & Pick<QueryRow, "__source_record_id" | "__source_table_id"> : QueryRow;
 /** Fields shared by every query hook's return value. */
 interface QueryStateBase {
     /**
@@ -311,11 +334,16 @@ export interface WorkflowResult<TData = unknown> {
     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.
+     * Per-input refusals, keyed by the INPUT name the alias 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.
+     *
+     * Either half of the round trip fills it: the SERVER, when the payload does
+     * not match what the alias declares, and the workflow's own
+     * `return({ field_errors })`. One key, so a screen wires the control once
+     * rather than branching on which half refused. Absent when neither named a
+     * field — and an older server names none.
      */
     field_errors?: Record<string, string>;
 }
@@ -344,9 +372,10 @@ type QueryArgs<K extends string, O> = K extends keyof AppQueries ? AppQueries[K]
  *
  * Per-app CLI codegen writes `.lotics/app_queries.d.ts` augmenting `AppQueries`
  * with the declared alias → param-type map, so an undeclared alias is a
- * compile-time error and params are typed per the manifest.
+ * compile-time error and params are typed per the manifest. The same file names
+ * the alias's projected columns, which is what bounds a ROW read — see `RowOf`.
  */
-export declare function useQuery<K extends string>(alias: K, ...args: QueryArgs<K, QueryOptions<ColumnKeyOf<K>>>): QueryState<QueryRow>;
+export declare function useQuery<K extends string>(alias: K, ...args: QueryArgs<K, QueryOptions<ColumnKeyOf<K>>>): QueryState<RowOf<K>>;
 /** The resolved option set of one select column, plus an index for value
  *  rendering. The companion to a query row, for select fields. */
 export interface FieldOptions {
@@ -366,14 +395,20 @@ export interface FieldOptions {
      */
     byKey: (key: string) => ResolvedOption | undefined;
 }
-/** Return value of `useFieldOptions`. */
-export interface FieldOptionsState {
+/** Return value of `useFieldOptions`. `C` is the column key's type — the alias's
+ *  projected outputs, see `ColumnKeyOf`. */
+export interface FieldOptionsState<C extends string = string> {
     /**
-     * Resolved option sets keyed by the query's OUTPUT column name. A select
-     * column the server couldn't resolve to a source field (a UNION output, a
-     * computed column) is simply absent — read defensively (`fields.status?`).
+     * Resolved option sets keyed by the query's OUTPUT column name — the alias's
+     * own columns, so a key belonging to another query is a `tsc` error rather
+     * than a `[]` picker nobody can open.
+     *
+     * EVERY key is optional, and that is the shape rather than a hedge: a select
+     * column the server could not resolve to a source field (a UNION output whose
+     * arms disagree, a computed column) is genuinely absent, and a non-select
+     * column never had options. Read through it (`fields.status?.options ?? []`).
      */
-    fields: Record<string, FieldOptions>;
+    fields: Partial<Record<C, FieldOptions>>;
     loading: boolean;
     isValidating: boolean;
     error: string | null;
@@ -395,8 +430,11 @@ export interface FieldOptionsOptions {
  * added/removed option flows through with no app change.
  *
  * Addressed by the same alias you query: the option sets resolve from the named
- * query's output columns, scoped exactly like running it. A column the server
- * can't map to a source select field (UNION output, computed column) is absent.
+ * query's output columns, scoped exactly like running it, and `fields` is keyed
+ * by that same union — the alias that CARRIES the column is the one to ask, and
+ * asking another is a compile error instead of an empty picker. A column the
+ * server can't map to a source select field (UNION output, computed column) is
+ * absent, so every key is optional.
  *
  * ```tsx
  * const { fields } = useFieldOptions("records");
@@ -407,7 +445,7 @@ export interface FieldOptionsOptions {
  * <Status option={fields.status?.byKey(readSelect(r.status)[0]?.key ?? "")} />
  * ```
  */
-export declare function useFieldOptions<K extends keyof AppQueries & string>(alias: K, opts?: FieldOptionsOptions): FieldOptionsState;
+export declare function useFieldOptions<K extends keyof AppQueries & string>(alias: K, opts?: FieldOptionsOptions): FieldOptionsState<ColumnKeyOf<K>>;
 export declare function useFieldOptions(alias: string, opts?: FieldOptionsOptions): FieldOptionsState;
 /**
  * Like `useQuery` but append/load-more: the first render loads one page and
@@ -418,7 +456,7 @@ export declare function useFieldOptions(alias: string, opts?: FieldOptionsOption
  * const { rows, loadMore, hasMore } = useInfiniteQuery("feed", {}, { pageSize: 30 });
  * ```
  */
-export declare function useInfiniteQuery<K extends string>(alias: K, ...args: QueryArgs<K, InfiniteQueryOptions<ColumnKeyOf<K>>>): InfiniteQueryState<QueryRow>;
+export declare function useInfiniteQuery<K extends string>(alias: K, ...args: QueryArgs<K, InfiniteQueryOptions<ColumnKeyOf<K>>>): InfiniteQueryState<RowOf<K>>;
 /**
  * Page-model query with a total — the data hook behind a numbered, jumpable
  * table (pairs with `@lotics/ui/pagination`). It owns the page
@@ -433,7 +471,7 @@ export declare function useInfiniteQuery<K extends string>(alias: K, ...args: Qu
  *   usePaginatedQuery("orders", { q }, { pageSize: 25, sort, filter });
  * ```
  */
-export declare function usePaginatedQuery<K extends string>(alias: K, ...args: QueryArgs<K, PaginatedQueryOptions<ColumnKeyOf<K>>>): PaginatedQueryState<QueryRow>;
+export declare function usePaginatedQuery<K extends string>(alias: K, ...args: QueryArgs<K, PaginatedQueryOptions<ColumnKeyOf<K>>>): PaginatedQueryState<RowOf<K>>;
 /**
  * HOW MANY rows a query matches — one number, no rows fetched.
  *
@@ -617,9 +655,11 @@ interface MembersState {
 /** Options for `useMembers`. */
 export interface MembersOptions {
     /**
-     * Restrict to one member group (a group ID). The group must be declared on a
-     * `member` workflow input's `group` — listing an undeclared group errors. Omit
-     * to list the whole org roster.
+     * Restrict to one member group, as `GRP.<group>` from `.lotics/app_fields.ts`
+     * (a pasted `grp_…` id is refused by `lotics app check` — it resolves to
+     * nothing in a copy of the app). The group must be declared on a `member`
+     * workflow input's `group` — listing an undeclared group errors. Omit to list
+     * the whole org roster.
      */
     group?: string;
 }
@@ -636,7 +676,7 @@ export interface MembersOptions {
  * `group` — so an app can only list (and assign into) groups it declares.
  *
  * ```tsx
- * const { members } = useMembers({ group: "grp_..." });
+ * const { members } = useMembers({ group: GRP.sale });
  * // <Select variant="native" options={members.map((m) => ({
  * //   value: m.id, label: m.name || m.email || m.id, image: m.image,
  * // }))} />

package/dist/src/hooks.js

@@ -557,7 +557,7 @@ export function useAiContext(slot, context) {
  * `group` — so an app can only list (and assign into) groups it declares.
  *
  * ```tsx
- * const { members } = useMembers({ group: "grp_..." });
+ * const { members } = useMembers({ group: GRP.sale });
  * // <Select variant="native" options={members.map((m) => ({
  * //   value: m.id, label: m.name || m.email || m.id, image: m.image,
  * // }))} />

package/dist/src/index.d.ts

@@ -16,7 +16,7 @@
 export { mount } from "./mount.js";
 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 type { QueryRow, RowOf, 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, AppCommentAuthor, AppCommentFile, CommentsState, UseCommentsArgs, CommentCountsState, UseCommentCountsArgs, } from "./comments.js";
 export { useViewer } from "./viewer.js";

package/dist/src/row.js

@@ -87,7 +87,15 @@ function datetime(v) {
         return null;
     return new Date(Number(m[1]), (m[2] ? Number(m[2]) : 1) - 1, m[3] ? Number(m[3]) : 1, m[4] ? Number(m[4]) : 0, m[5] ? Number(m[5]) : 0);
 }
-/** One `{ id, display }` object → ResolvedLink, or null if absent/malformed. */
+/**
+ * One `{ id, display }` object → ResolvedLink, or null if absent/malformed.
+ *
+ * A MISSING `display` IS NOT A LINK. Other cells carry `{ id }` without one — a
+ * member is the everyday case — and answering `display: ""` for them made every
+ * assignee read as a blank-named link wherever a reader tried links first. A
+ * link the server resolved always states its display, even as the empty string,
+ * so requiring the KEY costs a real link nothing.
+ */
 function asLink(v) {
     if (!v || typeof v !== "object")
         return null;
@@ -95,7 +103,7 @@ function asLink(v) {
     if (typeof id !== "string" || !id)
         return null;
     const display = v.display;
-    return { id, display: typeof display === "string" ? display : "" };
+    return typeof display === "string" ? { id, display } : null;
 }
 /**
  * select_record_link → the FIRST linked record as `{ id, display }` (or null).

package/dist/src/rpc.js

@@ -568,6 +568,34 @@ export function transportErrorMessage(status, parsed) {
         parsed.code.length > 0;
     return status < 500 || authored ? jsonMessage : gatewayErrorMessage(status);
 }
+/**
+ * A failed request, carrying the per-input refusals when the API named any.
+ *
+ * A body that does not match what an alias declares is answered 400 with
+ * top-level `field_errors` — one sentence per INPUT name, which is what a form
+ * puts on the control that is wrong, where the message can only say it at the
+ * screen's scope. It rides the error because the transport's own callers are
+ * what turn a failure into the result an app reads. Optional throughout: a
+ * server that predates them sends none.
+ */
+class ApiRefusal extends Error {
+    field_errors;
+    constructor(message, field_errors) {
+        super(message);
+        this.field_errors = field_errors;
+    }
+}
+/** The `field_errors` of an error body, when it carries a well-formed one. */
+function readFieldErrors(parsed) {
+    if (parsed === null || typeof parsed !== "object" || !("field_errors" in parsed)) {
+        return undefined;
+    }
+    const raw = parsed.field_errors;
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const named = Object.entries(raw).filter((entry) => typeof entry[1] === "string");
+    return named.length > 0 ? Object.fromEntries(named) : undefined;
+}
 /**
  * The error a stream that never started should throw.
  *
@@ -663,8 +691,9 @@ async function apiCall(method, path, body, opts) {
             return new Promise(() => { });
         }
         // Never surface a non-JSON body (a gateway HTML error page) or a 5xx body as
-        // the message — emit a body-free, status-derived message instead.
-        throw new Error(transportErrorMessage(res.status, parsed));
+        // the message — emit a body-free, status-derived message instead. The
+        // per-input refusals ride along, for the caller that can place them.
+        throw new ApiRefusal(transportErrorMessage(res.status, parsed), readFieldErrors(parsed));
     }
     return parsed ?? (text ? text : {});
 }
@@ -793,7 +822,16 @@ async function standaloneWorkflow(p) {
         // rejection carrying a raw body) so an app reads `result.status === "error"`
         // uniformly with a handled workflow error. `apiCall` already sanitized the
         // message, so it never contains an HTML body.
-        return { status: "error", message: err instanceof Error ? err.message : "The workflow failed to run." };
+        //
+        // A payload the alias refuses is that same shape plus the inputs it named,
+        // which is the half a form can act on — the same key a workflow's own
+        // `return({ field_errors })` arrives under, so a screen wires one control
+        // once whichever half answered.
+        return {
+            status: "error",
+            message: err instanceof Error ? err.message : "The workflow failed to run.",
+            ...(err instanceof ApiRefusal && err.field_errors ? { field_errors: err.field_errors } : {}),
+        };
     }
 }
 async function standaloneAgentRuns(p) {

package/docs/data_fetching.md

@@ -116,6 +116,11 @@ sort for a typed alias names its keys `ColumnKeyOf<"alias">` — `QueryFilter<Co
 `QuerySortKey<…>`; `QueryFilterCondition` and `QueryFilterGroup` take the same parameter — so the
 check reaches the helper that derives the key, not only the hook call that sends it.
 
+**The option map is keyed the same way.** `useFieldOptions(alias).fields` is keyed by that alias's
+projected columns too — ask the alias that CARRIES the column, because a picker fed from a sibling
+query's map is otherwise a control that renders empty with nothing reporting it. Every key is
+optional: [./members_and_options.md](./members_and_options.md).
+
 `@lotics/ui`'s `columnFilterToConditions` carries the same parameter (`FilterableColumn<C>` →
 `FilterConditionNode<C>`), so a per-column filter UI built over a typed alias composes without a
 cast.
@@ -411,10 +416,17 @@ workflows), `__created_at` / `__updated_at` (record timestamps), and per-project
 metadata. A grouped query collapses rows and emits none of these. Details:
 [./queries.md](./queries.md).
 
-A row is typed `QueryRow`: projected columns are `unknown` (the manifest declares them, so the
-readers below are what narrow them), while `__source_record_id` / `__source_table_id` are typed
-`string | undefined` — reachable without a cast, but only after narrowing, because "a grouped query
-emits none of these" is a fact the type states rather than one you have to remember.
+A row is typed from the alias's own projection. Codegen names the columns each query carries
+(`AppQueryColumns` in `.lotics/app_queries.d.ts`) and a row read is bounded to them, so a misspelt
+column, a renamed field and a projection moved to a sibling alias are one `tsc` error rather than a
+blank cell — the server answers an unprojected column with `undefined`, and every reader below
+answers `undefined` with its empty value, so nothing else reports it. The values stay `unknown` (a
+column's TYPE is the field's, which the manifest does not carry, so the readers are the narrowing),
+while `__source_record_id` / `__source_table_id` are typed `string | undefined` — reachable without
+a cast, but only after narrowing, because "a grouped query emits none of these" is a fact the type
+states rather than one you have to remember. Write the row type down as `RowOf<"alias">`; an alias
+whose columns cannot be read off its AST keeps the open `QueryRow`, where any column compiles and
+the server's answer is the only check — the rule the filter keys follow too.
 
 ### The readers
 
@@ -473,7 +485,10 @@ never carry avatar images — the avatar lives on the `useMembers` roster
 
 **`readLinks` / `row.link`.** `display` is the linked record's primary-field text — render it;
 use `id` to correlate, filter (link `has_any_of`), or fetch detail. `row.link` reads the first
-entry only — on a multi-link field use `readLinks`.
+entry only — on a multi-link field use `readLinks`. An entry carrying an `id` and **no
+`display` key** is not a link and is skipped: a member cell has that shape, so reading one as a
+link would otherwise render every assignee under a blank name. Read a member cell with
+`readMembers`.
 
 **`readFiles`.** Each entry's `url` (and `thumbnail_url` for images) is **presigned with a 24-hour
 TTL** — it renders directly in an `<Image>`/preview and works from the sandboxed iframe and for

package/docs/members_and_options.md

@@ -68,8 +68,11 @@ const { fields } = useFieldOptions("orders");   // same alias you query
 
 ### What comes back
 
-`fields` is a `Record<outputColumnName, FieldOptions>` — keyed by the query's **output column
-name**, not the field key. Each `FieldOptions`:
+`fields` is keyed by the query's **output column name**, not the field key — and by *that alias's*
+columns: `Partial<Record<ColumnKeyOf<"alias">, FieldOptions>>`. A key the alias does not project is
+a compile error, so a picker fed from a sibling query's option map fails at your desk instead of
+rendering with no options; and every key is optional, so the read is through `?.` and never a bare
+`.options`. Each `FieldOptions`:
 
 | Property | Meaning |
 | --- | --- |
@@ -80,8 +83,8 @@ name**, not the field key. Each `FieldOptions`:
 - `color` is a named palette token (e.g. `"blue"`, `"emerald"`). Pass the option straight to
   `@lotics/ui`'s `Status`; a missing/unrecognized token degrades to a neutral badge.
 - **A column the server can't map to a single source select field is simply absent** from
-  `fields` — a UNION output whose arms disagree on the source field, or a computed column. Read
-  defensively: `fields.status?.options ?? []`.
+  `fields` — a UNION output whose arms disagree on the source field, or a computed column. That is
+  why the type makes every key optional: `fields.status?.options ?? []`.
 - Addressed by the same alias you query, and scoped exactly like running that query — it exposes
   nothing the query itself doesn't. Params are irrelevant (they only fill filter values, never
   change the projection), so no params argument exists.
@@ -147,7 +150,7 @@ contract as `readSelect`: `[]` for null/empty/unexpected cells, malformed entrie
 The candidate set for an "assign to a member" picker (`dist/src/hooks.d.ts`):
 
 ```tsx
-const { members, loading, error } = useMembers({ group: "grp_fulfillment" });
+const { members, loading, error } = useMembers({ group: GRP.fulfillment });
 <MemberSelect members={members} value={assignee} onValueChange={setAssignee} />
 ```
 
@@ -175,11 +178,17 @@ three gates are observable as an `error` on the hook:
    member declaration gets: *"This app has not declared member access — listing members requires a
    declared workflow `member` input or query `member` param."* Member access is a declared,
    auditable surface, like queries and workflows.
-3. **Declared groups only.** `{ group: "grp_…" }` restricts the roster to one member group — but
+3. **Declared groups only.** `{ group }` restricts the roster to one member group — but
    only a group declared on some member input's `group` property. An undeclared group errors; an
    app can only enumerate groups it actually assigns into. A declared group with no members
    resolves to `{ members: [] }`.
 
+Name the group `GRP.<group>`, from the generated `.lotics/app_fields.ts` — `GRP` is that workspace's
+group directory keyed by slugified display name, so the same source resolves in every copy of the
+app. A pasted `grp_…` id is an id one workspace minted: it resolves to nothing anywhere else, and
+`lotics app check` refuses it. (The manifest DECLARATION below is the exception — it carries the
+concrete id, and publish inverts it.)
+
 ```jsonc
 // package.json → "lotics" — the declaration that unlocks useMembers
 "workflows": {

package/docs/mutations.md

@@ -65,7 +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 |
+| `field_errors` | `Record<string, string>?` | Per-input refusals, keyed by the INPUT name the alias declares — from the server when the payload does not match what the alias declares, and from the workflow's own `return({ field_errors })`. Absent when neither named a field |
 
 ### The failure model: check `status`, never just try/catch
 
@@ -81,6 +81,11 @@ convert every failure into a resolved `{ status: "error", message }`:
 | Alias not bound / workflow deleted | `status: "error"` with the explanatory message |
 | Gateway timeout (a 524 on a long run), any 5xx, a non-JSON error page | `status: "error"` with a friendly, **body-free** message — never raw gateway HTML |
 
+A workflow call is **synchronous end to end** — about 100 s at the edge, 30 s through the bridged
+host — and a timed-out call may still have committed. So model work that can run for minutes belongs
+in an agent run, which is asynchronous by construction and polls to completion, never in a workflow
+step.
+
 So the correct handling is:
 
 ```tsx
@@ -106,8 +111,10 @@ 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:
+Two things refuse a call, and both address the input they refused. A payload that does not match
+what the alias declares — a missing required input, a value of the wrong type — is refused before
+the workflow runs, with one sentence per input name. A workflow that validates its own inputs
+refuses the same way, with both halves — a message for the dialog and a map for the controls:
 
 ```ts
 return({ status: "error", message: "Thiếu lý do.",
@@ -125,7 +132,8 @@ setErrs(result.field_errors ?? {});
 ```
 
 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).
+together (a `Callout` at the dialog's scope plus the per-field text). One reading covers both
+refusals: the key is the same whichever half answered, so a form never branches on that.
 
 ### Generated files come back in `files[]`
 

package/docs/queries.md

@@ -114,7 +114,9 @@ A result is `{ rows, columns, source_fields_by_table_id }` (`+ total` for a coun
 `columns` is the statically computed output schema — `{ name, type, nullable?,
 source_table_id?, source_field_key? }` per column. Rows are plain objects keyed by output
 column name; decode cells with the SDK readers (`row.*`, `readSelect`, `readMembers`,
-`readLinks`, `readFiles` — see [data_fetching.md](./data_fetching.md)).
+`readLinks`, `readFiles` — see [data_fetching.md](./data_fetching.md)). Those output names are also
+the row's TYPE: codegen writes them into `AppQueryColumns`, so reading a column this query does not
+project is a `tsc` error.
 
 **`source_fields_by_table_id` is always `{}`** — the key is part of the shape, the map is not
 filled. The server reads the source tables' field definitions to resolve option and member

package/package.json

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