@assembly-js/app-foundation 0.0.53 → 0.0.55

package/CHANGELOG.md

@@ -14,6 +14,13 @@ A foundation update reads the sections between an app's version and the target:
 from every bullet except `[guidance]`, agent work from the check scripts those `[action]`
 bullets ship. Write `[fix]`, `[behavior]` and `[action]` bullets for the app's owner.
 
+## 0.0.55
+- [new] Add a scan the platform can run on demand to find calls that use a signed-in viewer's access to the platform API from pages and routes clients can open. Nothing in the app changes and no file is added to it.
+
+## 0.0.54
+- [new] Add `isAppInstalled` and `getInstalledAppIds`, helpers an app can adopt to check which optional modules are installed in its workspace.
+- [guidance] The build agent is taught to check that a module is installed before relying on features that depend on it.
+
 ## 0.0.53
 - [action] A page or server action that calls a helper exported from a client-component file errors for every visitor who opens it; the build now reports the call, and the helper moves to a plain module both sides import.
 - [guidance] Tell the build agent that a helper shared between a server-rendered page and a client component belongs in a plain module, not the client component's file.

package/CLAUDE.md

@@ -167,7 +167,9 @@ Before adding a feature, check whether Assembly already covers it. If it does, *
 
 **Always available (every workspace):** Clients, companies, and custom fields — see "The data model" below. Use them; do not rebuild them. Notification infrastructure (`listNotifications`, `createNotification`, `deleteNotification`, `markNotificationRead`, `markNotificationUnread`) is also always available.
 
-**Optional modules (may or may not be installed in this workspace):** Messages, Files, Contracts, Forms, Billing, Knowledge Base, Tasks, and Notes. Before suggesting one or calling its SDK, confirm it is installed — call `listAppInstalls`. If it is installed, use it through the SDK; do not rebuild it. If it is not installed, do not suggest it, do not plan the app around it, and do not ask the user to install it.
+**Optional modules (may or may not be installed in this workspace):** Messages, Files, Contracts, Forms, Billing, Knowledge Base, Tasks, and Notes. Before suggesting one or building on one, confirm it is installed: gate the feature with `isAppInstalled(assembly, <appId>)` from `@assembly-js/app-foundation/server` and render an honest "<app> isn't installed in this workspace" state when it is false; the plan's module list is the build-time source of truth. If it is installed, use it through the SDK; do not rebuild it. If it is not installed, do not suggest it, do not plan the app around it, and do not ask the user to install it.
+
+**Never ask the user to test a client-facing write (a form request, message, invoice, notification) on a real client.** Suggest a throwaway test client instead, and say before the first test that a form request can't be undone from the app — it can only be removed in the dashboard.
 
 - **Messages** — Direct messaging between staff and clients. SDK groups: Messages, MessageChannels.
 - **Files** — Secure file/folder sharing. *For app-private uploads (attachments, exports) use the storage helpers from `@assembly-js/app-foundation/server` (see the `assembly-storage` skill) instead — Files is only for files the user wants in the portal Files tab.* SDK groups: Files, FileChannels.

package/bin/client-safe-sdk-methods.mjs

@@ -0,0 +1,11 @@
+// PROVISIONAL until the final client-safe public route list lands.
+//
+// The routes a client bearer may keep calling once clients stop acting as admin,
+// as SDK method names (the SDK is flat: `retrieveClient`, not `clients.retrieve`):
+//   GET /v1/me                -> retrieveMe
+//   GET /v1/clients/{id}      -> retrieveClient (the client's own record only)
+//   GET /v1/session/flags     -> no SDK method yet, so nothing to list; add it
+//                                here when the SDK gains one.
+// retrieveClient is allowlisted by name: whether the id is the viewer's own is a
+// runtime fact a static scan cannot see.
+export const CLIENT_SAFE_SDK_METHODS = Object.freeze(['retrieveClient', 'retrieveMe']);

package/bin/foundation-exports.mjs

@@ -0,0 +1,59 @@
+// Every name `@assembly-js/app-foundation/server` and `/client` export that is NOT a way to
+// obtain an Assembly client or request context for the person using the app. The scan
+// follows viewer clients only from the sources it knows (SDK_FACTORIES, afterAssembly,
+// getRequestContext in scan-client-calls.mjs); an import from those entry points that is in
+// neither place is something it cannot classify, so it records a defeater instead of
+// assuming the name is harmless.
+//
+// scan-client-calls.test.mjs checks this list against the package's real exports: a new
+// export fails there until it is classified, and one whose signature returns or hands out
+// an AssemblyAPI or ActionContext cannot be listed here. Classify it as a source in the
+// scanner, not in this list.
+//
+// automationActionRoute hands its handler an ActionContext, but that context is the platform's
+// automation caller (an app), never a viewer. makeTestActionContext builds a fake context for
+// tests that no request can reach. getClientAccessScope, getInternalUserAccess,
+// requireCompanyScope, getInstalledAppIds and isAppInstalled take a client as an argument;
+// none of them returns one.
+export const NON_CLIENT_EXPORTS = new Set([
+  'APP_CSRF_HEADER', 'AUTH_UNAVAILABLE_CODE', 'ActionContext', 'ActionError',
+  'ActionErrorStatus', 'AirtableFieldSchema', 'AirtableFormattedField',
+  'AirtableFormattedRecord', 'AirtableRecord', 'AirtableSchemaResult', 'AirtableTableSchema',
+  'AssemblyProxyForwardContext', 'AssemblyProxyOptions', 'AuthUnavailableError',
+  'BEARER_COOKIE_NAME', 'BEARER_HEADER_NAME', 'BEARER_IN_BODY_HEADER', 'BEARER_TTL_MS',
+  'CLIENT_BEARER_HEADER', 'CLIENT_FLAGS_COOKIE_NAME', 'COOKIE_OUTCOME_EVENT',
+  'COOKIE_PROBE_NAME', 'Caller', 'ClearClientNotificationsInput', 'ClientAccessScope',
+  'ConnectionStatus', 'ConnectorError', 'ConnectorErrorCode', 'CookieOutcome', 'CronHandler',
+  'DEFAULT_LABELS', 'EXCHANGE_REJECTION_HEADER', 'ExchangeRejectedViewer', 'ExchangedSession',
+  'FormatAirtableRecordsOpts', 'GmailSendArgs', 'GmailSendResult', 'IntegrationClient',
+  'InternalUserAccess', 'LEGACY_APP_IDS', 'MintFailure', 'MintOutcome', 'MintSessionOptions', 'MintedAppBearer',
+  'MintedBearer', 'NETWORK_CAPTURE_MESSAGE_TYPE', 'NetworkCaptureHeaderFingerprint',
+  'NetworkCaptureRecord', 'PAINTED_BEACON_EVENT', 'PAINTED_BEACON_PATH',
+  'PORTAL_ORIGIN_COOKIE_NAME', 'PREVIEW_V2_FLAG', 'PdfText', 'PrincipalAllow', 'PrincipalKind',
+  'Provider', 'ProxyOpts', 'RENEW_OUTCOME_EVENT', 'RenewOutcome', 'ReplaceChildRowsResult',
+  'RequestSource', 'ResolveResourceOpts', 'ResourceError', 'ResourceFieldMap',
+  'ResourceOption', 'ResourcePage', 'ScheduleCadence', 'SlackChannel',
+  'SlackPostMessageResult', 'TOKEN_EXPIRED_HEADER', 'TokenInvalidError', 'TokenPayload',
+  'TtlCache', 'VERIFY_OUTCOME_EVENT', 'VERIFY_PATH', 'VIEWER_BEARER_HEADER',
+  'VerifiedIdentity', 'VerifyResult', 'Viewer', 'WorkspaceLabels', 'authUnavailableResponse',
+  'automationActionRoute', 'badRequest', 'bootstrapPortalOrigin', 'buildMimeMessage',
+  'canAccessClient', 'canAccessCompanies', 'classifyExchangeFailure',
+  'clearClientNotifications', 'collectHeaders', 'collectXhrResponseHeaders',
+  'cookielessReexchangeHeaders', 'cookiesAreBlocked', 'createAssemblyProxy', 'cronRoute',
+  'decodeBearer', 'expandClientsByCompany', 'extractPdfText', 'fetchSessionFlags',
+  'findResource', 'formatAirtableRecords', 'getAirtableTableSchema', 'getCapturedRecords',
+  'getClientAccessScope', 'getCookielessBearer', 'getDownloadUrl', 'getInstalledAppIds', 'getIntegration',
+  'getInternalUserAccess', 'getLabels', 'getSessionIdentity', 'getUploadUrl',
+  'getVerifiedIdentity', 'gmailSendEmail', 'handlePaintedBeacon', 'handleRouteError',
+  'hasClientFlag', 'hasFlag', 'installFetchCapture', 'installNetworkCapture',
+  'installPaintBeacon', 'installXhrCapture', 'internalError', 'isAppInstalled', 'isConnected', 'isCronRequest',
+  'isDocumentRequest', 'isPaintedBeaconPath', 'isSessionExchangeEnabled', 'isUuid',
+  'isValidHexColor', 'listAll', 'logCookieOutcome', 'logFailures', 'logPaintedBeacon',
+  'logRenewOutcome', 'makeTestActionContext', 'mintBearerFromAppKey',
+  'mintBearerFromSessionToken', 'nextRunAfter', 'normalizeResourcePage', 'notFound',
+  'parseExchangeRejection', 'parseUuid', 'principalKind', 'readCookie', 'recordNetworkCapture',
+  'redactUrl', 'replaceChildRows', 'requireAuth', 'requireCompanyScope', 'resolveFont',
+  'resolveResource', 'sendThrottled', 'serializeBearerCookie', 'serializeCookieProbe',
+  'setCookielessBearer', 'slackErrorCode', 'slackFindChannelId', 'slackListChannels',
+  'slackPostMessage', 'slackResolveMentions', 'snippetFromRequestBody', 'verifyBearer',
+]);

package/bin/scan-client-calls.mjs

@@ -0,0 +1,934 @@
+// Finds platform SDK calls an app makes with a viewer's bearer from code a
+// client session can reach, so apps that break once client bearers are denied by
+// default can be found before the switch.
+//
+// A static scan can prove an app breaks but never that it is fine, so each app
+// lands in one of three classes:
+//   BREAKS     a non-allowlisted SDK method is called on a viewer-bound client
+//              from a client-reachable entry.
+//   CLEAN      no such call, and nothing the scan could not see through.
+//   UNRESOLVED everything else: a construct defeats the analysis (a receiver
+//              escaping into a call, spread or dynamic property access, an
+//              any-typed receiver, a dynamic import), or an import could not be
+//              followed.
+//
+// The work is split so a second projection (cross-app calls) can reuse it:
+// `createAnalysis` yields per-file facts (every SDK call with its provenance,
+// plus the constructs that defeat analysis) and the import graph;
+// `projectClientReachable` is one projection over those facts.
+//
+// Parse-only like scan-routes: ts.createSourceFile, no Program, no type check,
+// so an app that does not typecheck still scans. Files are parsed lazily, only
+// when an entry reaches them.
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { CLIENT_SAFE_SDK_METHODS } from './client-safe-sdk-methods.mjs';
+import { NON_CLIENT_EXPORTS } from './foundation-exports.mjs';
+import {
+  EXCLUDING_WRAPPERS,
+  PROXY_METHODS,
+  ROUTE_FILE_PREDICATE,
+  analyseExports,
+  byteCompare,
+  isReservedTemplate,
+  listFiles,
+  loadTypeScript,
+  readPrivateRoutes,
+  templatesForDirs,
+  templatesForFile,
+  wrapperName,
+} from './scan-routes.mjs';
+
+export const SCANNER_VERSION = 1;
+
+export const CLASS_BREAKS = 'BREAKS';
+export const CLASS_CLEAN = 'CLEAN';
+export const CLASS_UNRESOLVED = 'UNRESOLVED';
+
+export const PROVENANCE_VIEWER = 'viewer';
+// Installer and offline clients act with the app's own authority, so a call on
+// them never breaks when client bearers lose admin reach.
+export const PROVENANCE_INSTALLER = 'installer';
+export const PROVENANCE_OFFLINE = 'offline';
+
+// getInstallerAssembly and ctx.installer come from the installer-client work and
+// may not be on every foundation version yet; the names are known either way.
+export const SDK_FACTORIES = Object.freeze({
+  getAssembly: PROVENANCE_VIEWER,
+  getAssemblyForRequest: PROVENANCE_VIEWER,
+  getInstallerAssembly: PROVENANCE_INSTALLER,
+  getOfflineAssembly: PROVENANCE_OFFLINE,
+});
+export const CTX_MEMBERS = Object.freeze({
+  assembly: PROVENANCE_VIEWER,
+  installer: PROVENANCE_INSTALLER,
+});
+// afterAssembly captures getAssembly({ token }) and hands that viewer client to
+// its callback; the factory list above does not mention it.
+const AFTER_ASSEMBLY = 'afterAssembly';
+// getRequestContext() returns the same request context a page receives as `ctx`, so
+// its `assembly` and `installer` members carry the same provenance under any local name.
+const REQUEST_CONTEXT = 'getRequestContext';
+
+const SOURCE_FILE = /\.(?:ts|tsx|js|jsx|mjs|cjs|mts|cts)$/;
+const DECLARATION_FILE = /\.d\.[cm]?ts$/;
+const RESOLVE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mts', '.cts'];
+// Pages and the files Next loads around them: all served to whoever opens the page.
+const PAGE_FILE = /^(?:src\/)?app\/((?:.+\/)?)(?:page|layout|template|default|loading|error|not-found|global-error)\.(?:ts|tsx|js|jsx)$/;
+const LAYOUT_FILE = /(?:^|\/)layout\.(?:ts|tsx|js|jsx)$/;
+const APP_ROOT_PREFIXES = ['app/', 'src/app/'];
+// Module specifiers the scan treats as the app's own code or the platform's.
+const LOCAL_SPECIFIER = /^(?:\.{1,2}(?:\/|$)|@\/|~\/)/;
+const SDK_SPECIFIER = /^@assembly-js\//;
+// The entry points that export the client sources. A name imported from them that is neither
+// a known source nor listed as harmless is one the scan cannot classify.
+const FOUNDATION_ENTRY = /^@assembly-js\/app-foundation\/(?:server|client)$/;
+const ALIAS_ROOTS = ['', 'src/'];
+const PROMISE_CHAIN_METHODS = new Set(['then', 'catch', 'finally']);
+// The SDK is flat and its method names follow the codegen verbs (`listClients`, `retrieveMe`,
+// `getV1Comments`), so a call with one of these shapes is an SDK call whatever the receiver is
+// called. Recognising the method instead of the source is what keeps a client the name-based
+// tagging never saw from reading CLEAN.
+const SDK_METHOD_SHAPE = /^(?:(?:list|retrieve|create|update|delete|send|cancel|add|mark|request|download)[A-Z]|(?:get|put|post)V1)/;
+// `fetch` is the one flat client method the verb pattern cannot match; it is how apps reach
+// non-SDK endpoints such as the AI proxy.
+const SDK_METHOD_EXTRAS = new Set(['fetch']);
+// Browser and Node methods that fit the verb pattern on any receiver (a media query list, a
+// ref, a form), so a call on one says nothing about the SDK.
+const NON_SDK_METHODS = new Set([
+  'addEventListener', 'removeEventListener', 'requestSubmit', 'requestPermission',
+  'requestFullscreen', 'requestAnimationFrame', 'cancelAnimationFrame', 'createReadStream',
+  'createWriteStream',
+]);
+// Platform objects whose verb-shaped methods (`URL.createObjectURL`, `document.createElement`)
+// are not SDK calls.
+const NON_SDK_RECEIVERS = new Set([
+  'URL', 'document', 'window', 'React', 'Object', 'Array', 'JSON', 'Promise', 'Math', 'Intl',
+  'console', 'crypto', 'navigator', 'globalThis', 'self', 'Reflect', 'Symbol', 'Number', 'String', 'Date',
+]);
+
+export const DEFEATER = Object.freeze({
+  ESCAPES: 'receiver escapes into a call or value the scan cannot follow',
+  SPREAD: 'receiver is spread',
+  DYNAMIC_ACCESS: 'receiver member accessed dynamically',
+  METHOD_REFERENCE: 'receiver method used as a value instead of called',
+  DESTRUCTURED: 'receiver is destructured',
+  ANY_TYPED: 'receiver is typed any',
+  REASSIGNED: 'receiver variable is reassigned',
+  PROMISE_CHAIN: 'receiver reached through a promise chain',
+  FACTORY_VALUE: 'SDK factory used as a value instead of called',
+  FACTORY_ALIAS: 'SDK factory re-exported under another name',
+  DYNAMIC_IMPORT: 'dynamic import the scan cannot resolve',
+  UNRESOLVED_IMPORT: 'local import could not be resolved to a file',
+  UNKNOWN_SOURCE: 'SDK export the scan does not classify',
+  UNTRACKED_SDK_METHOD: 'SDK-shaped method called on a receiver the scan could not trace to a client',
+});
+
+// ---------------------------------------------------------------------------
+// Per-file facts
+// ---------------------------------------------------------------------------
+
+// The names a viewer client can come from: the viewer factories, afterAssembly's callback and
+// the request context getter.
+const isViewerSource = (name) =>
+  SDK_FACTORIES[name] === PROVENANCE_VIEWER || name === AFTER_ASSEMBLY || name === REQUEST_CONTEXT;
+
+const lineOf = (sf, node) => sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+
+class Scope {
+  constructor(parent) {
+    this.parent = parent;
+    this.bindings = new Map(); // name -> { provenance | null }
+  }
+  lookup(name) {
+    for (let s = this; s; s = s.parent) if (s.bindings.has(name)) return s.bindings.get(name);
+    return undefined;
+  }
+}
+
+function scriptKind(ts, file) {
+  if (/\.(?:tsx|jsx)$/.test(file)) return ts.ScriptKind.TSX;
+  return /\.[cm]?js$/.test(file) ? ts.ScriptKind.JS : ts.ScriptKind.TS;
+}
+
+// What one file does with SDK clients, independent of any entry or allowlist:
+// `calls` are every method call on a tagged receiver, `defeaters` are the
+// constructs that stop the scan following a viewer receiver, `specifiers` the
+// module specifiers it imports.
+export function collectFileFacts(ts, file, text) {
+  const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, scriptKind(ts, file));
+  const calls = [];
+  const defeaters = [];
+  const specifiers = [];
+  const factoryLocals = new Map(); // local name -> provenance
+  const namespaceLocals = new Set();
+  const afterAssemblyLocals = new Set();
+  const requestContextLocals = new Set();
+  const callbackViewerParams = new WeakSet();
+  const declared = new WeakSet();
+
+  const defeat = (node, reason) => defeaters.push({ line: lineOf(sf, node), reason });
+
+  const isLiteralText = (n) => n && (ts.isStringLiteral(n) || ts.isNoSubstitutionTemplateLiteral(n));
+
+  // --- imports ------------------------------------------------------------
+  const acceptsFactories = (spec) => LOCAL_SPECIFIER.test(spec) || SDK_SPECIFIER.test(spec);
+  for (const stmt of sf.statements) {
+    if (ts.isImportDeclaration(stmt) && ts.isStringLiteral(stmt.moduleSpecifier)) {
+      const spec = stmt.moduleSpecifier.text;
+      specifiers.push(spec);
+      const bindings = stmt.importClause?.namedBindings;
+      if (FOUNDATION_ENTRY.test(spec) && stmt.importClause && !stmt.importClause.isTypeOnly) {
+        // Fail closed: a source the scan does not know about would otherwise read CLEAN.
+        if (stmt.importClause.name) defeat(stmt.importClause, DEFEATER.UNKNOWN_SOURCE);
+        if (bindings && ts.isNamedImports(bindings)) {
+          for (const el of bindings.elements) {
+            const imported = (el.propertyName ?? el.name).text;
+            if (el.isTypeOnly || SDK_FACTORIES[imported] || imported === AFTER_ASSEMBLY || imported === REQUEST_CONTEXT
+              || NON_CLIENT_EXPORTS.has(imported)) continue;
+            defeat(el, DEFEATER.UNKNOWN_SOURCE);
+          }
+        }
+      }
+      if (!bindings || !acceptsFactories(spec)) continue;
+      if (ts.isNamespaceImport(bindings)) namespaceLocals.add(bindings.name.text);
+      else {
+        for (const el of bindings.elements) {
+          const imported = (el.propertyName ?? el.name).text;
+          if (SDK_FACTORIES[imported]) factoryLocals.set(el.name.text, SDK_FACTORIES[imported]);
+          if (imported === AFTER_ASSEMBLY) afterAssemblyLocals.add(el.name.text);
+          if (imported === REQUEST_CONTEXT) requestContextLocals.add(el.name.text);
+        }
+      }
+    } else if (ts.isExportDeclaration(stmt) && stmt.moduleSpecifier && ts.isStringLiteral(stmt.moduleSpecifier)) {
+      specifiers.push(stmt.moduleSpecifier.text);
+      if (stmt.exportClause && ts.isNamedExports(stmt.exportClause)) {
+        for (const el of stmt.exportClause.elements) {
+          // Consumers import the alias, which the name-based tagging cannot recognise.
+          if (el.propertyName && isViewerSource(el.propertyName.text)) defeat(el, DEFEATER.FACTORY_ALIAS);
+        }
+      }
+    }
+  }
+
+  // --- provenance of an expression ----------------------------------------
+  const unwrap = (node) => {
+    let n = node;
+    let anyCast = false;
+    while (
+      ts.isParenthesizedExpression(n) || ts.isAwaitExpression(n) || ts.isNonNullExpression(n) ||
+      ts.isAsExpression(n) || ts.isTypeAssertionExpression(n) || ts.isSatisfiesExpression?.(n)
+    ) {
+      const t = n.type;
+      if (t && t.kind === ts.SyntaxKind.AnyKeyword) anyCast = true;
+      n = n.expression;
+    }
+    return { node: n, anyCast };
+  };
+
+  const namespaceMember = (expr) => {
+    if (ts.isPropertyAccessExpression(expr)) {
+      return ts.isIdentifier(expr.expression) && namespaceLocals.has(expr.expression.text)
+        ? expr.name.text : null;
+    }
+    if (ts.isElementAccessExpression(expr) && isLiteralText(expr.argumentExpression)) {
+      return ts.isIdentifier(expr.expression) && namespaceLocals.has(expr.expression.text)
+        ? expr.argumentExpression.text : null;
+    }
+    return null;
+  };
+
+  const factoryProvenance = (call, scope) => {
+    const callee = call.expression;
+    if (ts.isIdentifier(callee)) {
+      return !scope.lookup(callee.text) ? factoryLocals.get(callee.text) ?? null : null;
+    }
+    const member = namespaceMember(callee);
+    return member ? SDK_FACTORIES[member] ?? null : null;
+  };
+
+  const isAfterAssemblyCallee = (callee, scope) => {
+    if (ts.isIdentifier(callee)) return !scope.lookup(callee.text) && afterAssemblyLocals.has(callee.text);
+    return namespaceMember(callee) === AFTER_ASSEMBLY;
+  };
+
+  const isDynamicNamespaceAccess = (expr) =>
+    ts.isElementAccessExpression(expr) && ts.isIdentifier(expr.expression)
+      && namespaceLocals.has(expr.expression.text) && !isLiteralText(expr.argumentExpression);
+
+  const markUnusedNamespaceFactory = (node) => {
+    const parent = node.parent;
+    if (parent && ts.isCallExpression(parent) && parent.expression === node) return;
+    const name = namespaceMember(node);
+    if (name == null) {
+      if (isDynamicNamespaceAccess(node)) defeat(node, DEFEATER.DYNAMIC_ACCESS);
+      return;
+    }
+    if (isViewerSource(name)) defeat(node, DEFEATER.FACTORY_VALUE);
+  };
+
+  const isRequestContextCall = (node, scope) => {
+    if (!ts.isCallExpression(node)) return false;
+    const callee = node.expression;
+    if (ts.isIdentifier(callee)) return !scope.lookup(callee.text) && requestContextLocals.has(callee.text);
+    return namespaceMember(callee) === REQUEST_CONTEXT;
+  };
+
+  // The literal name `ctx`, a variable bound to getRequestContext(), or the call itself.
+  const isContextReceiver = (expr, scope) => {
+    if (ts.isIdentifier(expr)) return expr.text === 'ctx' || scope.lookup(expr.text)?.isCtx === true;
+    return isRequestContextCall(unwrap(expr).node, scope);
+  };
+
+  const ctxProvenance = (node, scope) =>
+    ts.isPropertyAccessExpression(node) && isContextReceiver(node.expression, scope)
+      ? CTX_MEMBERS[node.name.text] ?? null
+      : null;
+
+  // The provenance an expression carries when it is itself a receiver source or
+  // a reference to a tracked variable.
+  const provenanceOf = (node, scope) => {
+    if (ts.isCallExpression(node)) return factoryProvenance(node, scope);
+    if (ts.isIdentifier(node)) return scope.lookup(node.text)?.provenance ?? null;
+    return ctxProvenance(node, scope);
+  };
+
+  // --- usage of a tagged receiver -----------------------------------------
+  // Climbs out of wrappers that do not change what the value is, then reads how
+  // the value is used. Only viewer provenance records defeaters.
+  const classifyUse = (node, provenance, scope) => {
+    const viewer = provenance === PROVENANCE_VIEWER;
+    let cur = node;
+    let anyCast = false;
+    let awaited = false;
+    for (;;) {
+      const p = cur.parent;
+      if (p && (ts.isParenthesizedExpression(p) || ts.isNonNullExpression(p) || ts.isAwaitExpression(p) ||
+        ts.isAsExpression(p) || ts.isTypeAssertionExpression(p) || ts.isSatisfiesExpression?.(p))) {
+        if (ts.isAwaitExpression(p)) awaited = true;
+        if (p.type && p.type.kind === ts.SyntaxKind.AnyKeyword) anyCast = true;
+        cur = p;
+      } else break;
+    }
+    if (anyCast && viewer) defeat(node, DEFEATER.ANY_TYPED);
+    const parent = cur.parent;
+    if (!parent) return;
+
+    const recordCall = (method, at) => calls.push({ line: lineOf(sf, at), method, provenance });
+
+    if (ts.isPropertyAccessExpression(parent) && parent.expression === cur) {
+      const call = parent.parent;
+      const called = call && ts.isCallExpression(call) && call.expression === parent;
+      if (!called) {
+        if (viewer) defeat(parent, DEFEATER.METHOD_REFERENCE);
+        return;
+      }
+      const name = parent.name.text;
+      // `getAssembly().then(...)` is the client arriving later, not a method of it.
+      if (ts.isCallExpression(node) && !awaited && PROMISE_CHAIN_METHODS.has(name)) {
+        if (viewer) defeat(parent, DEFEATER.PROMISE_CHAIN);
+        return;
+      }
+      recordCall(name, parent.name);
+      return;
+    }
+    if (ts.isElementAccessExpression(parent) && parent.expression === cur) {
+      const arg = parent.argumentExpression;
+      const call = parent.parent;
+      if (isLiteralText(arg) && call && ts.isCallExpression(call) && call.expression === parent) {
+        recordCall(arg.text, arg);
+      } else if (viewer) defeat(parent, DEFEATER.DYNAMIC_ACCESS);
+      return;
+    }
+    if (ts.isVariableDeclaration(parent) && parent.initializer === cur) {
+      if (ts.isIdentifier(parent.name)) {
+        if (viewer && parent.type?.kind === ts.SyntaxKind.AnyKeyword) defeat(parent, DEFEATER.ANY_TYPED);
+        // The alias is bound by declareDecl; its own uses are classified there.
+        return;
+      }
+      if (viewer) defeat(parent, DEFEATER.DESTRUCTURED);
+      return;
+    }
+    if (!viewer) return;
+    if (ts.isSpreadElement(parent) || ts.isSpreadAssignment(parent)) return defeat(parent, DEFEATER.SPREAD);
+    if (ts.isExpressionStatement(parent)) return; // `await getAssembly();` for its side effect
+    if (ts.isPrefixUnaryExpression(parent) && parent.operator === ts.SyntaxKind.ExclamationToken) return;
+    if (ts.isIfStatement(parent) && parent.expression === cur) return;
+    if (ts.isBinaryExpression(parent)) {
+      const op = parent.operatorToken.kind;
+      if (op === ts.SyntaxKind.InstanceOfKeyword && parent.left === cur) return;
+      if (op === ts.SyntaxKind.EqualsEqualsToken || op === ts.SyntaxKind.EqualsEqualsEqualsToken
+        || op === ts.SyntaxKind.ExclamationEqualsToken || op === ts.SyntaxKind.ExclamationEqualsEqualsToken) return;
+      if (op === ts.SyntaxKind.EqualsToken && parent.right === cur) return defeat(parent, DEFEATER.REASSIGNED);
+    }
+    // getAssemblyForRequest returns a Response on failure; the documented
+    // `if (a instanceof NextResponse) return a;` hands that Response back, not
+    // the client, so it is not an escape.
+    if (ts.isReturnStatement(parent) && ts.isIdentifier(node) && returnsNarrowedResponse(parent, node.text)) return;
+    defeat(cur, DEFEATER.ESCAPES);
+  };
+
+  const returnsNarrowedResponse = (ret, name) => {
+    for (let n = ret.parent; n; n = n.parent) {
+      if (ts.isIfStatement(n)) {
+        const c = n.expression;
+        return ts.isBinaryExpression(c) && c.operatorToken.kind === ts.SyntaxKind.InstanceOfKeyword
+          && ts.isIdentifier(c.left) && c.left.text === name;
+      }
+      if (ts.isFunctionLike(n)) return false;
+    }
+    return false;
+  };
+
+  // The context call itself: bound to a variable (declareDecl follows it), read through
+  // a member, or dropped. Any other use hands the context somewhere the scan cannot see.
+  const checkContextCall = (node) => {
+    let cur = node;
+    let awaited = false;
+    for (;;) {
+      const p = cur.parent;
+      if (p && (ts.isParenthesizedExpression(p) || ts.isNonNullExpression(p) || ts.isAwaitExpression(p) ||
+        ts.isAsExpression(p) || ts.isTypeAssertionExpression(p) || ts.isSatisfiesExpression?.(p))) {
+        if (ts.isAwaitExpression(p)) awaited = true;
+        cur = p;
+      } else break;
+    }
+    const parent = cur.parent;
+    if (!parent) return;
+    if (ts.isVariableDeclaration(parent) && parent.initializer === cur) return;
+    if (ts.isPropertyAccessExpression(parent) && parent.expression === cur) {
+      // `getRequestContext().then(...)` is the context arriving later, not a member of it.
+      if (!awaited) defeat(parent, DEFEATER.PROMISE_CHAIN);
+      return;
+    }
+    if (ts.isExpressionStatement(parent)) return;
+    defeat(cur, DEFEATER.ESCAPES);
+  };
+
+  // --- bindings ------------------------------------------------------------
+  const declareNames = (name, scope, provenance) => {
+    if (ts.isIdentifier(name)) scope.bindings.set(name.text, { provenance });
+    else for (const el of name.elements) if (!ts.isOmittedExpression(el)) declareNames(el.name, scope, null);
+  };
+
+  const declareDecl = (decl, scope) => {
+    if (declared.has(decl)) return;
+    declared.add(decl);
+    let provenance = null;
+    if (decl.initializer && ts.isIdentifier(decl.name)) {
+      const init = unwrap(decl.initializer).node;
+      if (isRequestContextCall(init, scope)) {
+        scope.bindings.set(decl.name.text, { provenance: null, isCtx: true });
+        return;
+      }
+      provenance = provenanceOf(init, scope);
+    } else if (decl.initializer) {
+      // `const { assembly } = ctx` destructures a member out of the request context.
+      const init = unwrap(decl.initializer).node;
+      if (ts.isObjectBindingPattern(decl.name) && isContextReceiver(init, scope)) {
+        for (const el of decl.name.elements) {
+          // A rest or nested pattern takes members the scan cannot follow.
+          if (el.dotDotDotToken) defeat(el, DEFEATER.SPREAD);
+          else if (!ts.isIdentifier(el.name) || (el.propertyName && !ts.isIdentifier(el.propertyName))) {
+            defeat(el, DEFEATER.DESTRUCTURED);
+          }
+          const member = ts.isIdentifier(el.name) ? (el.propertyName ?? el.name).text : null;
+          if (member && CTX_MEMBERS[member] && ts.isIdentifier(el.name)) {
+            scope.bindings.set(el.name.text, { provenance: CTX_MEMBERS[member] });
+          } else if (ts.isIdentifier(el.name)) scope.bindings.set(el.name.text, { provenance: null });
+        }
+        return;
+      }
+    }
+    if (provenance === PROVENANCE_VIEWER && ts.isVariableStatement(decl.parent?.parent)
+      && hasExportModifier(decl.parent.parent)) {
+      defeat(decl, DEFEATER.ESCAPES);
+    }
+    declareNames(decl.name, scope, provenance);
+  };
+
+  const hasExportModifier = (stmt) => !!stmt.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+
+  // Hoisted: a function declared above `const assembly = await getAssembly()`
+  // still sees the binding when it runs.
+  const declareBlock = (statements, scope) => {
+    for (const stmt of statements) {
+      if (ts.isVariableStatement(stmt)) for (const d of stmt.declarationList.declarations) declareDecl(d, scope);
+    }
+  };
+
+  const isReferenceIdentifier = (node) => {
+    const p = node.parent;
+    if (!p) return false;
+    if (ts.isPropertyAccessExpression(p) && p.name === node) return false;
+    if ((ts.isPropertyAssignment(p) || ts.isPropertyDeclaration(p) || ts.isMethodDeclaration(p) ||
+      ts.isBindingElement(p) || ts.isParameter(p) || ts.isVariableDeclaration(p) ||
+      ts.isFunctionDeclaration(p) || ts.isClassDeclaration(p) || ts.isPropertySignature(p) ||
+      ts.isImportSpecifier(p) || ts.isImportClause(p) || ts.isNamespaceImport(p) ||
+      ts.isExportSpecifier(p) || ts.isLabeledStatement(p)) && p.name === node) return false;
+    if (ts.isBindingElement(p) && p.propertyName === node) return false;
+    if (ts.isTypeNode(p) || ts.isQualifiedName(p) || ts.isTypeQueryNode?.(p)) return false;
+    return true;
+  };
+
+  // Backstop for every way of obtaining a client the tagging above does not follow (a helper
+  // returning it, a destructured callback parameter, a binding exported from another file):
+  // an SDK-shaped method on a receiver with no recorded provenance is not provably safe.
+  const rootIdentifier = (expr) => {
+    let e = unwrap(expr).node;
+    while (ts.isPropertyAccessExpression(e) || ts.isElementAccessExpression(e)) e = unwrap(e.expression).node;
+    return ts.isIdentifier(e) ? e.text : null;
+  };
+
+  const checkUntrackedSdkCall = (node, scope) => {
+    const callee = node.expression;
+    let name = null;
+    if (ts.isPropertyAccessExpression(callee)) name = callee.name.text;
+    else if (ts.isElementAccessExpression(callee) && isLiteralText(callee.argumentExpression)) name = callee.argumentExpression.text;
+    if (name == null || NON_SDK_METHODS.has(name)) return;
+    if (!SDK_METHOD_SHAPE.test(name) && !SDK_METHOD_EXTRAS.has(name)) return;
+    const receiver = unwrap(callee.expression).node;
+    if (provenanceOf(receiver, scope)) return;
+    const root = rootIdentifier(receiver);
+    if (root && !scope.lookup(root) && NON_SDK_RECEIVERS.has(root)) return;
+    defeat(callee, DEFEATER.UNTRACKED_SDK_METHOD);
+  };
+
+  // --- walk ----------------------------------------------------------------
+  const visit = (node, scope) => {
+    let inner = scope;
+    if (ts.isSourceFile(node) || ts.isBlock(node) || ts.isModuleBlock(node) || ts.isCaseBlock(node)) {
+      inner = ts.isSourceFile(node) ? scope : new Scope(scope);
+      declareBlock(ts.isCaseBlock(node) ? node.clauses.flatMap((c) => [...c.statements]) : node.statements, inner);
+    } else if (ts.isFunctionLike(node) || ts.isForStatement(node) || ts.isForInStatement(node) ||
+      ts.isForOfStatement(node) || ts.isCatchClause(node)) {
+      inner = new Scope(scope);
+      if (ts.isFunctionLike(node)) {
+        for (const prm of node.parameters) declareNames(prm.name, inner, null);
+        // afterAssembly's callback receives the viewer client as its first argument.
+        if (callbackViewerParams.has(node) && node.parameters[0]) {
+          const first = node.parameters[0];
+          if (ts.isIdentifier(first.name)) inner.bindings.set(first.name.text, { provenance: PROVENANCE_VIEWER });
+          // A pattern takes the client apart into names the scan then cannot follow.
+          else defeat(first, DEFEATER.DESTRUCTURED);
+        }
+      }
+    }
+
+    if (ts.isVariableDeclaration(node)) declareDecl(node, inner);
+
+    // `export { sdk }` hands a tracked viewer client to importers without a reference the scan reads.
+    if (ts.isExportSpecifier(node) && !node.parent.parent.moduleSpecifier
+      && inner.lookup((node.propertyName ?? node.name).text)?.provenance === PROVENANCE_VIEWER) {
+      defeat(node, DEFEATER.ESCAPES);
+    }
+
+    if (ts.isCatchClause(node) && node.variableDeclaration) declareNames(node.variableDeclaration.name, inner, null);
+
+    if (ts.isCallExpression(node)) {
+      checkUntrackedSdkCall(node, inner);
+      const callee = node.expression;
+      if (callee.kind === ts.SyntaxKind.ImportKeyword) {
+        const arg = node.arguments[0];
+        if (isLiteralText(arg)) specifiers.push(arg.text);
+        // Bindings from the module namespace are not followed, so a re-exported
+        // getAssembly would otherwise vanish. Follow the file; mark unresolved.
+        if (!isLiteralText(arg) || SDK_SPECIFIER.test(arg.text) || LOCAL_SPECIFIER.test(arg.text)) {
+          defeat(node, DEFEATER.DYNAMIC_IMPORT);
+        }
+      } else if (ts.isIdentifier(callee) && callee.text === 'require' && !inner.lookup('require')) {
+        const arg = node.arguments[0];
+        if (isLiteralText(arg)) specifiers.push(arg.text);
+        if (!isLiteralText(arg) || SDK_SPECIFIER.test(arg.text) || LOCAL_SPECIFIER.test(arg.text)) {
+          defeat(node, DEFEATER.DYNAMIC_IMPORT);
+        }
+      } else if (isAfterAssemblyCallee(callee, inner)) {
+        const cb = node.arguments[0];
+        if (cb && (ts.isArrowFunction(cb) || ts.isFunctionExpression(cb))) callbackViewerParams.add(cb);
+        else defeat(node, DEFEATER.ESCAPES);
+      } else if (isRequestContextCall(node, inner)) {
+        checkContextCall(node);
+      } else {
+        const provenance = factoryProvenance(node, inner);
+        if (provenance) classifyUse(node, provenance, inner);
+        else if (isDynamicNamespaceAccess(callee)) defeat(node, DEFEATER.DYNAMIC_ACCESS);
+      }
+    } else if (ts.isPropertyAccessExpression(node)) {
+      const provenance = ctxProvenance(node, inner);
+      if (provenance) classifyUse(node, provenance, inner);
+      else markUnusedNamespaceFactory(node);
+    } else if (ts.isElementAccessExpression(node)) {
+      markUnusedNamespaceFactory(node);
+    } else if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken
+      && ts.isIdentifier(node.left)) {
+      // Reassigning a tracked variable to anything else would hide the receiver.
+      if (inner.lookup(node.left.text)?.provenance === PROVENANCE_VIEWER) defeat(node, DEFEATER.REASSIGNED);
+    } else if (ts.isIdentifier(node) && isReferenceIdentifier(node)) {
+      const binding = inner.lookup(node.text);
+      if (binding?.provenance) classifyUse(node, binding.provenance, inner);
+      else if (binding?.isCtx) {
+        // Only `.member` reads are followed; handing the context on hides its client.
+        const p = node.parent;
+        if (!(ts.isPropertyAccessExpression(p) && p.expression === node)) defeat(node, DEFEATER.ESCAPES);
+      }
+      else if (!binding && (factoryLocals.get(node.text) === PROVENANCE_VIEWER || afterAssemblyLocals.has(node.text)
+        || requestContextLocals.has(node.text))) {
+        const p = node.parent;
+        if (!(ts.isCallExpression(p) && p.expression === node)) defeat(node, DEFEATER.FACTORY_VALUE);
+      } else if (!binding && namespaceLocals.has(node.text)) {
+        const p = node.parent;
+        // Member access is classified on the property/element node; any other
+        // use (destructure, alias, pass) drops the factories where we cannot
+        // follow them, so CLEAN would hide a viewer call.
+        if (!((ts.isPropertyAccessExpression(p) || ts.isElementAccessExpression(p)) && p.expression === node)) {
+          defeat(node, DEFEATER.FACTORY_VALUE);
+        }
+      }
+    }
+
+    ts.forEachChild(node, (child) => visit(child, inner));
+  };
+
+  visit(sf, new Scope(null));
+  return { calls, defeaters, specifiers };
+}
+
+// ---------------------------------------------------------------------------
+// Entries
+// ---------------------------------------------------------------------------
+
+// An entry that stops at a top-level check turning away anyone without an internalUserId
+// (`if (!x.internalUserId) return/throw/notFound()/redirect()`) is reported in `gatedEntries`.
+// It is an annotation for whoever triages a finding, never a reason to drop one: the check
+// is recognised by name, so a guard on an unrelated object, or a sibling server action in the
+// same file, would otherwise turn a client-reachable call into a false CLEAN.
+const GATE_EXITS = new Set(['notFound', 'redirect', 'permanentRedirect', 'forbidden', 'unauthorized']);
+const HTTP_HANDLERS = new Set(PROXY_METHODS);
+
+function hasMod(node, kind) {
+  return !!node.modifiers?.some((m) => m.kind === kind);
+}
+
+function entryFunctions(ts, sf) {
+  const out = [];
+  const byName = new Map();
+  for (const stmt of sf.statements) {
+    if (ts.isFunctionDeclaration(stmt) && stmt.name) byName.set(stmt.name.text, stmt);
+    if (ts.isVariableStatement(stmt)) {
+      for (const d of stmt.declarationList.declarations) {
+        if (ts.isIdentifier(d.name) && d.initializer && ts.isFunctionLike(d.initializer)) {
+          byName.set(d.name.text, d.initializer);
+        }
+      }
+    }
+  }
+  for (const stmt of sf.statements) {
+    if (ts.isFunctionDeclaration(stmt) && hasMod(stmt, ts.SyntaxKind.DefaultKeyword)) {
+      out.push(stmt);
+      continue;
+    }
+    if (ts.isExportAssignment(stmt) && !stmt.isExportEquals) {
+      if (ts.isFunctionLike(stmt.expression)) out.push(stmt.expression);
+      else if (ts.isIdentifier(stmt.expression) && byName.has(stmt.expression.text)) {
+        out.push(byName.get(stmt.expression.text));
+      }
+      continue;
+    }
+    if (ts.isFunctionDeclaration(stmt) && stmt.name && HTTP_HANDLERS.has(stmt.name.text)
+      && hasMod(stmt, ts.SyntaxKind.ExportKeyword)) {
+      out.push(stmt);
+      continue;
+    }
+    if (ts.isVariableStatement(stmt) && hasMod(stmt, ts.SyntaxKind.ExportKeyword)) {
+      for (const d of stmt.declarationList.declarations) {
+        if (ts.isIdentifier(d.name) && HTTP_HANDLERS.has(d.name.text)
+          && d.initializer && ts.isFunctionLike(d.initializer)) {
+          out.push(d.initializer);
+        }
+      }
+    }
+    if (ts.isExportDeclaration(stmt) && !stmt.moduleSpecifier
+      && stmt.exportClause && ts.isNamedExports(stmt.exportClause)) {
+      for (const el of stmt.exportClause.elements) {
+        const exported = el.name.text;
+        const local = (el.propertyName ?? el.name).text;
+        if (HTTP_HANDLERS.has(exported) && byName.has(local)) out.push(byName.get(local));
+      }
+    }
+  }
+  return out;
+}
+
+function hasInternalUserGate(ts, file, text) {
+  const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, scriptKind(ts, file));
+  const exits = (stmt) => {
+    if (!stmt) return false;
+    if (ts.isReturnStatement(stmt) || ts.isThrowStatement(stmt)) return true;
+    if (ts.isBlock(stmt)) return stmt.statements.some(exits);
+    if (ts.isExpressionStatement(stmt)) {
+      const e = stmt.expression;
+      return ts.isCallExpression(e) && ts.isIdentifier(e.expression) && GATE_EXITS.has(e.expression.text);
+    }
+    return false;
+  };
+  const isNegatedInternalCheck = (expr) =>
+    ts.isPrefixUnaryExpression(expr) && expr.operator === ts.SyntaxKind.ExclamationToken
+    && ts.isPropertyAccessExpression(expr.operand) && expr.operand.name.text === 'internalUserId';
+  const isLit = (n) => n && (ts.isStringLiteral(n) || ts.isNoSubstitutionTemplateLiteral(n));
+  const isViewerFactoryCallee = (expr) => {
+    if (ts.isIdentifier(expr)) {
+      return SDK_FACTORIES[expr.text] === PROVENANCE_VIEWER || expr.text === AFTER_ASSEMBLY;
+    }
+    if (ts.isPropertyAccessExpression(expr)) {
+      return SDK_FACTORIES[expr.name.text] === PROVENANCE_VIEWER || expr.name.text === AFTER_ASSEMBLY;
+    }
+    if (ts.isElementAccessExpression(expr) && isLit(expr.argumentExpression)) {
+      const name = expr.argumentExpression.text;
+      return SDK_FACTORIES[name] === PROVENANCE_VIEWER || name === AFTER_ASSEMBLY;
+    }
+    return false;
+  };
+  const isContextCall = (n) => {
+    let e = n;
+    while (ts.isParenthesizedExpression(e) || ts.isAwaitExpression(e) || ts.isNonNullExpression(e) || ts.isAsExpression(e)) {
+      e = e.expression;
+    }
+    return ts.isCallExpression(e) && (
+      (ts.isIdentifier(e.expression) && e.expression.text === REQUEST_CONTEXT) ||
+      (ts.isPropertyAccessExpression(e.expression) && e.expression.name.text === REQUEST_CONTEXT)
+    );
+  };
+  // Names a function binds from getRequestContext(): the context itself, and the viewer
+  // client destructured out of it. By name only, as the rest of the gate check is.
+  const contextNamesIn = (body) => {
+    const contextNames = new Set();
+    const viewerNames = new Set();
+    const walk = (n) => {
+      if (ts.isVariableDeclaration(n) && n.initializer && isContextCall(n.initializer)) {
+        if (ts.isIdentifier(n.name)) contextNames.add(n.name.text);
+        else if (ts.isObjectBindingPattern(n.name)) {
+          for (const el of n.name.elements) {
+            const member = el.propertyName ?? el.name;
+            if (ts.isIdentifier(member) && ts.isIdentifier(el.name) && CTX_MEMBERS[member.text] === PROVENANCE_VIEWER) {
+              viewerNames.add(el.name.text);
+            }
+          }
+        }
+      }
+      ts.forEachChild(n, walk);
+    };
+    walk(body);
+    return { contextNames, viewerNames };
+  };
+  const statementHasViewerSdkUse = (stmt, { contextNames, viewerNames }) => {
+    let found = false;
+    const walk = (n) => {
+      if (found) return;
+      if (ts.isCallExpression(n) && isViewerFactoryCallee(n.expression)) found = true;
+      else if (
+        ts.isPropertyAccessExpression(n) && CTX_MEMBERS[n.name.text] === PROVENANCE_VIEWER
+        && ((ts.isIdentifier(n.expression) && (n.expression.text === 'ctx' || contextNames.has(n.expression.text)))
+          || isContextCall(n.expression))
+      ) found = true;
+      else if (ts.isIdentifier(n) && viewerNames.has(n.text)) found = true;
+      else ts.forEachChild(n, walk);
+    };
+    walk(stmt);
+    return found;
+  };
+  const isGate = (stmt) =>
+    ts.isIfStatement(stmt) && isNegatedInternalCheck(stmt.expression) && exits(stmt.thenStatement);
+  const functionHasGate = (entry) => {
+    const body = entry.body;
+    if (!body || !ts.isBlock(body)) return false;
+    const names = contextNamesIn(body);
+    for (const stmt of body.statements) {
+      if (isGate(stmt)) return true;
+      if (statementHasViewerSdkUse(stmt, names)) return false;
+    }
+    return false;
+  };
+  const entries = entryFunctions(ts, sf);
+  return entries.length > 0 && entries.every(functionHasGate);
+}
+
+const REASON_RESERVED = 'reserved-segment';
+const REASON_WRAPPER = 'wrapper';
+const REASON_PRIVATE = 'private-routes';
+
+function classifyEntries(ts, root, files, read) {
+  const privateRoutes = readPrivateRoutes(root);
+  const fileSet = new Set(files);
+  const gateCache = new Map();
+  const gated = (file) => {
+    if (!gateCache.has(file)) gateCache.set(file, fileSet.has(file) && hasInternalUserGate(ts, file, read(file)));
+    return gateCache.get(file);
+  };
+  // A gate in a layout turns away everyone below it. Layouts do not run around
+  // route.ts handlers, so only pages inherit them.
+  const ancestorLayouts = (file) => {
+    const parts = file.split('/');
+    const out = [];
+    for (let i = parts.length - 1; i >= 1; i--) {
+      const layout = [...parts.slice(0, i), 'layout'].join('/');
+      const hit = files.find((f) => f !== file && f.startsWith(`${layout}.`) && LAYOUT_FILE.test(f));
+      if (hit) out.push(hit);
+    }
+    return out;
+  };
+
+  const entries = [];
+  const excluded = [];
+  const gatedEntries = [];
+  for (const file of files) {
+    let templates = null;
+    let wrapper = null;
+    if (ROUTE_FILE_PREDICATE.test(file)) {
+      templates = templatesForFile(file);
+      if (!templates) continue; // Parallel-route slots and intercepting routes are not served.
+      const { names } = analyseExports(ts, file, read(file));
+      // A wrapper protects its own handler only: a sibling handler without one is still served.
+      const wrappers = [...names.entries()]
+        .filter(([name]) => PROXY_METHODS.includes(name))
+        .map(([, init]) => (init ? wrapperName(ts, init) : null));
+      wrapper = wrappers.length > 0 && wrappers.every((w) => w && EXCLUDING_WRAPPERS.includes(w)) ? wrappers[0] : null;
+    } else {
+      const m = PAGE_FILE.exec(file);
+      if (!m || file.startsWith('app/api/') || file.startsWith('src/app/api/')) continue;
+      // An unservable layout (slot, intercepting route) can still be loaded by
+      // a client, so it stays in rather than risk a false CLEAN.
+      templates = templatesForDirs(m[1].split('/').filter(Boolean)) ?? [{ template: '' }];
+    }
+
+    const reason = templates.some((t) => isReservedTemplate(t.template))
+      ? REASON_RESERVED
+      : wrapper
+        ? `${REASON_WRAPPER}:${wrapper}`
+        : templates.some((t) => privateRoutes.some((re) => re.test(t.template)))
+          ? REASON_PRIVATE
+          : null;
+    if (reason) excluded.push({ file, reason });
+    else {
+      entries.push(file);
+      if ((ROUTE_FILE_PREDICATE.test(file) ? [file] : [file, ...ancestorLayouts(file)]).some(gated)) gatedEntries.push(file);
+    }
+  }
+  entries.sort(byteCompare);
+  gatedEntries.sort(byteCompare);
+  excluded.sort((a, b) => byteCompare(a.file, b.file));
+  return { entries, excluded, gatedEntries };
+}
+
+// ---------------------------------------------------------------------------
+// Analysis and projection
+// ---------------------------------------------------------------------------
+
+// Facts and the import graph for one app, computed lazily and memoised, so a
+// projection pays only for the files it reaches.
+export function createAnalysis(root) {
+  const ts = loadTypeScript();
+  const files = listFiles(root).filter((f) => SOURCE_FILE.test(f) && !DECLARATION_FILE.test(f)).sort(byteCompare);
+  const fileSet = new Set(files);
+  const texts = new Map();
+  const facts = new Map();
+
+  const read = (file) => {
+    if (!texts.has(file)) texts.set(file, readFileSync(path.join(root, file), 'utf8'));
+    return texts.get(file);
+  };
+
+  const resolveBase = (base) => {
+    if (fileSet.has(base)) return base;
+    for (const ext of RESOLVE_EXTENSIONS) if (fileSet.has(base + ext)) return base + ext;
+    for (const ext of RESOLVE_EXTENSIONS) if (fileSet.has(`${base}/index${ext}`)) return `${base}/index${ext}`;
+    return null;
+  };
+
+  // `@/` is tsconfig's usual alias for the app root or `src/`; reading
+  // tsconfig paths is out of scope, so an alias that fits neither is unresolved.
+  const resolve = (from, spec) => {
+    if (spec.startsWith('.')) return resolveBase(path.posix.normalize(path.posix.join(path.posix.dirname(from), spec)));
+    const rest = spec.replace(/^(?:@|~)\//, '');
+    for (const prefix of ALIAS_ROOTS) {
+      const hit = resolveBase(path.posix.normalize(prefix + rest));
+      if (hit) return hit;
+    }
+    return null;
+  };
+
+  const factsFor = (file) => {
+    if (!facts.has(file)) {
+      const raw = collectFileFacts(ts, file, read(file));
+      const imports = [];
+      const defeaters = [...raw.defeaters];
+      for (const spec of raw.specifiers) {
+        if (!LOCAL_SPECIFIER.test(spec)) continue;
+        const target = resolve(file, spec);
+        if (target) imports.push(target);
+        // Only a missing source file is a gap; assets and styles are not code.
+        else if (!/\.[a-z0-9]+$/i.test(spec) || RESOLVE_EXTENSIONS.some((e) => spec.endsWith(e))) {
+          defeaters.push({ line: 1, reason: DEFEATER.UNRESOLVED_IMPORT });
+        }
+      }
+      facts.set(file, { calls: raw.calls, defeaters, imports: [...new Set(imports)] });
+    }
+    return facts.get(file);
+  };
+
+  return { root, files, ts, read, facts: factsFor, classifyEntries: () => classifyEntries(ts, root, files, read) };
+}
+
+// Maps every file an entry can load to the byte-smallest entry that loads it.
+function reachFrom(analysis, entries) {
+  const reach = new Map();
+  for (const entry of entries) {
+    const queue = [entry];
+    while (queue.length) {
+      const file = queue.pop();
+      if (reach.has(file)) continue;
+      reach.set(file, entry);
+      queue.push(...analysis.facts(file).imports);
+    }
+  }
+  return reach;
+}
+
+export const sortFindings = (list) =>
+  list.sort((a, b) => byteCompare(a.file, b.file) || a.line - b.line || byteCompare(a.method ?? a.reason, b.method ?? b.reason));
+
+// The client-reachable projection: viewer calls outside the allowlist, and the
+// constructs that stop the scan proving there are none.
+export function projectClientReachable(analysis, allowlist = CLIENT_SAFE_SDK_METHODS) {
+  const allowed = new Set(allowlist);
+  const { entries, excluded, gatedEntries } = analysis.classifyEntries();
+  const reach = reachFrom(analysis, entries);
+  const findings = [];
+  const unresolved = [];
+  for (const [file, entry] of reach) {
+    const { calls, defeaters } = analysis.facts(file);
+    for (const c of calls) {
+      if (c.provenance === PROVENANCE_VIEWER && !allowed.has(c.method)) {
+        findings.push({ file, line: c.line, method: c.method, provenance: c.provenance, entry });
+      }
+    }
+    for (const d of defeaters) unresolved.push({ file, line: d.line, reason: d.reason, entry });
+  }
+  sortFindings(findings);
+  sortFindings(unresolved);
+  const cls = findings.length ? CLASS_BREAKS : unresolved.length ? CLASS_UNRESOLVED : CLASS_CLEAN;
+  return { class: cls, findings, unresolved, excludedEntries: excluded, gatedEntries };
+}
+
+export function scanClientCalls(root, { allowlist = CLIENT_SAFE_SDK_METHODS, appId } = {}) {
+  const app = { app: appId ?? path.basename(path.resolve(root)), ...projectClientReachable(createAnalysis(root), allowlist) };
+  return { scannerVersion: SCANNER_VERSION, apps: [app] };
+}
+
+export const serializeClientCalls = (result) => JSON.stringify(result, null, 2) + '\n';
+
+// Plug-in row for bin/scan.mjs. It has no `output`: the result is returned to
+// the caller instead of being committed into the app.
+export const clientCallScanner = {
+  name: 'client-calls',
+  run: (root) => ({ result: scanClientCalls(root), warnings: [] }),
+};

package/bin/scan-routes.mjs

@@ -36,9 +36,9 @@ const APP_JSON_PATH = '.assembly/app.json';
 const NEXT_CONFIG_FILES = ['next.config.js', 'next.config.mjs', 'next.config.cjs', 'next.config.ts', 'next.config.mts'];
 const SKIPPED_DIRS = new Set(['node_modules', '.git', '.next', '.vercel', '.turbo']);
 
-const byteCompare = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b));
+export const byteCompare = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b));
 
-function loadTypeScript() {
+export function loadTypeScript() {
   // Resolved from this file, so an installed package finds the app's own
   // typescript and this repo's tests find the devDependency.
   return createRequire(import.meta.url)('typescript');
@@ -60,7 +60,7 @@ function walk(root, dir = '') {
 }
 
 // What `git add -A` would stage, so the scan describes the commit it rides in.
-function listFiles(root) {
+export function listFiles(root) {
   if (existsSync(path.join(root, '.git'))) {
     const res = spawnSync('git', ['ls-files', '-z', '--cached', '--others', '--exclude-standard'], {
       cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024,
@@ -122,7 +122,11 @@ const DYNAMIC = /^\[([^\].]+)\]$/;
 // proxy cannot serve (parallel-route slots, intercepting routes); an optional
 // catch-all yields two templates.
 export function templatesForFile(file) {
-  const dirs = file.slice(API_PREFIX.length).split('/').slice(0, -1);
+  return templatesForDirs(file.slice(API_PREFIX.length).split('/').slice(0, -1));
+}
+
+// The segment walk, shared with scanners that derive page templates from `app/`.
+export function templatesForDirs(dirs) {
   let templates = [{ segments: [], catchAll: false }];
   for (const seg of dirs) {
     if (SLOT.test(seg) || INTERCEPTING.test(seg)) return null;
@@ -169,7 +173,7 @@ function globToRegExp(glob) {
   return new RegExp(`^${re}$`);
 }
 
-function readPrivateRoutes(root) {
+export function readPrivateRoutes(root) {
   try {
     const parsed = JSON.parse(readFileSync(path.join(root, APP_JSON_PATH), 'utf8'));
     const list = parsed?.privateRoutes;
@@ -187,7 +191,7 @@ const hasModifier = (ts, node, kind) => node.modifiers?.some((m) => m.kind === k
 
 // Returns the exported handler bindings and whether the export surface is
 // opaque (`export *`, CommonJS) so names cannot be read statically.
-function analyseExports(ts, file, text) {
+export function analyseExports(ts, file, text) {
   const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, false, file.endsWith('x') ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
   const names = new Map(); // exported name -> initializer expression | null
   let opaque = false;
@@ -236,7 +240,7 @@ function analyseExports(ts, file, text) {
 // The callee identifier of a handler initializer, matched by name only: no
 // resolution, so `export const POST = cronRoute(...)` is recognised without
 // following the import.
-function wrapperName(ts, init) {
+export function wrapperName(ts, init) {
   let node = init;
   while (node && (ts.isParenthesizedExpression(node) || ts.isAwaitExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression?.(node))) {
     node = node.expression;

package/bin/scan.mjs

@@ -9,6 +9,7 @@
 import { mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { clientCallScanner } from './scan-client-calls.mjs';
 import { scanRoutes, serializeRoutes } from './scan-routes.mjs';
 
 const SCANNERS = [
@@ -22,6 +23,11 @@ const SCANNERS = [
   },
 ];
 
+// Scanners whose result goes to the caller, not to a committed file. They run
+// only when asked (`runScanners(root, ON_DEMAND_SCANNERS)`), so a generated app
+// pays for them on no turn and gains no new file.
+export const ON_DEMAND_SCANNERS = [clientCallScanner];
+
 function writeIfChanged(file, content) {
   try {
     if (readFileSync(file, 'utf8') === content) return;
@@ -35,22 +41,24 @@ function writeIfChanged(file, content) {
   renameSync(tmp, file);
 }
 
-export function runScanners(root = process.cwd()) {
+export function runScanners(root = process.cwd(), scanners = SCANNERS) {
   // Every scanner runs before any file is written, so one throwing leaves all
   // previous outputs intact rather than a mix of old and new.
-  const results = SCANNERS.map((scanner) => ({ scanner, ...scanner.run(root) }));
+  const results = scanners.map((scanner) => ({ scanner, ...scanner.run(root) }));
   const warnings = [];
-  for (const { scanner, content, warnings: found } of results) {
-    writeIfChanged(path.join(root, scanner.output), content);
+  const outputs = {};
+  for (const { scanner, content, result, warnings: found } of results) {
+    if (scanner.output) writeIfChanged(path.join(root, scanner.output), content);
+    else outputs[scanner.name] = result;
     warnings.push(...found.map((w) => ({ scanner: scanner.name, ...w })));
   }
-  return { warnings };
+  return { warnings, outputs };
 }
 
 // argv[1] is not realpathed but import.meta.url is, so a symlinked path would skip the run.
 if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
   try {
-    process.stdout.write(JSON.stringify(runScanners()) + '\n');
+    process.stdout.write(JSON.stringify({ warnings: runScanners().warnings }) + '\n');
   } catch (err) {
     console.error(`scan: ${err && err.stack ? err.stack : err}`);
     process.exit(1);

package/dist/app-installs.d.ts

@@ -0,0 +1,17 @@
+import type { AssemblyAPI } from '@assembly-js/node-sdk';
+/**
+ * @deprecated Built-in modules are being replaced by generated apps, so this
+ * map will be removed. Prefer an appId you resolved from the workspace; use
+ * these only to gate a feature on a module that still ships built in.
+ */
+export declare const LEGACY_APP_IDS: {
+    readonly messages: "38323633-6465-6132-3730-383065323230";
+    readonly billing: "64346438-6461-6431-6565-366361383434";
+    readonly files: "33343966-3136-6166-6561-343739303432";
+    readonly contracts: "34633033-3365-6561-6332-386434316430";
+    readonly forms: "66666663-3861-6633-3830-323337613065";
+    readonly helpdesk: "30643961-3563-3361-3035-396231663435";
+    readonly tasks: "0e1dff29-1ce3-40ac-b58d-264097f6b319";
+};
+export declare function getInstalledAppIds(assembly: AssemblyAPI): Promise<Set<string>>;
+export declare function isAppInstalled(assembly: AssemblyAPI, appId: string): Promise<boolean>;

package/dist/app-installs.js

@@ -0,0 +1,34 @@
+// Every node-sdk call for install lookups lives in getInstalledAppIds, so the
+// node-sdk namespace migration is a one-line change here and never reaches
+// generated apps.
+/**
+ * @deprecated Built-in modules are being replaced by generated apps, so this
+ * map will be removed. Prefer an appId you resolved from the workspace; use
+ * these only to gate a feature on a module that still ships built in.
+ */
+export const LEGACY_APP_IDS = {
+    messages: '38323633-6465-6132-3730-383065323230',
+    billing: '64346438-6461-6431-6565-366361383434',
+    files: '33343966-3136-6166-6561-343739303432',
+    contracts: '34633033-3365-6561-6332-386434316430',
+    forms: '66666663-3861-6633-3830-323337613065',
+    helpdesk: '30643961-3563-3361-3035-396231663435',
+    tasks: '0e1dff29-1ce3-40ac-b58d-264097f6b319',
+};
+// A disabled install is dropped: it is present in the list but its surfaces and
+// API behave as if the app were not there.
+export async function getInstalledAppIds(assembly) {
+    try {
+        const installs = await assembly.listAppInstalls({});
+        return new Set(installs.filter((i) => !i.disabled && i.appId).map((i) => i.appId));
+    }
+    catch (err) {
+        // Fails closed so a lookup error renders the "not installed" state instead
+        // of throwing into the page.
+        console.error('getInstalledAppIds: listAppInstalls failed', err);
+        return new Set();
+    }
+}
+export async function isAppInstalled(assembly, appId) {
+    return (await getInstalledAppIds(assembly)).has(appId);
+}

package/dist/server.d.ts

@@ -3,6 +3,7 @@ export * from './assembly.js';
 export * from './action-route.js';
 export * from './auth.js';
 export * from './client-access.js';
+export * from './app-installs.js';
 export * from './mint-bearer.js';
 export * from './verify-bearer.js';
 export * from './nango.js';

package/dist/server.js

@@ -7,6 +7,7 @@ export * from './assembly.js';
 export * from './action-route.js';
 export * from './auth.js';
 export * from './client-access.js';
+export * from './app-installs.js';
 export * from './mint-bearer.js';
 export * from './verify-bearer.js';
 export * from './nango.js';

package/package.json

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

package/skills/assembly-native-resources/SKILL.md

@@ -9,6 +9,10 @@ description: Use any time the app references a native Assembly message channel,
 
 Discover instead. The pattern is always the same two steps: **list, then match on a stable attribute** the workspace owner controls (a title, a name), or resolve the resource from the current request's identity. Never a literal.
 
+## Check the app is installed first
+
+Gate any feature that depends on another app with `isAppInstalled(assembly, <appId>)` from `@assembly-js/app-foundation/server`, and show an honest "<app> isn't installed in this workspace" state when it is false. It works the same for core, marketplace and custom apps.
+
 ## Discovering a form
 
 A form's display name is on `fields`, not on the form itself. Walk every page — matching by name against only the first page reports the form as missing once the workspace has more than a page of forms:
@@ -31,6 +35,8 @@ await assembly.requestFormResponse({
 });
 ```
 
+**Testing a form request:** never ask the user to send one to a real client. Suggest a throwaway test client, and say before the first test that a request can't be undone from the app — it can only be removed in the dashboard.
+
 There is **no** method for a custom app to submit answers to a native form — you can request a response from a client and read `listFormResponses`, nothing more. Build your own form (see `assembly-forms`) if the app needs to collect the answers itself.
 
 ## Discovering a message channel