@lotics/app-sdk 0.62.2 → 0.62.4

package/AGENTS.md

@@ -15,7 +15,7 @@ signature; open the file.**
 | Doc | Read it for |
 |---|---|
 | [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 three read hooks (`useQuery`/`useInfiniteQuery`/`usePaginatedQuery`), cell readers (`row.*`, `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`), `useFieldOptions`, data discipline, the search-as-you-type + record-picker patterns. |
+| [docs/data_fetching.md](./docs/data_fetching.md) | The three read hooks (`useQuery`/`useInfiniteQuery`/`usePaginatedQuery`), the `QueryRow` shape (projected columns `unknown`; `__source_record_id`/`__source_table_id` typed but optional), cell readers (`row.*`, `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`), `useFieldOptions`, data discipline, 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, diff-before-update, locked records, `useOptimistic`, 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 + link 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. |
@@ -38,6 +38,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)
+- **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)
 - **Errors fail loud** — no swallowed catches, no silent fallbacks.
 
 ## Keeping this reference current

package/dist/src/comments.d.ts

@@ -62,10 +62,18 @@ export interface UseCommentsArgs {
     record_id: string;
 }
 /**
+ * `record_id` must be a REAL id. The fetch keys on `available` alone, so an
+ * empty string is not skipped — it fetches comments for nothing. When the id
+ * comes off a row's `__source_record_id` addressing column, narrow it first: a
+ * grouped query carries none, and a hook cannot be called conditionally, so the
+ * guard belongs at the component that renders the panel.
+ *
  * ```tsx
- * const { comments, available, createComment } = useComments({
- *   record_id: row.__source_record_id,
- * });
+ * // In a record screen, where an id definitionally exists:
+ * const { comments, available, createComment } = useComments({ record_id: recordId });
+ *
+ * // From a row, gate the whole panel rather than passing a placeholder:
+ * {row.__source_record_id && <CommentsPanel recordId={row.__source_record_id} />}
  * ```
  */
 export declare function useComments(args: UseCommentsArgs): CommentsState;

package/dist/src/comments.js

@@ -38,10 +38,18 @@ function toStorageFiles(files) {
 }
 let optimisticCounter = 0;
 /**
+ * `record_id` must be a REAL id. The fetch keys on `available` alone, so an
+ * empty string is not skipped — it fetches comments for nothing. When the id
+ * comes off a row's `__source_record_id` addressing column, narrow it first: a
+ * grouped query carries none, and a hook cannot be called conditionally, so the
+ * guard belongs at the component that renders the panel.
+ *
  * ```tsx
- * const { comments, available, createComment } = useComments({
- *   record_id: row.__source_record_id,
- * });
+ * // In a record screen, where an id definitionally exists:
+ * const { comments, available, createComment } = useComments({ record_id: recordId });
+ *
+ * // From a row, gate the whole panel rather than passing a placeholder:
+ * {row.__source_record_id && <CommentsPanel recordId={row.__source_record_id} />}
  * ```
  */
 export function useComments(args) {

package/dist/src/hooks.d.ts

@@ -6,6 +6,41 @@ import type { ResolvedMember } from "./members.js";
 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.
+ *
+ * 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 `__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
+ * — what `useComments`, a workflow's `record_id` input, and `useAiContext`'s
+ * record refs all need. Typed as `unknown` they were unusable without a cast,
+ * which is how this SDK's own examples came to show code that does not compile.
+ *
+ * They are OPTIONAL, and that is the honest shape rather than a hedge: a
+ * grouped query collapses rows, so its output has no originating record and the
+ * compiler emits no addressing columns for it (the platform's own `record_id`
+ * filter refuses such a query for exactly this reason). Narrow before use —
+ * on an aggregate row these are genuinely absent, not merely unproven.
+ *
+ * The line for what belongs here is "consumed RAW", not "starts with
+ * `__source_`". A row also carries `__source_locked`, `__created_at` /
+ * `__updated_at` and per-projection `__src_field_*`, and each of those has a
+ * reader that owns its decoding (`readLocked`, the `row.*` helpers) — a reader
+ * IS the narrowing, so a type here would duplicate it. Only these two are
+ * handed straight to a `record_id` / `table_id` parameter with nothing in
+ * between, which is why only these two needed a type.
+ */
+export interface QueryRow {
+    [column: string]: unknown;
+    /** The record this row came from. Absent on a grouped/aggregated row. */
+    __source_record_id?: string;
+    /** The table that record lives in. Absent on a grouped/aggregated row. */
+    __source_table_id?: string;
+}
 /** Fields shared by every query hook's return value. */
 interface QueryStateBase {
     /**
@@ -152,7 +187,9 @@ export interface PaginatedQueryOptions extends BaseQueryOptions {
  *
  * ```tsx
  * const issue = useWorkflow("issueInvoiceStorageDrop");
- * await issue({ record_id: row.__source_record_id });
+ * // Guard the addressing column: a grouped query's rows carry none, and the
+ * // workflow would be handed `undefined` where it declares a record.
+ * if (row.__source_record_id) await issue({ record_id: row.__source_record_id });
  * ```
  */
 export declare function useWorkflow<K extends keyof AppWorkflows & string>(alias: K): UseWorkflowFn<K>;
@@ -199,8 +236,8 @@ type QueryArgs<K extends keyof AppQueries & string, O> = AppQueries[K] extends R
  * with the declared alias → param-type map, so an undeclared alias is a
  * compile-time error and params are typed per the manifest.
  */
-export declare function useQuery<K extends keyof AppQueries & string>(alias: K, ...args: QueryArgs<K, QueryOptions>): QueryState<Record<string, unknown>>;
-export declare function useQuery(alias: string, params?: Record<string, unknown>, opts?: QueryOptions): QueryState<Record<string, unknown>>;
+export declare function useQuery<K extends keyof AppQueries & string>(alias: K, ...args: QueryArgs<K, QueryOptions>): QueryState<QueryRow>;
+export declare function useQuery(alias: string, params?: Record<string, unknown>, opts?: QueryOptions): QueryState<QueryRow>;
 /** 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 {
@@ -272,8 +309,8 @@ export declare function useFieldOptions(alias: string, opts?: FieldOptionsOption
  * const { rows, loadMore, hasMore } = useInfiniteQuery("feed", {}, { pageSize: 30 });
  * ```
  */
-export declare function useInfiniteQuery<K extends keyof AppQueries & string>(alias: K, ...args: QueryArgs<K, InfiniteQueryOptions>): InfiniteQueryState<Record<string, unknown>>;
-export declare function useInfiniteQuery(alias: string, params?: Record<string, unknown>, opts?: InfiniteQueryOptions): InfiniteQueryState<Record<string, unknown>>;
+export declare function useInfiniteQuery<K extends keyof AppQueries & string>(alias: K, ...args: QueryArgs<K, InfiniteQueryOptions>): InfiniteQueryState<QueryRow>;
+export declare function useInfiniteQuery(alias: string, params?: Record<string, unknown>, opts?: InfiniteQueryOptions): InfiniteQueryState<QueryRow>;
 /**
  * Page-model query with a total — the data hook behind a numbered, jumpable
  * table (pairs with `@lotics/ui/pagination`). It owns the page
@@ -288,8 +325,8 @@ export declare function useInfiniteQuery(alias: string, params?: Record<string,
  *   usePaginatedQuery("orders", { q }, { pageSize: 25, sort, filter });
  * ```
  */
-export declare function usePaginatedQuery<K extends keyof AppQueries & string>(alias: K, ...args: QueryArgs<K, PaginatedQueryOptions>): PaginatedQueryState<Record<string, unknown>>;
-export declare function usePaginatedQuery(alias: string, params?: Record<string, unknown>, opts?: PaginatedQueryOptions): PaginatedQueryState<Record<string, unknown>>;
+export declare function usePaginatedQuery<K extends keyof AppQueries & string>(alias: K, ...args: QueryArgs<K, PaginatedQueryOptions>): PaginatedQueryState<QueryRow>;
+export declare function usePaginatedQuery(alias: string, params?: Record<string, unknown>, opts?: PaginatedQueryOptions): PaginatedQueryState<QueryRow>;
 /** A file the host has stored and resolved serving URLs for. */
 export interface UploadedFile {
     id: string;
@@ -412,7 +449,14 @@ export declare function useAttachments(): AttachmentsState;
  * ```tsx
  * useAiContext("orders_list", {
  *   description: `Viewing ${rows.length} orders filtered to status=open, sorted by due date.`,
- *   records: rows.map((r) => ({ table_id: r.__source_table_id, record_id: r.__source_record_id })),
+ *   // `flatMap` + the guard, not `map`: the addressing columns are absent on a
+ *   // GROUPED query's rows, so a ref built without checking carries `undefined`
+ *   // and points the agent at nothing.
+ *   records: rows.flatMap((r) =>
+ *     r.__source_table_id && r.__source_record_id
+ *       ? [{ table_id: r.__source_table_id, record_id: r.__source_record_id }]
+ *       : [],
+ *   ),
  *   data: { filter: "status=open", sort: "due_date desc" },
  * });
  * ```

package/dist/src/hooks.js

@@ -373,7 +373,14 @@ function serializeAiContext(context) {
  * ```tsx
  * useAiContext("orders_list", {
  *   description: `Viewing ${rows.length} orders filtered to status=open, sorted by due date.`,
- *   records: rows.map((r) => ({ table_id: r.__source_table_id, record_id: r.__source_record_id })),
+ *   // `flatMap` + the guard, not `map`: the addressing columns are absent on a
+ *   // GROUPED query's rows, so a ref built without checking carries `undefined`
+ *   // and points the agent at nothing.
+ *   records: rows.flatMap((r) =>
+ *     r.__source_table_id && r.__source_record_id
+ *       ? [{ table_id: r.__source_table_id, record_id: r.__source_record_id }]
+ *       : [],
+ *   ),
  *   data: { filter: "status=open", sort: "due_date desc" },
  * });
  * ```

package/dist/src/index.d.ts

@@ -17,7 +17,7 @@
 export { mount } from "./mount.js";
 export type { MountOptions } from "./mount.js";
 export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useFieldOptions, useFileUpload, useAttachments, useMembers, useAgentRun, useAgentRuns, useAiContext, buildChoiceOutput, } from "./hooks.js";
-export type { UploadedFile, AttachedFile, BaseQueryOptions, QueryOptions, InfiniteQueryOptions, PaginatedQueryOptions, QuerySortKey, QueryFilter, QueryFilterCondition, QueryFilterGroup, WorkflowResult, MembersOptions, AgentRunOptions, UseAgentRun, AgentRunLanding, AgentRunRecord, AgentRunState, AgentUIPart, PendingChoice, ChoiceQuestion, ChoiceOption, AskUserChoiceOutput, FieldOptions, FieldOptionsState, FieldOptionsOptions, } from "./hooks.js";
+export type { QueryRow, UploadedFile, AttachedFile, BaseQueryOptions, QueryOptions, InfiniteQueryOptions, PaginatedQueryOptions, QuerySortKey, QueryFilter, QueryFilterCondition, 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 { useViewer } from "./viewer.js";

package/docs/ai.md

@@ -22,7 +22,7 @@ A declaration carries:
 | `instructions` | System instructions — the task the agent performs per run |
 | `tool_names` | The tools the agent may call, resolved against the platform's automation tool registry. The capability boundary for everything EXCEPT workspace data — the run can use nothing else. May be empty — including for an agent that reads documents, since a [`file` input carries its own content](#file-inputs--what-the-agent-can-actually-see) |
 | `knowledge_doc_ids` | The knowledge docs the agent may read, and the whole set it can reach — a doc absent from this list is unreadable even if the agent names its id. Declare `grep_knowledge` / `read_knowledge` in `tool_names` to read them. There is no size limit and nothing is inlined, so a multi-megabyte reference corpus (a full tariff, a regulation set) is a normal declaration. Reach for `code_exec` only to COMPUTE across the corpus — counting, cross-referencing — never merely to read it |
-| `query_aliases` | The app's own named queries the agent may run via `run_app_query` — its **entire read surface** over records |
+| `query_aliases` | The app's own named queries the agent may run via `run_app_query` — its **entire read surface** over records. You list them; there is no "all of them" shorthand, and adding a query to the app never widens an existing agent. Omitted means the agent reads nothing |
 | `workflow_aliases` | The app's own workflows the agent may invoke via `run_app_workflow` — its **entire write surface** |
 | `model_id` | Optional chat model pin. Omit (preferred) to follow the platform default chat model, resolved at run time — the agent tracks model generations with no rewrite. Pin only a deliberate, tested choice |
 | `effort_level` | Optional reasoning depth for adaptive-thinking models. Requires an explicit `model_id` pin — effort is tuned per model |
@@ -277,7 +277,13 @@ import { useAiContext } from "@lotics/app-sdk";
 // A list screen publishes what it rendered:
 useAiContext("orders_list", {
   description: `Viewing ${rows.length} orders filtered to status=open, sorted by due date.`,
-  records: rows.map((r) => ({ table_id: r.__source_table_id, record_id: r.__source_record_id })),
+  // Guarded, not `map`: the addressing columns are absent on a GROUPED query's
+  // rows, so an unchecked ref carries `undefined` and points the agent at nothing.
+  records: rows.flatMap((r) =>
+    r.__source_table_id && r.__source_record_id
+      ? [{ table_id: r.__source_table_id, record_id: r.__source_record_id }]
+      : [],
+  ),
   data: { filter: "status=open", sort: "due_date desc" },
 });
 
@@ -337,6 +343,13 @@ gated per turn on `app:use` for the app in the member's workspace, and runs
 under the app's OWNER authority with `is_current_member` bound to the MEMBER
 (exactly as the app's own UI does).
 
+The agent is handed a **catalog** of those aliases — each one's params and its
+`description` (a query's own, [declared in the manifest](./queries.md); a
+workflow's, off its workflow row) — so it picks the right one instead of
+guessing an alias and learning the list from a refusal. Your descriptions are
+what it reads, on this surface and inside your own agents' runs. They enter the
+prompt as a capability listing, never as instructions.
+
 **Writes carry a second gate that reads do not: `run_app_workflow` asks the
 member to approve every call from chat.** A wrong read is fixed by asking
 again; a wrong write is not. The alias list bounds what an agent *could* reach;

package/docs/data_fetching.md

@@ -246,6 +246,11 @@ 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.
+
 ### The readers
 
 | Reader | In → out | Semantics |

package/docs/files.md

@@ -265,6 +265,9 @@ with `files` absent.
 
 ```tsx
 const generate = useWorkflow("generateInvoice");
+// `__source_record_id` is optional — a grouped query carries none — so narrow it
+// rather than handing the workflow `undefined` where it declares a record.
+if (!row.__source_record_id) return;
 const result = await generate({ record_id: row.__source_record_id });
 if (result.status === "success" && result.files?.length) {
   await openExternal(result.files[0].url);

package/docs/members_and_options.md

@@ -241,13 +241,18 @@ client-side up front, and re-checked server-side.
 ### Reading & writing
 
 ```tsx
-const { comments, available, createComment } = useComments({
-  record_id: row.__source_record_id,
-});
+// In a record screen, where an id definitionally exists:
+const { comments, available, createComment } = useComments({ record_id: recordId });
+
+// From a row, gate the whole panel rather than passing a placeholder:
+{row.__source_record_id && <CommentsPanel recordId={row.__source_record_id} />}
 ```
 
-`record_id` comes from the row's `__source_record_id` addressing column (see
-[queries](./queries.md)). State: `{ comments, loading, error, available, createComment,
+`record_id` must be a **real** id — the fetch keys on `available` alone, so an empty string is not
+skipped, it fetches comments for nothing. When the id comes from a row's `__source_record_id`
+addressing column (see [queries](./queries.md)) narrow it first: a grouped query emits no addressing
+columns, and a hook cannot be called conditionally, so the guard belongs at the component that
+renders the panel. State: `{ comments, loading, error, available, createComment,
 updateComment, deleteComment, refetch }`.
 
 - `comments` — newest first on the wire (server order). Pass the array as-is to `@lotics/ui`'s

package/docs/queries.md

@@ -35,7 +35,8 @@ Queries live in the app's `package.json` under `lotics.queries` — an alias →
       },
       "orderByCode": {
         "ast": { /* … a filter with "{{params.code}}" … */ },
-        "params": { "code": { "type": "text" } }
+        "params": { "code": { "type": "text" } },
+        "description": "One order by its code, with its customer and line total."
       }
     }
   }
@@ -48,9 +49,15 @@ Queries live in the app's `package.json` under `lotics.queries` — an alias →
   (`text`, `number`, `boolean`, `date`, `datetime`, `email`, `select`, `member`, `record_link`,
   `date_range`, `file`, `json`, `object`, `array`); each param may set `required: false`
   (default is required) and `description`. Nesting is capped at depth 8.
+- **`description`** — one line saying what the query returns, capped at 300 characters. No app
+  code reads it. It is for the **agents** that reach this app's data — the app's own declared
+  agents, and a member's chat while they have the app open — which otherwise see only an alias,
+  a JS identifier that names a query without saying what it covers. Write it for whoever has to
+  choose between your aliases; longer guidance belongs in an agent's own `instructions`.
 - Aliases must be valid JS identifiers (`useQuery("openOrders")` and codegen depend on it).
 
-`lotics app deploy` syncs this map to the server. The **server holds the canonical template**;
+`lotics app query set <alias>` (or `--all`) pushes this map to the server — a **deploy does
+not**, it echoes the live row back unchanged. The **server holds the canonical template**;
 the app never sends a raw AST over the wire. This is the exposure model: a public app can read
 exactly what its author's queries project — params fill declared value holes and can never
 widen the query's reach (a token in a `table_id` or field-key position fails deploy validation).
@@ -59,7 +66,8 @@ widen the query's reach (a token in a `table_id` or field-key position fails dep
 
 Deploy fails — with the compiler's own message, never raw SQL/Postgres text — when any alias:
 
-1. isn't a valid identifier, or the declaration isn't `{ ast, params? }`;
+1. isn't a valid identifier, or the declaration isn't `{ ast, params?, description? }` (a
+   description over 300 characters is refused here too);
 2. references `{{params.x}}` without declaring param `x` (typos can't silently widen);
 3. doesn't parse as a `QueryNode` **as the raw template** (the runtime parses the stored
    template before substitution, so a template that only parses after substitution would fail
@@ -99,7 +107,7 @@ executes it inside a bounded transaction.
   (`private_filters`) are excluded on every reach — base scans, link extraction, and
   non-self-scoped traversals alike. (Row scopes don't apply when the app owner is an admin.)
 - **Dev loop**: `lotics app dev` forwards query RPCs to the **deployed** manifest. Editing
-  `lotics.queries` locally does nothing until you `lotics app deploy`.
+  `lotics.queries` locally does nothing until you `lotics app query set`.
 
 ### Results
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.62.2",
+  "version": "0.62.4",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {
@@ -20,7 +20,7 @@
     "docs"
   ],
   "scripts": {
-    "build": "tsgo",
+    "build": "tsgo -p tsconfig.build.json",
     "typecheck": "tsgo --noEmit",
     "test": "vitest run",
     "prepublishOnly": "npm run build"