@lotics/app-sdk 0.60.0 → 0.60.3

package/AGENTS.md

@@ -17,12 +17,12 @@ signature; open the file.**
 | [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/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 `lotics app workflow check` loop. |
-| [docs/files.md](./docs/files.md) | Files end to end — `useFileUpload`, `useAttachments`, `readFiles`/presigned URLs, workflow-generated files, 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/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. |
 | [docs/members_and_options.md](./docs/members_and_options.md) | People + select options + comments — `useMembers`, `useFieldOptions`, `useViewer`, `useComments`, 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), `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, auto query-refetch on chat mutation). **A `file` input carries its own content** — images/PDFs are perceived natively, Word/Excel/CSV/text are materialized into the run; no reader tool to declare. **An agent reaches record DATA only through its declared `query_aliases` / `workflow_aliases`** (`run_app_query` / `run_app_workflow`); the raw record read/write tools are rejected. |
-| [docs/security.md](./docs/security.md) | **Read before shipping** — the owner-principal model, `is_current_member` scoping, write attribution, group gates, public-app bounds, what runtime refinement cannot widen. |
+| [docs/security.md](./docs/security.md) | **Read before shipping** — the owner-principal model, `is_current_member` scoping, write attribution, group gates, public-app bounds, what runtime refinement cannot widen, and why a per-input bound is a tenancy floor rather than an authorization check (a caller-supplied id must be intersected with the record server-side). |
 | [docs/runtime.md](./docs/runtime.md) | `mount()`, the two transports, `rpc()`, `openExternal`/`downloadFile`, geofencing, analytics, `useConfig` (App-Packages installation config), `getAppBinding` (package apps' runtime `F`/`OPT`/`ROLE` resolution via the generated `.lotics/app_fields.ts`), and the publish chain for package contributors. |
 
 ## Non-negotiables (each detailed in its doc)

package/docs/ai.md

@@ -306,18 +306,60 @@ Declarative and lifecycle-bound: mounting or changing `context` pushes it; unmou
 | `slot` | ≤ 50 chars |
 | `description` | ≤ 1000 chars (truncated with `…`) |
 | `records` | ≤ 20 refs |
-| `data` | must JSON-serialize to ≤ 2000 chars, else the `data` field is **dropped** (the description is kept) |
+| `data` | must JSON-serialize to ≤ 2000 chars, else it is **replaced by an `omitted` marker** the agent reads (the description is kept) |
 | slots per app | ≤ 8 (a 9th evicts the least-recently-updated) |
 
-Keep `description` tight and human-readable — it is the line the agent reads. Put anything structured (filter/sort/form values) in `data`, and remember it is dropped whole past its size cap, so don't hide load-bearing facts there that aren't also in `description`.
+Keep `description` tight and human-readable — it is the line the agent reads. Put anything structured (filter/sort/form values) in `data`, and remember it is replaced whole past its size cap: the agent is told the state existed but not what it was, so don't hide load-bearing facts there that aren't also in `description`. It is replaced rather than silently dropped so the agent cannot mistake "too big to send" for "there was nothing".
 
 ### Security — push-only, a snapshot of what was already rendered
 
-This is a **one-way push of data the app already showed this member** — never a channel for chat to pull app-authority data back out. Two consequences hold it to that:
+This hook is a **one-way push of data the app already showed this member**. (Chat can also PULL, through the app's declared aliases — a separate channel with its own `app:use` gate, below.) Two consequences hold the push to what was rendered:
 
 - **`records` are raw `{ table_id, record_id }` refs, passed UNRESOLVED.** The app does not resolve them here; the member's own chat agent may read or act on them only where **that member's IAM already allows**. A ref to a record the member can't see stays inert.
 - **`description` and `data` enter the agent's prompt as clearly-labeled DATA, never as instructions.** Text an app renders can't hijack the agent — the host wraps it as app-supplied view state (see [security](./security.md) for the labeled-data convention).
 
+### The chat can also USE the app, not just be told about it
+
+`useAiContext` is a PUSH — a snapshot of what one screen rendered. It cannot
+answer a question about a record that is not on screen, and it is capped, so it
+was never the whole story.
+
+While a member has an app open, their chat agent can also **call that app's own
+declared aliases** — named queries via `run_app_query`, workflows via
+`run_app_workflow`. This adds no exposure: every declared alias is already
+callable by that member against `POST /v1/apps/{id}/query` and
+`POST /v1/apps/{id}/workflows/{alias}/execute`, so the manifest already IS
+their reachable surface — the agent simply reaches it without devtools. It is
+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).
+
+**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;
+the approval is what stops the wrong one. Approval applies to the chat surface
+only — an app agent's run is already an explicit act with no human in the loop
+to answer.
+
+The prompt names the action and lists the inputs the agent chose, so **your
+input names are what the member reads before authorizing the write**. Name them
+for that reader (`ma_khach_hang`, `so_tien`), and keep the decisive ones
+top-level — a value nested inside an opaque payload shows as JSON, and long
+values are truncated. Context ids the member never chose (`app_id`,
+`workspace_id`, `organization_id`) are filtered out.
+
+Nothing about your app changes to get this — declare a workflow as you already
+do, and it becomes reachable. If a workflow should NOT be agent-reachable, it
+does not belong in the manifest at all, since the member can already fire it
+from the app's own buttons.
+
+**What this means for what you push.** Keep `description` — the one line that
+says who is on screen and where they stand, which is what makes "this one"
+resolvable. Don't pack bulk rows into `data` to pre-answer questions that may
+never be asked: the agent can fetch them when needed, fresher than a snapshot,
+and a payload pushed on every message is carried by every later turn (see the
+caps above).
+
 ### Query freshness — the mutation companion
 
 When the ambient chat agent's turn ends and it mutated records, the host pushes every mounted query hook to re-read, so the screen the member is looking at reflects the agent's change without a manual refresh. That companion behavior is automatic — you write no code for it — and is documented with the query caching contract in [data_fetching](./data_fetching.md#caching-loading-states-and-errors).

package/docs/files.md

@@ -210,8 +210,11 @@ file. It is pure and never throws.
 - **Thumbnails are optimistic.** `thumbnail_url` is emitted for every image without checking that
   the variant exists; a not-yet-generated variant 404s on fetch. `@lotics/ui`'s `FileThumbnail`
   falls back to `url` on image error — a hand-rolled `<img src={thumbnail_url}>` must do the same.
-- **Don't persist the URLs.** They expire in 24 h. Apps re-query on load, so the TTL refreshes
-  naturally; store `id`s, never `url`s.
+- **A presigned `url` is a bearer credential for the bytes.** It carries its own authorization —
+  anyone holding it fetches the file for 24 h with no session — so it must never leave the render
+  path: not into a log line, not into telemetry, not into an error report or a bug ticket. Don't
+  persist it either; apps re-query on load, so the TTL refreshes naturally. Store `id`s, never
+  `url`s.
 - **Warning:** SVG, HTML, and XHTML files are presigned with a forced-download disposition — their
   `url` downloads instead of rendering inline (stored-XSS defense). An SVG in an `<img>` will not
   display; treat these types as download-only.
@@ -278,6 +281,30 @@ if (result.status === "success" && result.files?.length) {
 - For bytes the app builds *in the browser* (a client-side .xlsx/CSV export), the counterpart is
   `downloadFile(filename, data, mimeType?)` — see [runtime](./runtime.md).
 
+### Naming what goes into a zip
+
+A workflow that bundles files (`zip_files`) names each entry itself: an item in `file_ids` is a
+file id, **or** `{ id, name }`. An entry given no name keeps whatever the uploader called the file
+(`IMG_4821.jpg`, `scan (3).pdf`) — which is exactly what the recipient opens — so pass the name the
+app already knows (document type, record key, sequence). Renaming the stored file first is not
+required, and would change what the record shows everyone else.
+
+```js
+// in a workflow body — the two forms mix freely
+const bundle = await zip_files({
+  file_ids: [{ id: inputs.signed_doc, name: "Bản ký" }, inputs.appendix],
+  filename: "ho-so",
+});
+```
+
+An entry name is a **file name, not a path**. Separators are folded away, so a document number
+survives readably (`Số 123/QĐ-BXD` arrives as `Số 123-QĐ-BXD`); a name without an extension is given
+the stored file's; two files handed the same name are suffixed `_2`, `_3`. A name that cannot be
+read as one fails the run rather than being quietly rewritten — a control character, a non-string,
+over 200 characters, punctuation alone, or the empty string a name expression yields when it found
+nothing. `null` is the one absence that is not an error (an empty record field reads as `null`): it
+means "no name", and that entry keeps the stored filename.
+
 ## Previewing — wiring to `@lotics/ui`
 
 Render any file inline — image, PDF, video, audio, Word, Excel, CSV — with `@lotics/ui`. Never

package/docs/queries.md

@@ -120,6 +120,15 @@ Delivery-layer enrichment (applied to the response, per request):
   only for authenticated members of the app's own org).
 - **`select` cells** — bare option-key arrays become `{ key, label }[]` (colors ride in
   `useFieldOptions`, not the cell — see [members_and_options.md](./members_and_options.md)).
+  **Enrichment needs the column's source addressing**, which a passthrough projection carries, a
+  union carries when its arms agree (or per-row, when the compiler emits it), and a **link
+  extraction** carries as of the target field it reads. The one shape that has none is a select
+  reached through a **lookup FIELD**: the column addresses the lookup, whose own type is `lookup`,
+  not `select` — so the cell stays bare `opt_*` keys AND `useFieldOptions` omits the column
+  entirely, and reading `.label` off it renders the option KEY. Carry the keys out
+  (`readSelect(cell).map((o) => o.key)`) and resolve them against an alias that projects the
+  underlying field DIRECTLY — `useFieldOptions` takes no params, so any alias whose schema
+  contains it works.
 - **`number` columns** arrive as JS numbers (Postgres `numeric` strings are coerced; a
   high-precision decimal that would lose digits stays a string). **`date`/`datetime`** columns
   arrive as canonical wall-clock strings (`YYYY-MM-DD` / `YYYY-MM-DDTHH:mm`).
@@ -350,6 +359,12 @@ target table can silently re-point (or break) the extraction — prefer field **
 target's names are volatile. Each extraction is a correlated subquery evaluated per output
 row — cheap on a filtered detail read, expensive over thousands of rows.
 
+An extracted column **is** addressed to the field it reads on the target table, so the delivery
+layer treats it like any other field-backed column: an extracted `select` enriches to
+`{key,label}` and appears in `useFieldOptions`, and an extracted date resolves relative-date
+filters in the source field's timezone. It is still never **writable** — a correlated subquery is
+not a write path, and `writable_target` rejects it.
+
 ### The expression escape hatch
 
 `{ "expression": "…" }` compiles a small jexpr subset to SQL. Column references are

package/docs/runtime.md

@@ -288,6 +288,17 @@ It is the client-side counterpart to the server path (workflow generates a file
   the browser attributes the download to the user gesture. Build the bytes in
   the handler, then call `downloadFile` — an `await` between the click and the
   call can void the gesture and get the download blocked.
+- **One gesture buys one download.** Browsers block — or prompt over — repeated
+  programmatic downloads from a single interaction, so a loop calling
+  `downloadFile` once per file delivers the first and silently loses the rest.
+  Several files leave as **one archive**: build the bundle, hand it over in a
+  single call.
+- **Guard a URL before fetching bytes you did not build.** `fetch("")` — an
+  empty or relative string where a file URL was expected — resolves against the
+  app's own page and returns **200** with the app's HTML, which then saves under
+  the filename you intended: a plausible-looking file with the wrong contents
+  and no error anywhere. Require the URL to be present and absolute, and treat a
+  missing one as a failure, never as an empty download.
 - `mimeType` defaults to `application/octet-stream`. The blob URL is revoked on
   the next task, after the download has started.
 

package/docs/security.md

@@ -30,13 +30,21 @@ Callers never submit query ASTs or workflow definitions — the server holds the
 | `record_link` | Every submitted record id must live in the declared table |
 | `file` | Every submitted file id must live in the app's workspace — a foreign tenant's `file_id` is rejected |
 
+**Each of those bounds is a tenancy floor, not an authorization check.** It proves the value
+belongs to the app's own workspace (or to a declared group or table) — never that *this caller*
+should reach *that* row, file, or member. A `file` input is floored to the **workspace**, so a
+caller may substitute the id of any file in it, including one attached to a record they have
+never opened; a `record_link` id is floored to its declared **table**, not to the records the
+caller may see. Whenever a run acts on ids the caller supplied, intersect them server-side with
+what the target record actually holds before reading, bundling, or writing them.
+
 Workflows and agent runs additionally execute behind a **workspace tenant floor**: every table a run touches must live in the app's own workspace, so no input value can steer a run at another workspace's data even under an admin owner's authority. An **agent** run is bounded harder still: it reaches records only through the queries and workflows its declaration names (`query_aliases` / `workflow_aliases`), never a raw table — so the ceiling is what you declared for that agent, not what the owner can see. See [ai](./ai.md).
 
 What the platform does **not** constrain is the *meaning* of your params. A query param is a value hole in the template (a filter value, a search term); the server checks its type only — the group/table bindings above apply to workflow and agent-run inputs, **not** to query params — never whether the value should have been derived from the caller's identity. That's the next section.
 
 ### The devtools test
 
-Before shipping any query or workflow, ask: **could a member open the browser devtools, replay the app's RPC, and pass someone else's id?** Every declared alias is callable by every member with app access (and by *anyone*, if the app is public) with arbitrary typed values — the app's UI is not a boundary. If substituting another member's id (or another record's id) into a param would show that member's data or perform a write only they should trigger, the design has an IDOR. The fixes are always server-side:
+Before shipping any query or workflow, ask: **could a member open the browser devtools, replay the app's RPC, and pass someone else's id?** Every declared alias is callable by every member with app access (and by *anyone*, if the app is public) with arbitrary typed values — the app's UI is not a boundary. If substituting another member's id (or another record's or file's id) into a param would show that member's data or perform a write only they should trigger, the design has an IDOR. The fixes are always server-side:
 
 - Reads scoped to "the current member" → an `is_current_member` filter **in the query template**, never a client-supplied member-id param.
 - Writes attributed to the caller → `runtime.triggered_by_member_id` **in the workflow body**, never a client-supplied member input.

package/docs/workflows.md

@@ -50,6 +50,13 @@ leave `outputs` off to let the body's `return({ data })` derive it), write the b
 `check`, then `set`. Input declaration vocabulary and validation:
 [mutations](./mutations.md#declaring-workflow-inputs).
 
+**Adding an input to an alias that is already bound reverses that order.** `codegen` types a
+*registered* alias from the server's **bound** schema — the manifest declaration is only the
+fallback for an alias the server has never seen — so a newly-declared input is absent from the
+local globals and `check` rejects every read of it, however correct the body is. `set` pushes the
+manifest's `inputs` with the body and the server verifies against *those*, so the working order
+is `set` → `codegen` → `check`.
+
 An app workflow body carries **no trigger declaration** — the binding supplies the trigger
 context. A stray `on({ … })` line is rejected.
 
@@ -598,7 +605,9 @@ genuinely recursive.
 `lotics app workflow check [alias]` runs the server's **own** parse and type passes locally: the
 same subset parser, the same generated `.d.ts` and envelope, the same compiler options, one
 isolated program per alias. **Green means pushable and red means real** — do not push through a
-red check.
+red check. It is also the *only* local gate on a body: the app project's own `npm run typecheck`
+excludes `src/workflows` (bodies compile against the server's globals, not the app's DOM lib), so
+it never sees one — a fully green app typecheck says nothing about any workflow.
 
 Order matters. A subset rejection is reported *alone* and the compiler is skipped, because a body
 the parser refuses never reaches the type checker on the server anyway. Diagnostics carry
@@ -621,6 +630,22 @@ There is no separate verify endpoint: the loop is `set` → read the returned di
 round trip, not one per fix — and raw TypeScript shape errors are rewritten into field-naming,
 fix-stating messages before you see them.
 
+### Static green is not a run
+
+`check` and `set` prove parse, types, name resolution, and lint — **none of them evaluates an
+expression**. A body that saves clean can still take the wrong branch, hand a tool a filter it
+rejects, or read a path that is null on real data. The rehearsal for that is `dry_run_workflow`
+(`lotics run dry_run_workflow '<json>'`): pass the `source`, `trigger_type: "app_workflow"`,
+`table_id: null`, the input **values** as `trigger_payload`, and the declared schema as
+`app_workflow_inputs`. It walks the real step tree with the production expression evaluator and
+hands back `planned_calls` (every tool call in order, with its fully-resolved input),
+`return_value`, `validation_failures`, `evaluation_errors`, and `tool_input_errors` — inputs the
+target tool would reject, which can only surface once the values are computed. **Write tools are
+recorded, never dispatched**, and nothing is persisted. For a table-triggered body, pass
+`record_id` + `table_id` instead of `trigger_payload` and the read-only tools (`query_records`,
+`get_record`, `aggregate_records`) dispatch for real, so data-dependent gates are exercised
+against actual rows. Do this before the first live run of anything that writes.
+
 ## A worked body
 
 An app action that creates an order after checking for a duplicate, then returns the new id.

package/package.json

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