@lotics/app-sdk 0.46.1 → 0.47.0

package/docs/runtime.md

@@ -0,0 +1,432 @@
+# The app runtime
+
+How a custom-code app boots and talks to the platform: **`mount()`** (the entry
+point, including the design-time mock harness and automatic PostHog analytics),
+the **two transports** the SDK switches between (embedded postMessage bridge vs.
+standalone direct API — app code never branches), the raw **`rpc()`** escape
+hatch, and the browser capabilities the sandbox would otherwise block —
+**`openExternal`**, **`downloadFile`**, and **`requestGeofencedLocation`** /
+**`isWithinZone`**. Ends with the contribution contract for the package itself
+(publish chain, wiring a new RPC op, bundler constraints). Read this when wiring
+an app's entry file, when a browser capability misbehaves inside the iframe,
+when you need to drop below the hooks, or when changing the SDK.
+
+## `mount()` — the entry point
+
+```tsx
+import { mount } from "@lotics/app-sdk";
+import App from "./App";
+
+mount(<App />);
+```
+
+`mount(element: ReactNode, options?: MountOptions): void` (exact signature:
+`dist/src/mount.d.ts`) is called **once** from the app's entry file. It:
+
+1. **Registers the mock fixture**, if `options.fixture` was passed (below).
+2. **Finds or creates `#root`.** Uses the `<div id="root">` from the starter's
+   `index.html`; if the bundler didn't ship one, it creates and appends it.
+3. **Installs visible error handlers.** `window` `error` and
+   `unhandledrejection` listeners render a fixed red monospace banner (message +
+   stack) above the app — a render crash or an unhandled promise rejection is
+   visible in the iframe itself, even before any host telemetry is wired up.
+   Banners are informational only; they are not removed automatically.
+4. **Renders the tree** with React 19's `createRoot`.
+5. **Boots analytics** fire-and-forget (see [Automatic analytics](#automatic-analytics-posthog)).
+   Never awaited — it cannot delay first paint, and any failure leaves the app
+   fully functional and untracked.
+
+### The mock harness (`options.fixture` + `?__mock=1`)
+
+The optional second argument registers a demo/design-time fixture:
+
+```tsx
+mount(<App />, {
+  fixture: {
+    queries: {
+      orders: MOCK_ORDERS,       // alias → rows, same aliases as package.json#lotics.queries
+      customers: MOCK_CUSTOMERS,
+    },
+  },
+});
+```
+
+Activation is a **two-step gate** — both must hold, so demo data shipping in the
+bundle never leaks into normal traffic:
+
+1. A fixture is registered via `mount({ fixture })` (`AppFixture` type:
+   `dist/src/mock.d.ts` — `{ queries?: Record<string, Array<Record<string, unknown>>> }`).
+2. The page URL carries `?__mock=1` (exactly `1`). Without the flag the fixture
+   is completely inert.
+
+When active, the [query hooks](./data_fetching.md) return `fixture.queries[alias]`
+instead of making any request (`loading` stays `false`). **Partial mocking is
+supported**: an alias absent from the fixture still flows through the real
+transport. Calling `mount` again (HMR) replaces the registration last-write-wins.
+
+- **Fixture rows stand in for wire rows.** They pass through the same code path
+  as fetched rows, so shape them exactly like the query's real output — the same
+  serialized cells your `row.*` / `readSelect` / `readFiles` readers decode —
+  or the readers will decode nothing.
+- **Not mocked:** workflows (`useWorkflow`), uploads, `useFieldOptions`, members,
+  comments, agent runs. In mock mode those still hit the real transport;
+  mutations have side effects, so there is deliberately no workflow mock.
+- **Analytics is disabled** whenever `?__mock=1` is present, fixture or not — a
+  screenshot/design-time load emits no events.
+- The `__mock` param-name prefix is reserved by the SDK; don't use it for
+  [URL state](./navigation_and_state.md) keys.
+
+**Warning:** anyone can append `?__mock=1` to a deployed app's URL and see the
+fixture rows instead of real data. That is harmless by design — the fixture is
+compiled into the publicly served bundle either way — but it means fixtures must
+only ever contain invented data, never a copy of real records.
+
+## The two transports
+
+An app reaches the Lotics API one of two ways. The SDK picks **automatically**
+at each call from the iframe URL: the embedding host passes its origin via the
+reserved `?lotics_host=` query param — present (non-empty) means **embedded**,
+absent means **standalone**. App code never branches on the mode; every hook and
+helper works identically in both. `isEmbedded(): boolean` is exported
+(`dist/src/rpc.d.ts`) for the rare display-level need, and the
+[security doc](./security.md) explains what mode implies for identity.
+
+| | **Embedded (bridged)** | **Standalone (direct)** |
+|---|---|---|
+| Where | Iframe inside the Lotics product, or the `lotics app dev` wrapper page | The app's own top-level page at `<slug>.lotics.app` |
+| Who holds credentials | The **host** — the member's session never reaches the app | Nobody — the visitor is anonymous (an optional app password gates access, not identity) |
+| How ops travel | `postMessage` to the parent frame; the host makes the API call with its session | `fetch` to the public `https://api.lotics.ai/v1/apps/{id}/*` endpoints |
+| Viewer identity | The signed-in member (`useViewer`, comments, agent runs available) | `member_id` is `null`; members-only surfaces reject |
+
+### Embedded: the postMessage bridge
+
+The app posts `{ id, op, payload }` to `window.parent` targeted at the host
+origin; the host replies `{ id, type: "result", data }` or
+`{ id, type: "error", message }` (streaming agent runs use a multi-message
+variant: `run-id`? → `stream-chunk`\* → `stream-end` | `error`). The bridge is
+**origin-locked both ways**: the SDK only accepts messages whose `source` is the
+parent window *and* whose `origin` equals the `lotics_host` value, and every
+outgoing message is targeted at that origin — a third frame can neither inject
+results nor observe payloads. A host error with no message rejects as
+`"RPC failed"`.
+
+**Warning:** a bridged call has **no timeout**. An op the host doesn't
+implement does reject (`"Unknown RPC op: …"`), but a message the host drops
+without replying (a crashed handler, a malformed envelope) leaves the returned
+promise pending forever. Don't build UI that deadlocks awaiting an op you
+haven't verified exists in the host (see
+[op availability](#op-availability-by-transport)).
+
+**Warning (dev loop):** `lotics app dev` prints a wrapper URL — always drive
+*that* page. The wrapper embeds the app iframe with `?lotics_host=` and bridges
+ops to the API; the bare Vite origin has no host param, so the SDK falls into
+standalone mode, tries to resolve an app from the hostname, and every data call
+fails. Dev apps are always bridged; standalone mode exists only on the deployed
+`<slug>.lotics.app` host.
+
+### Standalone: direct public API
+
+On first data call the SDK resolves the app's identity from its own subdomain
+(one shared `GET /v1/apps/by-subdomain/{slug}` fetch — concurrent first calls
+coalesce; a transient failure isn't cached, the next call retries). If the app
+is password-protected, the SDK renders its own full-screen password overlay
+(plain DOM, so it works before React data arrives), exchanges the password for a
+session token, and stores it in `localStorage` under
+`lotics_app_session:<app_id>` with its expiry. The token rides as a `Bearer`
+header on subsequent calls; a `401` with error code `PASSWORD_REQUIRED` (the
+owner rotated or cleared the password) drops the stored token, re-prompts, and
+retries the original call once. There is no cancel button — the visitor enters
+the password or leaves. When `localStorage` is unavailable (private browsing,
+quota) the token lives in memory for the page's lifetime and the next reload
+re-prompts. What the password does and doesn't protect: [security](./security.md).
+
+### Transport error semantics
+
+Both transports guarantee an `Error.message` (or a `WorkflowResult.message`)
+that is safe to render:
+
+- A genuine JSON error response (a 4xx carrying `{ message }`) surfaces its
+  message verbatim.
+- Any **5xx**, any **non-JSON body** (a gateway HTML error page), or a JSON body
+  without a `message` becomes a body-free, status-derived message:
+  - `524` → `"The request took too long to finish (gateway timeout). It may
+    still be running — check back in a moment, or try again."`
+  - other `5xx` → `"The service is temporarily unavailable. Please try again
+    shortly."`
+  - otherwise → `"The service returned an unexpected response. Please try again."`
+- The `workflow` op **resolves instead of rejecting** on a transport/gateway
+  failure — you get `{ status: "error", message }`, uniform with a handled
+  workflow error. Always check `result.status`, not just `try/catch` — see
+  [mutations](./mutations.md).
+
+### Op availability by transport
+
+Most ops work everywhere; the exceptions are members-only or host-only
+surfaces:
+
+| Op | Embedded (product) | `lotics app dev` | Standalone |
+|---|---|---|---|
+| `query`, `field_options`, `workflow`, `members`, `context`, `upload`, `urlState.get/set`, `openExternal` | yes | yes | yes |
+| `comments.*` | yes | yes | rejects — `"Comments are available only in embedded apps — a signed-in member is required."` |
+| `agentRun` (streaming, internal to `useAgentRun`) | yes | yes | yes |
+| `agentRuns`, `agentRun.get`, `agentRun.cancel` | yes | **no** — the dev forwarder doesn't implement them (`"Unknown RPC op: …"`) | yes |
+| `askAi` | yes | **no** — `"Unknown RPC op: askAi"` | rejects — `"askAi is only available when the app runs inside Lotics"` |
+
+**Limitation:** in the dev loop, run *history* and server-side *cancel* for
+agent runs error (the local abort of a live stream still works); verify those
+paths on a deployed app. The standalone `query` transport forwards only
+`alias`/`params`/`limit`/`offset` — runtime `sort`/`filter`/`count` refinement
+is embedded-only (see [data fetching](./data_fetching.md)).
+
+## `rpc()` — the raw bridge (escape hatch)
+
+```ts
+import { rpc } from "@lotics/app-sdk";
+
+const { rows } = await rpc<{ rows: Record<string, unknown>[] }>("query", {
+  alias: "orders",
+  params: {},
+  limit: 500,
+  offset: 1000,
+});
+```
+
+`rpc<T = unknown>(op: RpcOp, payload: unknown): Promise<T>` sends one op over
+whichever transport is active. **Prefer the hooks** — they add SWR caching,
+loading/error state, analytics, and typing from your declared aliases. `rpc()`
+exists for the imperative cases the hooks don't model, chiefly paging a query to
+exhaustion for a full export — `rpc("query", { alias, params, limit, offset })`
+until a short page, then feed the rows to `downloadFile` (below). `T` is *your*
+assertion — the SDK does not validate the result shape.
+
+The full `RpcOp` union (`dist/src/rpc.d.ts`), each op's payload, and where its
+semantics are documented:
+
+| Op | Payload | Resolves to | Owning doc |
+|---|---|---|---|
+| `query` | `{ alias, params?, limit?, offset?, … }` | `{ rows }` | [queries](./queries.md), [data fetching](./data_fetching.md) |
+| `field_options` | `{ alias }` | `{ fields }` | [members & options](./members_and_options.md) |
+| `workflow` | `{ alias, inputs }` | `WorkflowResult` | [mutations](./mutations.md) |
+| `upload` | `{ file: File }` (the `File` crosses the bridge by structured clone) | uploaded-file object | [files](./files.md) |
+| `members` | `{ group? }` | `{ members }` | [members & options](./members_and_options.md) |
+| `context` | `{}` | app identity (below) | this doc |
+| `openExternal` | `{ url }` | `void` | this doc |
+| `askAi` | prompt/files/records seed | `void` | [ai](./ai.md) |
+| `agentRuns` | `{ session_id, limit?, offset? }` | `{ runs }` | [ai](./ai.md) |
+| `agentRun.get` | `{ run_id }` | `{ run }` | [ai](./ai.md) |
+| `agentRun.cancel` | `{ run_id }` | `{ ok: true }` | [ai](./ai.md) |
+| `urlState.get` / `urlState.set` | — / `{ params }` | `UrlParams` / `void` | [navigation & state](./navigation_and_state.md) |
+| `comments.list/create/update/delete/counts` | comment ops | comment payloads | [members & options](./members_and_options.md) |
+
+The **streaming** agent-run op is *not* reachable through `rpc()` — its
+response is a chunk stream, not a single value; it's internal to `useAgentRun`.
+
+`rpc("context", {})` resolves the app's identity: `{ app_id, app_name,
+workspace_id, organization_id, member_id, comments_enabled }`. `member_id` is
+the signed-in member when embedded, `null` standalone. **Limitation:** the
+context type is not exported from the package root — type the result yourself
+via the `rpc<T>` generic.
+
+## `openExternal()` — open a link in a new tab
+
+```tsx
+import { openExternal } from "@lotics/app-sdk";
+await openExternal(result.files[0].url);
+```
+
+`openExternal(url: string): Promise<void>` (`dist/src/open_external.d.ts`). The
+embedded app iframe is sandboxed **without `allow-popups`**, so a direct
+`window.open` from app code is *silently dropped* — no error, nothing happens.
+`openExternal` routes the URL to whoever can actually open it: the un-sandboxed
+host frame (embedded — including the dev wrapper) or the app's own top-level
+page (standalone). Opens in a new tab with `noopener,noreferrer`.
+
+- **Scheme validation at the point of open**: only `http:` and `https:` are
+  allowed; any other scheme (`javascript:`, `data:`, …) rejects the promise with
+  `openExternal: unsupported URL scheme "<protocol>"`, and a non-string `url`
+  rejects with `openExternal requires a url string`. The opener re-validates on
+  its own side — a URL handed across the bridge is never trusted.
+- Typical use: opening a workflow-generated file's `url` from
+  `WorkflowResult.files[]` (see [mutations](./mutations.md)).
+- **Not a preview mechanism.** To *view* a file inline, use `@lotics/ui`'s
+  `FilePreview`/`FileGalleryModal` (see [files](./files.md)); `openExternal` is
+  "leave the app".
+
+## `downloadFile()` — save browser-built bytes
+
+```tsx
+import { downloadFile } from "@lotics/app-sdk";
+import { buildDataWorkbook, exportWorkbook } from "@lotics/xlsx";
+
+function onExportClick() {
+  const wb = buildDataWorkbook({ columns, rows });
+  downloadFile(
+    "report.xlsx",
+    exportWorkbook(wb),
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  );
+}
+```
+
+`downloadFile(filename: string, data: Uint8Array | Blob | string, mimeType?:
+string): void` (`dist/src/download.d.ts`) saves bytes the app generated **in the
+browser** (an exported .xlsx, a CSV, generated text) to the visitor's device.
+It is the client-side counterpart to the server path (workflow generates a file
+→ `WorkflowResult.files[].url` → `openExternal`).
+
+- **Pure DOM, no RPC.** The embed sandbox includes `allow-downloads`, so a
+  same-origin blob download triggered from a user gesture needs no host
+  mediation; standalone pages download natively.
+- **Call it synchronously from the click handler that produced the bytes** so
+  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.
+- `mimeType` defaults to `application/octet-stream`. The blob URL is revoked on
+  the next task, after the download has started.
+
+## Device location & geofencing
+
+The host grants the app iframe the `geolocation` Permissions-Policy, so app code
+reads the device position **directly through the browser** — no RPC. The browser
+permission prompt appears as usual (attributed to the embedding site when
+embedded). Exact signatures: `dist/src/geolocation.d.ts`.
+
+**`isWithinZone(latitude, longitude, zone): boolean`** — pure great-circle
+(haversine) check: is the point within `zone.radius` meters of
+`zone.coordinates`? `GeofenceZone` is `{ coordinates: [latitude, longitude],
+radius: number /* meters */ }`.
+
+**`requestGeofencedLocation(zones: GeofenceZone[], opts?): Promise<GeofenceOutcome>`**
+gets a position fix and checks it against the allowed zones, returning a
+**structured outcome** — never a thrown permission error — so the app renders
+its own guidance in its own language:
+
+```tsx
+const r = await requestGeofencedLocation(ALLOWED_SITES);
+if (!r.ok) return showLocationGuidance(r.reason); // "denied" | "unavailable" | "outside"
+await checkIn({ latitude: r.coords.latitude, longitude: r.coords.longitude });
+```
+
+| Outcome | Meaning |
+|---|---|
+| `{ ok: true, coords }` | A fix landed inside at least one zone (or `zones` is empty). `coords` = `{ latitude, longitude, accuracy /* meters, browser-reported */ }`. |
+| `{ ok: false, reason: "denied" }` | Location permission not granted. A hard denial is fast-pathed via the Permissions API (where available) — no hang until timeout, and the browser will not re-prompt once blocked. |
+| `{ ok: false, reason: "unavailable" }` | No fix: geolocation unsupported, location services off, or the request timed out (`opts.timeoutMs`, default 15 000 ms). |
+| `{ ok: false, reason: "outside" }` | A fix was obtained but falls in no zone. |
+
+- An **empty `zones` array means "no geofence"** — resolves `ok` with the raw
+  position; use it as a plain location read.
+- The fix is standard accuracy (high-accuracy mode is not requested) and never
+  served from cache.
+- **Warning — the gate is advisory, client-side UX, not security.** It prevents
+  honest-user mistakes; it cannot stop a tampered client, and the server never
+  verifies position. Pass `coords` into a workflow input to *record* where an
+  action happened; any real authorization belongs in the workflow
+  (see [security](./security.md)).
+- **A blocked outcome leaves no server-side trace** — the action never ran, so
+  there is no workflow log to find. If field failures need diagnosing, surface
+  the `reason` visibly in the UI.
+
+## Automatic analytics (PostHog)
+
+`mount()` boots a PostHog instance per app — apps are a separate cross-origin
+bundle, invisible to the product's own analytics. **No per-app wiring**: don't
+install `posthog-js` or call any analytics API from app code.
+
+- **Explicit events only.** Autocapture, pageviews, and session replay are off
+  (autocapture is disabled at the project level — a client flag could not
+  re-enable it). Data reads (`useQuery` fetches) are deliberately not events.
+- Events the SDK emits automatically:
+
+| Event | Fired when | Properties |
+|---|---|---|
+| `app_opened` | analytics finished initializing after `mount()` | — |
+| `app_workflow_run` | each `useWorkflow` call settles | `alias`, `ok` |
+| `app_file_uploaded` | a `useFileUpload` upload succeeds | `mime_type` |
+| `app_agent_run` | a `useAgentRun` run finishes | `alias`, `ok` |
+| `app_comment_created` | a comment is created via `useComments` | `has_files` |
+| `app_comment_updated` / `app_comment_deleted` | comment edit/delete succeeds | — |
+
+- Every event carries the app identity as super-properties (`app_id`,
+  `app_name`, `workspace_id`, `organization_id`) and rolls up under the
+  `organization` group. Embedded apps `identify` the signed-in member — app and
+  product events share one person; standalone visitors stay anonymous.
+- Uncaught exceptions are captured (PostHog error tracking) in addition to
+  `mount()`'s visible banner.
+- **Tracking is gated to the deployed app host** (`*.lotics.app`). `lotics app
+  dev` (localhost) and any `?__mock=1` load emit nothing. Best-effort
+  throughout: a failed init or a failed `context` resolution disables tracking
+  and never breaks the app. Events fired before init completes are buffered
+  (bounded) and drained on init.
+- **Limitation:** there is no public API for custom app events — the capture
+  function is internal to the SDK. If a bespoke funnel matters, model it as a
+  workflow (which produces `app_workflow_run`) or request the surface as a
+  platform change.
+- **Limitation:** PostHog's default bot/user-agent filter applies — headless
+  browsers (e.g. Playwright) are never tracked, so analytics cannot be verified
+  through headless automation.
+
+## For package contributors
+
+Everything below concerns changing `@lotics/app-sdk` itself (in the Lotics
+monorepo), not building apps with it.
+
+### The publish chain — nothing reaches apps without a version bump
+
+Apps install the SDK from **npm**. Publish CI runs on pushes to `main` touching
+the package and publishes **only when `package.json#version` differs from the
+version on npm** — nothing else triggers it. `dist/`, `AGENTS.md`, and `docs/`
+(this file) are what ship (`package.json#files`), so a docs-only fix needs the
+same chain. A source or doc change reaches zero apps until:
+
+1. the version is bumped and the change merges to `main` (publish CI builds and
+   publishes),
+2. each app widens/updates its dependency range and reinstalls,
+3. the app redeploys.
+
+### Wiring a new RPC op — all four transports, or it 404s somewhere
+
+A new bridge op must be implemented in every transport, or it works in one place
+and breaks in another:
+
+1. `packages/app-sdk/src/rpc.ts` — the `RpcOp` union **and** the standalone
+   (direct-API) implementation,
+2. `frontend/features/app_ui/app_iframe_host.tsx` — the product host's bridge
+   handler,
+3. `packages/sdk/src/dev/` — the `lotics app dev` wrapper page and its Node
+   forwarder (`rpc_handler.ts`),
+4. the `LoticsClient` method (`packages/sdk/src/client.ts`) that forwarder
+   calls.
+
+The backend endpoint deploys with the PR, but `lotics app dev` forwards to the
+**production** API — a new op is not usable in the dev loop until the backend
+has deployed. Skipping a transport produces exactly the gaps in the
+[op availability table](#op-availability-by-transport) above — every "no" there
+is a transport that wasn't wired.
+
+### Bundler & dependency constraints
+
+- **Pure ESM, browser-only.** Apps bundle the SDK with Vite. No `require()`,
+  no dynamic `import()`, no Node built-ins. Don't touch `window` at module top
+  level — resolve lazily (test environments import modules before `jsdom` is
+  ready).
+- **Two bundlers in the family.** Apps build with Vite; the Lotics product
+  frontend builds with Metro (React Native Web). The SDK itself is never
+  Metro-bundled — the host frontend is forbidden from importing
+  `@lotics/app-sdk` (enforced by a dependency-direction test) — but sibling
+  packages apps share with the product (`@lotics/ui`, `@lotics/xlsx`,
+  `@lotics/docx`) build under both. When a shared package must diverge per
+  target, use platform files (`x.web.ts` / `x.ts`) plus conditional package
+  `exports` — never a runtime `require` or dynamic import.
+- **Self-contained on npm.** The SDK cannot import workspace-private or
+  host-only packages (`@lotics/shared`, `@lotics/ui-internal`, the frontend's
+  `@/` alias) or any React Native / Expo module — also test-enforced. A helper
+  that exists privately elsewhere gets a local copy here, with a comment saying
+  why.
+- **Data + RPC only — zero UI.** Never re-export a `@lotics/ui` component; the
+  SDK stays off the React-Native-Web dependency tree. Apps import `@lotics/ui`
+  directly.
+- **Keep the dependency set minimal.** Runtime deps are `posthog-js` and `swr`;
+  `react`/`react-dom` are peers. `react-router-dom` is an **optional** peer
+  pulled in only by the `@lotics/app-sdk/router` subpath export — the root entry
+  must never import it.

package/docs/security.md

@@ -0,0 +1,116 @@
+# Security: authority & scoping
+
+Every data operation an app performs — queries, workflows, agent runs — executes under the **app owner's** IAM principal, not the viewing member's. That single fact drives the whole author-facing security contract: the platform decides *what the app can reach* (the owner's access), and **you** decide *what each caller gets* — per-user scoping, write attribution, and privilege gates are authored into query templates and workflow bodies, never inferred from the client. Read this before shipping any app that shows per-user data, performs writes on behalf of a member, gates an action to a role, or is shared publicly. Related: [queries](./queries.md) (the read surface these rules apply to), [mutations](./mutations.md) (workflows), [ai](./ai.md) (agent runs), [files](./files.md) (presigned URLs).
+
+## The owner-principal model
+
+| Surface | Runs under | Caller identity available? |
+|---|---|---|
+| Named queries (`useQuery`, the query RPC) | App owner | Yes — bound server-side into `is_current_member` / `current_member` filter predicates |
+| Workflows (`useWorkflow`) | App owner | Yes — `runtime.triggered_by_member_id` in the workflow body (`null` for anonymous) |
+| Agent runs (`useAgentRun`) | App owner | Yes — requires an authenticated member; runs are private to that member |
+| Comments (`useComments`) | App authority for **access**; the **author** is always the real member | Always — members-only, anonymous callers are rejected |
+
+Consequences of owner authority:
+
+- **Data reach is the owner's.** A query reaches exactly the tables the owner can access; referencing a table the owner cannot reach fails with an "inaccessible tables" error.
+- **Row security evaluates against the owner, not the viewer.** Table-level row scoping (private filters) is applied for the *owner's* identity. If the owner is an org admin/owner, no row scope applies at all — the query sees every row of every table it references. An app can therefore surface rows the viewing member's own table permissions would hide. That is the design: the owner *chose* to expose those columns and rows by declaring the query.
+- **The viewer never widens or narrows a data op by existing.** A member with zero table access sees whatever the app's queries project, and a member with admin table access sees no more than that. `app:use` (or the public grant, below) is the only gate on invoking the app's declared surface.
+- **Who the model protects against.** The boundary is not "what the owner can do" — the owner declared the queries and workflows, so their authority is intentional. The boundary is **what a caller can do**: any caller, including an anonymous public visitor, can only invoke the declared aliases with typed, per-input-constrained values. An owner weakening their own declared constraint is a footgun, not an escalation — but a *caller* gaining data or capability the aliases don't declare is a real vulnerability, and the sections below are how you prevent the ones the platform cannot detect for you.
+
+Comments are the one deliberate exception: access is app-authority (any member with `app:use` + the app's declared `comments` capability may read/post on any record in the app's workspace, regardless of their own table access — a tenant floor rejects record ids outside the app's workspace), but the **author is always the real authenticated member** — never the app owner, never a "View as" subject — and edit/delete are author-only. Anonymous visitors cannot comment: the comment endpoints require an authenticated member.
+
+## The caller boundary
+
+Callers never submit query ASTs or workflow definitions — the server holds the canonical, deploy-validated template and the caller supplies only an **alias plus typed values**. Three per-input constraints are enforced server-side on **workflow and agent-run inputs** at invocation time, so a hand-crafted request can't redirect a run executing under owner authority:
+
+| Input type | Server-enforced bound |
+|---|---|
+| `member` (with a declared `group`) | Every submitted member id must belong to the declared group — the group scope is a write-time constraint, not a cosmetic picker filter |
+| `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 |
+
+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.
+
+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:
+
+- 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.
+- Writes only some members may perform → `current_member_in_any_group(...)` **in the workflow body**, never a client-side role check.
+
+## Scoping reads: `is_current_member` in the template
+
+To show a member only their own rows, put the scoping in the query template itself — a filter condition with the `is_current_member` operator on a member field (or `is_not_current_member` for the inverse). The server binds the predicate to the signed-in viewer at execution time and the client receives only the surviving rows. A client-supplied `member_id` param achieves the same UI with none of the security: any member can replay the query with a different id and read that member's rows (the devtools test fails).
+
+Who the server binds `is_current_member` to:
+
+| Caller | Binds to |
+|---|---|
+| Authenticated member of the app's org | That member |
+| Admin using "View as" (product UI, or `lotics app dev --view-as <member_id>`) | The **viewed** member — so an admin previews exactly what the member sees |
+| Authenticated member of a *different* org (public app, cross-org) | Their own member id — which matches no member cells in the app's workspace, so self-scoped queries return no rows |
+| Anonymous visitor (public app) | **The app owner** — see the public-app warning below |
+
+For **manager-only reads**, the template can carry a requester-level predicate: `current_member` with the `in_any_group` operator and a list of group ids. It matches when the *viewer* belongs to any listed group — so a "pending approvals" query returns rows only to members of the approvers group, and returns nothing to everyone else. Pair it with the workflow-side gate below; the read hides the queue, the write gate enforces it.
+
+## Attributing writes: `runtime.triggered_by_member_id`
+
+Who performed a write is derived server-side. In the workflow body, `runtime.triggered_by_member_id` is the authenticated member who invoked the workflow — stamped by the server from the session, `null` when an anonymous visitor invoked it through a public app. Use it to fill "requested by" / "submitted by" fields and to attribute side effects.
+
+A client-passed `member` input is **not** an identity: it's a spoofable value like any other param. The only thing the server binds a member input to is its *declared group* (the table above) — never to the caller. Use member inputs for genuine member *selection* (assign this order to a teammate), and `runtime.triggered_by_member_id` for *actor* identity.
+
+Anonymous invocations are audited with a `public` actor; member invocations carry the member id in the change origin.
+
+**"View as" does not carry into writes.** Under impersonation, *reads* bind the viewed member (the table above), but `runtime.triggered_by_member_id` — and the group gate below — bind the **real** authenticated member. An admin previewing a member's app stays attributed as themselves, and cannot acquire the viewed member's group privileges (nor lose their own).
+
+## Gating privileged writes: `current_member_in_any_group`
+
+A write only some members may perform — approve, override, close out — is authorized **in the workflow body**, because the workflow runs under owner authority and every member with app access can invoke it (devtools test). The workflow expression helper:
+
+```
+current_member_in_any_group(["grp_abc123"])
+```
+
+returns `true` when the **triggering member** belongs to any of the listed groups, and is fail-closed: no triggering member (anonymous or system trigger), a member in no groups, or a deleted/unknown group id all yield `false`. Branch on it and fail the run (or route to a rejection path) when it's `false`.
+
+**Model approvers as a group**, not as a hardcoded member id or a client-side check: a group survives personnel changes, is auditable, and is the unit both predicates understand — `current_member_in_any_group([...])` gates the write while `current_member in_any_group [...]` in a query template gates the matching read, so non-approvers never see the pending queue *and* can't act on it.
+
+## Public apps: anonymous reach and its bounds
+
+A publicly-shared app (`<slug>.lotics.app`, or its public link) is reachable by **anyone** — the public share grants `app:use` to anonymous visitors and to authenticated members of any other org alike. What anonymous visitors can and cannot do:
+
+| Surface | Anonymous access |
+|---|---|
+| Named queries + field options | Yes — under owner authority |
+| Workflow execution | Yes — under owner authority; `runtime.triggered_by_member_id` is `null`, audit actor is `public` |
+| File upload (workflow `file` inputs) | Yes — bounded to the app's workspace |
+| Query/workflow file outputs | Yes — file cells and workflow-produced files return direct presigned URLs (24-hour TTL) that anonymous viewers can fetch; see [files](./files.md) |
+| Agent runs (`useAgentRun`) | **No** — rejected: agent runs require an authenticated member, and each member's run history is private to them (a guessed session id cannot read another member's thread) |
+| Comments (`useComments`) | **No** — members-only |
+| Member roster (`useMembers`) | **No** — same-org members only (below) |
+
+**Warning — `is_current_member` on a public app resolves to the app owner.** An anonymous request has no viewer to bind, so both `is_current_member` and `current_member in_any_group` fall back to the owner's identity and the owner's groups. A "my items" query shows every anonymous visitor the *owner's* items, and a manager-only read template gated on a group the owner belongs to **passes for every anonymous visitor**. Never rely on viewer-bound predicates in a public app.
+
+**Per-user data does not ship in a public app.** A public app has no visitor identity to scope by, so a free-param lookup — `getOrder(order_id)` — is an enumerable IDOR: anyone can walk the id space. No server mechanism detects a "sensitive param"; the only correct designs are (a) an **embedded** (authenticated) app with `is_current_member` scoping, or (b) a public app whose every query is safe to show to the whole internet. A shared **password** can be set on a public app (exchanged for a session token, rate-limited) — it gates *access to the app*, but password-holding visitors are still anonymous: no identity binds, all the fallbacks above still apply.
+
+### Member roster access
+
+Listing members (`useMembers`) is deliberately narrow, because an org roster with emails must not leak through an arbitrary app. Three gates, all server-enforced: (1) the caller must be an **authenticated member of the app's own org** with `app:use` — anonymous and cross-org callers get 403; (2) the app must have **declared member access** — at least one workflow input or query param of type `member`; an app that never works with members cannot enumerate the roster; (3) a `group_id` filter is honored only for a group **declared** on one of those member inputs — an app cannot enumerate groups it never uses. In query *results*, projected member cells resolve to `{ id, name }` for everyone; `email` is included only for authenticated members of the app's own org. See [members_and_options](./members_and_options.md).
+
+## What runtime refinement cannot widen
+
+The query RPC accepts runtime `filter` and `sort` (for search boxes, sortable tables, pickers) — but these are **bounded to the named query's output columns**. A `field_key` naming a column the query does not project is rejected, so a caller can never filter or sort by — and thereby probe — a field the author didn't expose. The caller's `limit` is clamped to the server row cap, params fill the template's *value holes* only — filter values and the search term; tables, joins, and projections are author-fixed — and `count` mode returns a single total over the same bounded filter. Full mechanics in [queries](./queries.md).
+
+**Warning — templated free-text search is not output-bounded.** A `search` term in the query template (typically a `{{params.q}}` hole) matches against the record's **whole search document**: every searchable field of the table — text, numbers, dates (in three formats), select option names, member names, linked-record display text, formula/rollup/lookup values, and autonumbers (only booleans, buttons, and file fields are excluded). It is *not* restricted to the columns the query projects. A caller who controls the search term can therefore probe the *contents* of unprojected fields by watching which rows match — a row-membership oracle. Put a `search` hole only in queries over tables where every searchable field is acceptable to probe for that audience; for a search box over a table with sensitive unprojected fields, use runtime `filter` with `contains` on the projected columns instead.
+
+## `useViewer` is display-only
+
+`useViewer()` returns the signed-in member currently viewing the app — the view-as target under "View as", `null` for an anonymous public visitor or while the context loads. It exists to **personalize and prefill**: greet the member, default an assignment to them, pass them into a picker. It is **never an authorization fact and never a scoping mechanism** — anything the client sends, including a `useViewer`-derived id, is replayable with a different value. Row scoping belongs in the query template (`is_current_member`, which the server resolves to the same person `useViewer` reports, view-as included); actor identity belongs in the workflow body (`runtime.triggered_by_member_id`); privilege belongs in the workflow gate (`current_member_in_any_group`). Signature: `dist/src/viewer.d.ts`.
+
+---
+
+*For platform maintainers*: the full IAM model, the public-access grant mechanics, and the rationale behind owner authority live in the monorepo's `docs/apps.md` and `docs/iam.md` (not shipped with this package).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.46.1",
+  "version": "0.47.0",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {
@@ -16,7 +16,8 @@
   "types": "./dist/src/index.d.ts",
   "files": [
     "dist",
-    "AGENTS.md"
+    "AGENTS.md",
+    "docs"
   ],
   "scripts": {
     "build": "tsgo",