@lotics/app-sdk 0.63.0 → 0.63.2

package/docs/ai.md

@@ -209,6 +209,8 @@ Sessions are scoped to the authenticated member who ran them: two members using
 |---|---|---|
 | **Perceived natively** | `image/*`, `application/pdf` | A vision / document part — the agent literally sees it |
 | **Materialized** | Word (`.docx`/`.doc`), Excel (`.xlsx`/`.xls`), CSV, and text (`.txt`, `.md`, `.json`, `.eml`, `.html`, `.xml`, `.yaml`) | Read server-side by the same engines `view_files` uses and inlined into the run's message, truncated at 40,000 characters with the agent told when that happened |
+
+**Pictures inside a Word document are delivered as images**, so a scanned page, an ID card photographed into a `.docx`, or a screenshot pasted into one is READ, not merely described. A document whose content is entirely pictures carries no text at all — it used to arrive as empty paragraphs plus a size in centimetres, and the agent correctly reported it could not read it. Any picture that is skipped or unresolvable is counted and stated in the text, so a partially-read document never reads as a complete one.
 | **Unreadable** | Archives, audio, video | The run fails immediately, naming the file — a fact about the upload, not a gap in your configuration |
 
 Every file in a `multi` input is materialized — nothing is collapsed to the first. Get the ids from [`useFileUpload` / `useAttachments`](./files.md).
@@ -223,6 +225,7 @@ Every file in a `multi` input is materialized — nothing is collapsed to the fi
 - **Owner-billed.** Token usage is recorded against the app's organization's AI credits. The quota is enforced before the first model call (a `run()` rejection) and re-checked between steps (a mid-run exhaustion settles the run as an error).
 - **Hard duration cap: 20 minutes per run.** A capped run settles as an error — but with whatever partial transcript and captured output it produced, recoverable from the persisted run.
 - **Concurrency cap: 5 in-flight runs per member.** Exceeding it rejects with "Too many agent runs in progress".
+- **One tool result may not exceed 512 KiB.** A tool's result is persisted into the run's transcript and replayed on every later step, so an oversized one is paid again per step until the run stops fitting in a request. A tool that overruns fails by name ("Tool \"x\" returned N bytes…") rather than being delivered; narrow the call, or use a tool that returns a reference instead of the bytes. Reaching this from a normal call means too much was asked for at once — read a range, not a whole sheet.
 
 **Limitation (dev harness):** `lotics app dev` streams runs but does not forward the run id, so in the dev loop `cancel()` degrades to a local `abort()` (the run keeps executing server-side) and connection-drop recovery is unavailable. Both work fully in the embedded product.
 

package/docs/queries.md

@@ -853,6 +853,22 @@ per-table queries you merge client-side; the merge already happens in the index.
 sort key to be a bare field projection — a computed/literal/type-overridden sort column falls back
 to the whole-union sort.)
 
+**An aggregate arm you cannot filter costs its whole table, every execution.** The shape to watch
+is the mirror of the one above: a `join` whose right side is a `group` over one or more entire
+tables — a lookup built by scanning everything in order to decorate a small left side. Rule 1 is
+no help here, and that is what makes it easy to ship: the arm keys on a value the LEFT side
+supplies at run time (a code, a serial number), so there is no static predicate to push down. The
+left side's size is irrelevant; you pay for the arms. As a unit to budget with: a four-table arm
+totalling ~14k rows is **seconds, not milliseconds**, on every single execution. Prefer a
+materialized **lookup/rollup field** on the row (the platform keeps it current and it filters at
+the source), or drop the arm entirely if the value it fetches now lives on the row already.
+
+**Measure before you change a shape, and after.** Latency is observable per alias: each `useQuery`
+goes out as its own RPC, so a screen's cold load attributes a duration to every query by name in
+the browser's network panel. Time it, fix the one that dominates, time it again. Reasoning
+alone mis-ranks these — the union above looks expensive and is fast, the join here looks ordinary
+and is not — and a playbook rule applied to the wrong query costs effort while proving nothing.
+
 ### The authoring rules
 
 1. **Filter at the source.** Push every static predicate into `from_table.filter`.
@@ -875,6 +891,12 @@ to the whole-union sort.)
     at once (`by: [a, b, c, …]`) and fold each facet client-side by summing over the others:
     `count` and `sum` fold exactly. `unique` does NOT fold across groups (the same value can
     appear in many groups) — keep a separate query for each distinct-count you render.
+11. **Re-derive a query when its tables change shape.** A `join` or `union` that exists to bridge
+    two tables becomes pure cost the moment those tables become one — and nothing fails, because
+    it keeps returning the right answer at the old price. Migrations that merge, move or back-fill
+    a table are exactly when this happens, and exactly when nobody re-reads the queries. After
+    one, open every query over the affected tables and ask what it would look like written today,
+    not what it needs to keep working.
 
 ---
 

package/package.json

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