@lotics/app-sdk 0.60.1 → 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/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/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.1",
+  "version": "0.60.3",
   "description": "Runtime SDK for Lotics custom-code apps \u2014 typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {