@k2b/cloud 0.29.1 → 0.31.0

package/src/contracts/app.ts

@@ -2,7 +2,7 @@ import type { Sync } from "@k2b/sync";
 import type { PlatformPermission } from "./outgoing-mail";
 import type { AppRegistryHelpSummary } from "./registry";
 import type { Role } from "./shared";
-import type { DashboardWidgetPresentation } from "./widgets";
+import type { DashboardWidgetPresentation, DashboardWidgetSize } from "./widgets";
 
 /**
  * One link entry contributed by an app to the global legal/info footer
@@ -69,6 +69,13 @@ export type AppPresentationTranslation = {
   searchLinks?: Readonly<Record<string, string>>;
   /** Search-link descriptions keyed by their stable same-origin href. */
   searchLinkDescriptions?: Readonly<Record<string, string>>;
+  /** Dashboard widget titles and descriptions keyed by `widgets[].id`. */
+  widgets?: Readonly<Record<string, AppWidgetTranslation>>;
+};
+
+export type AppWidgetTranslation = {
+  title?: string;
+  description?: string;
 };
 
 export type AppPresentationCatalog = {
@@ -161,7 +168,32 @@ export type WidgetEndpoint = {
   id: string;
   /** Absolute path on the app's HTTP service, e.g. "/api/accounts/widget/open-requests". */
   path: string;
-  /** Optional initial layout recommendation. Explicit user choices win. */
+  /**
+   * Name of the widget in the dashboard and its widget gallery, up to 80 characters, in the app's `baseLocale`;
+   * translate it with `presentation.translations[locale].widgets[id].title`. Defaults to the app's name.
+   */
+  title?: string;
+  /** One sentence for the widget gallery, up to 200 characters; translated like `title`. Defaults to the app's description. */
+  description?: string;
+  /** Sizes the widget offers on the board. Defaults to `["large"]`; offer smaller sizes only when the handler fills them. */
+  sizes?: readonly DashboardWidgetSize[];
+  /** Size the widget starts in, one of `sizes`. Defaults to the largest offered size. */
+  defaultSize?: DashboardWidgetSize;
+  /**
+   * Put the widget on the default board of everyone who may see it and list it under "Suggested for you" in the
+   * gallery. Suggest only widgets that are useful without any setup.
+   */
+  suggest?: boolean;
+  /**
+   * Show the widget in the gallery and on the default board only to people with one of these roles, like
+   * `nav.requiresRoles`. Visibility only: the handler still authorizes every request and answers `403`.
+   */
+  requiresRoles?: readonly Role[];
+  /**
+   * @deprecated The dashboard has no zones or widths any more; declare `sizes` and `defaultSize` instead. Keep an
+   * existing value: the dashboard reads it only to convert a board saved before sizes existed into the one the person
+   * saw.
+   */
   presentation?: DashboardWidgetPresentation;
 };
 

package/src/contracts/capabilities.ts

@@ -349,6 +349,26 @@ export type CapabilityUniversalSearchDefinition = {
 
 export type CapabilitySchemaPresentation = Readonly<Record<string, string>>;
 
+/**
+ * What one Action does, in words people read in approvals, receipts, and step rows. Each sentence is a
+ * template: `{input.to}` inserts a field of the validated call input by its dotted schema path, and
+ * `done` may also read the Action's result data with `{data.id}`. Cloud inserts values as escaped,
+ * bounded plain text, formats fields with a `date` or `date-time` schema format for the reader, and
+ * names an object by its email, address, or path before its display name. A sentence whose value is
+ * missing falls back to the generic wording, so every sentence stays optional. A `done` sentence
+ * replaces the result's runtime summary in the receipt.
+ */
+export type CapabilityActionSentences = {
+  /** What will happen, as a short instruction: "Send email to {input.to}". */
+  approval?: string;
+  /** What happened after the Action ran: "Sent email to {input.to}". */
+  done?: string;
+  /** What did not happen because the person rejected it: "Did not send email to {input.to}". */
+  rejected?: string;
+  /** What did not happen because the turn ended first: "Email to {input.to} not sent". */
+  notRun?: string;
+};
+
 export type CapabilityOperationPresentationTranslation = {
   title?: string;
   description?: string;
@@ -358,6 +378,8 @@ export type CapabilityOperationPresentationTranslation = {
   data?: CapabilitySchemaPresentation;
   /** Search-tag presentation keyed by the stable tag token. */
   searchTags?: Readonly<Record<string, { title?: string; description?: string }>>;
+  /** Actions only: the complete set of sentences in this locale. */
+  sentences?: CapabilityActionSentences;
 };
 
 export type CapabilityPresentationTranslation = {
@@ -370,6 +392,8 @@ export type CapabilityPresentationTranslation = {
 export type CapabilityPresentationCatalog = {
   /** Locale of the complete Type, Query, Action, search-tag, and schema presentation. */
   baseLocale: string;
+  /** Optional Action sentences in the base locale, keyed by Action local ID. */
+  sentences?: Readonly<Record<string, CapabilityActionSentences>>;
   /** Partial presentation overlays with exact -> ancestor -> base fallback. */
   translations: Readonly<Record<string, CapabilityPresentationTranslation>>;
 };

package/src/contracts/pwa-paths.ts

@@ -1,6 +1,11 @@
 /**
- * Paths of the installable mobile app, without schemas, so browser code that runs on every page can test for an
- * app page without loading the contract's validators.
+ * Paths and ids of the installable mobile app, without schemas, so browser code that runs on every page can test for
+ * an app page without loading the contract's validators.
  */
 export const PWA_SCOPE = "/pwa/";
 export const PWA_AUTH_PATH = "/pwa/_auth";
+export const PWA_SERVICE_WORKER_PATH = "/pwa/sw.js";
+/** Ids that can never own a part: the shell itself and its own pages `/pwa/settings` and `/pwa/offline`. */
+export const PWA_RESERVED_IDS = ["pwa", "settings", "offline"] as const;
+/** Whether the app with this id may have a part at `/pwa/<id>`: a plain app id that the shell does not reserve. */
+export const isPwaPartId = (id: string): boolean => /^[a-z][a-z0-9-]*$/.test(id) && !PWA_RESERVED_IDS.some((reserved) => reserved === id);

package/src/contracts/pwa.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { PWA_AUTH_PATH, PWA_SCOPE } from "./pwa-paths";
+import { isPwaPartId, PWA_AUTH_PATH, PWA_RESERVED_IDS, PWA_SCOPE, PWA_SERVICE_WORKER_PATH } from "./pwa-paths";
 
-export { PWA_AUTH_PATH, PWA_SCOPE };
+export { isPwaPartId, PWA_AUTH_PATH, PWA_RESERVED_IDS, PWA_SCOPE, PWA_SERVICE_WORKER_PATH };
 
 /**
  * The installable mobile app (preview). One shell application `pwa` owns the
@@ -11,11 +11,6 @@ export { PWA_AUTH_PATH, PWA_SCOPE };
 export const PWA_SHELL_APP_ID = "pwa";
 export const PWA_API_PATH = "/api/auth/pwa/v1";
 export const PWA_MANIFEST_PATH = "/pwa/manifest.webmanifest";
-export const PWA_SERVICE_WORKER_PATH = "/pwa/sw.js";
-/** Ids that can never own a part: the shell itself and its own pages `/pwa/settings` and `/pwa/offline`. */
-export const PWA_RESERVED_IDS = ["pwa", "settings", "offline"] as const;
-/** Whether the app with this id may have a part at `/pwa/<id>`: a plain app id that the shell does not reserve. */
-export const isPwaPartId = (id: string): boolean => /^[a-z][a-z0-9-]*$/.test(id) && !PWA_RESERVED_IDS.some((reserved) => reserved === id);
 /**
  * The page canvas of the app (`--k2b-surface-canvas` of `@k2b/ui`) in light and dark. App documents paint it
  * before any stylesheet loads and give it to the status bar.

package/src/contracts/registry.ts

@@ -2,7 +2,7 @@ import type { AppAdminNavigationGroup, AppAppearance, AppAppearanceColor, AppPre
 import type { CapabilityManifest, CapabilityPresentationCatalog } from "./capabilities";
 import type { PlatformPermission } from "./outgoing-mail";
 import type { Role } from "./shared";
-import type { DashboardWidgetPresentation } from "./widgets";
+import type { DashboardWidgetPresentation, DashboardWidgetSize } from "./widgets";
 
 /**
  * App-registry entry type. Populated internally by `defineApp()` + the
@@ -52,10 +52,18 @@ export type AppRegistryLegalLink = {
   icon?: string;
 };
 
+/** A widget declaration as the registry carries it; see `WidgetEndpoint`. Older apps send only `id` and `path`. */
 export type AppRegistryWidget = {
   id: string;
   /** Absolute path on the app's HTTP service, e.g. "/api/quotes/widget/random". */
   path: string;
+  title?: string;
+  description?: string;
+  sizes?: readonly DashboardWidgetSize[];
+  defaultSize?: DashboardWidgetSize;
+  suggest?: boolean;
+  requiresRoles?: readonly Role[];
+  /** @deprecated Read only to convert dashboard boards saved before sizes existed. */
   presentation?: DashboardWidgetPresentation;
 };
 
@@ -88,6 +96,7 @@ export type AppRegistryEntry = {
   adminNav?: AppAdminNavigationGroup[];
   capabilities?: AppRegistryCapabilitySummary;
   help?: AppRegistryHelpSummary;
+  skills?: { manifestHash: string };
   legalLinks?: AppRegistryLegalLink[];
   searchLinks?: readonly AppSearchLink[];
   /** The app's part of the mobile app (preview); `href` is `/pwa/<id>`. Older readers ignore it. */

package/src/contracts/shared.ts

@@ -329,6 +329,11 @@ export const AccessEntrySchema = z.object({
   avatarHash: z.string().nullable().optional(),
   /** Kind of a `service_account` principal; presentation only, never authorization. */
   serviceAccountKind: ServiceAccountKindSchema.optional(),
+  /**
+   * A narrower part of the resource the grant covers, defined by the application, such as Mail's
+   * `assigned` conversations. Absent for a grant on the whole resource.
+   */
+  scope: z.string().min(1).max(64).optional(),
 });
 export type AccessEntry = z.infer<typeof AccessEntrySchema>;
 

package/src/contracts/widgets.ts

@@ -38,18 +38,63 @@ const WidgetHrefSchema = z
 export const WidgetToneSchema = z.enum(["emerald", "amber", "red", "blue", "zinc"]);
 export type WidgetTone = z.infer<typeof WidgetToneSchema>;
 
+/** @deprecated The dashboard no longer has zones; declare `sizes` and `defaultSize` instead. */
 export type DashboardWidgetZone = "focus" | "overview" | "context";
+/** @deprecated The dashboard no longer has spans; declare `sizes` and `defaultSize` instead. */
 export type DashboardWidgetSpan = "standard" | "wide";
 
 /**
- * Stable, app-owned recommendation for a widget's initial dashboard layout.
- * Explicit user layout settings always take precedence.
+ * @deprecated The dashboard has no zones or widths any more. Declare `sizes` and `defaultSize` on the widget instead;
+ * the dashboard reads this recommendation only to convert a board saved before sizes existed.
  */
 export type DashboardWidgetPresentation = {
   defaultZone?: DashboardWidgetZone;
   defaultSpan?: DashboardWidgetSpan;
 };
 
+/**
+ * The three sizes a widget can take on the dashboard board, which has four columns on wider screens and two on
+ * phones: `small` is one column and one row, `medium` two columns and one row, and `large` two columns and two rows.
+ * On a phone, `small` takes half the width and `medium` and `large` the full width.
+ */
+export const DASHBOARD_WIDGET_SIZES = ["small", "medium", "large"] as const;
+export type DashboardWidgetSize = (typeof DASHBOARD_WIDGET_SIZES)[number];
+
+/** Longest declared widget title, in characters, the same bound as a shortcut title. */
+export const WIDGET_TITLE_MAX_LENGTH = 80;
+/** Longest declared widget description, in characters: one sentence in the widget gallery. */
+export const WIDGET_DESCRIPTION_MAX_LENGTH = 200;
+
+export const isDashboardWidgetSize = (value: unknown): value is DashboardWidgetSize =>
+  DASHBOARD_WIDGET_SIZES.some((size) => size === value);
+
+/**
+ * The sizes a widget offers and the size it starts with. A widget that declares no valid size offers only `large`,
+ * the height every widget had before sizes existed; without a valid `defaultSize`, it starts at its largest size.
+ */
+export const resolveWidgetSizes = (declaration: {
+  sizes?: readonly unknown[];
+  defaultSize?: unknown;
+}): { sizes: DashboardWidgetSize[]; defaultSize: DashboardWidgetSize } => {
+  const declared = DASHBOARD_WIDGET_SIZES.filter((size) => declaration.sizes?.includes(size));
+  const sizes: DashboardWidgetSize[] = declared.length > 0 ? declared : ["large"];
+  const defaultSize =
+    isDashboardWidgetSize(declaration.defaultSize) && sizes.includes(declaration.defaultSize) ? declaration.defaultSize : sizes.at(-1)!;
+  return { sizes, defaultSize };
+};
+
+/** `requested` when the widget offers it, otherwise the widget's default size. */
+export const fitWidgetSize = (
+  requested: unknown,
+  widget: { sizes: readonly DashboardWidgetSize[]; defaultSize: DashboardWidgetSize },
+): DashboardWidgetSize => (isDashboardWidgetSize(requested) && widget.sizes.includes(requested) ? requested : widget.defaultSize);
+
+/** What the dashboard asks a widget handler for, read with `getWidgetRequest(c)`. */
+export type WidgetRequest = {
+  /** The size the widget is shown in, always one the widget declares. */
+  size: DashboardWidgetSize;
+};
+
 export const WidgetAccentSchema = z
   .object({
     tone: WidgetToneSchema,
@@ -181,3 +226,23 @@ export const WidgetResponseSchema = z
   })
   .strip();
 export type WidgetResponse = z.infer<typeof WidgetResponseSchema>;
+
+/** A widget's stable key on the dashboard and in the widget stream: `<appId>/<widgetId>`. */
+export const widgetKey = (appId: string, widgetId: string): string => `${appId}/${widgetId}`;
+
+/**
+ * How one widget answered in the widget stream: `ok` carries its response, `empty` is a `204`, `forbidden` a `403`,
+ * `timeout` means it did not answer within its own budget, and `error` covers every other failure.
+ */
+export type WidgetStreamStatus = "ok" | "empty" | "forbidden" | "timeout" | "error";
+
+/**
+ * One line of `GET /api/widgets/v1` (`application/x-ndjson`): `start` names the widgets Core asks, in registry
+ * order; one `widget` line follows per widget in the order they finish; `done` closes the stream. Every widget named
+ * in `start` gets exactly one line.
+ */
+export type WidgetStreamLine =
+  | { type: "start"; widgets: string[] }
+  | { type: "widget"; key: string; status: "ok"; widget: WidgetResponse; ms: number }
+  | { type: "widget"; key: string; status: Exclude<WidgetStreamStatus, "ok">; ms: number }
+  | { type: "done"; status: "complete" | "partial" };

package/src/desktop/solid.tsx

@@ -1,3 +1,4 @@
+import { suppressTextSelection } from "@k2b/ui";
 import { deserialize as deserializeProps, serialize as serializeProps } from "seroval";
 import type { Component, JSX, ParentProps } from "solid-js";
 import { children, createContext, createMemo, createSignal, For, onCleanup, onMount, Show, useContext } from "solid-js";
@@ -483,10 +484,11 @@ const startDesktopResize = (event: PointerEvent, onMove: (dx: number, dy: number
   const startX = event.clientX;
   const startY = event.clientY;
   const move = (next: PointerEvent) => onMove(next.clientX - startX, next.clientY - startY);
+  const releaseTextSelection = suppressTextSelection(event.pointerId);
   const stop = () => {
     window.removeEventListener("pointermove", move);
     window.removeEventListener("pointerup", stop);
-    document.body.style.userSelect = "";
+    releaseTextSelection();
     document.body.style.cursor = "";
   };
   window.addEventListener("pointermove", move);
@@ -631,10 +633,9 @@ export const DesktopWorkspace = ((props: DesktopWorkspaceProps) => {
 
   const resizeSidebar = (event: PointerEvent) => {
     const pane = sidebar();
-    if (!pane?.resizable) return;
+    if (!pane?.resizable || event.button !== 0) return;
     const start = sidebarOpen() ? sidebarSize() : sidebarColumnSize();
     document.body.style.cursor = "col-resize";
-    document.body.style.userSelect = "none";
     startDesktopResize(event, (dx) => {
       const raw = start + dx;
       if (shouldRail(pane, raw)) {
@@ -650,10 +651,9 @@ export const DesktopWorkspace = ((props: DesktopWorkspaceProps) => {
 
   const resizeRight = (event: PointerEvent) => {
     const pane = right();
-    if (!pane?.resizable) return;
+    if (!pane?.resizable || event.button !== 0) return;
     const start = rightOpen() ? rightSize() : rightColumnSize();
     document.body.style.cursor = "col-resize";
-    document.body.style.userSelect = "none";
     startDesktopResize(event, (dx) => {
       const raw = start - dx;
       if (shouldRail(pane, raw)) {
@@ -669,10 +669,9 @@ export const DesktopWorkspace = ((props: DesktopWorkspaceProps) => {
 
   const resizeBottom = (event: PointerEvent) => {
     const pane = bottom();
-    if (!pane?.resizable) return;
+    if (!pane?.resizable || event.button !== 0) return;
     const start = bottomOpen() ? bottomSize() : bottomRowSize();
     document.body.style.cursor = "row-resize";
-    document.body.style.userSelect = "none";
     startDesktopResize(event, (_dx, dy) => {
       const raw = start - dy;
       if (shouldRail(pane, raw)) {

package/src/index.ts

@@ -35,6 +35,7 @@ export {
 export type { RuntimeCompatibilityIssue } from "./_internal/runtime-compatibility";
 export { assessRuntimeCompatibility } from "./_internal/runtime-compatibility";
 export { buildRuntimeFromRegistry } from "./_internal/runtime-context";
+export { type AppSkillDefinition, skill } from "./ai/app-skills";
 export { defineCapabilities } from "./contracts/capabilities";
 export type {
   AnyBoundNotificationDefinition,

package/src/server/help.ts

@@ -3,6 +3,7 @@ import { parse as parseYaml } from "yaml";
 import { z } from "zod";
 import { type HelpDocumentManifest, type HelpDocumentPayload, type HelpSearchPayload, helpLocaleChain } from "../shared/help";
 import { markdownToPlainText, renderHelpMarkdown } from "../shared/markdown";
+import { auth } from "./middleware/auth";
 
 const metadataSchema = z.object({
   id: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
@@ -133,6 +134,9 @@ export const defineHelp = (
  * Define one app-owned help corpus. The explicit source list is deliberate:
  * IDs, ordering and ownership stay visible in code; no filesystem scanning or
  * build-time convention is required.
+ *
+ * @deprecated Declare Help with `defineHelp()` and pass it to `app.start({ help })`. This router only
+ * requires sign-in; it does not apply the app's Help visibility, so the mounting app's routes must guard it.
  */
 export const defineHelpCollection = (options: { basePath: string; sources: readonly string[] }): HelpCollection => {
   const basePath = options.basePath.replace(/\/$/, "");
@@ -151,7 +155,10 @@ export const defineHelpCollection = (options: { basePath: string; sources: reado
     url: `${basePath}/${encodeURIComponent(id)}`,
   }));
 
-  const router = new Hono()
+  // Help is for signed-in people wherever an app mounts this router; its own route policy may narrow it further.
+  const router = new Hono();
+  router.use(auth.requireRole("authenticated"), auth.requireUser());
+  router
     .get("/search", (context) => {
       const query = context.req.query("q")?.trim().toLocaleLowerCase().slice(0, 200) ?? "";
       const payload: HelpSearchPayload = {

package/src/server/index.ts

@@ -94,3 +94,4 @@ export {
   updateAccess,
 } from "./services";
 export { getDateConfig, getTimeZone, TIMEZONE_COOKIE, time } from "./time";
+export { getWidgetRequest } from "./widget-request";

package/src/server/widget-request.ts

@@ -0,0 +1,27 @@
+import type { Context } from "hono";
+import { type DashboardWidgetSize, fitWidgetSize, resolveWidgetSizes, type WidgetRequest } from "../contracts/widgets";
+
+/** The query parameter Core uses to ask a widget handler for one size. */
+export const WIDGET_SIZE_PARAM = "size";
+
+const requests = new WeakMap<Request, WidgetRequest>();
+
+/**
+ * Records what the dashboard asked a declared widget for, already fitted to the declaration. Only the framework's
+ * internal widget route calls this, before it runs the handler.
+ */
+export const setWidgetRequest = (
+  c: Context,
+  declaration: { sizes?: readonly DashboardWidgetSize[]; defaultSize?: DashboardWidgetSize },
+): WidgetRequest => {
+  const request = { size: fitWidgetSize(c.req.query(WIDGET_SIZE_PARAM), resolveWidgetSizes(declaration)) };
+  requests.set(c.req.raw, request);
+  return request;
+};
+
+/**
+ * What the dashboard asks this widget handler for. `size` is always one of the sizes the widget declares; return the
+ * content that fits it, for example only the one number in `small`. Outside a dashboard invocation, such as a request
+ * to the handler's own public route, the request is `large`, the height every widget had before sizes existed.
+ */
+export const getWidgetRequest = (c: Context): WidgetRequest => requests.get(c.req.raw) ?? { size: "large" };

package/src/services/accounts/users.ts

@@ -223,6 +223,21 @@ export const getMinimal = async (params: { id: string } | { uid: string }): Prom
   return buildUserMutationTarget(rows[0]!);
 };
 
+/** Audience roles for a resolved access subject, including delegated users and group managers. */
+export const getRoles = async (userId: string): Promise<Role[]> => {
+  const { groupsAdmin } = await getFreeIpaConfig();
+  const [row] = await sql<DbRow[]>`SELECT u.provider, u.profile,
+    CASE WHEN u.provider='local' THEN u.admin ELSE EXISTS (
+      SELECT 1 FROM auth.ipa_user_effective_groups eg WHERE eg.user_id=u.id
+        AND eg.group_name=ANY(${toPgTextArray(groupsAdmin)}::text[])
+    ) END AS effective_admin,
+    ARRAY(${managedGroupsNamesSubquery(sql`u.id`)}) AS manages
+    FROM auth.users u WHERE u.id=${userId}::uuid`;
+  if (!row) return [];
+  const { provider, profile } = resolveProviderProfile(row);
+  return buildRoles({ provider, profile, memberofGroup: [], manages: stringArray(row.manages), admin: Boolean(row.effective_admin) });
+};
+
 export const getByUid = async (params: { uid: string }): Promise<{ id: string; roles: Role[] } | null> => {
   const { groupsAdmin } = await getFreeIpaConfig();
   const rows = await sql<DbRow[]>`

package/src/services/approvals/index.ts

@@ -0,0 +1,225 @@
+import { type SQL, sql } from "bun";
+import { capabilityRequestHash } from "../../capabilities/claims";
+import type { CapabilityActionReview } from "../../contracts/capabilities";
+import { isAppSessionActor } from "../../server/actor";
+import type { RequestActor, RequestCredentialKind } from "../../server/middleware/auth";
+import { audit } from "../audit";
+import { toPgTextArray } from "../postgres";
+
+export { migrateApprovals } from "./migrate";
+
+// Derived from chat's AI_ACTION_BUDGET_MS and Studio's one-day abandonment of pending calls.
+export const APPROVAL_MAX_WAIT_MS = 24 * 60 * 60_000;
+export type ApprovalDecisionChannel = "web_session" | "app_session" | "oauth" | "api_key" | "invocation";
+export type ApprovalRequesterKind = "assistant_turn" | "studio_app";
+export type ApprovalStatus = "pending" | "approved" | "rejected" | "expired" | "cancelled" | "consumed";
+export type ApprovalAssurance = "standard" | "confirm";
+
+/**
+ * `standard` when the person may remember the approval of this call: an Action with `approval: "rememberable"` whose
+ * review names a scope for these arguments, a tool whose policy allows remembering, or a website. Otherwise `confirm`.
+ */
+export const approvalAssurance = (rememberable: boolean): ApprovalAssurance => (rememberable ? "standard" : "confirm");
+export const approvalArgsDigest = (input: unknown): string => capabilityRequestHash(input);
+export const approvalReviewDigest = (review: CapabilityActionReview | null | undefined): string => capabilityRequestHash(review ?? null);
+export const approvalDecisionChannel = (input: {
+  credentialKind?: RequestCredentialKind;
+  actor?: RequestActor;
+}): ApprovalDecisionChannel =>
+  input.credentialKind === "session"
+    ? isAppSessionActor(input.actor)
+      ? "app_session"
+      : "web_session"
+    : (input.credentialKind ?? "invocation");
+export const approvalScopeFromToolName = (name: string): { appId: string; action: string } => {
+  const dot = name.indexOf(".");
+  return dot < 0 ? { appId: "assistant", action: name } : { appId: name.slice(0, dot), action: name.slice(dot + 1) };
+};
+
+export type ApprovalRequestInput = {
+  appId: string;
+  action: string;
+  approvalScope?: string | null;
+  requester: { kind: ApprovalRequesterKind; ref: string; appId: string; title?: string | null };
+  subjectId: string;
+  approverUserId: string;
+  assurance: ApprovalAssurance;
+  sentence: string;
+  review?: CapabilityActionReview | null;
+  input: unknown;
+  expiresInMs: number;
+};
+export type ApprovalRequest = {
+  id: string;
+  appId: string;
+  action: string;
+  approvalScope: string | null;
+  requesterKind: ApprovalRequesterKind;
+  requesterRef: string;
+  requesterAppId: string;
+  requesterTitle: string | null;
+  subjectId: string;
+  approverUserId: string;
+  assurance: ApprovalAssurance;
+  sentence: string;
+  details: CapabilityActionReview | null;
+  argsDigest: string;
+  reviewDigest: string;
+  status: ApprovalStatus;
+  decidedVia: ApprovalDecisionChannel | null;
+  decidedAt: Date | null;
+  consumedAt: Date | null;
+  createdAt: Date;
+  expiresAt: Date;
+};
+// SQL aliases keep the public row shape identical for reads and locked transaction reads. A function, because a
+// fragment built at import time would bind the default sql handle before a test can choose its database.
+const columns = () => sql`id, app_id AS "appId", action, approval_scope AS "approvalScope",
+  requester_kind AS "requesterKind", requester_ref AS "requesterRef", requester_app_id AS "requesterAppId",
+  requester_title AS "requesterTitle", subject_id AS "subjectId", approver_user_id AS "approverUserId",
+  assurance, sentence, details, args_digest AS "argsDigest", review_digest AS "reviewDigest", status,
+  decided_via AS "decidedVia", decided_at AS "decidedAt", consumed_at AS "consumedAt",
+  created_at AS "createdAt", expires_at AS "expiresAt"`;
+
+const transaction = <T>(db: SQL | undefined, run: (tx: SQL) => Promise<T>): Promise<T> => (db && db !== sql ? run(db) : sql.begin(run));
+
+export type ApprovalRequestResult = { ok: true; id: string } | { ok: false; code: "CONFLICT" };
+/**
+ * Records the question once per requester reference. Asking again, for example after a worker restart, returns the
+ * open request unchanged: its snapshot is what the person may already see, so a changed effect fails `consume` and
+ * asks again instead of rebinding that decision. A reference whose request is decided, expired, or another person's
+ * is a conflict.
+ */
+export const request = async (input: ApprovalRequestInput, db?: SQL): Promise<ApprovalRequestResult> => {
+  // Zero or less records a request that is already expired, such as a call that waited too long before the upgrade.
+  const expiresInMs = Number.isNaN(input.expiresInMs)
+    ? APPROVAL_MAX_WAIT_MS
+    : Math.max(0, Math.min(input.expiresInMs, APPROVAL_MAX_WAIT_MS));
+  return transaction(db, async (tx): Promise<ApprovalRequestResult> => {
+    const [row] = await tx<{ id: string }[]>`
+      INSERT INTO approvals.requests (app_id, action, approval_scope, requester_kind, requester_ref, requester_app_id,
+        requester_title, subject_id, approver_user_id, assurance, sentence, details, args_digest, review_digest, expires_at)
+      VALUES (${input.appId}, ${input.action}, ${input.approvalScope ?? null}, ${input.requester.kind}, ${input.requester.ref},
+        ${input.requester.appId}, ${input.requester.title ?? null}, ${input.subjectId}::uuid, ${input.approverUserId}::uuid,
+        ${input.assurance}, ${input.sentence}, ${JSON.stringify(input.review ?? null)}::text::jsonb,
+        ${approvalArgsDigest(input.input)}, ${approvalReviewDigest(input.review)}, now() + (${expiresInMs} * interval '1 millisecond'))
+      ON CONFLICT (requester_kind, requester_ref) DO NOTHING
+      RETURNING id
+    `;
+    if (row) return { ok: true, id: row.id };
+    const [open] = await tx<{ id: string }[]>`SELECT id FROM approvals.requests
+      WHERE requester_kind=${input.requester.kind} AND requester_ref=${input.requester.ref}
+        AND status='pending' AND expires_at > now() AND subject_id=${input.subjectId}::uuid
+        AND approver_user_id=${input.approverUserId}::uuid AND app_id=${input.appId} AND action=${input.action}`;
+    return open ? { ok: true, id: open.id } : { ok: false, code: "CONFLICT" };
+  });
+};
+
+export const get = async (id: string, db?: SQL): Promise<ApprovalRequest | null> =>
+  transaction(db, async (tx) => {
+    const [row] = await tx<ApprovalRequest[]>`SELECT ${columns()} FROM approvals.requests WHERE id=${id}::uuid`;
+    return row ?? null;
+  });
+
+export type ApprovalDecisionResult =
+  | { ok: true; status: ApprovalStatus; replay: boolean }
+  | { ok: false; code: "EXPIRED" | "NOT_FOUND" }
+  | { ok: false; code: "ALREADY_DECIDED"; status: ApprovalStatus };
+export const decide = async (
+  id: string,
+  decision: { approved: boolean },
+  actor: { userId: string; via: ApprovalDecisionChannel },
+  db?: SQL,
+): Promise<ApprovalDecisionResult> => {
+  const result = await transaction(db, async (tx): Promise<ApprovalDecisionResult> => {
+    const [row] = await tx<ApprovalRequest[]>`SELECT ${columns()} FROM approvals.requests
+      WHERE id=${id}::uuid AND approver_user_id=${actor.userId}::uuid FOR UPDATE`;
+    if (!row) return { ok: false, code: "NOT_FOUND" };
+    const status = decision.approved ? "approved" : "rejected";
+    const [won] = await tx<ApprovalRequest[]>`
+      UPDATE approvals.requests SET status=${status}, decided_via=${actor.via}, decided_at=now()
+      WHERE id=${id}::uuid AND approver_user_id=${actor.userId}::uuid AND status='pending' AND expires_at > now()
+      RETURNING ${columns()}
+    `;
+    if (won) {
+      await audit.record(
+        {
+          action: decision.approved ? "auth.action.approve" : "auth.action.deny",
+          outcome: "allowed",
+          actor: { userId: actor.userId },
+          target: { type: "approval_request", id, label: `${won.appId}.${won.action}` },
+          metadata: {
+            appId: won.appId,
+            action: won.action,
+            assurance: won.assurance,
+            decidedVia: actor.via,
+            requesterKind: won.requesterKind,
+            requesterAppId: won.requesterAppId,
+          },
+        },
+        tx,
+      );
+      return { ok: true, status, replay: false };
+    }
+    if (row.status === "pending") {
+      await tx`UPDATE approvals.requests SET status='expired' WHERE id=${id}::uuid AND status='pending' AND expires_at <= now()`;
+      return { ok: false, code: "EXPIRED" };
+    }
+    if (
+      (decision.approved && (row.status === "approved" || row.status === "consumed")) ||
+      (!decision.approved && row.status === "rejected")
+    )
+      return { ok: true, status: row.status, replay: true };
+    return { ok: false, code: "ALREADY_DECIDED", status: row.status };
+  });
+  // Publish a later NATS decision hint only after the owning transaction commits.
+  return result;
+};
+
+export type ApprovalConsumeResult =
+  | { ok: true }
+  | { ok: false; code: "NOT_FOUND" | "NOT_APPROVED" | "ALREADY_CONSUMED" | "INPUT_CHANGED" | "REVIEW_CHANGED" };
+export const consume = async (
+  id: string,
+  input: { input: unknown; review: CapabilityActionReview | null; requester: { kind: ApprovalRequesterKind; ref: string } },
+  db?: SQL,
+): Promise<ApprovalConsumeResult> => {
+  const argsDigest = approvalArgsDigest(input.input),
+    reviewDigest = approvalReviewDigest(input.review);
+  return transaction(db, async (tx): Promise<ApprovalConsumeResult> => {
+    const [row] = await tx<ApprovalRequest[]>`SELECT ${columns()} FROM approvals.requests
+      WHERE id=${id}::uuid AND requester_kind=${input.requester.kind} AND requester_ref=${input.requester.ref} FOR UPDATE`;
+    if (!row) return { ok: false, code: "NOT_FOUND" };
+    if (row.status === "consumed") return { ok: false, code: "ALREADY_CONSUMED" };
+    if (row.status !== "approved") return { ok: false, code: "NOT_APPROVED" };
+    if (row.argsDigest !== argsDigest || row.reviewDigest !== reviewDigest) {
+      await tx`UPDATE approvals.requests SET status='cancelled' WHERE id=${id}::uuid AND status='approved'`;
+      return { ok: false, code: row.argsDigest !== argsDigest ? "INPUT_CHANGED" : "REVIEW_CHANGED" };
+    }
+    await tx`UPDATE approvals.requests SET status='consumed', consumed_at=now() WHERE id=${id}::uuid AND status='approved'
+      AND requester_kind=${input.requester.kind} AND requester_ref=${input.requester.ref}
+      AND args_digest=${argsDigest} AND review_digest=${reviewDigest}`;
+    return { ok: true };
+  });
+};
+
+export const cancel = async (ids: string[], db?: SQL): Promise<void> => {
+  if (!ids.length) return;
+  await transaction(db, async (tx) => {
+    await tx`UPDATE approvals.requests SET status='cancelled' WHERE id=ANY(${toPgTextArray(ids)}::uuid[]) AND status IN ('pending','approved')`;
+  });
+};
+
+export const pruneApprovalRequests = async (before: Date): Promise<number> => {
+  let total = 0;
+  let deleted: number;
+  do {
+    const result = await sql`WITH expired AS (SELECT id FROM approvals.requests WHERE expires_at < ${before} LIMIT 5000)
+      DELETE FROM approvals.requests request USING expired WHERE request.id=expired.id`;
+    deleted = result.count;
+    total += deleted;
+  } while (deleted === 5000);
+  return total;
+};
+
+export const approvals = { request, get, decide, consume, cancel };