@assembly-js/app-foundation 0.13.0 → 0.14.1

package/CHANGELOG.md

@@ -19,6 +19,13 @@ A patch release never changes what an app's build requires; a minor release may
 not by hand; see `changes/README.md`. CI fails a PR that changes a check script without a
 `bump: minor` change file.
 
+## 0.14.1
+- [guidance] The build agent is taught that a call to another app through the installer client or a raw `fetch` carries the client in a client's request, that the platform can refuse it with `viewer_cannot_open_app`, and which cases the check does not cover; a route that allows only app callers answers a client who arrives through another app with 403, so it must list `client` to admit them; a `check-app-only-routes: intended` comment only tells the check script that a route should stay app-only.
+
+## 0.14.0
+- [guidance] The build agent now counts related rows per record with `db.$count` or a joined subquery, instead of a raw correlated subselect that drizzle renders without table names and that reads 0 on every row.
+- [behavior] Later edits to the app now catch a per-record count that would always show 0 (for example "0 answers" on every question) before the change is saved, and fix it in the same edit.
+
 ## 0.13.0
 - [new] `<ClientName client={client} />` and `<CompanyName company={company} />` from `@assembly-js/app-foundation/lib-client` render a name that opens the record's CRM page for staff and is plain text for a client viewer.
 - [new] `bun run build` runs `check:linked-names`, which fails when a client's or company's name is rendered by hand instead of through those components. It only runs on apps that carry the platform-links skill.

package/CLAUDE.md

@@ -463,10 +463,10 @@ Relationships:
 **App isolation.** `listAppInstalls`/`retrieveAppInstall` tell you which apps are installed (id, appId, type, icon, and other install metadata), and `listAppConnections`/`createAppConnection` manage manual embed and link connections between installed apps — that's real, supported SDK surface, and requests to inspect an install or set up one of those connections are not out of bounds. None of it reaches another app's own data, though: you have no access to another installed app's database, tables, or any other internal data, and there is no SDK call that reads or writes another app's data store. If a request needs another app's private data, say only that it isn't possible and stop — no alternatives and no follow-up question. In user-facing chat, call them apps, not custom apps. Do not propose a bridge: no endpoint or API on the other app, no webhook, push, or sync, and nothing the user has to paste between chats. Do not volunteer automations, clients, companies, custom fields, or an Assembly module as a substitute. If the user explicitly asks to call an existing registered API exposed by another app, that is supported API access rather than database access; never suggest it unprompted. Likewise, if the request itself explicitly asks for automations, CRM data, or an installed module's supported data (for example invoices), that is a separate supported request. Never reach another app's database directly.
 <!-- feature:api-resources -->
 
-If the user names another app, read its file in `.assembly/docs/apps/` and follow the call recipe at the top of that file. If that folder is absent, the app is not callable (it may still need the Security update). Cross-app calls from pages, server actions and routes use `getInstallerAssembly()`; cron and webhooks use `getOfflineAssembly()`. Never return another app's response to a client unfiltered — scope any client data you forward. While a person is using the app, those calls use the installer client, because the platform does not yet prove which person the call is for. Once it can, use the viewer client for that person's data and keep the installer client for staff-wide reads.
+If the user names another app, read its file in `.assembly/docs/apps/` and follow the call recipe at the top of that file. If that folder is absent, the app is not callable (it may still need the Security update). Cross-app calls from pages, server actions and routes use `getInstallerAssembly()`; cron and webhooks use `getOfflineAssembly()`. Never return another app's response to a client unfiltered — scope any client data you forward. In a client's request, a call to another app through the installer client or a raw `fetch` to `/v1/apps/...` carries that client: the platform checks the client could open the other app (refusal `viewer_cannot_open_app`) and the other app sees a client whose calling app is this one. A staff request, cron, a webhook or a queue sends no client. See `assembly-app-clients` for the cases the check does not cover.
 <!-- /feature:api-resources -->
 <!-- feature:cross-app-apis -->
-When `generated/apps/<appId>/` exists for that app, call it through the generated client instead (see the `assembly-app-clients` skill); the docs recipe is the fallback for an app with no folder there. The generated client supersedes the installer-client note above: a client contact's own calls use `viewerClient`, which the platform scopes to that contact; team members and background work use `installerClient`.
+When `generated/apps/<appId>/` exists for that app, call it through the generated client instead (see the `assembly-app-clients` skill); the docs recipe is the fallback for an app with no folder there. The generated client supersedes the installer-client note above: a client contact's own calls use `viewerClient`, which the platform scopes to that contact; team members and background work use `installerClient`, which in a client's request also carries that client.
 <!-- /feature:cross-app-apis -->
 
 ---
@@ -648,6 +648,14 @@ export const items = pgTable('items', {
 - Use `drizzle-kit push` (not `migrate`) — no migration files; schema is pushed directly.
 - Use `@neondatabase/serverless` with `drizzle-orm/neon-http` — not `pg` or `postgres.js`. It's the standard driver for the Vercel serverless (Node) runtime this app deploys to; `lib/db.ts` already wires it up.
 - **No interactive transactions.** `db.transaction(async (tx) => …)` is unsupported on neon-http and throws (a 500). For atomic multi-writes use `db.batch([...])`; otherwise sequential `await`s. See the `assembly-db-transactions` skill.
+- **Per-row counts: `db.$count` or a joined subquery, never a raw correlated subselect.** In a `.select({ … })` field of a query with no join, drizzle writes the columns inside a `sql` template without table names, so `(select count(*) from ${answers} where ${answers.questionId} = ${questions.id})` compares answers with itself and every row counts 0, with no error. (`.where()` is unaffected.) Use one of:
+  ```ts
+  db.select({ id: questions.id, answerCount: db.$count(answers, and(eq(answers.questionId, questions.id), eq(answers.kind, 'answer'))) }).from(questions);
+
+  const ac = db.select({ questionId: answers.questionId, c: count().as('c') }).from(answers).where(eq(answers.kind, 'answer')).groupBy(answers.questionId).as('ac');
+  db.select({ id: questions.id, answerCount: sql<number>`coalesce(${ac.c}, 0)` }).from(questions).leftJoin(ac, eq(ac.questionId, questions.id));
+  ```
+  `bun run build` fails on the raw form (`check:sql-subselects`).
 - **Create writes every field the create form submits.** If a later save writes nested rows (packages, add-ons, blocks), create calls that same writer with the submitted payload. A success toast and a redirect to the editor do not save. See `assembly-record-writes`.
 - `DATABASE_URL` is already in the shell env. Do NOT hardcode it or write it to `.env.local`.
 - Use `db` from `lib/db.ts` in **server components, server actions, and route handlers only** — never in client components. This is enforced: `lib/db.ts` imports `server-only`, so pulling it (or anything that imports it, e.g. a lib file re-exporting constants) into a `'use client'` module fails `bun run build`. Keep client-shared constants/types in their own file, not next to server queries.
@@ -928,7 +936,7 @@ The foundation runs the whole session; you write none of it:
 
 - `getAssembly()` — the viewer, in server components and server actions. The default for anything shown to or done for the person using the app.
 - `getAssemblyForRequest(request)` — the viewer, in a route handler; returns the client or a 401 to return as is.
-- `getInstallerAssembly()` — the installing admin, inside a user request, for staff-wide reads and writes the app is entitled to on its own (notification helpers, app storage, connectors). Filter what it returns before showing it to a client.
+- `getInstallerAssembly()` — the installing admin, inside a user request, for staff-wide reads and writes the app is entitled to on its own (notification helpers, app storage, connectors). Filter what it returns before showing it to a client. Its calls to another app are the exception: in a client's request they carry that client.
 - `getOfflineAssembly()` — no viewer at all (cron, webhooks): an app-scoped bearer minted from `ASSEMBLY_API_KEY`. It refuses inside a viewer request.
 
 **Identity.** Branch on who the viewer is before making data calls, never by catching a 403: server-side `const id = await getSessionIdentity()` (`{ workspaceId, internalUserId?, clientId?, companyId? } | null`), client-side `useAssembly()` (`isClient`, `internalUserId`, `clientId`, seeded from the server, no loading state). A client may read only its own record and its active company.

package/bin/check-sql-subselects.mjs

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+// Fails the build when a raw `sql` template in a drizzle `.select({ … })` field
+// list runs a correlated subselect against another table and the statement has
+// no join. drizzle renders columns embedded in a select field as bare names when
+// the query has a single table, so `where ${answers.questionId} = ${questions.id}`
+// becomes `where "question_id" = "id"`: the inner table is compared with itself,
+// the SQL stays valid, and a per-row count is 0 for every row. A field that names
+// the template through a const in the same file is followed too.
+// Dependency free on purpose: it runs inside the generated app's sandbox before
+// any deps beyond Node are guaranteed.
+//
+// On a platform update turn (ASSEMBLY_UPDATE_TURN=1) it only warns, because an
+// update never rewrites an app's queries.
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+
+const ROOT = process.cwd();
+const UPDATE_TURN = process.env.ASSEMBLY_UPDATE_TURN === '1';
+const SOURCE_DIRS = ['app', 'lib', 'components', 'src'];
+const SOURCE_FILE = /\.(tsx|ts|jsx|js|mjs)$/;
+const OPT_OUT = /sql-subselects:\s*qualified/;
+const SELECT_OBJECT = /\.select\s*\(\s*\{/g;
+const SQL_TEMPLATE = /\bsql\s*(?:<[^`;]*?>)?\s*`/g;
+// `const answerCountSql = sql\`…\`` or `const answerCountSql = (…) => sql\`…\``.
+const NAMED_TEMPLATE =
+  /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::[^=;]+)?=\s*(?:\([^)]*\)\s*(?::[^=;]+)?=>\s*)?sql\s*(?:<[^`;]*?>)?\s*`/g;
+const DECLARATION = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)/g;
+const FIELD_VALUE = /:\s*([A-Za-z_$][\w$]*)\b/g;
+const SUBSELECT = /\(\s*select\b/i;
+const FROM_TABLE = /\bfrom\s+\$\{\s*([A-Za-z_$][\w$]*)\s*\}/gi;
+const COLUMN_REF = /\$\{\s*([A-Za-z_$][\w$]*)\.[A-Za-z_$]/g;
+const JOIN = /\.(?:left|inner|right|full|cross)Join(?:Lateral)?\s*\(/;
+// A line that starts a new statement; without semicolons the next query would
+// otherwise be read as part of this one and its join would excuse this query.
+const NEXT_STATEMENT = /^\n\s*(?:export|const|let|var|function|async|return|await|if|for|while|class|import)\b/;
+
+function sourceFiles(dir) {
+  const out = [];
+  if (!existsSync(dir)) return out;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules' || entry.name === '.next') continue;
+      out.push(...sourceFiles(full));
+    } else if (SOURCE_FILE.test(entry.name)) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+// Index just past a string, template literal or comment starting at `i`, or `i`
+// when none starts there. Templates recurse through their `${…}` holes.
+function skipLiteral(src, i) {
+  const c = src[i];
+  if (c === '/' && src[i + 1] === '/') {
+    const end = src.indexOf('\n', i);
+    return end === -1 ? src.length : end;
+  }
+  if (c === '/' && src[i + 1] === '*') {
+    const end = src.indexOf('*/', i + 2);
+    return end === -1 ? src.length : end + 2;
+  }
+  if (c === '"' || c === "'") {
+    let j = i + 1;
+    while (j < src.length && src[j] !== c && src[j] !== '\n') j += src[j] === '\\' ? 2 : 1;
+    return j + 1;
+  }
+  if (c === '`') return templateEnd(src, i);
+  return i;
+}
+
+// Index just past the template literal whose opening backtick is at `i`.
+function templateEnd(src, i) {
+  let j = i + 1;
+  while (j < src.length) {
+    if (src[j] === '\\') j += 2;
+    else if (src[j] === '`') return j + 1;
+    else if (src[j] === '$' && src[j + 1] === '{') j = closingIndex(src, j + 1) + 1;
+    else j += 1;
+  }
+  return src.length;
+}
+
+// Index of the bracket that closes the one at `i`.
+function closingIndex(src, i) {
+  let depth = 0;
+  let j = i;
+  while (j < src.length) {
+    const skipped = skipLiteral(src, j);
+    if (skipped !== j) {
+      j = skipped;
+      continue;
+    }
+    const c = src[j];
+    if (c === '(' || c === '[' || c === '{') depth += 1;
+    else if (c === ')' || c === ']' || c === '}') {
+      depth -= 1;
+      if (depth === 0) return j;
+    }
+    j += 1;
+  }
+  return src.length;
+}
+
+// The statement a `.select(` belongs to, from it to the next `;` at depth 0, a
+// new statement on a later line, or the bracket that closes the expression around it.
+function statementTail(src, i) {
+  let depth = 0;
+  let j = i;
+  while (j < src.length) {
+    const skipped = skipLiteral(src, j);
+    if (skipped !== j) {
+      j = skipped;
+      continue;
+    }
+    const c = src[j];
+    if (c === '(' || c === '[' || c === '{') depth += 1;
+    else if (c === ')' || c === ']' || c === '}') {
+      depth -= 1;
+      if (depth < 0) break;
+    } else if (depth === 0 && (c === ';' || (c === '\n' && NEXT_STATEMENT.test(src.slice(j, j + 40))))) break;
+    j += 1;
+  }
+  return src.slice(i, j);
+}
+
+// Bodies of every `sql` template in `text`, with their offset in it.
+function templatesIn(text) {
+  const out = [];
+  for (const m of text.matchAll(SQL_TEMPLATE)) {
+    const start = m.index + m[0].length - 1;
+    out.push({ body: text.slice(start, templateEnd(text, start)), offset: m.index });
+  }
+  return out;
+}
+
+function correlatesAnotherTable(body) {
+  if (!SUBSELECT.test(body)) return false;
+  const inner = new Set([...body.matchAll(FROM_TABLE)].map((m) => m[1]));
+  if (inner.size === 0) return false;
+  return [...body.matchAll(COLUMN_REF)].some((m) => !inner.has(m[1]));
+}
+
+// The source with comments and quoted strings blanked out (newlines and quotes
+// kept, so offsets and line numbers still match), so a query kept in a comment
+// or an example string is never checked. Template literals stay: `sql` is one.
+function withoutComments(src) {
+  let out = '';
+  let i = 0;
+  while (i < src.length) {
+    const end = skipLiteral(src, i);
+    if (end === i) {
+      out += src[i];
+      i += 1;
+      continue;
+    }
+    const chunk = src.slice(i, end);
+    if (src[i] === '/') out += chunk.replace(/[^\n]/g, ' ');
+    else if (src[i] === '`') out += chunk;
+    else out += chunk[0] + chunk.slice(1, -1).replace(/[^\n]/g, ' ') + chunk.slice(-1);
+    i = end;
+  }
+  return out;
+}
+
+function lineAt(src, index) {
+  return src.slice(0, index).split('\n').length;
+}
+
+const files = SOURCE_DIRS.flatMap((dir) => sourceFiles(join(ROOT, dir)));
+const violations = [];
+for (const file of files) {
+  const raw = readFileSync(file, 'utf8');
+  if (!raw.includes('.select(') || OPT_OUT.test(raw)) continue;
+  const src = withoutComments(raw);
+
+  // A name declared more than once in the file cannot be tied to one template
+  // without scope analysis, so it is not followed rather than guessed.
+  const declared = new Map();
+  for (const m of src.matchAll(DECLARATION)) declared.set(m[1], (declared.get(m[1]) ?? 0) + 1);
+  const named = new Map();
+  for (const m of src.matchAll(NAMED_TEMPLATE)) {
+    if (declared.get(m[1]) > 1) continue;
+    const start = m.index + m[0].length - 1;
+    named.set(m[1], src.slice(start, templateEnd(src, start)));
+  }
+
+  for (const m of src.matchAll(SELECT_OBJECT)) {
+    const objStart = m.index + m[0].length - 1;
+    const fields = src.slice(objStart, closingIndex(src, objStart) + 1);
+    const hits = templatesIn(fields)
+      .filter((t) => correlatesAnotherTable(t.body))
+      .map((t) => objStart + t.offset);
+    for (const v of fields.matchAll(FIELD_VALUE)) {
+      const body = named.get(v[1]);
+      if (body && correlatesAnotherTable(body)) hits.push(objStart + v.index);
+    }
+    if (hits.length === 0 || JOIN.test(statementTail(src, m.index))) continue;
+    const rel = relative(ROOT, file).split(sep).join('/');
+    for (const at of hits) violations.push(`${rel}:${lineAt(src, at)}`);
+  }
+}
+
+if (violations.length > 0 && UPDATE_TURN) {
+  console.warn('');
+  console.warn('check-sql-subselects: correlated sql subselect in a single-table select (this update turn is not failed for it):');
+  for (const v of violations) console.warn('  - ' + v);
+  console.warn('');
+} else if (violations.length > 0) {
+  console.error('');
+  console.error('A raw sql subselect in a .select({ … }) field reads another table, and the query has no join:');
+  console.error('');
+  for (const v of violations) console.error('  - ' + v);
+  console.error('');
+  console.error('drizzle writes the columns in that template without table names when the query has');
+  console.error('one table, so `${answers.questionId} = ${questions.id}` compares answers with itself');
+  console.error('and the count is 0 on every row. Use db.$count as the field instead:');
+  console.error('  answerCount: db.$count(answers, and(eq(answers.questionId, questions.id), eq(answers.kind, "answer")))');
+  console.error('or group the counts in a subquery (.groupBy(...).as("ac")) and .leftJoin it.');
+  console.error('A template whose names are already qualified (sql.raw) can add the comment');
+  console.error('`// sql-subselects: qualified` to the file.');
+  process.exit(1);
+}

package/dist/assembly.d.ts

@@ -103,6 +103,11 @@ export declare function getOfflineAssembly(): Promise<AssemblyAPI>;
  * a second call in the same request reuses that bearer. A call through `fetch` to
  * another app (`/v1/apps/...`) is the exception: in a client's request it is made
  * as that client (see getCrossAppBearer), in a staff request as this app.
+ *
+ * The check does not cover work deferred past the response (`after()` throws
+ * rather than carry the bearer), an app that mints its own bearer, or a calling app
+ * on a foundation release before this one. A callee route that allows only app
+ * callers answers 403 to a client who arrives this way; see bin/check-app-only-routes.mjs.
  */
 export declare function getInstallerAssembly(): Promise<AssemblyAPI>;
 export type AppProxyCaller = 'viewer' | 'installer';

package/dist/assembly.js

@@ -383,6 +383,11 @@ async function getInstallerBearer() {
  * a second call in the same request reuses that bearer. A call through `fetch` to
  * another app (`/v1/apps/...`) is the exception: in a client's request it is made
  * as that client (see getCrossAppBearer), in a staff request as this app.
+ *
+ * The check does not cover work deferred past the response (`after()` throws
+ * rather than carry the bearer), an app that mints its own bearer, or a calling app
+ * on a foundation release before this one. A callee route that allows only app
+ * callers answers 403 to a client who arrives this way; see bin/check-app-only-routes.mjs.
  */
 export async function getInstallerAssembly() {
     return getBearerAssembly(await getInstallerBearer(), undefined, {

package/dist/codegen.js

@@ -155,7 +155,7 @@ const { data, error } = await installerClient.GET('/projects/{id}', {
 });
 \`\`\`
 
-- \`installerClient\` calls as this app. Use it for pages and actions a team member runs, and from cron, webhooks and background work. Filter anything you show to a client.
+- \`installerClient\` calls as this app. Use it for pages and actions a team member runs, and from cron, webhooks and background work. In a client's request it also carries that client, so the platform checks the client could open this app. Filter anything you show to a client.
 - \`viewerClient\` calls as the signed-in client contact. The platform scopes the call to that contact, so do not filter what it returns. Use it for pages and actions a contact runs; it is refused for a team member.
 
 ## Operations

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [

package/skills/assembly-api-contract/SKILL.md

@@ -30,7 +30,11 @@ A route is not callable by other apps, so it must not appear, when it is:
 
 Every operation in the contract is proxied to other apps, so its handler must admit an app caller. Call `requireAuth` and `requireCompanyScope` with no `allow` option, or list `'app'` (`allow: ['internal', 'client', 'app']`). A route that passes only `['internal', 'client']` answers every other app with a 403, which the calling app reports as the request being refused.
 
-An app caller carries `callerAppId` and no `internalUserId` or `clientId`. Give it its own branch rather than mapping identity through a person-only viewer that returns null and falls into a 403. Read and write on the app's own authority with `getInstallerAssembly()`, as staff would, and never return client-private data you would not show staff. A route that must stay human-only belongs in `privateRoutes`, and stays out of this contract.
+An app caller carries `callerAppId`. When the calling app is acting for itself (a staff request, cron, a webhook), there is no `internalUserId` or `clientId`: give it its own branch rather than mapping identity through a person-only viewer that returns null and falls into a 403. Read and write on the app's own authority with `getInstallerAssembly()`, as staff would, and never return client-private data you would not show staff.
+
+When the calling app was serving a client, the call arrives as that client with `callerAppId` set, and the platform has already checked the client could open this app. A person wins over the calling app, so a route that allows only `'app'` (`allow: ['app']` or `['internal', 'app']`) answers that client 403, and a handler that takes the app branch and uses the installer lands in the client branch with a limited SDK. List `'client'` on a route such a client may reach and scope what it returns to that client. A route that should stay app-only carries a `check-app-only-routes: intended` comment on its allow list or the line above; `bin/check-app-only-routes.mjs` lists every allow list that admits `'app'` but not `'client'`.
+
+A route that must stay human-only belongs in `privateRoutes`, and stays out of this contract.
 
 ## Worked example
 

package/skills/assembly-app-clients/SKILL.md

@@ -1,7 +1,7 @@
 <!-- feature:cross-app-apis -->
 ---
 name: assembly-app-clients
-description: Use when the app calls another workspace app and `generated/apps/<appId>/` exists for it. Covers reading the generated README and types, calling `viewerClient` or `installerClient` by verb and path, and rendering an empty state that names the app when the call is refused (app_not_found, operation_not_found, viewer_not_allowed, callee_error) instead of throwing a 500.
+description: Use when the app calls another workspace app and `generated/apps/<appId>/` exists for it. Covers reading the generated README and types, calling `viewerClient` or `installerClient` by verb and path, and rendering an empty state that names the app when the call is refused (app_not_found, operation_not_found, viewer_not_allowed, viewer_cannot_open_app, callee_error) instead of throwing a 500.
 ---
 
 ## Where the client lives
@@ -33,7 +33,13 @@ Call it from server code only: pages, server actions, route handlers, cron and w
 
 `viewerClient` calls as the signed-in client contact. The platform scopes the call to that contact, so do not filter or double-check what it returns. Use it for pages and actions a contact runs. The platform refuses it for a team member.
 
-`installerClient` calls as this app, not as a person. Use it for pages and actions a team member runs, and from cron, webhooks and other background work. Filter anything you show to a client.
+`installerClient` calls as this app. Use it for pages and actions a team member runs, and from cron, webhooks and other background work. Filter anything you show to a client.
+
+In a client's request it also carries that client: the platform checks the client could open the other app, and the other app sees a client whose calling app is this one. A client who cannot gets `viewer_cannot_open_app`. A staff request, cron, a webhook and a queue send no client. If the client's session cannot be verified (exchange off, a rejected header, an expired cookie) the call throws the token-invalid error rather than running as this app, and a call made where the request cannot be read (`'use cache'`, prerender, `after()`) throws; make it from a page, server action or route handler.
+
+The check does not cover work deferred until after the response, an app that mints its own bearer instead of using this client, or a calling app on a foundation release before the one that added it. Do not rely on it to filter data.
+
+A route in this app that allows only app callers (`allow: ['app']`) answers 403 to a client who arrives through another app, because a person wins over the calling app. Add `'client'` and scope the data to that client, or mark a route that should stay app-only with a `check-app-only-routes: intended` comment on the allow list or the line above; `bin/check-app-only-routes.mjs` lists the routes.
 
 If an operation can be called by a contact, it must not make platform calls about clients, companies or the workspace as the caller. Contacts are refused on those routes and the call surfaces as a generic failure. Look things up with the app's own access, or store the display names on the row when the item is assigned.
 
@@ -46,6 +52,7 @@ The other app can be uninstalled, can drop an operation, or can fail on its own.
 | `app_not_found` | The app is not installed in this workspace, or this app may not call it. | Empty state: "<App name> is not available in this workspace." |
 | `operation_not_found` | The app no longer offers this operation. | Empty state: "<App name> no longer provides this." |
 | `viewer_not_allowed` | The platform refused the call for this person: a team member used `viewerClient`, or a contact could not be resolved. | For a team member, call with `installerClient`. For a contact, render an empty or permission state naming the app and never retry with `installerClient`. |
+| `viewer_cannot_open_app` | The client who triggered the call could not open the other app themselves, so the platform refused `installerClient` in their request. | Render an empty or permission state naming the app. Do not retry with other authority. |
 | `callee_error` | The other app answered with its own failure. The most common case at runtime. | Error state: "<App name> could not load this right now." |
 
 Branch on the result and render a state that names the app:

package/skills/assembly-automations/SKILL.md

@@ -383,7 +383,7 @@ export const GET = automationActionRoute(async (_input, { workspaceId }) => {
 
 ## Calling another app
 
-If the user names another app, read its file in `.assembly/docs/apps/` and follow the call recipe at the top of that file. If that folder is absent, the app is not callable (it may still need the Security update). Cross-app calls from pages, server actions and routes use `getInstallerAssembly()`; cron and webhooks use `getOfflineAssembly()`. Never return another app's response to a client unfiltered — scope any client data you forward. While a person is using the app, those calls use the installer client, because the platform does not yet prove which person the call is for. Once it can, use the viewer client for that person's data and keep the installer client for staff-wide reads.
+If the user names another app, read its file in `.assembly/docs/apps/` and follow the call recipe at the top of that file. If that folder is absent, the app is not callable (it may still need the Security update). Cross-app calls from pages, server actions and routes use `getInstallerAssembly()`; cron and webhooks use `getOfflineAssembly()`. Never return another app's response to a client unfiltered — scope any client data you forward. In a client's request, a call to another app through the installer client or a raw `fetch` to `/v1/apps/...` carries that client: the platform checks the client could open the other app (refusal `viewer_cannot_open_app`) and the other app sees a client whose calling app is this one. A staff request, cron, a webhook or a queue sends no client. See `assembly-app-clients` for the cases the check does not cover.
 
 ## Telling the user