@lotics/app-sdk 0.87.9 → 0.88.0

package/AGENTS.md

@@ -16,7 +16,7 @@ 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), 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/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/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. |

package/dist/src/hooks.d.ts

@@ -1,7 +1,7 @@
 import { type ImageFidelity } from "./upload/optimize.js";
 import { type AiContextValue } from "./rpc.js";
 import { type AgentUIPart, type PendingChoice, type AgentRunLanding } from "./agent_stream.js";
-import type { AppWorkflows, AppWorkflowResults, AppQueries, AppAgents, AppAgentResults } from "./types.js";
+import type { AppWorkflows, AppWorkflowResults, AppQueries, AppQueryColumns, AppAgents, AppAgentResults } from "./types.js";
 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";
@@ -100,8 +100,11 @@ interface PaginatedQueryState<R> extends QueryStateBase {
  * un-projected `field_key` is rejected), so an app can sort by any column it
  * actually selects without the query template declaring it.
  */
-export interface QuerySortKey {
-    field_key: string;
+export interface QuerySortKey<C extends string = string> {
+    /** One of the query's projected outputs — `AppQueryColumns[alias]` on a
+     *  typed alias, so a column the query does not carry is a compile error
+     *  rather than the server's request-time refusal. */
+    field_key: C;
     order: "asc" | "desc";
     /**
      * Where rows BLANK in this column sit — `"bottom"` when omitted, which is what
@@ -116,10 +119,11 @@ export interface QuerySortKey {
      */
     blank_position?: "top" | "bottom";
 }
-/** A filter condition over one output column (wire shape of a filter node). */
-export interface QueryFilterFieldCondition {
+/** A filter condition over one output column (wire shape of a filter node).
+ *  `C` is the key's type — see `QuerySortKey`. */
+export interface QueryFilterFieldCondition<C extends string = string> {
     node_type: "condition";
-    field_key: string;
+    field_key: C;
     type?: string;
     operator: string;
     value?: unknown;
@@ -135,21 +139,29 @@ export interface QueryFilterRecordIdCondition {
     operator: string;
     value?: unknown;
 }
-export type QueryFilterCondition = QueryFilterFieldCondition | QueryFilterRecordIdCondition;
+export type QueryFilterCondition<C extends string = string> = QueryFilterFieldCondition<C> | QueryFilterRecordIdCondition;
 /** A boolean group of filter nodes (wire shape — recursive). */
-export interface QueryFilterGroup {
+export interface QueryFilterGroup<C extends string = string> {
     node_type: "group";
     logic: "and" | "or";
-    children: Array<QueryFilterCondition | QueryFilterGroup>;
+    children: Array<QueryFilterCondition<C> | QueryFilterGroup<C>>;
 }
 /**
  * Runtime filter applied AFTER the named query, bounded to its output columns
- * (same exposure invariant as `sort`). Build a group from per-column filters
- * with `columnFilterToConditions` (`@lotics/ui/column_filter`).
+ * (same exposure invariant as `sort`) — at compile time through `C`, and again
+ * on the server. Build a group from per-column filters with
+ * `columnFilterToConditions` (`@lotics/ui/column_filter`).
  */
-export type QueryFilter = QueryFilterCondition | QueryFilterGroup;
-/** Options shared by every query hook. */
-export interface BaseQueryOptions {
+export type QueryFilter<C extends string = string> = QueryFilterCondition<C> | QueryFilterGroup<C>;
+/**
+ * The type a runtime `filter`/`sort` key takes on alias `K`: the union codegen
+ * wrote into `AppQueryColumns`, else `string` (the server's check is then the
+ * only one). A computed key must be narrowed to the union to compile.
+ */
+export type ColumnKeyOf<K extends string> = K extends keyof AppQueryColumns ? AppQueryColumns[K] & string : string;
+/** Options shared by every query hook. `C` is the filter/sort key's type — see
+ *  `ColumnKeyOf`. */
+export interface BaseQueryOptions<C extends string = string> {
     /**
      * When `false`, the query does not run: `rows` stays empty, `loading` is
      * false, and no request is sent. Flip it back to `true` to fetch. This is the
@@ -171,21 +183,21 @@ export interface BaseQueryOptions {
      * Sort the result by output columns at runtime. Changing it re-queries (it is
      * part of the cache key). Empty/omitted leaves the query's own order intact.
      */
-    sort?: QuerySortKey[];
+    sort?: QuerySortKey<C>[];
     /**
      * Filter the result by output columns at runtime. Changing it re-queries.
      * Compose from per-column UI filters via `columnFilterToConditions`.
      */
-    filter?: QueryFilter;
+    filter?: QueryFilter<C>;
 }
 /** Options for `useQuery` — a single fetch. */
-export interface QueryOptions extends BaseQueryOptions {
+export interface QueryOptions<C extends string = string> extends BaseQueryOptions<C> {
     /** Max rows to fetch in the one request (a cap, not pagination). The server
      *  still clamps to its own maximum. Omit to fetch up to the server cap. */
     pageSize?: number;
 }
 /** Options for `useInfiniteQuery` — append/load-more. */
-export interface InfiniteQueryOptions extends BaseQueryOptions {
+export interface InfiniteQueryOptions<C extends string = string> extends BaseQueryOptions<C> {
     /** Rows per page. `loadMore()` appends the next page. */
     pageSize: number;
 }
@@ -196,14 +208,14 @@ export interface InfiniteQueryOptions extends BaseQueryOptions {
  * COUNT over the filtered set; ordering it and paginating it are meaningless,
  * and an option a hook silently drops is worse than one that will not compile.
  */
-export type CountOptions = Omit<BaseQueryOptions, "sort">;
+export type CountOptions<C extends string = string> = Omit<BaseQueryOptions<C>, "sort">;
 /** Return value of `useCount` — the size of a filtered set, and nothing else. */
 interface CountState extends QueryStateBase {
     /** Rows in the filtered set. `undefined` until the count resolves. */
     total: number | undefined;
 }
 /** Options for `usePaginatedQuery` — page-model with a total. */
-export interface PaginatedQueryOptions extends BaseQueryOptions {
+export interface PaginatedQueryOptions<C extends string = string> extends BaseQueryOptions<C> {
     /** Rows per page. Default 25. */
     pageSize?: number;
     /**
@@ -289,7 +301,15 @@ export interface WorkflowResult<TData = unknown> {
     files?: UploadedFile[];
     data?: TData;
 }
-type QueryArgs<K extends keyof AppQueries & string, O> = AppQueries[K] extends Record<string, never> ? [params?: Record<string, never>, opts?: O] : [params: AppQueries[K], opts?: O];
+/**
+ * The (params, opts) tail of a query hook for alias `K`: `params` optional when
+ * the alias declares none, required otherwise, then an optional `opts` — a
+ * variadic tuple so `f("a", { … })` and `f("a", params, { … })` both type-check.
+ * ONE conditional signature, never a typed overload beside a loose
+ * `alias: string` one: a rejected filter key would fall through to the loose
+ * overload and compile.
+ */
+type QueryArgs<K extends string, O> = K extends keyof AppQueries ? AppQueries[K] extends Record<string, never> ? [params?: Record<string, never>, opts?: O] : [params: AppQueries[K], opts?: O] : [params?: Record<string, unknown>, opts?: O];
 /**
  * Read rows from a query the app's author declared in `lotics.queries` — a
  * single fetch, no pagination. For long lists use `usePaginatedQuery`
@@ -308,8 +328,7 @@ 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<QueryRow>;
-export declare function useQuery(alias: string, params?: Record<string, unknown>, opts?: QueryOptions): QueryState<QueryRow>;
+export declare function useQuery<K extends string>(alias: K, ...args: QueryArgs<K, QueryOptions<ColumnKeyOf<K>>>): 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 {
@@ -381,8 +400,7 @@ 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<QueryRow>;
-export declare function useInfiniteQuery(alias: string, params?: Record<string, unknown>, opts?: InfiniteQueryOptions): InfiniteQueryState<QueryRow>;
+export declare function useInfiniteQuery<K extends string>(alias: K, ...args: QueryArgs<K, InfiniteQueryOptions<ColumnKeyOf<K>>>): 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
@@ -397,8 +415,7 @@ 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<QueryRow>;
-export declare function usePaginatedQuery(alias: string, params?: Record<string, unknown>, opts?: PaginatedQueryOptions): PaginatedQueryState<QueryRow>;
+export declare function usePaginatedQuery<K extends string>(alias: K, ...args: QueryArgs<K, PaginatedQueryOptions<ColumnKeyOf<K>>>): PaginatedQueryState<QueryRow>;
 /**
  * HOW MANY rows a query matches — one number, no rows fetched.
  *
@@ -434,8 +451,7 @@ export declare function usePaginatedQuery(alias: string, params?: Record<string,
  * return <Badge label={total == null ? "…" : `${total}`} />;
  * ```
  */
-export declare function useCount<K extends keyof AppQueries & string>(alias: K, ...args: QueryArgs<K, CountOptions>): CountState;
-export declare function useCount(alias: string, params?: Record<string, unknown>, opts?: CountOptions): CountState;
+export declare function useCount<K extends string>(alias: K, ...args: QueryArgs<K, CountOptions<ColumnKeyOf<K>>>): CountState;
 /** A file the host has stored and resolved serving URLs for. */
 export interface UploadedFile {
     id: string;

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, useCount, useFieldOptions, useFileUpload, useAttachments, useMembers, useAgentRun, useAgentRuns, useAiContext, buildChoiceOutput, } from "./hooks.js";
-export type { QueryRow, UploadedFile, AttachedFile, BaseQueryOptions, QueryOptions, InfiniteQueryOptions, PaginatedQueryOptions, CountOptions, 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, 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 { useViewer } from "./viewer.js";
@@ -33,7 +33,7 @@ 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 { AppWorkflows, AppWorkflowResults, AppQueries, AppAgents, AppAgentResults } from "./types.js";
+export type { AppWorkflows, AppWorkflowResults, AppQueries, AppQueryColumns, AppAgents, AppAgentResults } from "./types.js";
 export { row, readLinks, readFiles, readLocked } from "./row.js";
 export type { ResolvedLink, AppFile } from "./row.js";
 export { useOptimistic } from "./use_optimistic.js";

package/dist/src/types.d.ts

@@ -68,6 +68,26 @@ export interface AppWorkflowResults {
  */
 export interface AppQueries {
 }
+/**
+ * The OUTPUT COLUMN NAMES each query projects — the same codegen, from the same
+ * manifest, as a literal union per alias:
+ *
+ * ```ts
+ * declare module "@lotics/app-sdk" {
+ *   interface AppQueryColumns {
+ *     "openOrders": "id" | "customer" | "total";
+ *   }
+ * }
+ * ```
+ *
+ * A runtime `filter` / `sort` `field_key` is typed against it, so a column the
+ * query does not carry is a `tsc` error instead of the server's request-time
+ * refusal. An alias is ABSENT when its names cannot be read off the AST alone
+ * (a bare `from_table`); its key stays `string` and the server's check is the
+ * only one — a union that could be wrong is worse than none.
+ */
+export interface AppQueryColumns {
+}
 /**
  * App-specific AGENT augmentation point — same pattern as `AppWorkflows`, for
  * the streaming agents declared in `package.json` lotics.agents and invoked via

package/docs/data_fetching.md

@@ -91,21 +91,41 @@ Per-hook additions:
 | `pageSize: number` | `useInfiniteQuery` | rows per appended page — the options type requires it, though omitting `opts` entirely type-checks and defaults to 30 |
 | `pageSize?: number` | `usePaginatedQuery` | rows per page, default 25 |
 
-Runtime `sort`/`filter` are **server-bounded to the named query's output columns** — a `field_key`
-the query doesn't project is rejected with an error, so a sortable/filterable UI can never widen
-the app's data exposure. The full runtime-refinement contract (which operators are valid per column
-type, record-link membership filtering, and the field-less system conditions — `record_id` works in
-a runtime filter; `locked` / `current_member` are template-only and rejected at the runtime layer)
-lives in [./queries.md](./queries.md).
+Runtime `sort`/`filter` are **bounded to the named query's output columns**, twice over. At
+compile time, `field_key` on a typed alias is the literal union of the columns the query projects —
+codegen writes it into `.lotics/app_queries.d.ts` as `AppQueryColumns[alias]`, read off the query's
+AST by the same naming rule the server applies — so a key the query does not carry fails
+`npm run typecheck` (and therefore `lotics app check` and deploy) at your desk. At request time the
+server checks the same rule again and rejects an un-projected key with an error, so a
+sortable/filterable UI can never widen the app's data exposure even from an untyped call. The full
+runtime-refinement contract (which operators are valid per column type, record-link membership
+filtering, and the field-less system conditions — `record_id` works in a runtime filter; `locked` /
+`current_member` are template-only and rejected at the runtime layer) lives in
+[./queries.md](./queries.md).
+
+**A key you compute must be narrowed, not widened.** A register that derives its filter columns
+from a ladder — `` `hs_${step.leaves}` `` — must type `leaves` as the literal union of the stamps
+it can name, so the template literal resolves to members of `AppQueryColumns[alias]`; a `string`
+there is a compile error on a typed alias, and that error is the point. It is exactly the bug the
+type exists to catch: a rung added to the ladder without its column added to the query, which no
+`app dev` session notices until a member scopes to the one project on that ladder. An alias whose
+columns cannot be known from its AST (a bare `from_table`) has no `AppQueryColumns` entry, and its
+key stays `string` — the server's check is then the only one. A helper that builds a filter or
+sort for a typed alias names its keys `ColumnKeyOf<"alias">` — `QueryFilter<ColumnKeyOf<"register">>`,
+`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.
+
+`@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.
 
 Refinement order is fixed: the runtime **filter narrows** the named query's result, then **sort
 orders** it, then **limit/offset paginate** it. The template's own filters/sort/limit run first,
 inside the named query.
 
-**Limitation:** the exported `QueryFilterCondition` type declares `field_key` as required, but the
-field-less `record_id` system condition documented in [./queries.md](./queries.md) (the one usable
-in a runtime filter) carries no field. To satisfy the type, include `field_key: ""` on it — the
-server validates system conditions by `type` and never reads `field_key` on them.
+The field-less `record_id` system condition documented in [./queries.md](./queries.md) (the one
+usable in a runtime filter) is its own member of `QueryFilterCondition` with no `field_key` at all —
+write it as `{ node_type: "condition", type: "record_id", operator, value }`.
 
 ## Caching, loading states, and errors
 

package/docs/files.md

@@ -99,7 +99,7 @@ to object storage → finalize. The API server never proxies the bytes.
 
 | Bound | Value |
 |---|---|
-| Max file size | 25 MiB (26,214,400 bytes) — enforced at URL mint *and* re-verified at finalize |
+| Max file size | 2 GiB (2,147,483,648 bytes) — enforced at URL mint *and* re-verified at finalize; a video passes through untouched, so this is the bound that matters for one |
 | Allowed MIME types | **any** — type is unrestricted at upload |
 | Upload-URL validity | 10 minutes |
 

package/package.json

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