@lotics/app-sdk 0.70.0 → 0.73.0

package/docs/ai.md

@@ -26,6 +26,7 @@ A declaration carries:
 | `workflow_aliases` | The app's own workflows the agent may invoke via `run_app_workflow` — its **entire write surface** |
 | `model_tier` | Optional model tier — `haiku` \| `sonnet` \| `opus`. Omit (preferred) to follow the platform default tier, resolved at run time. A tier names capability, not a version, so the agent tracks model generations with no rewrite. Pin only a deliberate, tested choice |
 | `effort_level` | Optional reasoning depth for adaptive-thinking tiers. Requires an explicit `model_tier` pin — effort is tuned per tier |
+| `prefix_cache_ttl` | Optional prompt-cache window for the agent's stable prefix (tools + system). **Omit it** — the default (`"5m"`, Anthropic's own) is right for essentially every agent. `"1h"` is a leveraged bet: it doubles the write price (2x the input rate against 1.25x, both reading back at 0.1x) to buy only the five-minute-to-one-hour band, and an entry nothing re-reads inside the hour was paid for twice over. Declining it is never "uncached" — the same prefix stays cached at the default window. Set `"1h"` only with measured cadence showing runs reliably land in that band, such as a scheduled sweep |
 | `inputs` | Optional typed input schema for one run — the same vocabulary as workflow inputs (`text`, `number`, `file`, `member`, `record_link`, `select`, …). The server validates every run payload against it |
 | `outputs` | Optional typed output schema. Declared → **structured agent** (the run must emit a matching result); omitted → **free-text agent** (the answer is the final prose) |
 

package/docs/queries.md

@@ -121,7 +121,8 @@ Delivery-layer enrichment (applied to the response, per request):
 
 - **`files` cells** — each entry gains a presigned `url` + `thumbnail_url` (24 h TTL) and
   `size` (bytes) + `created_at`, resolved from the file object at read. Presigning is
-  server-bounded (§10). Public apps hand out direct presigned URLs — anonymous-fetchable,
+  server-bounded (§10) — and it is per ENTRY, which is why a list that renders one thumbnail
+  should project the column with `limit` (§3) rather than the whole array. Public apps hand out direct presigned URLs — anonymous-fetchable,
   time-boxed. (App workflow-execute responses presign returned files the same way, so their
   URLs also work for anonymous public-app viewers — see [files.md](./files.md).)
 - **`select_member` cells** — bare member-id arrays become
@@ -199,6 +200,20 @@ indexes live (§10). `sort` entries are `{ field_key, order: "asc"|"desc", blank
   (§4), never a relabel. An uncastable combination is rejected at deploy.
 - **Project only what you render.** A bare `from_table` ships every column — including `files`
   cells with storage keys — to the client (over-exposure + the presign ceiling at scale).
+- **A files column takes `limit` — bound it when the surface renders a THUMBNAIL, not the
+  collection.** `{ "type": "files", "output": "photo", "source": "fld_…", "limit": 1 }` returns
+  the first entry per cell, in stored order, cut in SQL so the rest is never read or signed.
+  Without it the cell yields the whole array and the response pays to resolve every entry it
+  will never show: a register over containers averaging 33 gate photos each resolved ~832 files
+  to display 25 thumbnails, within 2.4× of the response-wide presign ceiling (§10) that would
+  reject the query outright. The bound is per CELL and caps at `FILES_PROJECTION_MAX_LIMIT`
+  (10) — a row wanting more than a handful is asking for the collection, which belongs to the
+  record surface that opens it. It is a different axis from the query's own `limit`, which
+  counts ROWS; `limit` on any non-`files` column — or on a computed source, which has no cell
+  to bound — is rejected at deploy rather than ignored. **On a UNION, set it on every arm.**
+  Arms align by column name and type, and `limit` is neither, so an arm that omits it still
+  yields whole cells — the query stays correct and silently costs what the bound was there to
+  avoid.
 
 ### `filter` — predicate over derived columns
 

package/package.json

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