@lotics/app-sdk 0.62.3 → 0.63.0

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

@@ -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" },
 });
 

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

@@ -442,7 +442,7 @@ derived surfaces share one implementation.
 | formula | its declared output type (`number`/`text`/`boolean`/`date`/`datetime`; `json` until inferred) | filtered by the output type's operators; `#ERROR:` cells are guarded — they count as empty and never match value operators | same | Extracted as a real scalar, so numeric formulas feed `sum`/`avg`/sorts. A **datetime-output** formula matches day-level date filters (full-day expansion). |
 | rollup | number-returning ops → `number`; `earliest`/`latest`/`date_range` → `date`/`datetime` per the aggregated field's format | number or date operators per output type; text operators route as text | same | Datetime-format rollups match day-level date filters. |
 | lookup | the looked-up field's type | operators of the looked-up type, evaluated with ANY-element semantics over the linked values (a row matches if *any* linked value matches) | array-typed lookups follow their column type's rules | **Projection returns the first element only.** Emptiness on a files-lookup checks the inner file arrays (a linked record with zero files counts empty). For all values across links: unnest the link column + join (§8). |
-| autonumber | `text` | text operators — filter by the visible composed string (`"ORD-0042"`) | same | Lexical sort matches numeric order (constant prefix + padding). |
+| autonumber | `text` | text operators — filter by the visible composed string (`"ORD-0042"`) | same | Sorts numerically when the stored value is a bare integer, lexicographically otherwise — so `"ORD-0042"` orders by its padding and an unprefixed `"124"` orders after `"99"`, not before it. |
 | button | `json` | **not filterable** — buttons are not data | — | Project/ignore; only presence-counting aggregates. |
 
 **Field-less conditions** (no `field_key`):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.62.3",
+  "version": "0.63.0",
   "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"