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

package/CLAUDE.md

@@ -254,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()` returns the viewer the platform verified for it. 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()` decodes the viewer. See "How auth works". |
 
 ---
 
@@ -647,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. 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.
+`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.
 
 #### Identity — who is the viewer?
 
-Server-side, `getSessionIdentity()` returns the viewer the platform verified for the bearer (no token to pass; the check is cached briefly per server instance):
+Server-side, `getSessionIdentity()` returns the viewer decoded from the bearer (no token, no API call):
 
 ```ts
 import { getSessionIdentity } from '@assembly-js/app-foundation/server';
@@ -714,9 +714,25 @@ For an imperative one-off (button handler, mutation), use `callAction` from `use
 - **Actions take no token.** Never accept, read, or pass a token — `getAssembly()` resolves the bearer itself. Never touch `AssemblyBridge.sessionToken.*` in a component or copy anything into your own `useState`/`useRef`.
 - **Data actions must let `TokenInvalidError` propagate** — never `try/catch` it into `null`/empty. The auto-retry only fires if the action surfaces the expiry. And never hand-roll refresh/retry; `useServerAction`/`callAction` already do it.
 
+#### Server action or route handler?
+
+A client-to-server call is a server action by default. Its argument is a TypeScript parameter, so a payload that does not match the signature fails `tsc` in your inner loop. A route handler's body is an untyped wire contract — `JSON.stringify` on one side, `request.json()` on the other — and nothing checks that the two agree until a user sends the first request, which you cannot do from the sandbox. A mismatch `tsc` would catch in an action ships silently through a route and 400s for every user.
+
+Write a route handler only when the caller needs a raw `Response` — streamed bytes, a file download, a webhook or cron entry point — or when the caller is not this app's own client component. When you do, define the body schema in a shared `lib/` module with no server-only imports, and type the client's payload with `z.input<typeof schema>` so the compiler checks the wire shape:
+
+```ts
+// lib/reply-contract.ts — imported by both the route and the component (`bun add zod` if it is not installed yet)
+import { z } from 'zod';
+export const replyBody = z.object({ parentId: z.string().uuid().nullish(), text: z.string().min(1) });
+export type ReplyBody = z.input<typeof replyBody>;
+
+// app/api/replies/route.ts: const parsed = replyBody.safeParse(await request.json());
+// component:               const body: ReplyBody = { parentId, text }; // tsc rejects what the route would 400
+```
+
 #### Client → server via route handlers — `authFetch`
 
-For mutations and route-handler calls from client components, use `authFetch` from `app/components/lib-client.ts`. The bearer rides the cookie automatically; `authFetch` adds the required CSRF header and re-exchanges + retries once on a bearer expiry:
+For the route-handler calls that remain, use `authFetch` from `app/components/lib-client.ts`. The bearer rides the cookie automatically; `authFetch` adds the required CSRF header and re-exchanges + retries once on a bearer expiry:
 
 ```tsx
 'use client';
@@ -800,7 +816,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)`** 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.
+**`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.
 
 **`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`.
 
@@ -870,7 +886,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()` returns the platform-verified viewer; no token to pass):
+Server-side (`getSessionIdentity()` decodes the bearer; no API call):
 
 ```ts
 import { getSessionIdentity } from '@assembly-js/app-foundation/server';
@@ -1160,7 +1176,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 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).
+- ❌ 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).
 <!-- !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.
@@ -1181,7 +1197,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 re-notify a still-true condition from a cron. Mark a recipient sent only after `createNotification` succeeds, and clear that record when the condition ends unless the alert is once per billing period; keep those successful outcomes until the period resets, even if usage dips below the threshold. 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/dist/api-errors.js

@@ -1,5 +1,4 @@
 import { NextResponse } from 'next/server';
-import { AuthUnavailableError, authUnavailableResponse } from './assembly.js';
 export function badRequest(message) {
     return NextResponse.json({ error: message }, { status: 400 });
 }
@@ -27,10 +26,6 @@ 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,17 +19,6 @@ 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-
@@ -59,8 +48,6 @@ 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,55 +3,33 @@ 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 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() {
+// 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() {
     try {
         const fromProxy = (await headers()).get(BEARER_HEADER_NAME);
+        if (fromProxy && decodeBearer(fromProxy))
+            return fromProxy;
         const fromCookie = (await cookies()).get(BEARER_COOKIE_NAME)?.value;
-        return [fromProxy, fromCookie].filter((b) => Boolean(b));
+        if (fromCookie && decodeBearer(fromCookie))
+            return fromCookie;
     }
     catch {
-        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;
     }
     return undefined;
 }
-// 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.
+// 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).
 async function resolveRequestBearer() {
     if (!isSessionExchangeEnabled())
         return undefined;
@@ -86,22 +64,15 @@ async function hasViewerRequest() {
         return false;
     }
 }
-// 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.
+// 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).
 export async function getSessionIdentity() {
-    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 };
+    const bearer = await resolveRequestBearer();
+    return bearer ? decodeBearer(bearer) : null;
 }
 /**
  * Thrown when a session token is required but missing, or was supplied but
@@ -120,20 +91,6 @@ 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
@@ -147,25 +104,31 @@ 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()) {
-        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 bearer = token ?? (await resolveRequestBearer());
+        if (!bearer) {
+            throw new TokenInvalidError('Assembly bearer is required');
         }
-        else {
-            viewer = await resolveRequestViewer();
+        const assembly = await assemblyApi({ bearer, baseUrl: trustedBaseUrl });
+        const payload = await assembly.getTokenPayload?.();
+        if (!payload?.workspaceId) {
+            throw new TokenInvalidError();
         }
-        if (!viewer) {
-            throw new TokenInvalidError(token ? undefined : 'Assembly bearer is required');
+        // 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);
         }
-        return getBearerAssembly(viewer.bearer, viewer.identity);
+        return assembly;
     }
     // 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
@@ -235,35 +198,13 @@ 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. 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;
+// 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 });
 }
 /**
  * OFFLINE / BACKGROUND ONLY — cron jobs, webhook handlers, and any other code
@@ -309,30 +250,23 @@ export async function getOfflineAssembly() {
 }
 // Returns a request-scoped SDK client authenticated for the current user.
 //
-// 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 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 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. 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.
+        // 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.
         const bearer = req.headers.get(BEARER_HEADER_NAME) ??
             req.cookies.get(BEARER_COOKIE_NAME)?.value;
-        if (!bearer) {
+        if (!bearer || !decodeBearer(bearer)) {
             return tokenExpiredResponse();
         }
-        const result = await verifyBearer(bearer);
-        if (!result.ok) {
-            return result.reason === 'rejected'
-                ? tokenExpiredResponse()
-                : authUnavailableResponse();
-        }
-        return getBearerAssembly(bearer, result.identity);
+        return getBearerAssembly(bearer);
     }
     // Legacy (exchange disabled): authenticate from the session-token header,
     // sent as X-API-Key. Missing token ⇒ 401 marker.

package/dist/auth.js

@@ -1,7 +1,6 @@
 import { NextResponse } from 'next/server';
-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';
+import { getAssembly } from './assembly.js';
+import { BEARER_COOKIE_NAME, BEARER_HEADER_NAME, decodeBearer, isSessionExchangeEnabled, TOKEN_EXPIRED_HEADER, } from './session-exchange.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.
@@ -15,35 +14,26 @@ 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 — 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 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 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;
-        if (!bearer) {
+        const session = bearer ? decodeBearer(bearer) : null;
+        if (!session) {
             return tokenExpiredResponse();
         }
-        const result = await verifyBearer(bearer);
-        if (!result.ok) {
-            return result.reason === 'rejected'
-                ? tokenExpiredResponse()
-                : authUnavailableResponse();
-        }
-        const { identity } = result;
         return {
-            workspaceId: identity.workspaceId,
-            clientId: identity.clientId,
-            internalUserId: identity.internalUserId,
-            companyId: identity.companyId,
-            notificationId: identity.notificationId,
-            instanceId: identity.instanceId,
+            workspaceId: session.workspaceId,
+            clientId: session.clientId,
+            internalUserId: session.internalUserId,
+            companyId: session.companyId,
+            notificationId: session.notificationId,
+            instanceId: session.instanceId,
         };
     }
     const token = req.headers.get('x-assembly-token');

package/dist/replace-rows.js

@@ -33,7 +33,8 @@ async function runStatements(db, statements) {
         return;
     }
     const batch = db.batch;
-    await batch([first, ...rest]);
+    // drizzle's batch reads this.session, so it must be invoked on db, never as a bare function.
+    await batch.call(db, [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.

package/dist/resource-resolution.d.ts

@@ -86,5 +86,4 @@ 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,7 +139,4 @@ export class TtlCache {
         }
         this.entries.set(key, { value, expiresAt: Date.now() + ttlMs });
     }
-    delete(key) {
-        this.entries.delete(key);
-    }
 }

package/dist/server.d.ts

@@ -3,7 +3,6 @@ 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';

package/dist/server.js

@@ -7,7 +7,6 @@ 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';

package/dist/session-exchange.js

@@ -1,13 +1,15 @@
 // 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. 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.
+// 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.
 //
-// decodeBearer is a no-network shape and expiry precheck.
+// 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.
 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:
@@ -174,10 +176,11 @@ function decodeBase64UrlJson(segment) {
     const bytes = Uint8Array.from(binary, (ch) => ch.charCodeAt(0));
     return JSON.parse(new TextDecoder().decode(bytes));
 }
-// 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.
+// 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.
 export function decodeBearer(bearer) {
     const parts = bearer.split('.');
     if (parts.length !== 3)

package/package.json

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

package/skills/assembly-ai/SKILL.md

@@ -37,25 +37,26 @@ export async function chatCompletion(messages: Array<{ role: string; content: st
 
 ## Server-side only
 
-ALL AI calls MUST happen server-side (API routes, server components, server actions). Never call the AI proxy from client components.
+ALL AI calls MUST happen server-side (server actions, server components, route handlers). Never call the AI proxy from client components.
 
-Example Next.js API route:
+Expose an AI call to the client as a server action — its arguments are type-checked end to end, so a payload mismatch fails `tsc` instead of the user's first request. Reserve a route handler for the streaming case below, where the client needs the raw `Response`.
 
 ```typescript
-// app/api/ai/summarize/route.ts
-import { NextRequest, NextResponse } from 'next/server';
+// app/actions/summarize.ts
+'use server';
 import { chatCompletion } from '@/lib/ai';
 
-export async function POST(request: NextRequest) {
-  const { text } = await request.json();
+export async function summarize(text: string): Promise<string> {
   const response = await chatCompletion([
     { role: 'user', content: `Summarize the following:\n\n${text}` },
   ]);
   const data = await response.json();
-  return NextResponse.json({ summary: data.choices[0].message.content });
+  return data.choices[0].message.content;
 }
 ```
 
+From a client component: `const summary = await callAction(() => summarize(text), { idempotent: true });` — the call writes nothing, so it is safe to re-run after a bearer renewal.
+
 ## Vision (image inputs)
 
 The proxy supports OpenAI's vision API. Use `gpt-4o` with the multi-part content format to analyze images. The `content` field becomes an array of typed parts instead of a plain string:

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` (the platform-verified identity) — `internalUserId`, else `clientId` |
+| `X-Assembly-Actor-Id` | the viewer's id from `requireAuth` — `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. 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.
+Read identity with `getSessionIdentity()` (server) or `useAssembly()` (client) — see `assembly-session-token`. Never call `assembly.getTokenPayload()` in app code.
 
 **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

@@ -10,7 +10,9 @@ description: Use when the app must notify internal users or clients, or needs pe
 
 ## Mental model
 
-Send a notification when something happens that the recipient should know about and didn't cause themselves — action required (review, approve, respond) or awareness (status changes, completions, new messages). Skip routine reads, navigation, and trivial state changes. Under-send rather than over-send.
+Send a notification when something happens that the recipient should know about — action required (review, approve, respond) or awareness (status changes, completions, new messages). Skip routine reads, navigation, trivial state changes, and routine confirmations of the recipient's own actions.
+
+For a required condition alert (a retainer reaching 90%, going over its allowance, or a budget crossing its limit), the audience is everyone specified by the requirement who has access, including the user whose action crossed the threshold. A sole admin logging usage must still receive the staff alert. Choose recipients by access; use the actor as sender without automatically removing them from the audience.
 
 Every notification is three decisions: **audience** (internal users and/or clients), **channel** (in-product, email, or both), and **context on arrival** (what the recipient sees and can do). Get those right; the rest is mechanics.
 
@@ -338,17 +340,11 @@ Option 2 is cheaper (no list call) and more reliable. Pick option 1 when you don
 
 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.
+Track each condition occurrence in the app's own table, keyed by subject and condition (include the billing period for a recurring allowance). Resolve the eligible audience before claiming the occurrence: an empty audience creates no sent marker.
 
-```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, /* ... */ } }),
-);
-```
+A concurrency claim reserves work; it is not proof of delivery. Keep pending claims retryable after a failure or an expired lease, and mark a recipient sent only after their `createNotification` succeeds. On partial failure, retry the failed recipients and skip those already sent. If there is only one recipient, track that outcome on the occurrence itself. Clear the occurrence when the condition ends if recurrence should alert again. For once-per-period threshold alerts, keep successful outcomes through dips below the threshold and use a new occurrence when the period resets.
+
+A permanent marker written before fan-out can consume an alert without sending anything. Marking the whole occurrence sent after `sendThrottled` is also insufficient: it returns per-recipient outcomes, so check failures before declaring delivery complete.
 
 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.
 
@@ -461,7 +457,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 re-send a condition alert to recipients already notified for that occurrence. Keep failed sends retryable and track successful outcomes (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-route-auth/SKILL.md

@@ -13,7 +13,7 @@ import { requireAuth, requireCompanyScope, handleRouteError } from '@assembly-js
 
 ## How the helpers work
 
-**`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.
+**`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.
 
 **`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,7 +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 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. Mark a recipient sent only after `createNotification` succeeds, and clear that record when the condition ends unless the alert is once per billing period; keep those successful outcomes until the period resets, even if usage dips below the threshold. 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.

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()` 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:
+Server-side, `getSessionIdentity()` decodes the viewer from the bearer (no token, no API call). It returns `null` when unauthenticated:
 
 ```ts
 import { getSessionIdentity } from '@assembly-js/app-foundation/server';

package/dist/verify-bearer.d.ts

@@ -1,29 +0,0 @@
-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

@@ -1,170 +0,0 @@
-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;
-}