@assembly-js/app-foundation 0.0.35 → 0.0.37-rc.0

package/CLAUDE.md

@@ -198,6 +198,8 @@ Relationships:
 
 **Listing companies for users.** `listCompanies` excludes **placeholder** companies (nameless solo-client stand-ins) by default for app-builder apps, so company dropdowns, tables, and filters won't show blank "ghost" rows — you don't need to filter them yourself. To *include* placeholders (e.g. to surface solo clients), pass `listCompanies({ isPlaceholder: true })` explicitly. See `assembly-companies` skill.
 
+**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.
+
 ---
 
 ## Iframe constraints — read before writing UI
@@ -252,7 +254,7 @@ Two things flow into the running app from Assembly:
 | | Where | Visibility |
 |---|---|---|
 | `ASSEMBLY_API_KEY` | `process.env.ASSEMBLY_API_KEY` | **Server only.** Never expose. Identifies the *app*, not the user. Used by the foundation to mint bearers — you don't touch it. |
-| User bearer | HttpOnly cookie, set by the middleware after the one-time `?token=` exchange | **You never handle it.** `getAssembly()` reads it to act as the current user; `getSessionIdentity()` decodes the viewer. See "How auth works". |
+| User bearer | HttpOnly cookie, set by the middleware after the one-time `?token=` exchange | **You never handle it.** `getAssembly()` reads it to act as the current user; `getSessionIdentity()` returns the viewer the platform verified for it. See "How auth works". |
 
 ---
 
@@ -645,11 +647,11 @@ const assembly = await getAssembly();      // no token — the bearer comes from
 const items = await assembly.listItems({});
 ```
 
-`getAssembly()` is async — always `await` it. If the bearer is missing or expired it throws `TokenInvalidError`; let it propagate, and the client helpers (`useServerAction` / `authFetch`) re-exchange and retry for you.
+`getAssembly()` is async — always `await` it. If the bearer is missing or expired it throws `TokenInvalidError`; let it propagate, and the client helpers (`useServerAction` / `authFetch`) re-exchange and retry for you. If the platform cannot be reached to verify the bearer it throws `AuthUnavailableError` (and `getSessionIdentity()` does too) — a different error on purpose: it is not an expiry, so never catch it into `null`/signed-out and never re-exchange on it; let a route return 503, and render a retry state ("Couldn't load, try again" with a retry button) wherever a server component reads identity.
 
 #### Identity — who is the viewer?
 
-Server-side, `getSessionIdentity()` returns the viewer decoded from the bearer (no token, no API call):
+Server-side, `getSessionIdentity()` returns the viewer the platform verified for the bearer (no token to pass; the check is cached briefly per server instance):
 
 ```ts
 import { getSessionIdentity } from '@assembly-js/app-foundation/server';
@@ -798,7 +800,7 @@ Two pre-built helpers guard API routes that operate on company-scoped resources:
 import { requireAuth, requireCompanyScope } from '@assembly-js/app-foundation/server';
 ```
 
-**`requireAuth(req)`** decodes the viewer's identity from the bearer and returns it. Returns a 401 `NextResponse` with a `{ code: 'token_expired' }` body **and** `x-assembly-token-expired: 1` header when the bearer is missing/expired — `authFetch` detects this and re-exchanges + retries automatically.
+**`requireAuth(req)`** verifies the bearer with the platform and returns the identity from the platform's verification response. Returns a 401 `NextResponse` with a `{ code: 'token_expired' }` body **and** `x-assembly-token-expired: 1` header when the bearer is missing, expired or not accepted — `authFetch` detects this and re-exchanges + retries automatically. When the platform cannot be reached to verify, it returns a 503 with `{ code: 'auth_unavailable' }` and **no** expiry marker, so nothing re-exchanges; the 503 reaches the app, which should render a retry state or let the user retry.
 
 **`requireCompanyScope(identity, resource, assembly?)`** asserts the viewer can access a resource scoped to a company **or to a client**. Internal users always pass (client-vs-staff isolation only — not Client Access; filter app-owned data for limited internal users per `assembly-internal-users`). For a company-scoped resource, client access is checked against `identity.companyId`; when that is absent (a multi-company client not loaded in a CRM tab), pass the bearer client from `getAssemblyForRequest` as the third argument and the helper fetches the client's full `companyIds` list to verify membership. For a **client-scoped resource** (`companyId` null), pass the resource's `clientId` too — `{ companyId: item.companyId, clientId: item.clientId }` — so the owning client passes; without it every client gets a 404, including the one the record is assigned to. Returns `null` on success, or a 403/404 `NextResponse` on mismatch. A 403 from `requireCompanyScope` is a permanent authorization failure — a re-exchange will not fix cross-tenant access. When a row carries **both** scope columns the helper requires both to match, so a client-owned row is never reachable by a sibling client in the same company — see `assembly-route-auth`.
 
@@ -868,7 +870,7 @@ So there is nothing to refresh, subscribe to, or thread. Don't touch `AssemblyBr
 
 Use identity to branch your UI *before* making data calls — don't infer the viewer by catching a 403 (slow, and any unrelated 403 misclassifies).
 
-Server-side (`getSessionIdentity()` decodes the bearer; no API call):
+Server-side (`getSessionIdentity()` returns the platform-verified viewer; no token to pass):
 
 ```ts
 import { getSessionIdentity } from '@assembly-js/app-foundation/server';
@@ -1158,7 +1160,7 @@ Use `AssemblyBridge.header.*` for breadcrumbs, CTAs, and actions menu. See `.cla
 - ❌ Don't make Assembly API calls from client components without a server-side proxy. The apiKey can't leave the server.
 - ❌ Don't reinvent Clients, Companies, or custom fields — they are always available via the SDK. For Messages, Files, Forms, Tasks, Billing, Contracts, Notes, or Knowledge Base: confirm the module is installed (`listAppInstalls`) first; if it is, call the SDK methods listed above rather than rebuilding it. If it is not installed, do not suggest it or plan around it.
 - ❌ Don't use `assembly.clients.list()` — the SDK is flat. Use `assembly.listClients(...)`.
-- ❌ Don't cache decoded payloads for >30s — token rotates every 5 min and the user could be different on the next call (rare, but possible if a session is shared across tabs).
+- ❌ Don't cache a viewer's identity yourself. The foundation already caches the platform's verification for up to 60 seconds per server instance; a longer cache of your own can outlive a session change (a shared session across tabs can switch viewers).
 <!-- !feature:app-owned-header -->
 - ❌ Don't render your own breadcrumbs / titles in the DOM — use `AssemblyBridge.header.*`.
 - ❌ Don't render primary page-level actions (Submit, Save, Edit, Create) as `<Button>` elements inside the page body. These MUST go in the header via the `useAssemblyHeader` hook's `primaryCta`. Contextual inline actions (e.g. row-level edit icons, list "Add item" buttons) may stay in-page. In-page primary CTAs make the UX inconsistent with the rest of the portal. **Exception: the notification surface (`/n`).** The Notification Center renders `/n` in a headerless iframe — `useAssemblyHeader` is ignored. On this surface, primary actions MUST be inline `<Button>` elements.
@@ -1179,6 +1181,7 @@ Use `AssemblyBridge.header.*` for breadcrumbs, CTAs, and actions menu. See `.cla
 - ❌ Don't hardcode mutation error messages like "Failed to save preference". Read `error` from the response body and surface it to the user.
 - ❌ Don't `throw new Error` with a sentence the user should read from a server action. Production redacts that throw, so the toast shows a generic React error and the response is HTTP 500. Return `{ ok: false, message }` and toast `message`. Let `TokenInvalidError` and unexpected failures throw. See `assembly-action-results`.
 - ❌ Don't `Promise.all` a list-sized write fan-out (one `createNotification` / `markNotificationRead` / update per recipient or record). Writes cap at 5 concurrent per token; firing a whole list 429s and silently drops the overflow. Use `sendThrottled` from `@assembly-js/app-foundation/server`. A fixed handful of calls is the only exception. See "Write rate limit" above.
+- ❌ Don't re-notify a still-true condition from a cron. Record the alert on the subject before the send and clear it when the condition ends. See "Recurring conditions" in `assembly-notifications`.
 - ❌ Don't use title case — see "Labels, copy, and dropdowns" above.
 - ❌ Don't render raw IDs or pass a raw ID string as `value` on `ComboboxItem` — see "Select and Combobox — base-ui differences" above.
 - ❌ Don't write a scalar string to a custom field that has options. **All option-bearing custom fields are `multiSelect` in Assembly's schema** — even ones that LOOK like single-select dropdowns. The value must always be an array of option keys: `{ favorite_pizza: ['pepperoni'] }`, never `{ favorite_pizza: 'pepperoni' }`. A scalar string for a multiSelect causes a 400 with `invalid custom field option <value> provided`.

package/bin/validate-manifest.mjs

@@ -18,8 +18,11 @@ const MAX_NOTIFICATION_SETTINGS = 50;
 // Setting ids are permanent: they key each internal user's saved toggles and
 // are passed as notificationSettingId on createNotification, so the validator
 // requires stable author-chosen ids instead of letting the platform generate
-// ones that would rotate on every deploy.
-const KEBAB_ID = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+// ones that would rotate on every deploy. Hyphens and underscores are both
+// stable (a UUID is hyphenated and already matches). Rejecting underscores
+// failed the build when the user or the plan named a category that way
+// (past_due). This check does not rewrite ids already saved on the app.
+const NOTIFICATION_SETTING_ID = /^[a-z0-9]+([_-][a-z0-9]+)*$/;
 
 function fail(lines) {
   console.error('');
@@ -166,10 +169,11 @@ if (doc.notificationSettings !== undefined) {
           errors.push(at + ' must be an object with "id", "label", and "surfaces".');
           return;
         }
-        if (typeof setting.id !== 'string' || !KEBAB_ID.test(setting.id)) {
+        if (typeof setting.id !== 'string' || !NOTIFICATION_SETTING_ID.test(setting.id)) {
           errors.push(
             at +
-              '.id is required and must be kebab-case (e.g. "task-completed"). Ids are permanent — ' +
+              '.id is required and must be lowercase letters, digits, hyphens, or underscores ' +
+              '(e.g. "task-completed" or "past_due"). Ids are permanent — ' +
               "they key each internal user's saved toggles and are passed as notificationSettingId " +
               'when creating notifications.',
           );

package/dist/api-errors.js

@@ -1,4 +1,5 @@
 import { NextResponse } from 'next/server';
+import { AuthUnavailableError, authUnavailableResponse } from './assembly.js';
 export function badRequest(message) {
     return NextResponse.json({ error: message }, { status: 400 });
 }
@@ -26,6 +27,10 @@ function isInvalidInputDbError(err) {
 // to the UI when handlers do that.
 export function handleRouteError(err, fallback = 'Something went wrong') {
     console.error(err);
+    // A platform outage is not an app bug; surface it as a retryable 503.
+    if (err instanceof AuthUnavailableError) {
+        return authUnavailableResponse();
+    }
     if (isInvalidInputDbError(err)) {
         return badRequest('Invalid request');
     }

package/dist/assembly.d.ts

@@ -19,6 +19,17 @@ export declare class TokenInvalidError extends Error {
     readonly code = "TOKEN_INVALID";
     constructor(message?: string);
 }
+/**
+ * Thrown when the platform could not be reached to verify the viewer's bearer
+ * (outage, throttle, timeout). It says nothing about the bearer, so it is NOT a
+ * token-invalid error: do not re-exchange on it (that would spend a single-use
+ * session token for nothing) and do not render a signed-out state. Render a
+ * retry state instead. Distinct `name`/`code` from TokenInvalidError on purpose.
+ */
+export declare class AuthUnavailableError extends Error {
+    readonly code = "AUTH_UNAVAILABLE";
+    constructor(message?: string);
+}
 export declare function getAssembly(input?: AssemblyInput): Promise<AssemblyAPI>;
 /**
  * Runs `task` after the response is sent (Next's `after()`), with a viewer-
@@ -48,6 +59,8 @@ export declare function getAssembly(input?: AssemblyInput): Promise<AssemblyAPI>
 export declare function afterAssembly(task: (assembly: AssemblyAPI) => Promise<unknown>, options?: {
     token?: string;
 }): void;
+export declare const AUTH_UNAVAILABLE_CODE = "auth_unavailable";
+export declare function authUnavailableResponse(): NextResponse;
 /**
  * OFFLINE / BACKGROUND ONLY — cron jobs, webhook handlers, and any other code
  * path where there is NO user in the loop and thus no session token or bearer

package/dist/assembly.js

@@ -3,33 +3,55 @@ import { cookies, headers } from 'next/headers';
 import { after, NextResponse } from 'next/server';
 import { BEARER_COOKIE_NAME, BEARER_HEADER_NAME, decodeBearer, isSessionExchangeEnabled, TOKEN_EXPIRED_HEADER, } from './session-exchange.js';
 import { mintBearerFromAppKey } from './mint-bearer.js';
+import { verifyBearer } from './verify-bearer.js';
 // Trusted API origin for this stack, supplied by the build environment — NOT by
 // a token claim. Empty in prod/shared-staging (the SDK's env default is already
 // correct); set to a per-dev private stack's platform-api URL otherwise. Passed
 // to the SDK as `baseUrl` so tokenless (cookie-only) calls reach the right stack.
 const trustedBaseUrl = process.env.ASSEMBLY_API_BASE_URL || undefined;
-// Reads the viewer bearer for the current request, independent of the exchange
-// flag. First the header the proxy forwards on first load (the exchange just
-// minted it; the Set-Cookie isn't yet visible), then the HttpOnly cookie on every
-// later request. Returns undefined outside a request scope (e.g. build-time
-// prerender) — not an error. Used both to resolve identity and, in
-// getOfflineAssembly, to detect that a viewer is present.
-async function readViewerBearer() {
+// Reads the viewer bearer candidates for the current request, independent of the
+// exchange flag: first the header the proxy forwards on first load (the exchange
+// just minted it; the Set-Cookie isn't yet visible), then the HttpOnly cookie on
+// every later request. Returns [] outside a request scope (e.g. build-time
+// prerender) — not an error.
+async function readBearerCandidates() {
     try {
         const fromProxy = (await headers()).get(BEARER_HEADER_NAME);
-        if (fromProxy && decodeBearer(fromProxy))
-            return fromProxy;
         const fromCookie = (await cookies()).get(BEARER_COOKIE_NAME)?.value;
-        if (fromCookie && decodeBearer(fromCookie))
-            return fromCookie;
+        return [fromProxy, fromCookie].filter((b) => Boolean(b));
     }
     catch {
-        return undefined;
+        return [];
+    }
+}
+// First candidate that survives the no-network precheck, unverified. For callers
+// that only need to carry the credential across a boundary (afterAssembly) and
+// verify it where it is used.
+async function readViewerBearer() {
+    return (await readBearerCandidates()).find((b) => decodeBearer(b));
+}
+// The viewer's bearer together with the identity the platform verified for it.
+// A rejected candidate falls through to the next one, as an undecodable one
+// always did. An unverifiable one stops the walk: it says nothing about the
+// bearer, so the request must neither be treated as signed out nor re-exchanged.
+async function readVerifiedViewer() {
+    for (const bearer of await readBearerCandidates()) {
+        const result = await verifyBearer(bearer);
+        if (result.ok)
+            return { bearer, identity: result.identity };
+        if (result.reason === 'unavailable')
+            throw new AuthUnavailableError();
     }
     return undefined;
 }
-// Viewer bearer for request-scoped auth: only consulted when the exchange flow is
-// on (the legacy path carries identity in proxy headers, not a bearer cookie).
+// Verified viewer for request-scoped auth: only consulted when the exchange flow
+// is on (the legacy path carries identity in proxy headers, not a bearer cookie).
+async function resolveRequestViewer() {
+    if (!isSessionExchangeEnabled())
+        return undefined;
+    return readVerifiedViewer();
+}
+// Unverified bearer for deferred work; see readViewerBearer.
 async function resolveRequestBearer() {
     if (!isSessionExchangeEnabled())
         return undefined;
@@ -64,15 +86,22 @@ async function hasViewerRequest() {
         return false;
     }
 }
-// Server-only: the current user's identity, resolved from the bearer (the
-// proxy-forwarded header on first load, else the HttpOnly cookie). This is how
-// the app learns who the viewer is — workspace, client/company, internal user —
-// without ever handling the raw session token. Used to seed the client provider
-// and by server components. Returns null when unauthenticated or when the
-// exchange is disabled (the legacy path carries identity in proxy headers).
+// Server-only: the current user's identity, verified by the platform for the
+// bearer (the proxy-forwarded header on first load, else the HttpOnly cookie).
+// This is how the app learns who the viewer is — workspace, client/company,
+// internal user — without ever handling the raw session token. Used to seed the
+// client provider and by server components. Returns null when unauthenticated or
+// when the exchange is disabled (the legacy path carries identity in proxy
+// headers). Throws AuthUnavailableError when the platform could not be reached
+// to verify, so a layout can render a retry state rather than a signed-out one.
 export async function getSessionIdentity() {
-    const bearer = await resolveRequestBearer();
-    return bearer ? decodeBearer(bearer) : null;
+    const viewer = await resolveRequestViewer();
+    if (!viewer)
+        return null;
+    // Project to the documented shape so layouts that pass the whole object to a
+    // client provider don't serialize server-side fields to the browser.
+    const { workspaceId, clientId, internalUserId, companyId, notificationId, instanceId, sessionId } = viewer.identity;
+    return { workspaceId, clientId, internalUserId, companyId, notificationId, instanceId, sessionId };
 }
 /**
  * Thrown when a session token is required but missing, or was supplied but
@@ -91,6 +120,20 @@ export class TokenInvalidError extends Error {
         this.name = 'TokenInvalidError';
     }
 }
+/**
+ * Thrown when the platform could not be reached to verify the viewer's bearer
+ * (outage, throttle, timeout). It says nothing about the bearer, so it is NOT a
+ * token-invalid error: do not re-exchange on it (that would spend a single-use
+ * session token for nothing) and do not render a signed-out state. Render a
+ * retry state instead. Distinct `name`/`code` from TokenInvalidError on purpose.
+ */
+export class AuthUnavailableError extends Error {
+    code = 'AUTH_UNAVAILABLE';
+    constructor(message = 'Assembly could not verify the session right now') {
+        super(message);
+        this.name = 'AuthUnavailableError';
+    }
+}
 export async function getAssembly(input) {
     const token = typeof input === 'string' ? input : input?.token;
     // Exchange enabled ⇒ this is a bearer-capable app, and it authenticates via
@@ -104,31 +147,25 @@ export async function getAssembly(input) {
     // after() and pass it through explicitly as `input.token`; this honors that
     // pre-resolved bearer instead of re-deriving it from request scope. The
     // common case (no explicit token) is unchanged: derive from the request.
+    // Either way the identity is the one the platform verified for the bearer.
     if (isSessionExchangeEnabled()) {
-        const bearer = token ?? (await resolveRequestBearer());
-        if (!bearer) {
-            throw new TokenInvalidError('Assembly bearer is required');
+        let viewer;
+        if (token) {
+            const result = await verifyBearer(token);
+            if (result.ok) {
+                viewer = { bearer: token, identity: result.identity };
+            }
+            else if (result.reason === 'unavailable') {
+                throw new AuthUnavailableError();
+            }
         }
-        const assembly = await assemblyApi({ bearer, baseUrl: trustedBaseUrl });
-        const payload = await assembly.getTokenPayload?.();
-        if (!payload?.workspaceId) {
-            throw new TokenInvalidError();
+        else {
+            viewer = await resolveRequestViewer();
         }
-        // The published SDK's bearer-mode payload maps only the identity claims,
-        // so overlay the embed-context claims here to keep getTokenPayload()'s
-        // documented contract (payload.notificationId marks the Notification
-        // Center surface) intact for exchange-capable apps. Becomes a harmless
-        // no-op once the SDK maps these claims natively.
-        const session = decodeBearer(bearer);
-        if (session?.notificationId || session?.instanceId) {
-            const merged = {
-                ...payload,
-                notificationId: session.notificationId,
-                instanceId: session.instanceId,
-            };
-            assembly.getTokenPayload = () => Promise.resolve(merged);
+        if (!viewer) {
+            throw new TokenInvalidError(token ? undefined : 'Assembly bearer is required');
         }
-        return assembly;
+        return getBearerAssembly(viewer.bearer, viewer.identity);
     }
     // Exchange disabled (legacy apps built before this feature, or a rollback):
     // the raw session token is the credential and is sent as X-API-Key, exactly
@@ -198,13 +235,35 @@ export function afterAssembly(task, options) {
 function tokenExpiredResponse() {
     return NextResponse.json({ error: 'Unauthorized', code: 'token_expired' }, { status: 401, headers: { [TOKEN_EXPIRED_HEADER]: '1' } });
 }
+export const AUTH_UNAVAILABLE_CODE = 'auth_unavailable';
+// 503 with deliberately NO token-expired marker: the bearer was never judged, so
+// authFetch must not re-exchange (which would spend a single-use session token)
+// and the client should retry the same request instead.
+export function authUnavailableResponse() {
+    return NextResponse.json({ error: 'Service unavailable', code: AUTH_UNAVAILABLE_CODE }, { status: 503 });
+}
 // Builds a bearer-only SDK client. The SDK's native `bearer` option sends
 // Authorization: Bearer on every request — generated service methods and fetch
-// alike — and, with no apiKey supplied, sends NO X-API-Key. Identity comes from
-// the bearer's own signed claims (getTokenPayload() reads them); the API origin
-// comes from the trusted build-env baseUrl, never a token/bearer claim.
-async function getBearerAssembly(bearer) {
-    return assemblyApi({ bearer, baseUrl: trustedBaseUrl });
+// alike — and, with no apiKey supplied, sends NO X-API-Key. The API origin comes
+// from the trusted build-env baseUrl, never a token/bearer claim. When the
+// caller has a verified identity, getTokenPayload() answers with it rather than
+// with the SDK's read of the bearer's claims.
+async function getBearerAssembly(bearer, identity) {
+    const assembly = await assemblyApi({ bearer, baseUrl: trustedBaseUrl });
+    if (identity) {
+        // Includes the embed-context ids the SDK's bearer-mode payload omits, so
+        // payload.notificationId still marks the Notification Center surface.
+        const payload = {
+            workspaceId: identity.workspaceId,
+            clientId: identity.clientId,
+            companyId: identity.companyId,
+            internalUserId: identity.internalUserId,
+            notificationId: identity.notificationId,
+            instanceId: identity.instanceId,
+        };
+        assembly.getTokenPayload = () => Promise.resolve(payload);
+    }
+    return assembly;
 }
 /**
  * OFFLINE / BACKGROUND ONLY — cron jobs, webhook handlers, and any other code
@@ -250,23 +309,30 @@ export async function getOfflineAssembly() {
 }
 // Returns a request-scoped SDK client authenticated for the current user.
 //
-// Exchange enabled: bearer-only. A valid bearer (proxy header or cookie) yields
-// a client that carries Authorization: Bearer on every request; a missing or
-// undecodable bearer yields a 401 NextResponse so the client re-exchanges via
-// the x-assembly-token-expired convention. There is no session-token fallback.
+// Exchange enabled: bearer-only. A bearer the platform verifies (proxy header or
+// cookie) yields a client that carries Authorization: Bearer on every request; a
+// missing or rejected bearer yields a 401 NextResponse so the client re-exchanges
+// via the x-assembly-token-expired convention, and a bearer that could not be
+// verified yields a 503 without that marker. There is no session-token fallback.
 // Exchange disabled: the legacy session-token (X-API-Key) path.
 export async function getAssemblyForRequest(req) {
     if (isSessionExchangeEnabled()) {
         // Bearer-only: the proxy-forwarded header on first load, else the HttpOnly
-        // cookie. Its signed claims carry identity for SDK init. No bearer (or an
-        // undecodable/expired one) ⇒ 401 marker so the client re-exchanges; there
-        // is no X-API-Key / session-token fallback for a bearer-capable app.
+        // cookie. No bearer (or a rejected/expired one) ⇒ 401 marker so the client
+        // re-exchanges; there is no X-API-Key / session-token fallback for a
+        // bearer-capable app.
         const bearer = req.headers.get(BEARER_HEADER_NAME) ??
             req.cookies.get(BEARER_COOKIE_NAME)?.value;
-        if (!bearer || !decodeBearer(bearer)) {
+        if (!bearer) {
             return tokenExpiredResponse();
         }
-        return getBearerAssembly(bearer);
+        const result = await verifyBearer(bearer);
+        if (!result.ok) {
+            return result.reason === 'rejected'
+                ? tokenExpiredResponse()
+                : authUnavailableResponse();
+        }
+        return getBearerAssembly(bearer, result.identity);
     }
     // Legacy (exchange disabled): authenticate from the session-token header,
     // sent as X-API-Key. Missing token ⇒ 401 marker.

package/dist/auth.js

@@ -1,6 +1,7 @@
 import { NextResponse } from 'next/server';
-import { getAssembly } from './assembly.js';
-import { BEARER_COOKIE_NAME, BEARER_HEADER_NAME, decodeBearer, isSessionExchangeEnabled, TOKEN_EXPIRED_HEADER, } from './session-exchange.js';
+import { authUnavailableResponse, getAssembly } from './assembly.js';
+import { BEARER_COOKIE_NAME, BEARER_HEADER_NAME, isSessionExchangeEnabled, TOKEN_EXPIRED_HEADER, } from './session-exchange.js';
+import { verifyBearer } from './verify-bearer.js';
 // Detect an expired/undecryptable-token error from the SDK by shape rather than
 // by importing a concrete class — the foundation builds against whatever SDK
 // version is published, which may not export the error type.
@@ -14,26 +15,35 @@ function tokenExpiredResponse() {
     return NextResponse.json({ error: 'Unauthorized', code: 'token_expired' }, { status: 401, headers: { [TOKEN_EXPIRED_HEADER]: '1' } });
 }
 // Resolves the current viewer's identity for a route handler.
-// Exchange on: bearer-only — decodes the bearer (proxy-forwarded header on first
-// load, else the HttpOnly cookie); a missing/undecodable bearer returns a 401
-// with the x-assembly-token-expired marker so the client re-exchanges. There is
-// no session-token fallback for a bearer-capable app.
+// Exchange on: bearer-only — verifies the bearer with the platform (proxy-
+// forwarded header on first load, else the HttpOnly cookie) and builds the
+// payload from the verified identity, never from the bearer's claims. A
+// missing/rejected bearer returns a 401 with the x-assembly-token-expired marker
+// so the client re-exchanges; a bearer that could not be verified returns a 503
+// without the marker, so nothing re-exchanges. There is no session-token
+// fallback for a bearer-capable app.
 // Exchange off (legacy): reads and decodes the x-assembly-token header.
 export async function requireAuth(req) {
     if (isSessionExchangeEnabled()) {
         const bearer = req.headers.get(BEARER_HEADER_NAME) ??
             req.cookies.get(BEARER_COOKIE_NAME)?.value;
-        const session = bearer ? decodeBearer(bearer) : null;
-        if (!session) {
+        if (!bearer) {
             return tokenExpiredResponse();
         }
+        const result = await verifyBearer(bearer);
+        if (!result.ok) {
+            return result.reason === 'rejected'
+                ? tokenExpiredResponse()
+                : authUnavailableResponse();
+        }
+        const { identity } = result;
         return {
-            workspaceId: session.workspaceId,
-            clientId: session.clientId,
-            internalUserId: session.internalUserId,
-            companyId: session.companyId,
-            notificationId: session.notificationId,
-            instanceId: session.instanceId,
+            workspaceId: identity.workspaceId,
+            clientId: identity.clientId,
+            internalUserId: identity.internalUserId,
+            companyId: identity.companyId,
+            notificationId: identity.notificationId,
+            instanceId: identity.instanceId,
         };
     }
     const token = req.headers.get('x-assembly-token');

package/dist/replace-rows.d.ts

@@ -0,0 +1,27 @@
+type BatchDb = {
+    batch(queries: never): Promise<unknown>;
+};
+export type ReplaceChildRowsResult = {
+    ok: true;
+    ids: string[];
+} | {
+    ok: false;
+    message: string;
+};
+type ReplaceChildRowsSpec<TRow extends {
+    id?: string;
+}, TDelete extends PromiseLike<unknown>, TUpsert extends PromiseLike<unknown>> = {
+    rows: readonly TRow[];
+    removeAll: () => TDelete;
+    removeMissing: (keepIds: readonly string[]) => TDelete;
+    upsert: (row: TRow & {
+        id: string;
+    }) => TUpsert;
+    readIds: () => Promise<ReadonlyArray<{
+        id: string;
+    }>>;
+};
+export declare function replaceChildRows<TRow extends {
+    id?: string;
+}, TDelete extends PromiseLike<unknown>, TUpsert extends PromiseLike<unknown>>(db: BatchDb, spec: ReplaceChildRowsSpec<TRow, TDelete, TUpsert>): Promise<ReplaceChildRowsResult>;
+export {};

package/dist/replace-rows.js

@@ -0,0 +1,51 @@
+// Replacing a parent's child rows is where generated apps drop data. The failure
+// that shows up once a parent already has children: insert the new rows, then
+// delete every id that was not in a keep-list built only from rows that already
+// had ids. The insert's id was never on that list, so the same batch deletes it.
+//
+// The neon-http batch method is generic over a one-or-more tuple. Putting that
+// tuple on this parameter makes a real `db` fail to assign, which pushes the
+// cast out to every call site. A function that accepts a specific tuple is
+// assignable to one that accepts `never`, so the cast stays here.
+const childRowsMismatchMessage = 'Save did not keep every row';
+function rowId(row) {
+    if (typeof row.id === 'string' && row.id !== '') {
+        return row;
+    }
+    return { ...row, id: crypto.randomUUID() };
+}
+function sameIds(expected, actual) {
+    const want = new Set(expected);
+    const got = new Set(actual);
+    if (want.size !== got.size)
+        return false;
+    for (const id of want) {
+        if (!got.has(id))
+            return false;
+    }
+    return true;
+}
+async function runStatements(db, statements) {
+    const [first, ...rest] = statements;
+    // One statement is the empty-payload delete. neon-http batch wants two or more.
+    if (rest.length === 0) {
+        await first;
+        return;
+    }
+    const batch = db.batch;
+    await batch([first, ...rest]);
+}
+export async function replaceChildRows(db, spec) {
+    // Ids exist before the delete is built, so a row added in this save is on the keep-list.
+    const written = spec.rows.map(rowId);
+    const statements = written.length === 0
+        ? [spec.removeAll()]
+        : [spec.removeMissing(written.map((row) => row.id)), ...written.map((row) => spec.upsert(row))];
+    await runStatements(db, statements);
+    const found = await spec.readIds();
+    const ids = written.map((row) => row.id);
+    if (!sameIds(ids, found.map((row) => row.id))) {
+        return { ok: false, message: childRowsMismatchMessage };
+    }
+    return { ok: true, ids };
+}

package/dist/resource-resolution.d.ts

@@ -86,4 +86,5 @@ export declare class TtlCache<V> {
     constructor(maxEntries: number);
     get(key: string): V | undefined;
     set(key: string, value: V, ttlMs: number): void;
+    delete(key: string): void;
 }

package/dist/resource-resolution.js

@@ -139,4 +139,7 @@ export class TtlCache {
         }
         this.entries.set(key, { value, expiresAt: Date.now() + ttlMs });
     }
+    delete(key) {
+        this.entries.delete(key);
+    }
 }

package/dist/server.d.ts

@@ -3,6 +3,7 @@ export * from './assembly.js';
 export * from './auth.js';
 export * from './client-access.js';
 export * from './mint-bearer.js';
+export * from './verify-bearer.js';
 export * from './nango.js';
 export * from './airtable.js';
 export * from './gmail.js';
@@ -10,6 +11,7 @@ export * from './app-storage.js';
 export * from './labels.js';
 export * from './notifications.js';
 export * from './cron.js';
+export * from './replace-rows.js';
 export * from './api-errors.js';
 export * from './params.js';
 export * from './client.js';

package/dist/server.js

@@ -7,6 +7,7 @@ export * from './assembly.js';
 export * from './auth.js';
 export * from './client-access.js';
 export * from './mint-bearer.js';
+export * from './verify-bearer.js';
 export * from './nango.js';
 export * from './airtable.js';
 export * from './gmail.js';
@@ -14,6 +15,7 @@ export * from './app-storage.js';
 export * from './labels.js';
 export * from './notifications.js';
 export * from './cron.js';
+export * from './replace-rows.js';
 // Returns NextResponse, so route handlers only — but nothing here reads a
 // secret, which is why a client file may still `import type` from them.
 export * from './api-errors.js';

package/dist/session-exchange.js

@@ -1,15 +1,13 @@
 // Stateless bearer helpers for the token-exchange flow (AI-260).
 // The proxy exchanges the session token once and sets the returned bearer as an
 // HttpOnly cookie. That bearer is a signed JWT carrying the caller's identity as
-// claims, so requireAuth()/getAssemblyForRequest() resolve identity by DECODING
-// the cookie — no server-side cache. A cache can't work here anyway: on Vercel
-// the middleware that would populate it and the route handlers that read it run
-// in separate runtimes/instances and never share memory.
+// claims. decodeBearer reads those claims without any network call, so it serves
+// as a cheap precheck (shape, expiry, workspace claim); identity itself comes
+// from verifyBearer, which asks the platform. Each runtime instance verifies a
+// given bearer once per cache window, because on Vercel the middleware and the
+// route handlers run in separate instances that never share memory.
 //
-// decodeBearer does NOT verify the signature. The platform-api authorizer
-// re-validates the token's signature and scope on every real API call, which is
-// the security boundary; these decoded claims are advisory to the app (SDK init,
-// early authz rejects) and never the sole gate.
+// decodeBearer is a no-network shape and expiry precheck.
 export const BEARER_COOKIE_NAME = 'x-assembly-bearer';
 export const BEARER_TTL_MS = 60 * 60 * 1_000; // 60 minutes, matches bearer TTL
 // The only statuses that prove the session token ITSELF is spent or invalid:
@@ -176,11 +174,10 @@ function decodeBase64UrlJson(segment) {
     const bytes = Uint8Array.from(binary, (ch) => ch.charCodeAt(0));
     return JSON.parse(new TextDecoder().decode(bytes));
 }
-// Decodes the identity claims from a bearer JWT. Signature is NOT verified here
-// (the platform-api authorizer re-validates it on every real call — the true
-// boundary); these claims are advisory for SDK init and early authz. Returns
-// null when the token is malformed, expired, or carries no workspace — callers
-// then return 401 / re-exchange.
+// Reads the bearer's claims locally (shape and expiry precheck only). Identity
+// for authorization comes from verifyBearer. Returns null when the token is
+// malformed, expired, or carries no workspace — callers then return 401 /
+// re-exchange.
 export function decodeBearer(bearer) {
     const parts = bearer.split('.');
     if (parts.length !== 3)

package/dist/verify-bearer.d.ts

@@ -0,0 +1,29 @@
+export interface VerifiedIdentity {
+    workspaceId: string;
+    clientId?: string;
+    companyId?: string;
+    internalUserId?: string;
+    notificationId?: string;
+    instanceId?: string;
+    sessionId?: string;
+    callerAppId?: string;
+    installerUserId?: string;
+    tokenKind?: string;
+    /** Epoch SECONDS at which the verified bearer expires. */
+    expiresAt: number;
+}
+export type VerifyResult = {
+    ok: true;
+    identity: VerifiedIdentity;
+} | {
+    ok: false;
+    reason: 'rejected' | 'unavailable';
+};
+export declare const VERIFY_PATH = "/v1/session/verify";
+export declare const VIEWER_BEARER_HEADER = "X-Assembly-Viewer-Bearer";
+export declare const VERIFY_OUTCOME_EVENT = "assembly.verify_outcome";
+/**
+ * Resolves a viewer bearer to the identity the platform vouches for. Identity
+ * must come from here, never from the bearer's decoded claims.
+ */
+export declare function verifyBearer(bearer: string): Promise<VerifyResult>;

package/dist/verify-bearer.js

@@ -0,0 +1,170 @@
+import { OpenAPI } from '@assembly-js/node-sdk';
+import { TtlCache } from './resource-resolution.js';
+import { decodeBearer } from './session-exchange.js';
+export const VERIFY_PATH = '/v1/session/verify';
+export const VIEWER_BEARER_HEADER = 'X-Assembly-Viewer-Bearer';
+export const VERIFY_OUTCOME_EVENT = 'assembly.verify_outcome';
+// A verify sits on every authenticated request's critical path, so it gets far
+// less rope than the exchange.
+const VERIFY_TIMEOUT_MS = 2_000;
+// Bounds how long a verdict can outlive a revocation on this instance.
+const POSITIVE_TTL_MS = 60_000;
+// Short enough that a bearer rejected during a transient state recovers quickly,
+// long enough to absorb a burst of requests carrying the same bad bearer.
+const REJECTED_TTL_MS = 10_000;
+const STALE_GRACE_MS = 5 * 60_000;
+// Separate bounds so rejected entries can never evict positive ones.
+const MAX_POSITIVE_ENTRIES = 1_000;
+const MAX_REJECTED_ENTRIES = 1_000;
+// The only 401 codes that prove the bearer itself is refused; any other 401
+// (a gateway or authorizer response) says nothing about it.
+const REJECTION_CODES = new Set(['invalid_token', 'token_expired']);
+// One cache per runtime instance: instances never share memory, so each
+// verifies a given bearer once per TTL.
+const positiveCache = new TtlCache(MAX_POSITIVE_ENTRIES);
+const rejectedCache = new TtlCache(MAX_REJECTED_ENTRIES);
+// The last verdict the platform gave, kept for a short grace period (never past
+// the bearer's own expiry). Only consulted when the platform cannot be reached,
+// so a blip does not take down viewers it had just vouched for; an explicit
+// rejection evicts it. Bounded tightly because during an outage a revocation
+// cannot be seen.
+const lastGoodCache = new TtlCache(MAX_POSITIVE_ENTRIES);
+const inFlight = new Map();
+// Raw bearers are never held in memory beyond the call; the digest is the key.
+async function hashBearer(bearer) {
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(bearer));
+    return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, '0')).join('');
+}
+function optionalString(value) {
+    return typeof value === 'string' && value !== '' ? value : undefined;
+}
+function parseIdentity(body) {
+    if (!body || typeof body !== 'object')
+        return null;
+    const b = body;
+    const workspaceId = optionalString(b.workspaceId);
+    if (!workspaceId)
+        return null;
+    if (typeof b.expiresAt !== 'number' || !Number.isFinite(b.expiresAt)) {
+        return null;
+    }
+    return {
+        workspaceId,
+        clientId: optionalString(b.clientId),
+        companyId: optionalString(b.companyId),
+        internalUserId: optionalString(b.internalUserId),
+        notificationId: optionalString(b.notificationId),
+        instanceId: optionalString(b.instanceId),
+        sessionId: optionalString(b.sessionId),
+        callerAppId: optionalString(b.callerAppId),
+        installerUserId: optionalString(b.installerUserId),
+        tokenKind: optionalString(b.tokenKind),
+        expiresAt: b.expiresAt,
+    };
+}
+function logOutcome(outcome, startedAt) {
+    console.log(JSON.stringify({
+        event_type: VERIFY_OUTCOME_EVENT,
+        outcome,
+        duration_ms: Date.now() - startedAt,
+    }));
+}
+// Callers get a copy so a mutation can never reach the cached identity.
+function frozenOk(identity) {
+    return { ok: true, identity: Object.freeze({ ...identity }) };
+}
+async function fetchVerdict(bearer) {
+    const apiKey = process.env.ASSEMBLY_API_KEY;
+    if (!apiKey)
+        return { ok: false, reason: 'unavailable' };
+    const base = (process.env.ASSEMBLY_API_BASE_URL || OpenAPI.BASE).replace(/\/$/, '');
+    const headers = {
+        'X-API-Key': apiKey,
+        [VIEWER_BEARER_HEADER]: bearer,
+    };
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), VERIFY_TIMEOUT_MS);
+    try {
+        const resp = await fetch(`${base}${VERIFY_PATH}`, {
+            headers,
+            signal: controller.signal,
+        });
+        if (resp.status === 200) {
+            const identity = parseIdentity(await resp.json());
+            return identity
+                ? { ok: true, identity }
+                : { ok: false, reason: 'unavailable' };
+        }
+        if (resp.status === 401) {
+            const body = (await resp.json());
+            if (typeof body?.code === 'string' && REJECTION_CODES.has(body.code)) {
+                return { ok: false, reason: 'rejected' };
+            }
+        }
+        return { ok: false, reason: 'unavailable' };
+    }
+    catch {
+        // Network failure, timeout, or a non-JSON body (gateway HTML).
+        return { ok: false, reason: 'unavailable' };
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+async function verifyUncached(bearer, key, startedAt) {
+    const result = await fetchVerdict(bearer);
+    if (result.ok) {
+        // Never outlive the bearer itself.
+        const ttl = Math.min(POSITIVE_TTL_MS, result.identity.expiresAt * 1_000 - Date.now());
+        positiveCache.set(key, result.identity, ttl);
+        lastGoodCache.set(key, result.identity, Math.min(STALE_GRACE_MS, result.identity.expiresAt * 1_000 - Date.now()));
+        logOutcome('miss', startedAt);
+        return frozenOk(result.identity);
+    }
+    if (result.reason === 'rejected') {
+        rejectedCache.set(key, true, REJECTED_TTL_MS);
+        lastGoodCache.delete(key);
+    }
+    else {
+        const lastGood = lastGoodCache.get(key);
+        if (lastGood) {
+            logOutcome('stale', startedAt);
+            return frozenOk(lastGood);
+        }
+    }
+    logOutcome(result.reason, startedAt);
+    return result;
+}
+/**
+ * Resolves a viewer bearer to the identity the platform vouches for. Identity
+ * must come from here, never from the bearer's decoded claims.
+ */
+export async function verifyBearer(bearer) {
+    const startedAt = Date.now();
+    // The decode is a no-network precheck: shape, expiry and workspace claim.
+    if (!decodeBearer(bearer)) {
+        logOutcome('rejected', startedAt);
+        return { ok: false, reason: 'rejected' };
+    }
+    const key = await hashBearer(bearer);
+    const cached = positiveCache.get(key);
+    if (cached && cached.expiresAt * 1_000 > Date.now()) {
+        logOutcome('hit', startedAt);
+        return frozenOk(cached);
+    }
+    if (rejectedCache.get(key)) {
+        logOutcome('rejected', startedAt);
+        return { ok: false, reason: 'rejected' };
+    }
+    // Concurrent requests carrying one bearer share a single platform call.
+    const pending = inFlight.get(key);
+    if (pending) {
+        const shared = await pending;
+        return shared.ok ? frozenOk(shared.identity) : shared;
+    }
+    const request = verifyUncached(bearer, key, startedAt).finally(() => {
+        inFlight.delete(key);
+    });
+    inFlight.set(key, request);
+    return request;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.0.35",
+  "version": "0.0.37-rc.0",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [
@@ -30,7 +30,7 @@
   },
   "scripts": {
     "build": "tsc && tsc-alias",
-    "test": "bun test",
+    "test": "bun test && tsc -p tsconfig.replace-rows.json",
     "prepublishOnly": "npm run build && npm run verify:dist && npm run verify:bin",
     "verify:dist": "node scripts/verify-dist-resolves.mjs",
     "verify:bin": "node scripts/verify-bin.mjs"
@@ -44,8 +44,10 @@
   "devDependencies": {
     "@assembly-js/app-bridge": "1.3.0",
     "@assembly-js/node-sdk": "4.2.4",
+    "@neondatabase/serverless": "^1.1.0",
     "@types/bun": "^1.1.0",
     "@types/node": "^22",
+    "drizzle-orm": "^0.45.2",
     "next": "^15.5.0",
     "server-only": "^0.0.1",
     "tsc-alias": "^1.9.1",

package/skills/assembly-automations/SKILL.md

@@ -256,7 +256,7 @@ Every event also lands in the workspace's audit log, where a workspace admin rea
 
 | Header | Value |
 |---|---|
-| `X-Assembly-Actor-Id` | the viewer's id from `requireAuth` — `internalUserId`, else `clientId` |
+| `X-Assembly-Actor-Id` | the viewer's id from `requireAuth` (the platform-verified identity) — `internalUserId`, else `clientId` |
 | `X-Assembly-Source` | `web` when a person did this in the app's UI |
 | `X-Assembly-Client-IP` | the request's `x-forwarded-for` |
 | `X-Assembly-User-Agent` | the request's `user-agent` |

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

@@ -14,7 +14,7 @@ const identity = await getSessionIdentity();
 // → { workspaceId, clientId?, companyId?, internalUserId? } | null
 ```
 
-Read identity with `getSessionIdentity()` (server) or `useAssembly()` (client) — see `assembly-session-token`. Never call `assembly.getTokenPayload()` in app code.
+Read identity with `getSessionIdentity()` (server) or `useAssembly()` (client) — see `assembly-session-token`. Never call `assembly.getTokenPayload()` in app code. The identity is the one the platform verified for the bearer, so `clientId` and `companyId` can be trusted for scoping; if verification is unavailable, `getSessionIdentity()` throws `AuthUnavailableError` — render a retry state rather than treating the viewer as signed out.
 
 **A client viewer always carries both ids.** `identity.clientId` is who they are; `identity.companyId` is the company they currently have active in the portal switcher. The platform guarantees the active company is populated for a client session, so **treat a client viewer with no `companyId` as an error, not as a case to fall back on** — do not widen the query to the client's other companies, and do not substitute `companyIds[0]`.
 

package/skills/assembly-notifications/SKILL.md

@@ -334,6 +334,24 @@ await markSubmissionNotified(submission.id);
 
 Option 2 is cheaper (no list call) and more reliable. Pick option 1 when you don't control the trigger schema.
 
+### Recurring conditions
+
+A cron that scans for a condition still being true — unassigned for a day, overdue, no reply — selects the same rows on every tick. `createNotification` does not remember a previous send, so each tick creates another copy for every recipient. `sendThrottled` only spaces that flood out; it does not stop it.
+
+Record the alert on the subject, in the app's own table, before sending. Key it by the subject and the condition (one thread, one kind), not by the recipient. Skip the send when that marker is set. Clear the marker when the condition ends (the thread is assigned, a reply arrives) so a later recurrence can alert again.
+
+```ts
+// Unique on (threadId, kind). Write the marker first so a tick that dies
+// mid-send skips the rest next time instead of notifying everyone again.
+if (await alreadyAlerted(thread.id, 'stale-unassigned')) continue;
+await markAlerted(thread.id, 'stale-unassigned');
+await sendThrottled(recipients, (u) =>
+  assembly.createNotification({ requestBody: { recipientInternalUserId: u.id, /* ... */ } }),
+);
+```
+
+Do not use `listNotifications` to decide. A sweep will not page the whole center, and a notification the recipient already read still has to count.
+
 ## Clearing the client portal badge
 
 Because clients see a badge counter rather than a Notification Center, every `createNotification({ recipientClientId })` is only half the job — the app must `markNotificationRead` at the right moment or the badge sticks forever. Leaving it unhandled is the most common bug in client-facing apps. There are two patterns:
@@ -443,6 +461,7 @@ Each client gets their own badge and clears it independently. `recipientCompanyI
 ## What NOT to do
 
 - Do not `Promise.all` a recipient-list fan-out. Writes cap at 5 concurrent; firing a whole list at once 429s and drops notifications. Use `sendThrottled` (see "Throttling fan-outs"). A fixed handful of calls is the only exception.
+- Do not re-send a cron alert because the same condition is still true. Record it on the subject before the send and clear that record when the condition ends (see "Recurring conditions").
 - Do not use `recipientId` — deprecated. Use `recipientClientId` or `recipientInternalUserId`.
 - Do not pass `recipientCompanyId` alone as a recipient. The API rejects it. To notify a company, fan out across its clients (see "Notifying a company").
 - Do not omit the company id when a multi-company client is involved. Notifying a multi-company client needs `recipientCompanyId` (`400 "company ID is required when notifying a client"`); a multi-company client *sending* to an internal user needs `senderCompanyId` (`400 "sender company ID is invalid based on sender"`). Single-company members are auto-inferred. See "Company scoping, by recipient type."

package/skills/assembly-record-writes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: assembly-record-writes
-description: REQUIRED when a form creates a persisted record that a later save or update also writes, especially when the payload includes nested rows (packages, add-ons, line items, blocks, children). Create and save must call one writer so create cannot drop fields the form submitted. A success toast after create does not mean those rows were stored.
+description: REQUIRED when a form creates a persisted record that a later save or update also writes, or when a save replaces nested rows (packages, add-ons, line items, blocks, children). Create and save must call one writer so create cannot drop fields the form submitted. Replacing those rows deletes missing ids before the upsert and reads them back before success. A success toast does not mean the rows were stored.
 ---
 
 A create form often submits the same payload a later edit form saves: parent columns plus nested collections. If create inserts only the parent (and maybe one child table and an audit event) while save writes the rest, the first submit looks successful and the editor opens empty. The redirect after create does not call save.
@@ -9,31 +9,66 @@ A create form often submits the same payload a later edit form saves: parent col
 
 One function writes the submitted payload. Create calls it for a new id; save calls it for an existing id.
 
+Leave these off the shared payload. They belong to the path that owns them:
+
+- ids, timestamps, a draft status, an audit-event row
+- a control flag that chooses an action (for example "send immediately") and is not itself stored, unless save stores that same flag
+- fields that appear only on a later edit form
+
+If the form submits it, the create call chain writes it, including by calling the shared writer.
+
+## Replacing child rows
+
+Import `replaceChildRows` from `@assembly-js/app-foundation/server`. Do not reimplement it. Inserting new rows and then deleting every id missing from a keep-list of only the rows that already had ids deletes the rows just inserted. That only shows up once the parent already has children, so the first save looks fine.
+
+When the user adds a row, assign `crypto.randomUUID()` on the client before submit. The helper also assigns any id that arrives empty, before it builds the delete, so a missing id cannot fall off the keep-list.
+
+Call the helper only for a collection the form submitted (`input.packages !== undefined`). An omitted collection stays as it is. An empty array means the user cleared that collection: every child of that parent is deleted. The helper uses a delete-all for that case and does not emit `id NOT IN ()`.
+
+Upsert the parent by id first. A save does not delete and recreate the parent. Then one `replaceChildRows` per submitted collection. The helper deletes missing ids before the upserts, in one `db.batch` when there is more than one statement. Do not use `db.transaction` (see `assembly-db-transactions`). On conflict, update a child only when it already belongs to this parent, so a submitted id from another record cannot change that record.
+
+If the result is `{ ok: false, message }`, return that from the server action. The message is `Save did not keep every row`. Do not toast success. The check compares ids only.
+
 ```ts
+import { replaceChildRows } from '@assembly-js/app-foundation/server';
+import { and, eq, notInArray } from 'drizzle-orm';
+import { db } from '@/lib/db';
+import { packages, proposals } from '@/lib/schema';
+
 async function writeProposal(id: string, input: ProposalInput) {
   await db.insert(proposals).values({ id, title: input.title, intro: input.intro })
     .onConflictDoUpdate({ target: proposals.id, set: { title: input.title, intro: input.intro } });
-  await replaceRows(packages, id, input.packages);
-  await replaceRows(addOns, id, input.addOns);
-  await replaceRows(blocks, id, input.blocks);
+
+  if (input.packages !== undefined) {
+    const replaced = await replaceChildRows(db, {
+      rows: input.packages,
+      removeAll: () => db.delete(packages).where(eq(packages.proposalId, id)),
+      removeMissing: (keepIds) =>
+        db.delete(packages).where(and(eq(packages.proposalId, id), notInArray(packages.id, [...keepIds]))),
+      upsert: (row) =>
+        db.insert(packages).values({ id: row.id, proposalId: id, name: row.name })
+          .onConflictDoUpdate({
+            target: packages.id,
+            set: { name: row.name },
+            where: eq(packages.proposalId, id),
+          }),
+      readIds: () => db.select({ id: packages.id }).from(packages).where(eq(packages.proposalId, id)),
+    });
+    if (!replaced.ok) return replaced;
+  }
 }
 
 export async function createProposal(input: ProposalInput) {
   const id = crypto.randomUUID();
-  await writeProposal(id, input);
+  const written = await writeProposal(id, input);
+  if (written) return written;
   await recordEvent(id, 'draft_created');
-  return id;
+  return { ok: true, id };
 }
 
 export async function saveProposal(id: string, input: ProposalInput) {
-  await writeProposal(id, input);
+  const written = await writeProposal(id, input);
+  if (written) return written;
+  return { ok: true };
 }
 ```
-
-Leave these off the shared payload. They belong to the path that owns them:
-
-- ids, timestamps, a draft status, an audit-event row
-- a control flag that chooses an action (for example "send immediately") and is not itself stored, unless save stores that same flag
-- fields that appear only on a later edit form
-
-If the form submits it, the create call chain writes it, including by calling the shared writer.

package/skills/assembly-route-auth/SKILL.md

@@ -13,7 +13,7 @@ import { requireAuth, requireCompanyScope, handleRouteError } from '@assembly-js
 
 ## How the helpers work
 
-**`requireAuth(req)`** decodes the viewer's identity from the bearer (read from the request cookie — no `x-assembly-token` header) and returns it. Returns a 401 `NextResponse` (with a `{ code: 'token_expired' }` body and an `x-assembly-token-expired: 1` header) when the bearer is missing or expired — `authFetch` detects this and re-exchanges + retries automatically.
+**`requireAuth(req)`** verifies the bearer (read from the request cookie — no `x-assembly-token` header) with the platform and returns the identity from the platform's verification response. Returns a 401 `NextResponse` (with a `{ code: 'token_expired' }` body and an `x-assembly-token-expired: 1` header) when the bearer is missing, expired or not accepted — `authFetch` detects this and re-exchanges + retries automatically. When the platform cannot be reached to verify, it returns a 503 with `{ code: 'auth_unavailable' }` and no expiry marker: return it as is. The 503 reaches the app, which should render a retry state or let the user retry; it never triggers a re-exchange.
 
 **`requireCompanyScope(identity, resource, assembly?)`** asserts the viewer can access a resource scoped to a company **or to a client**:
 

package/skills/assembly-scheduled-work/SKILL.md

@@ -144,6 +144,7 @@ Rules that fall out of this:
 
 - **`cronRoute` is not optional.** The route is a public URL; without the wrapper anyone who guesses it can trigger the app's scheduled work under the app's own credentials. Never hand-roll the header check.
 - **Use `getOfflineAssembly()`** for every platform call — there is no viewer and no cookie. `getSessionIdentity()` is `null` here, so a notification's `senderId` must be chosen explicitly (a system/admin internal user); see `assembly-notifications`.
+- **A scan that notifies must remember what it already sent.** Selecting every row that still matches (unassigned, overdue, unanswered) and calling `createNotification` notifies that same set again on the next tick. Record the alert on the subject before the send and clear it when the condition ends. See `assembly-notifications` ("Recurring conditions").
 - **A missed tick is harmless.** Vercel does not retry, but the row stays due until it is marked, so the next tick picks it up. Never mark a row done before its work succeeded.
 - **A stuck row frees itself.** If Vercel stops the function mid-run, the catch never runs and the row stays `running`; the stale-claim clause lets the next tick reclaim it after 15 minutes. Keep `claimedAt` and that clause — without them one hang parks a row forever.
 - **Never compute the next run by adding minutes to `now`.** Use `nextRunAfter`: it anchors to the scheduled time, skips missed occurrences, and keeps daily cadences on their local wall-clock time across daylight-saving changes.
@@ -174,4 +175,5 @@ Insert a row with `nextRunAt` in the past, run that, and confirm the side effect
 - ❌ Don't skip `cronRoute` or compare the header yourself.
 - ❌ Don't type, invent, or default `CRON_SECRET`. Declare it; the platform mints it.
 - ❌ Don't call `getAssembly()` in the dispatcher. There is no viewer; use `getOfflineAssembly()`.
+- ❌ Don't notify from a sweep without a per-subject marker. The next tick selects the same rows and sends again.
 - ❌ Don't replace `vercel.json`. Add `crons` to it.

package/skills/assembly-session-token/SKILL.md

@@ -11,7 +11,7 @@ Your job is to follow three rules.
 
 Never decode a token yourself and never call `AssemblyBridge.sessionToken.*` — that API is the foundation's, not yours.
 
-Server-side, `getSessionIdentity()` decodes the viewer from the bearer (no token, no API call). It returns `null` when unauthenticated:
+Server-side, `getSessionIdentity()` returns the viewer the platform verified for the bearer (no token to pass; the check is cached briefly per server instance). It returns `null` when unauthenticated, and throws `AuthUnavailableError` when the platform could not be reached to verify — that is not an expiry, so don't catch it into `null`, don't re-exchange on it, and render a retry state ("Couldn't load, try again" with a retry button) where a server component reads identity:
 
 ```ts
 import { getSessionIdentity } from '@assembly-js/app-foundation/server';