@lotics/app-sdk 0.94.0 → 0.95.0

package/AGENTS.md

@@ -16,10 +16,10 @@ 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 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/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` and `row.bool` answer `null` for an EMPTY cell, so none is distinguishable from zero and an unanswered checkbox from a "no" — `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/files.md](./docs/files.md) | Files end to end — `useFileUpload`, `useAttachments` (**the add-queue, and which lifecycle it keeps**: a composer clears, a record passes `landed` and each entry leaves as the stored pile takes it over), `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` (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. |

package/dist/src/attachments.d.ts

@@ -0,0 +1,68 @@
+import type { ImageFidelity } from "./upload/optimize.js";
+/** A file attached to a surface — its local preview is available immediately,
+ *  its stored `file_id` once the background upload completes. */
+export interface AttachedFile {
+    /** Stable local id — the React key and the `remove(id)` handle. */
+    id: string;
+    filename: string;
+    mime_type: string;
+    /** Local object-URL preview, available the INSTANT the file is added (before upload). */
+    preview_url: string;
+    status: "uploading" | "ready" | "error";
+    /** The stored file id, set once `status` is `"ready"` — pass to a workflow/agent. */
+    file_id?: string;
+}
+export interface AttachmentsOptions {
+    /**
+     * The stored ids the DESTINATION now holds. Every queued entry among them has
+     * arrived, so it leaves the queue and its preview URL is revoked.
+     *
+     * This is what makes the queue a record's rather than a composer's: pass what
+     * the row came back with and the queue hands over to the pile exactly as the
+     * pile takes it, with no window where neither is on screen. Pass nothing and
+     * the queue accumulates until `clear`.
+     */
+    landed?: readonly string[];
+}
+export interface AttachmentsState {
+    /** The current attachments, in the order added. */
+    files: AttachedFile[];
+    /**
+     * Add picked/pasted/dropped files — each shows its local preview at once and
+     * uploads in the background. Picking is the app's choice: wire a button to
+     * `@lotics/ui` `pickFiles`, or a paste/drop handler, then call this.
+     */
+    add: (files: File[], options?: {
+        fidelity?: ImageFidelity;
+    }) => void;
+    /**
+     * The same add, ANSWERED WHEN EVERY ONE OF THEM IS STORED — the ids, in the
+     * order given. What a write waits on: a record told it holds files whose
+     * bytes are still going up names ids the workspace does not have.
+     *
+     * Rejects with the first refusal instead of answering short, and the queue
+     * keeps every entry with its own status, so the reader sees which one failed
+     * and the ones that succeeded are not silently written without it.
+     */
+    attach: (files: File[], options?: {
+        fidelity?: ImageFidelity;
+    }) => Promise<string[]>;
+    /** Remove one attachment and revoke its preview URL. */
+    remove: (id: string) => void;
+    /** Remove all attachments and revoke their preview URLs. */
+    clear: () => void;
+    /** True while any attachment is still uploading — gate Send on it. */
+    uploading: boolean;
+    /** Stored file ids of the completed uploads — the workflow/agent payload. */
+    fileIds: string[];
+}
+/**
+ * The queue itself, over whichever upload the caller runs through. `upload` is
+ * typed by what this needs of it — a stored id — so the transport is the
+ * caller's to bring.
+ */
+export declare function useAttachmentQueue(upload: (file: File, options?: {
+    fidelity?: ImageFidelity;
+}) => Promise<{
+    id: string;
+}>, options?: AttachmentsOptions): AttachmentsState;

package/dist/src/attachments.js

@@ -0,0 +1,93 @@
+/**
+ * THE ADD-QUEUE — one owner of the preview → upload → id → revoke lifecycle,
+ * apart from the transport that carries the bytes.
+ *
+ * A surface that takes files has the same four moments wherever it stands: a
+ * local preview the instant one is picked, an upload in the background, the
+ * stored id when it lands, and the object URL revoked when the entry is done
+ * with. What differs is only WHEN an entry is done with — a composer keeps its
+ * pile until it sends, a record's section keeps one until the row comes back
+ * holding it — so the lifecycle is stated once and the caller says which.
+ *
+ * Parameterised by the upload rather than reaching for it, so the queue is the
+ * same queue wherever the bytes go.
+ */
+import { useCallback, useEffect, useState } from "react";
+let attachSeq = 0;
+/**
+ * What the landed ids are joined by to make the effect's one dependency, and
+ * split back on. A stored id is an opaque token with no punctuation in it; one
+ * that carried this would simply not match, leaving its own tile standing —
+ * never taking a different one away.
+ */
+const LANDED_SEPARATOR = ",";
+/**
+ * The queue itself, over whichever upload the caller runs through. `upload` is
+ * typed by what this needs of it — a stored id — so the transport is the
+ * caller's to bring.
+ */
+export function useAttachmentQueue(upload, options) {
+    const [files, setFiles] = useState([]);
+    const start = useCallback((file, uploadOptions) => {
+        const id = `att_${(attachSeq += 1)}`;
+        const previewUrl = URL.createObjectURL(file);
+        setFiles((prev) => [
+            ...prev,
+            { id, filename: file.name, mime_type: file.type, preview_url: previewUrl, status: "uploading" },
+        ]);
+        // SETTLES, NEVER REJECTS: the queue entry is where a failure is recorded,
+        // so a caller that only wanted the preview holds no rejected promise.
+        return upload(file, uploadOptions).then((uploaded) => {
+            setFiles((prev) => prev.map((f) => (f.id === id ? { ...f, status: "ready", file_id: uploaded.id } : f)));
+            return { kind: "stored", id: uploaded.id };
+        }, (cause) => {
+            setFiles((prev) => prev.map((f) => (f.id === id ? { ...f, status: "error" } : f)));
+            return { kind: "failed", reason: cause instanceof Error ? cause : new Error(String(cause)) };
+        });
+    }, [upload]);
+    const add = useCallback((incoming, uploadOptions) => {
+        for (const file of incoming)
+            void start(file, uploadOptions);
+    }, [start]);
+    const attach = useCallback(async (incoming, uploadOptions) => {
+        const settled = await Promise.all(incoming.map((file) => start(file, uploadOptions)));
+        const refused = settled.find((one) => one.kind === "failed");
+        if (refused?.kind === "failed")
+            throw refused.reason;
+        return settled.flatMap((one) => (one.kind === "stored" ? [one.id] : []));
+    }, [start]);
+    const remove = useCallback((id) => {
+        setFiles((prev) => {
+            const target = prev.find((f) => f.id === id);
+            if (target)
+                URL.revokeObjectURL(target.preview_url);
+            return prev.filter((f) => f.id !== id);
+        });
+    }, []);
+    const clear = useCallback(() => {
+        setFiles((prev) => {
+            for (const f of prev)
+                URL.revokeObjectURL(f.preview_url);
+            return [];
+        });
+    }, []);
+    // The IDS are the dependency, not the array holding them: a caller reading
+    // them off a row builds a fresh array every render.
+    const landedKey = options?.landed === undefined ? null : options.landed.join(LANDED_SEPARATOR);
+    useEffect(() => {
+        if (landedKey === null)
+            return;
+        const taken = new Set(landedKey === "" ? [] : landedKey.split(LANDED_SEPARATOR));
+        setFiles((prev) => {
+            const arrived = prev.filter((f) => f.file_id !== undefined && taken.has(f.file_id));
+            if (arrived.length === 0)
+                return prev;
+            for (const f of arrived)
+                URL.revokeObjectURL(f.preview_url);
+            return prev.filter((f) => !arrived.includes(f));
+        });
+    }, [landedKey]);
+    const uploading = files.some((f) => f.status === "uploading");
+    const fileIds = files.flatMap((f) => (f.status === "ready" && f.file_id ? [f.file_id] : []));
+    return { files, add, attach, remove, clear, uploading, fileIds };
+}

package/dist/src/hooks.d.ts

@@ -1,4 +1,5 @@
 import { type ImageFidelity } from "./upload/optimize.js";
+import { type AttachmentsOptions, type AttachmentsState } from "./attachments.js";
 import { type AiContextValue } from "./rpc.js";
 import { type AgentUIPart, type PendingChoice, type AgentRunLanding } from "./agent_stream.js";
 import type { AppWorkflows, AppWorkflowResults, AppQueries, AppQueryColumns, AppAgents, AppAgentResults } from "./types.js";
@@ -550,44 +551,16 @@ interface FileUploadState {
  * ```
  */
 export declare function useFileUpload(): FileUploadState;
-/** A file attached to a composer — its local preview is available immediately,
- *  its stored `file_id` once the background upload completes. */
-export interface AttachedFile {
-    /** Stable local id — the React key and the `remove(id)` handle. */
-    id: string;
-    filename: string;
-    mime_type: string;
-    /** Local object-URL preview, available the INSTANT the file is added (before upload). */
-    preview_url: string;
-    status: "uploading" | "ready" | "error";
-    /** The stored file id, set once `status` is `"ready"` — pass to a workflow/agent. */
-    file_id?: string;
-}
-interface AttachmentsState {
-    /** The current attachments, in the order added. */
-    files: AttachedFile[];
-    /** Add picked/pasted/dropped files — each shows its local preview at once and
-     *  uploads in the background. Picking is the app's choice: wire a button to
-     *  `@lotics/ui` `pickFiles`, or a paste/drop handler, then call this. */
-    add: (files: File[], options?: {
-        fidelity?: ImageFidelity;
-    }) => void;
-    /** Remove one attachment and revoke its preview URL. */
-    remove: (id: string) => void;
-    /** Remove all attachments and revoke their preview URLs. */
-    clear: () => void;
-    /** True while any attachment is still uploading — gate Send on it. */
-    uploading: boolean;
-    /** Stored file ids of the completed uploads — the workflow/agent payload. */
-    fileIds: string[];
-}
 /**
- * Composer attachments with the chat's optimistic-preview UX: a local object-URL
- * preview shows the INSTANT a file is added, the upload runs in the background,
- * and the stored `file_id` lands in `files` when it completes. Previews are
- * revoked on remove/clear. Picking is the app's (button / paste / drop) — pass
- * the resulting `File[]` to `add`; the hook owns the preview → upload → id →
- * revoke lifecycle so apps don't re-implement it.
+ * Attachments with the optimistic-preview UX: a local object-URL preview shows
+ * the INSTANT a file is added, the upload runs in the background, and the
+ * stored `file_id` lands in `files` when it completes. Picking is the app's
+ * (button / paste / drop) — pass the resulting `File[]` to `add`, or to
+ * `attach` where a write has to wait for the ids.
+ *
+ * WHICH LIFECYCLE is the caller's one decision. A composer accumulates and
+ * clears when it sends; a record's section passes what its row now holds as
+ * `landed`, and each entry leaves the queue as the pile takes it over.
  *
  * ```tsx
  * const { files, add, remove, clear, uploading, fileIds } = useAttachments();
@@ -602,8 +575,10 @@ interface AttachmentsState {
  * //   ))
  * // send:    design({ photo: fileIds[0] }); clear();
  * ```
+ *
+ * The queue is `useAttachmentQueue`, bound here to the app's own upload.
  */
-export declare function useAttachments(): AttachmentsState;
+export declare function useAttachments(options?: AttachmentsOptions): AttachmentsState;
 /**
  * Publish a slice of the CURRENT SCREEN's view state to the app's ambient chat
  * agent, so a member chatting alongside the app gets an agent that knows what

package/dist/src/hooks.js

@@ -17,6 +17,7 @@
  */
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { DEFAULT_IMAGE_FIDELITY } from "./upload/optimize.js";
+import { useAttachmentQueue } from "./attachments.js";
 import useSWR from "swr";
 import useSWRInfinite from "swr/infinite";
 import { rpc, rpcAgentRun, rpcAgentRunContinue, postHostNotification, subscribeQueriesChanged, registerQueryAlias, notifyLocalWrite, } from "./rpc.js";
@@ -408,14 +409,16 @@ export function useFileUpload() {
     }, []);
     return { upload, uploading: inFlight > 0, error };
 }
-let attachSeq = 0;
 /**
- * Composer attachments with the chat's optimistic-preview UX: a local object-URL
- * preview shows the INSTANT a file is added, the upload runs in the background,
- * and the stored `file_id` lands in `files` when it completes. Previews are
- * revoked on remove/clear. Picking is the app's (button / paste / drop) — pass
- * the resulting `File[]` to `add`; the hook owns the preview → upload → id →
- * revoke lifecycle so apps don't re-implement it.
+ * Attachments with the optimistic-preview UX: a local object-URL preview shows
+ * the INSTANT a file is added, the upload runs in the background, and the
+ * stored `file_id` lands in `files` when it completes. Picking is the app's
+ * (button / paste / drop) — pass the resulting `File[]` to `add`, or to
+ * `attach` where a write has to wait for the ids.
+ *
+ * WHICH LIFECYCLE is the caller's one decision. A composer accumulates and
+ * clears when it sends; a record's section passes what its row now holds as
+ * `landed`, and each entry leaves the queue as the pile takes it over.
  *
  * ```tsx
  * const { files, add, remove, clear, uploading, fileIds } = useAttachments();
@@ -430,41 +433,12 @@ let attachSeq = 0;
  * //   ))
  * // send:    design({ photo: fileIds[0] }); clear();
  * ```
+ *
+ * The queue is `useAttachmentQueue`, bound here to the app's own upload.
  */
-export function useAttachments() {
+export function useAttachments(options) {
     const { upload } = useFileUpload();
-    const [files, setFiles] = useState([]);
-    const add = useCallback((incoming, options) => {
-        for (const file of incoming) {
-            const id = `att_${(attachSeq += 1)}`;
-            const previewUrl = URL.createObjectURL(file);
-            setFiles((prev) => [
-                ...prev,
-                { id, filename: file.name, mime_type: file.type, preview_url: previewUrl, status: "uploading" },
-            ]);
-            upload(file, options)
-                .then((uploaded) => setFiles((prev) => prev.map((f) => (f.id === id ? { ...f, status: "ready", file_id: uploaded.id } : f))))
-                .catch(() => setFiles((prev) => prev.map((f) => (f.id === id ? { ...f, status: "error" } : f))));
-        }
-    }, [upload]);
-    const remove = useCallback((id) => {
-        setFiles((prev) => {
-            const target = prev.find((f) => f.id === id);
-            if (target)
-                URL.revokeObjectURL(target.preview_url);
-            return prev.filter((f) => f.id !== id);
-        });
-    }, []);
-    const clear = useCallback(() => {
-        setFiles((prev) => {
-            for (const f of prev)
-                URL.revokeObjectURL(f.preview_url);
-            return [];
-        });
-    }, []);
-    const uploading = files.some((f) => f.status === "uploading");
-    const fileIds = files.flatMap((f) => (f.status === "ready" && f.file_id ? [f.file_id] : []));
-    return { files, add, remove, clear, uploading, fileIds };
+    return useAttachmentQueue(upload, options);
 }
 /**
  * JSON-serialize the view-state snapshot — used for BOTH change-detection (a

package/dist/src/index.d.ts

@@ -16,7 +16,8 @@
 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, 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 type { QueryRow, RowOf, UploadedFile, 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 { AttachedFile, AttachmentsOptions, AttachmentsState } from "./attachments.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.d.ts

@@ -25,8 +25,19 @@ declare function text(v: unknown): string;
  * correct reading of an empty cell (a sum, a count).
  */
 declare function num(v: unknown): number | null;
-/** Checkbox/boolean → boolean (accepts the string "true"). */
-declare function bool(v: unknown): boolean;
+/**
+ * Checkbox/boolean → `true` / `false`, or `null` when the cell holds neither —
+ * an empty cell, a value of another kind. (The strings "true"/"false" decode.)
+ *
+ * AN UNANSWERED CHECKBOX IS NOT A "NO", exactly as an empty number cell is not a
+ * 0: the field's default is what the workspace writes when a row states
+ * something, and a row nobody has answered states nothing. Read as `false` it
+ * drew "No" for every partner nobody had assessed — the rows a gate exists to
+ * catch are precisely the ones that answer nothing — so the absence is preserved
+ * the way `num` and `date` preserve theirs. Write `=== true` where only the
+ * affirmative acts, `?? false` where the safe side IS the reading.
+ */
+declare function bool(v: unknown): boolean | null;
 /**
  * Date/datetime field → a LOCAL-midnight Date for the stored calendar day, so
  * calendar/gantt placement never shifts across timezones. Parses the leading
@@ -62,7 +73,17 @@ export interface ResolvedLink {
  * `readLinks` for the full list on multi-link fields.
  */
 declare function link(v: unknown): ResolvedLink | null;
-/** select_record_link → ALL linked records as `{ id, display }[]` (empty if none). */
+/**
+ * select_record_link → ALL linked records as `{ id, display }[]` (empty if none).
+ *
+ * A LOOKUP OF A LINK FIELD ARRIVES ONE LEVEL DEEPER — the cell holds one entry
+ * per linked record and each entry is THAT record's whole link cell, an array —
+ * so read entry-by-entry it decoded to nothing while the value was plainly
+ * there. The nesting is flattened here, at the boundary that owns the
+ * serialization, rather than at each caller: one level, in order, and a record
+ * two linked rows both point at is one link, so ids repeat at most once.
+ * Anything else still reads as empty.
+ */
 export declare function readLinks(v: unknown): ResolvedLink[];
 /**
  * A `files`-field cell entry, as the app query serializes it. The server

package/dist/src/row.js

@@ -52,9 +52,24 @@ function num(v) {
     }
     return null;
 }
-/** Checkbox/boolean → boolean (accepts the string "true"). */
+/**
+ * Checkbox/boolean → `true` / `false`, or `null` when the cell holds neither —
+ * an empty cell, a value of another kind. (The strings "true"/"false" decode.)
+ *
+ * AN UNANSWERED CHECKBOX IS NOT A "NO", exactly as an empty number cell is not a
+ * 0: the field's default is what the workspace writes when a row states
+ * something, and a row nobody has answered states nothing. Read as `false` it
+ * drew "No" for every partner nobody had assessed — the rows a gate exists to
+ * catch are precisely the ones that answer nothing — so the absence is preserved
+ * the way `num` and `date` preserve theirs. Write `=== true` where only the
+ * affirmative acts, `?? false` where the safe side IS the reading.
+ */
 function bool(v) {
-    return v === true || v === "true";
+    if (v === true || v === "true")
+        return true;
+    if (v === false || v === "false")
+        return false;
+    return null;
 }
 /**
  * Date/datetime field → a LOCAL-midnight Date for the stored calendar day, so
@@ -112,17 +127,34 @@ function asLink(v) {
  * `readLinks` for the full list on multi-link fields.
  */
 function link(v) {
-    if (Array.isArray(v))
-        return v.length ? asLink(v[0]) : null;
-    return asLink(v);
+    return readLinks(v)[0] ?? null;
 }
-/** select_record_link → ALL linked records as `{ id, display }[]` (empty if none). */
+/**
+ * select_record_link → ALL linked records as `{ id, display }[]` (empty if none).
+ *
+ * A LOOKUP OF A LINK FIELD ARRIVES ONE LEVEL DEEPER — the cell holds one entry
+ * per linked record and each entry is THAT record's whole link cell, an array —
+ * so read entry-by-entry it decoded to nothing while the value was plainly
+ * there. The nesting is flattened here, at the boundary that owns the
+ * serialization, rather than at each caller: one level, in order, and a record
+ * two linked rows both point at is one link, so ids repeat at most once.
+ * Anything else still reads as empty.
+ */
 export function readLinks(v) {
-    if (!Array.isArray(v)) {
-        const one = asLink(v);
-        return one ? [one] : [];
+    const cell = Array.isArray(v) ? v : [v];
+    const out = [];
+    const seen = new Set();
+    for (const entry of cell) {
+        const held = Array.isArray(entry) ? entry : [entry];
+        for (const one of held) {
+            const linked = asLink(one);
+            if (linked === null || seen.has(linked.id))
+                continue;
+            seen.add(linked.id);
+            out.push(linked);
+        }
     }
-    return v.map(asLink).filter((x) => x !== null);
+    return out;
 }
 /**
  * files field → the attached files with their presigned `url` (empty if none).
@@ -170,7 +202,9 @@ export function readFiles(v) {
 export function readLocked(rowValue) {
     if (!rowValue || typeof rowValue !== "object")
         return false;
-    return bool(rowValue["__source_locked"]);
+    // A row that says NOTHING about its lock is not locked — this is the flag's
+    // absence, not a record's unanswered question, so the safe side is the reading.
+    return bool(rowValue["__source_locked"]) === true;
 }
 /**
  * The stored record's timestamp on a `useQuery` row, read off the addressing

package/docs/data_fetching.md

@@ -435,11 +435,11 @@ the server's answer is the only check — the rule the filter keys follow too.
 | `row.opt(cell)` | select cell → `string \| null` | first option **key** (accepts the legacy bare-string / `{ id }` shapes); `null` when empty |
 | `row.text(cell)` | any → `string` | strings pass through, finite numbers stringify, everything else → `""` |
 | `row.num(cell)` | any → `number \| null` | finite numbers pass, parseable strings parse, everything else (empty cell, NaN/Infinity, unparseable string) → `null` |
-| `row.bool(cell)` | any → `boolean` | `true` or the string `"true"`; everything else `false` |
+| `row.bool(cell)` | any → `boolean \| null` | `true`/`false` (the strings decode too); everything else → `null` — an unanswered checkbox is not a "no" |
 | `row.date(cell)` | date/datetime cell → `Date \| null` | the stored **calendar day** at LOCAL midnight — time stripped; a reduced-precision value decodes to its **period start** |
 | `row.datetime(cell)` | date/datetime cell → `Date \| null` | local `Date` **keeping the stored wall-clock** (minute precision; seconds are dropped); missing time = midnight; a reduced-precision value decodes to its **period start** |
 | `row.link(cell)` | link cell → `{ id, display } \| null` | the FIRST linked record |
-| `readLinks(cell)` | link cell → `{ id, display }[]` | ALL linked records (`[]` when empty) |
+| `readLinks(cell)` | link cell → `{ id, display }[]` | ALL linked records (`[]` when empty), a LOOKUP of a link field included |
 | `readSelect(cell)` | select cell → `ResolvedOption[]` | all selected options as `{ key, label }` (`[]` when empty) |
 | `readMembers(cell)` | member cell → `ResolvedMember[]` | `{ id, name, email?, image?, groups? }[]` (`[]` when empty) |
 | `readFiles(cell)` | files cell → `AppFile[]` | attached files with presigned URLs (`[]` when empty) |
@@ -484,11 +484,13 @@ never carry avatar images — the avatar lives on the `useMembers` roster
 ([./members_and_options.md](./members_and_options.md)).
 
 **`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`. An entry carrying an `id` and **no
+use `id` to correlate, filter (link `has_any_of`), or fetch detail. `row.link` is the first of
+`readLinks` — 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`.
+`readMembers`. **A LOOKUP of a link field arrives one level deeper** — one entry per linked
+record, each entry that record's whole link cell — and both readers open it, in order and with a
+record two linked rows point at named once, so a looked-up link needs no unwrapping of its own.
 
 **`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/files.md

@@ -1,7 +1,7 @@
 # Files
 
-Files end to end in a custom-code app: uploading bytes (`useFileUpload`), composer attachments
-with instant previews (`useAttachments`), decoding `files` cells from query results (`readFiles` →
+Files end to end in a custom-code app: uploading bytes (`useFileUpload`), an add-queue with
+instant previews (`useAttachments`), decoding `files` cells from query results (`readFiles` →
 `AppFile`), documents a workflow generates (`WorkflowResult.files`), previewing with `@lotics/ui`,
 filtering on files fields, and the server-side delivery bounds that decide whether a file-bearing
 query succeeds at all. Read this before building any screen that shows, collects, or generates
@@ -15,7 +15,8 @@ discipline in [data fetching](./data_fetching.md).
 | Collect bytes from the visitor | `useFileUpload().upload(file)` | `UploadedFile` — a stored, **unattached** file id + presigned serving URLs |
 | Collect several with live previews | `useAttachments()` | `AttachedFile[]` with instant local previews; `fileIds` when done |
 
-`useAttachments().add(files, { fidelity })` takes the same `fidelity` as `upload`.
+`useAttachments().add(files, { fidelity })` and `.attach(files, { fidelity })` take the same
+`fidelity` as `upload`.
 | Attach to a record | a declared workflow with a `{ type: "file" }` input | the workflow writes the id(s) into a `files` field — the **only** write path |
 | Read back from records | `useQuery` + `readFiles(cell)` | `AppFile[]` — presigned `url`/`thumbnail_url` (24 h) + `size`/`created_at` |
 | Receive a generated document | `useWorkflow` → `WorkflowResult.files` | presigned files auto-extracted from the run |
@@ -122,21 +123,27 @@ For **agent** aliases the same `file` inputs are materialized into the model's v
 become image parts, PDFs file parts; other types stay an id the agent opens with its own tools.
 Pair `useFileUpload` with `useAgentRun` for photo→extraction flows — see [ai](./ai.md).
 
-## Composer attachments — `useAttachments`
+## Attachments — `useAttachments`
 
 The optimistic-preview UX in one hook: a local object-URL preview shows the *instant* a file is
 added, the upload runs in the background (through the same `useFileUpload` pipeline, image
 optimization included), and the stored `file_id` lands when it completes. Don't hand-roll the
-`createObjectURL` → upload → id → revoke lifecycle per app.
+`createObjectURL` -> upload -> id -> revoke lifecycle per app.
+
+**Which lifecycle is the one decision.** A composer accumulates and `clear()`s when it sends. A
+record's section hands its write the ids and then passes what the row now holds as `landed` — each
+entry leaves the queue, and its preview URL is revoked, exactly as the stored pile takes it over,
+so nothing blinks out between the two.
 
 ```tsx
+// A COMPOSER — accumulate, send, clear.
 const { files, add, remove, clear, uploading, fileIds } = useAttachments();
 const design = useWorkflow("design");
 
 // attach: picking is the app's choice — button, paste, or drop
 <Button icon="paperclip" onPress={() => pickFiles({ accept: "image/*" }).then(add)} />
 
-// preview: map each AttachedFile to a @lotics/ui DisplayFile (snake → camel)
+// preview: map each AttachedFile to a @lotics/ui DisplayFile (snake -> camel)
 {files.map((f) => (
   <FileThumbnail
     key={f.id}
@@ -151,23 +158,50 @@ await design({ photos: fileIds });   // multi:true input
 clear();
 ```
 
-Contract (`dist/src/hooks.d.ts`):
+```tsx
+// A RECORD'S SECTION — attach, write, hand over to the row.
+const held = readFiles(r.photo);
+const queue = useAttachments({ landed: held.map((file) => file.id) });
+const save = useWorkflow("update_item");
+
+const onAdd = async (picked: File[]) => {
+  if (picked.length === 0) return;             // a cancelled pick is not a write
+  const stored = await queue.attach(picked);   // answers when every byte is up
+  await save({ item_id: r.__source_record_id, photo_added: stored });
+};
+
+<RecordFiles
+  files={held.map(toDisplayFile)}
+  uploads={queue.files.map((f) => ({
+    id: f.id,
+    filename: f.filename,
+    mimeType: f.mime_type,
+    previewUrl: f.preview_url,
+    status: f.status === "error" ? "error" : "uploading",
+  }))}
+  onAdd={(picked) => { void onAdd(picked).catch(report); }}
+/>
+```
+
+Contract (`dist/src/attachments.d.ts`):
 
 | Member | Behavior |
 |---|---|
 | `files: AttachedFile[]` | Current attachments, in the order added |
-| `add(files: File[])` | Each file shows its local preview at once and uploads in the background |
+| `add(files: File[])` | Each file shows its local preview at once and uploads in the background. Never rejects — a failure is the entry's `status` |
+| `attach(files: File[])` | The same add, resolved with the stored ids once **every** one is up. Rejects with the first refusal rather than answering short |
 | `remove(id)` | Removes one attachment and revokes its preview object-URL |
 | `clear()` | Removes all and revokes every preview URL |
 | `uploading` | True while any attachment is still uploading — gate Send on it |
 | `fileIds: string[]` | Stored file ids of the **completed** uploads — the workflow/agent payload |
+| `useAttachments({ landed })` | Stored ids the destination now holds; each matching entry leaves the queue and its preview is revoked |
 
 Each `AttachedFile` is `{ id, filename, mime_type, preview_url, status, file_id? }`:
 
 - `id` — a stable *local* id (the React key and the `remove(id)` handle), **not** the stored file
   id.
 - `preview_url` — a local object-URL, available before the upload finishes. Revoked on
-  remove/clear — don't hold it past the attachment's lifetime.
+  remove/clear/`landed` — don't hold it past the attachment's lifetime.
 - `status` — `"uploading" | "ready" | "error"`. A failed upload stays in `files` with
   `status: "error"` (and no `file_id`); there is no auto-retry — offer remove + re-add.
 - `file_id` — the stored id, set once `status` is `"ready"`. `fileIds` includes only ready
@@ -175,10 +209,11 @@ Each `AttachedFile` is `{ id, filename, mime_type, preview_url, status, file_id?
 
 Wiring to `@lotics/ui`: in a `Composer`, trigger picking from `actionsButton` (via `pickFiles`),
 render the attachment pills with `FileThumbnail` as above, and gate `sendDisabled` on `uploading`.
-For a full add-files *screen* (not a composer pill), map each `AttachedFile` to a
-`FileThumbnailGrid` `FileUpload` entry — ready → `{ status: "complete", id: file_id, file:
-<DisplayFile> }`, else `{ status, id, filename, mimeType: mime_type, previewUrl: preview_url }`
-— and the grid renders the uploading/error/retry tiles itself.
+A record's section passes the queue to `RecordFiles` `uploads` (a `PendingUpload` each) so the
+picked file and the stored pile stand in one grid. For a full add-files *screen*, map each
+`AttachedFile` to a `FileThumbnailGrid` `FileUpload` entry — ready -> `{ status: "complete", id:
+file_id, file: <DisplayFile> }`, else `{ status, id, filename, mimeType: mime_type, previewUrl:
+preview_url }` — and the grid renders the uploading/error/retry tiles itself.
 
 ## File cells in query results — `readFiles` and `AppFile`
 

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, 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 |
+| `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, from the workflow's own `return({ field_errors })`, or from a failing `validate` check's `field_key`. Absent when none named a field |
 
 ### The failure model: check `status`, never just try/catch
 
@@ -135,6 +135,11 @@ Keep `message` too — it is what a refusal with no field to blame says, and the
 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.
 
+A failing `validate` check fills the same map from its `field_key`, so the key there is the INPUT
+name as well — `field_key: "ly_do"`, never the `fld_` key of whatever column the check happened
+to read ([workflows](./workflows.md) § `validate`). Nothing at run time corrects a key that names
+neither, so the refusal arrives and marks no control.
+
 ### Generated files come back in `files[]`
 
 Any step in the run whose tool output carries a `file_id` (most commonly the
@@ -455,7 +460,7 @@ The same trap one level up: **an action takes an ID, never a captured object.**
 happened, so no amount of waiting refreshes it — the confirm quotes, and the mint bills, the
 pre-edit total. Pass the key and resolve at use (`onPress={() => setConfirmKey(invoice.key)}`,
 then re-read or `find` where it is consumed). `@lotics/ui` gates the press itself
-(`docs/data_entry.md` § Inline edit), which fixes the ordering; the captured value is the app's
+(`docs/data_entry.md` § A field that saves itself), which fixes the ordering; the captured value is the app's
 to get right.
 
 ## Diff before update — send only what changed

package/docs/recipes.md

@@ -118,7 +118,9 @@ A query cell is `unknown` with a per-type serialized shape:
 
 - `row.opt` / `row.text` / `row.num` / `row.bool` / `row.date` — scalars and the first value of a
   select. `row.date` keeps only the calendar day; use **`row.datetime`** when the time matters.
-  `row.num` answers `null` for an empty cell — write `?? 0` only where zero is its correct reading.
+  `row.num` and `row.bool` answer `null` for an empty cell — an unanswered checkbox is not a "no"
+  any more than an empty number cell is a 0. Write `=== true` where only the affirmative acts, and
+  `?? 0` / `?? false` only where that side is the cell's correct reading.
 - `readSelect` — the full `{ key, label }[]` of a multi-select.
 - `readMembers` — `select_member` cells.
 - `row.link` / `readLinks` — `select_record_link` → `{ id, display }`. Read `.display` to render,

package/docs/workflows.md

@@ -203,9 +203,11 @@ return({ status: "success", message: "Order created.", data: { total: subtotal }
   expression). Both `field_errors` and `data` are optional.
 - `data` is what the app reads back as `result.data`; the alias's `outputs` schema is derived at
   save from its inferred type. Full contract: [mutations](./mutations.md) § "Structured results".
-- `field_errors` annotates a *rejected record write* — it is consumed by the table-workflow
-  surface for cell-level error rendering. An app-invoked workflow surfaces only `status`,
-  `message`, `data`, and `files`, so put anything the app must read under `data`.
+- `field_errors` maps a key to a message and reaches the app on `result.field_errors`, so a
+  form draws each one against the control it names. **The key names the control on the surface
+  that renders it**: for an app workflow that is the alias's declared INPUT name, for a
+  table-triggered one it is the record's `fld_` field key. The runtime keys the map by whatever
+  string you write, so a key naming neither reaches the dialog and lands on nothing.
 - A body that completes without hitting a `return` resolves `status: "success"` with no `data`.
 - Generated documents never travel through `data`; they are collected into `result.files[]`
   automatically ([files](./files.md)).
@@ -215,14 +217,22 @@ return({ status: "success", message: "Order created.", data: { total: subtotal }
 ```js
 validate({ checks: [{
   fail_when: size(dup.records) > 0,
-  field_key: "fld_order_code",
+  field_key: "order_code",
   message: "This order code already exists.",
 }]});
 ```
 
-`fail_when` rejects when truthy. `field_key` is an optional literal `fld_*`. A failing check ends
-the run as `status: "error"` with the failing messages joined — cleanly, not as a crash: it is
-control flow, so **`try`/`catch` does not catch it** (nor `return`).
+`fail_when` rejects when truthy. A failing check ends the run as `status: "error"` with the
+failing messages joined — cleanly, not as a crash: it is control flow, so **`try`/`catch` does
+not catch it** (nor `return`).
+
+`field_key` is optional, a string literal, and carries the same key `return({ field_errors })`
+does: **the control the message belongs to, on the surface that renders it** — an app workflow's
+declared INPUT name (`order_code`, the key under `lotics.workflows.<alias>.inputs`), a
+table-triggered workflow's `fld_` field key. Each failing check that names one contributes an
+entry to `field_errors`, so the app's form marks that control instead of only the dialog.
+A key naming neither is refused when the body is SAVED — by `lotics app workflow set`, by an
+agent binding one, by a table workflow's save — and by `lotics app workflow check` before that.
 
 ### `wait_for_approval` — the one wait worth binding
 
@@ -870,7 +880,8 @@ const dup = await query_records({
 
 validate({ checks: [{
   fail_when: size(dup.records) > 0,
-  field_key: "fld_order_code",
+  // The INPUT name, not the field key: this is what the app's form marks.
+  field_key: "order_code",
   message: `Order code ${i.order_code} already exists.`,
 }]});
 

package/package.json

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