@cosmicdrift/kumiko-framework 0.363.0 → 0.365.0

package/agents/widgets.md

@@ -0,0 +1,181 @@
+<!-- Generated by `bun run gen:agent-docs` from packages/renderer-web/src/index.ts. Do not edit. -->
+
+# Widgets
+
+Value exports of `@cosmicdrift/kumiko-renderer-web`.
+
+## Components
+
+| Name | Description |
+| --- | --- |
+| `ActionMenu` |  |
+| `AiTextArea` | Multi-line variant of {@link AiTextField}. |
+| `AiTextField` | Single-line AI text field — ghost-text completion + correct/translate/ rewrite toolbar. |
+| `AppLayout` |  |
+| `Avatar` |  |
+| `BareFormProvider` |  |
+| `BooleanField` | Checkbox/Switch = Field(layout:"inline") + Input(kind:"boolean"). |
+| `Card` |  |
+| `CollapsibleSection` | Aufklappbare Sektion (native <details>, aber React-kontrolliert: sonst springt das open-Attribut bei jedem Parent-Re-Render auf den Initialwert zurück). |
+| `ComparisonTable` | Transponierte Vergleichstabelle: Zeile = Kennzahl, Spalte = Variante, je Kennzahl optional die beste Spalte hervorgehoben. |
+| `DateField` | Datumsfeld = Field + Input(kind:"date"), ISO yyyy-mm-dd. |
+| `DefaultAppShell` |  |
+| `DetailList` | Read-only Schlüssel-Wert-Liste für Detail-Masken (Label links gedimmt, Wert rechts). |
+| `DispatcherProvider` |  |
+| `Drawer` | Slide-in panel beside a list (e.g. mail reader next to the inbox) — thin wrapper over the Sheet primitive with header/body/footer slots so screens skip per-route Radix boilerplate. |
+| `DropdownMenu` |  |
+| `DropdownMenuCheckboxItem` |  |
+| `DropdownMenuContent` |  |
+| `DropdownMenuItem` |  |
+| `DropdownMenuLabel` |  |
+| `DropdownMenuPortal` |  |
+| `DropdownMenuSeparator` |  |
+| `DropdownMenuTrigger` |  |
+| `EditorPanel` |  |
+| `EmptyState` | Leerer-Zustand mit optionalem Icon + CTA — die dashed-Box-Optik der entityList-Empty-States, als Standalone-Widget für Custom-Screens. |
+| `ErrorState` | Fehler-Zustand auf Basis des Banner-Primitives, mit Retry-Button. |
+| `FeedList` | Nicht-tabellarische Kurzliste (z.B. |
+| `FileField` | Datei-Upload = Field + Input(kind:"file"\|"image") — FileRef-basiert. |
+| `FloatingPanel` | Non-modal panel floating above the page: draggable by its header, resizable from all edges and corners, clamped to the viewport, geometry optionally remembered. |
+| `FormScreenShell` |  |
+| `HeaderActionGroup` |  |
+| `Icon` |  |
+| `InfinityList` | Cursor-paginated scroll list (mail inbox, activity feeds) — loads the next page when the end sentinel becomes visible (IntersectionObserver), instead of a pager bar like QueryTable/entityList. |
+| `KumikoLink` |  |
+| `KumikoScreen` |  |
+| `LanguageMenuItems` | Locale choices as dropdown entries, for a user menu that carries the shell controls. |
+| `LanguageSwitcher` |  |
+| `LiveEventsProvider` |  |
+| `LoadingState` | Lade-Zustand: Skeleton-Zeilen in Card-Optik. |
+| `LocaleProvider` |  |
+| `MiniStat` | Kompakte Kennzahl-Kachel (ohne Icon) — für dichte KPI-Raster. |
+| `ModeSwitch` | Segmented-Control für sich ausschließende Modi — die prominente Alternative zum vergrabenen <select>. |
+| `MoneyField` |  |
+| `NavProvider` |  |
+| `NavTree` |  |
+| `NumberField` | Zahlenfeld = Field + Input(kind:"number") in einem — nimmt der Screen die wiederholte id/name/value/onChange-Verdrahtung ab. |
+| `PageSection` |  |
+| `PercentField` |  |
+| `PhotoSlots` | Guided photo capture: one tile per requested shot in a two-column grid, each its own camera/gallery picker, filled tiles show the thumbnail. |
+| `PlainContentEditor` |  |
+| `PlanCard` |  |
+| `PlanGrid` |  |
+| `PrimitivesProvider` |  |
+| `ProfileMenu` |  |
+| `ProgressBar` | Progress bar, `value` 0..1 (clamped). |
+| `ProgressList` | Liste aus Label/Wert-Kopfzeile + Fortschrittsbalken pro Eintrag (z.B. |
+| `PublicShell` | One header and footer for anonymous pages; `focus` narrows to a task column, `card` centers a single card (sign-in). |
+| `QueryTable` |  |
+| `RangeField` | Schieberegler = Field + Input(kind:"range"). |
+| `RenderEdit` |  |
+| `RenderField` |  |
+| `RenderList` |  |
+| `ResizableHandle` |  |
+| `ResizablePanel` |  |
+| `ResizablePanelGroup` |  |
+| `ResultPanel` | Ergebnis-Sektion eines Rechners: SectionCard mit Empty-Zustand (Banner) oder Kennzahl-Liste (DetailList) + optionalen Extras (Tabelle, Hinweise). |
+| `ResultTable` | Statische, prop-getriebene Ergebnistabelle für berechnete Zeilen (Tranchen, Szenarien). |
+| `RichContentEditor` |  |
+| `ScreenWidthProvider` |  |
+| `SectionCard` | Sektion mit Titel + optionalem Action-Slot (Range-Umschalter, Filter) — ersetzt die wiederholten `<section className={CARD}>…<h2>`-Blöcke in Custom-Screens. |
+| `SelectField` | Auswahlfeld = Field + Input(kind:"select"). |
+| `SideBySideTable` | Small read-only grid with real table semantics (`th scope`) whose cells are arbitrary React nodes — for side-by-side comparisons like "from the document" vs. |
+| `Sidebar` |  |
+| `SidebarBrand` |  |
+| `SidebarMenu` |  |
+| `SidebarMenuButton` |  |
+| `SidebarMenuItem` |  |
+| `SidebarPanel` | Renders its children into the second sidebar column when the shell offers one. |
+| `SidebarProvider` |  |
+| `SidebarUser` |  |
+| `Sparkline` |  |
+| `Stack` |  |
+| `StatCard` | Icon-tragende Kennzahl-Kachel mit optionalem Delta-Chip, Trend-Zeile und Sparkline. |
+| `StatusBadge` | Pill badge with a status dot. |
+| `StatusBarChart` | Status bar strip (e.g. 90-day uptime): variable-height bars with gradient fade + tick line on top; the last entry gets a "now" accent stripe. |
+| `StepBar` | Wizard step overview — numbered chips with a connector line between them. |
+| `TextField` | Textfeld = Field + Input(kind:"text"). |
+| `TextareaField` | Mehrzeiliges Textfeld = Field + Input(kind:"textarea"). |
+| `ThemeMenuItem` | Theme toggle as a dropdown entry, for a user menu that carries the shell controls. |
+| `ThemeToggle` |  |
+| `TimeseriesChart` | Zeitreihen-Linien-Chart (geglättete Linie + Flächen-Verlauf). |
+| `ToastProvider` |  |
+| `TokensProvider` |  |
+| `Topbar` |  |
+| `UploadZone` | Drop zone + multi-file picker with a per-file status row (uploading/done/ error). |
+| `UserRolesProvider` |  |
+| `WorkspaceShell` |  |
+| `WorkspaceSwitcher` | Requires an ancestor `SidebarProvider` (see `../ui/sidebar`) — this component renders `SidebarMenuButton`, which calls `useSidebar()` internally and throws ("useSidebar must be used within a SidebarProvider.") when rendered outside one. |
+
+## Hooks
+
+| Name | Description |
+| --- | --- |
+| `useBrowserNavApi` | React-Hook der eine NavApi aus der Browser-History baut. |
+| `useBrowserTokensApi` | Hook der eine TokensApi für den Browser baut. |
+| `useDispatcher` |  |
+| `useDispatcherStatus` |  |
+| `useDraft` | Formular-State für Rechner-Screens: ein Draft-Objekt + `patch` für Teil-Updates + `field(name)` das die `{ id, name, value, onChange }`-Props fertig für die Feld-Widgets (NumberField/MoneyField/PercentField) liefert. |
+| `useForm` |  |
+| `useIsNarrowViewport` |  |
+| `useLiveEvents` | Hook für useQuery-like Consumer. |
+| `useLocale` | Liefert den aktuellen LocaleResolver und abonniert automatisch Locale-Änderungen — der aufrufende Component re-rendert sobald die Sprache gewechselt wird. |
+| `useNav` |  |
+| `usePrimitives` |  |
+| `useQuery` |  |
+| `useResolvers` |  |
+| `useStore` |  |
+| `useStoreSelector` |  |
+| `useToast` |  |
+| `useTokenController` | Volle API inkl. |
+| `useTokens` | Read-only Tokens-Hook. |
+| `useTranslation` | `t("key", params)` resolves in this order: 1. |
+| `useUserRoles` |  |
+
+## Functions
+
+| Name | Description |
+| --- | --- |
+| `applyTokensToCssVars` | Historisch: schrieb Tokens auf :root als CSS-vars. |
+| `buildFileUploadFormData` |  |
+| `buildNavRegistrySlice` |  |
+| `buildNavRegistrySliceForApp` |  |
+| `cn` | shadcn-Standard-Helper: clsx für konditionales Zusammenstecken, tailwind-merge für Konfliktauflösung (z.B. |
+| `createBrowserDraftStorage` | Default DraftStorage when createKumikoApp boots without one. |
+| `createBrowserLocaleResolver` | Default-Resolver wenn createKumikoApp ohne `locale`-Option gebootet wird. |
+| `createEventSourceLiveEvents` | Liefert einen `LiveEventSubscriber` der EventSource-backed ist. |
+| `createKumikoApp` |  |
+| `createPublicSurface` |  |
+| `createStaticLocaleResolver` | Default-Resolver für Apps ohne eigene i18n-Schicht. |
+| `filterAppSchemaNavsByAllowlist` |  |
+| `filterByAccess` |  |
+| `formatMoney` |  |
+| `formatPath` |  |
+| `parsePath` |  |
+| `parseTargetFromSearchParams` | Inverse — parse the current search-params back into a TargetRef. |
+| `postWithDownload` |  |
+| `qualifyScreenId` |  |
+| `readLoadedBuild` |  |
+| `reparentAppSchemaNavs` |  |
+| `resolveDefaultId` |  |
+| `smoothPath` | Quadratic-durch-Mittelpunkte-Trick: glättet die Zick-Zack-Linie ohne Overshoot (~5 Zeilen statt Catmull-Rom/Bezier-Fit). |
+| `synthesizeActionFormEntity` | Baut eine minimale EntityDefinition aus den Inline-Fields eines ActionForm- oder SecretMint-Screens. |
+| `synthesizeActionFormScreen` | Wandelt ein ActionFormScreenDefinition oder SecretMintScreenDefinition in die EntityEditScreen-Shape die RenderEdit erwartet. |
+| `uploadFileRef` | Posts one file to the stack's file endpoint (double-submit CSRF) and returns the new FileRef id. |
+
+## Constants
+
+| Name | Description |
+| --- | --- |
+| `BROWSER_LOCALE_STORAGE_KEY` |  |
+| `STATUS_TONE_TEXT` |  |
+| `cssVarTokens` | Tokens mit var-string-Werten. |
+| `defaultPrimitives` |  |
+| `defaultTokens` | Default-Tokens — identisch zu `cssVarTokens` (var-string-refs). |
+| `lightTokens` |  |
+
+## Classes
+
+| Name | Description |
+| --- | --- |
+| `FileUploadFailedError` | Carries the server's own `error` message when the upload endpoint sent one. |

package/dist/api/auth-middleware.d.ts

@@ -36,6 +36,8 @@ export type AnonymousAccessResolved = AnonymousAccessConfig & {
 export declare function authMiddleware(jwt: JwtHelper, options?: AuthMiddlewareOptions): (c: Context, next: Next) => Promise<Response | undefined>;
 export declare function getUser(c: Context): SessionUser;
 export declare function getAuthTransport(c: Context): AuthTransport | undefined;
+/** Rejection code of the stale auth cookie this request was downgraded to anonymous from; undefined otherwise. */
+export declare function getStaleCredentialCode(c: Context): string | undefined;
 /** JWT `exp` (epoch seconds) of the request's token; undefined for anonymous and verified-bearer (PAT) callers. */
 export declare function getAuthTokenExpiry(c: Context): number | undefined;
 export declare function resolveTenantTeardownStatus(tenantId: TenantId, resolveTenantLifecycleStatus: TenantLifecycleStatusResolver | undefined): Promise<string | undefined>;

package/dist/api/auth-middleware.js

@@ -8,6 +8,7 @@ import { isForeignCookieOrigin } from "./origin-middleware.js";
 import { clearSessionCookies, getSessionCookies, hasDuplicateSessionCookie, } from "./session-cookies.js";
 const USER_KEY = "pipelineUser";
 const AUTH_TRANSPORT_KEY = "authTransport";
+const STALE_CREDENTIAL_KEY = "staleCredentialCode";
 const AUTH_TOKEN_EXPIRY_KEY = "authTokenExpiry";
 export const CSRF_HEADER_NAME = "X-CSRF-Token";
 // Prefix that marks a bearer token as a long-lived Personal Access Token
@@ -161,6 +162,7 @@ export function authMiddleware(jwt, options = {}) {
         }
         const rejectInvalidCredential = async (rejection) => {
             if (isStaleCookieDowngradable(c, transport, anonymousAccess)) {
+                c.set(STALE_CREDENTIAL_KEY, rejection.code);
                 return await handleAnonymous(c, anonymousAccess, next, resolveTenantLifecycleStatus, {
                     staleCredential: { rejectionIfTenantUnresolved: rejection },
                 });
@@ -236,6 +238,11 @@ export function getAuthTransport(c) {
     // @cast-boundary engine-bridge — Hono context.get returns unknown
     return c.get(AUTH_TRANSPORT_KEY);
 }
+/** Rejection code of the stale auth cookie this request was downgraded to anonymous from; undefined otherwise. */
+export function getStaleCredentialCode(c) {
+    const code = c.get(STALE_CREDENTIAL_KEY);
+    return typeof code === "string" ? code : undefined;
+}
 /** JWT `exp` (epoch seconds) of the request's token; undefined for anonymous and verified-bearer (PAT) callers. */
 export function getAuthTokenExpiry(c) {
     // @cast-boundary engine-bridge — Hono context.get returns unknown

package/dist/api/auth-routes.d.ts

@@ -6,7 +6,6 @@ import { type AuthSessionChecker, type AuthSessionStatus, type TokenVerifier } f
 import { type ClientIpResolver } from "./client-ip.js";
 import type { JwtHelper } from "./jwt.js";
 import type { PostAuthLandingResolver } from "./post-auth-landing.js";
-export declare function assertRetiredCookieDomains(retiredCookieDomains: readonly string[] | undefined, cookieDomain: string | undefined): void;
 export type LoginRateLimiter = {
     check(key: string): Promise<boolean>;
     reset(key: string): Promise<void>;

package/dist/api/auth-routes.js

@@ -12,7 +12,7 @@ import { Routes } from "./api-constants.js";
 import { getUser, } from "./auth-middleware.js";
 import { clientIpSourceFromHonoContext, createClientIpResolver, } from "./client-ip.js";
 import { resolvePostAuthLandingPath } from "./post-auth-landing.js";
-import { AUTH_COOKIE_BASE, CSRF_COOKIE_BASE, clearSessionCookies, getSessionCookies, isHostPrefixedCookieName, resolveSessionCookies, } from "./session-cookies.js";
+import { AUTH_COOKIE_BASE, CSRF_COOKIE_BASE, clearSessionCookies, expireLegacySessionCookieVariants, getSessionCookies, resolveSessionCookies, } from "./session-cookies.js";
 import { generateToken } from "./tokens.js";
 // Double-entry cookie write used at login and switch-tenant. The auth cookie is
 // the HttpOnly carrier of the JWT; the csrf cookie is the JS-readable token the
@@ -35,11 +35,13 @@ function setAuthCookies(c, opts) {
     // would coexist with the new Domain cookie (RFC 6265 treats name+domain as
     // distinct) and the server could bind to the stale host-only token. With
     // __Host- names the unprefixed host-only cookie is a leftover from before
-    // the prefix and is expired too.
-    if (opts.domain !== undefined || isHostPrefixedCookieName(names.auth)) {
+    // the prefix and is expired too (and vice versa, see
+    // expireLegacySessionCookieVariants).
+    if (opts.domain !== undefined) {
         deleteCookie(c, AUTH_COOKIE_BASE, { path: "/" });
         deleteCookie(c, CSRF_COOKIE_BASE, { path: "/" });
     }
+    expireLegacySessionCookieVariants(c, opts.cookies);
     // Must precede the setCookie calls: browsers apply Set-Cookie in order and
     // a retired domain equal to the new one is rejected at config time.
     // Retired domains only ever carried unprefixed names (a __Host- cookie has no
@@ -59,7 +61,7 @@ function normalizeCookieDomain(domain) {
 }
 // A malformed entry would corrupt the Set-Cookie header; an entry equal to the
 // current cookieDomain would make login delete the cookie it just sets.
-export function assertRetiredCookieDomains(retiredCookieDomains, cookieDomain) {
+function assertRetiredCookieDomains(retiredCookieDomains, cookieDomain) {
     const current = cookieDomain === undefined ? undefined : normalizeCookieDomain(cookieDomain);
     for (const entry of retiredCookieDomains ?? []) {
         if (entry === "" || normalizeCookieDomain(entry) === "") {
@@ -320,6 +322,10 @@ export function createAuthRoutes(dispatcher, jwt, config) {
         retiredCookieDomains: config.retiredCookieDomains,
     });
     assertRetiredCookieDomains(config.retiredCookieDomains, cookieDomain);
+    if (config.mfaVerifyHandler && !config.switchTenantMfaGateHandler) {
+        throw new Error("createAuthRoutes: mfaVerifyHandler is set but switchTenantMfaGateHandler is not; " +
+            "POST /auth/switch-tenant would mint admin sessions without the second factor");
+    }
     const retiredCookieDomains = config.retiredCookieDomains ?? [];
     // Single hop-count-aware IP getter for every rate-limit call site below —
     // see AuthRoutesConfig.trustedProxyHops and client-ip.ts's resolveClientIp
@@ -328,19 +334,45 @@ export function createAuthRoutes(dispatcher, jwt, config) {
     // shared "unknown" bucket.
     const clientIpResolver = config.resolver ?? createClientIpResolver(config.trustedProxyHops ?? 0, "createAuthRoutes");
     const getClientIp = (c) => clientIpResolver.resolve(clientIpSourceFromHonoContext(c));
-    async function switchTenantMfaGateResponse(c, user, targetTenantId) {
+    // undefined = no gate wired (setup without MFA). "clearedRoles" are the roles the gate decided on,
+    // so the minted session cannot differ from what the gate checked.
+    async function switchTenantMfaGate(c, user, targetTenantId) {
         if (!config.switchTenantMfaGateHandler)
             return undefined;
         const gate = await dispatcher.write(config.switchTenantMfaGateHandler, { userId: user.id, tenantId: targetTenantId }, createSystemUser(user.tenantId));
         if (!gate.isSuccess) {
             const status = gate.error.httpStatus; // @cast-boundary engine-payload
-            return c.json({ isSuccess: false, error: gate.error }, status);
+            return { response: c.json({ isSuccess: false, error: gate.error }, status) };
         }
         // @cast-boundary engine-payload — the gate handler's three-shape result
         const gateData = gate.data;
         if (gateData.kind === "mfa-gate-clear")
-            return undefined;
-        return pendingMfaStepResponse(c, gateData);
+            return { clearedRoles: gateData.roles };
+        return { response: pendingMfaStepResponse(c, gateData) };
+    }
+    // Global roles (SystemAdmin etc.) come from the user feature when userQuery is wired, so they survive
+    // the tenant switch. buildSessionRoles calls stripForbiddenMembershipRoles on the membership side only — a backstop
+    // for a role a projection rebuild resurrected past command-time validation (engine/membership-roles).
+    async function resolveSwitchTenantRoles(user, membership) {
+        let globalRoles = [];
+        if (config.userQuery) {
+            try {
+                // @cast-boundary engine-payload — dispatcher.query returnt unknown,
+                // Per the AuthUserRow contract, userQuery returns a row with a roles column.
+                const userRow = (await dispatcher.query(config.userQuery, { id: user.id }, createSystemUser(user.tenantId)));
+                // roles is jsonb string[] (multiSelect); parseRoles also accepts legacy
+                // JSON-encoded text from pre-0.217.0 rows.
+                globalRoles = parseRoles(userRow?.roles ?? null);
+            }
+            catch (e) {
+                // Non-fatal: when global roles cannot be resolved the switch continues with tenant roles
+                // only. A server error carrying just the cause would hurt the UX more than a switch without
+                // SystemAdmin, which the user notices and reports.
+                if (!isUnknownHandlerError(e))
+                    throw e;
+            }
+        }
+        return buildSessionRoles(globalRoles, membership.roles);
     }
     // Shared tail of every route that ends a request logged-in: create the
     // session record (if wired), sign the JWT, set the auth+csrf cookies. Was
@@ -709,13 +741,13 @@ export function createAuthRoutes(dispatcher, jwt, config) {
             }
             // Session creation + JWT sign + cookies — see mintSessionAndRespond.
             const token = await mintSessionAndRespond(c, data.session);
-            const landingPath = landingPathFragment({
-                flow: "signup",
+            const signupOutcome = {
                 roles: data.session.roles,
                 tenantId: data.session.tenantId,
                 tenantKey: data.tenantKey,
                 ...(data.handover !== undefined && { handover: data.handover }),
-            });
+            };
+            const landingPath = landingPathFragment({ flow: "signup", ...signupOutcome });
             return c.json({
                 isSuccess: true,
                 token,
@@ -960,49 +992,20 @@ export function createAuthRoutes(dispatcher, jwt, config) {
             return switchTenantRejectionResponse(c, activeMembership.reason);
         }
         const membership = activeMembership.membership;
-        // Globale Rollen aus user-feature lesen wenn userQuery wired —
-        // tenant-unabhängige Rollen (SystemAdmin etc.) überleben so den
-        // tenant-switch. `parseRoles` liegt utils-side, hier inline-deserialize
-        // damit das Framework keine bundled-features-Imports kriegt.
-        let globalRoles = [];
-        if (config.userQuery) {
-            try {
-                // @cast-boundary engine-payload — dispatcher.query returnt unknown,
-                // userQuery liefert per AuthUserRow-Contract eine row mit roles-spalte.
-                const userRow = (await dispatcher.query(config.userQuery, { id: user.id }, createSystemUser(user.tenantId)));
-                // roles is jsonb string[] (multiSelect); parseRoles also accepts legacy
-                // JSON-encoded text from pre-0.217.0 rows.
-                globalRoles = parseRoles(userRow?.roles ?? null);
-            }
-            catch (e) {
-                // Non-fatal: globale Rollen kann nicht aufgelöst werden → switch
-                // läuft weiter mit nur tenant-rollen. Server-error mit nur dem
-                // Cause ohne Stack hochwerfen wäre für die UX schlimmer als ein
-                // Tenant-Switch ohne SystemAdmin (User merkt's und meldet's). Log
-                // it via the dispatcher so Ops sieht's.
-                if (!isUnknownHandlerError(e))
-                    throw e;
-            }
-        }
+        const gate = await switchTenantMfaGate(c, user, targetTenantId);
+        if (gate !== undefined && "response" in gate)
+            return gate.response;
+        const sessionRoles = gate !== undefined ? gate.clearedRoles : await resolveSwitchTenantRoles(user, membership);
         // Issue new JWT with the target tenant and its roles. Claims MUST be
         // recomputed for the new tenant — stale claims from the previous
         // tenant would leak identity facts across tenancies (e.g. teamId from
         // tenant A accidentally surviving into tenant B's session). The
         // resolver runs each feature's r.authClaims() hook under the new
         // TenantDb scope.
-        // buildSessionRoles calls stripForbiddenMembershipRoles internally and
-        // strips reserved roles from the membership side only — globalRoles
-        // (where SystemAdmin legitimately lives) is never filtered. Backstop for a
-        // membership role that a projection rebuild resurrected past command-time
-        // validation (see engine/membership-roles).
-        const mergedRoles = buildSessionRoles(globalRoles, membership.roles);
-        const pendingMfaStep = await switchTenantMfaGateResponse(c, user, targetTenantId);
-        if (pendingMfaStep !== undefined)
-            return pendingMfaStep;
         const targetSession = {
             id: user.id,
             tenantId: targetTenantId,
-            roles: mergedRoles,
+            roles: sessionRoles,
             // Tenant-independent prefs must survive the switch (fw#2343).
             ...tenantIndependentPrefs(user),
         };
@@ -1021,7 +1024,7 @@ export function createAuthRoutes(dispatcher, jwt, config) {
         // fresh csrfToken is minted (inside the helper) so a compromised csrf-
         // value can't cross a tenant boundary.
         const newToken = await mintSessionAndRespond(c, sessionForJwt);
-        return c.json({ token: newToken, tenantId: targetTenantId, roles: mergedRoles });
+        return c.json({ token: newToken, tenantId: targetTenantId, roles: sessionRoles });
     });
     return api;
 }

package/dist/api/extra-route.d.ts

@@ -57,6 +57,9 @@ export type SystemDispatchArgs = {
     readonly payload: unknown;
     readonly tenantId: TenantId;
 };
+export type RoleDispatchArgs = SystemDispatchArgs & {
+    readonly roles: readonly string[];
+};
 export type SignatureExtraRouteDeps = {
     readonly app: Hono<any, any>;
     readonly registry: Registry;

package/dist/api/index.d.ts

@@ -8,7 +8,7 @@ export type { AuthRoutesConfig, LoginRateLimiter, SessionChecker, SessionCreator
 export { createAuthRoutes, createInMemoryLoginRateLimiter, createRedisLoginRateLimiter, } from "./auth-routes.js";
 export type { ClientIpHeaderSource, ClientIpResolver } from "./client-ip.js";
 export { assertValidTrustedProxyHops, clientIpSourceFromHonoContext, createClientIpResolver, extractSocketAddress, parseTrustedProxyHopsEnv, TRUSTED_PROXY_HOPS_ENV, UNKNOWN_CLIENT_IP, } from "./client-ip.js";
-export type { AnonymousExtraRoute, AnonymousExtraRouteDeps, ExtraRouteDefinition, ExtraRouteEntry, ExtraRouteRejectionOptions, ExtraRouteRejectionStatus, SignatureExtraRoute, SignatureExtraRouteDeps, SignatureExtraRouteVerifyDeps, SignatureExtraRouteVerifyRequest, SystemDispatchArgs, UserExtraRoute, UserExtraRouteDeps, } from "./extra-route.js";
+export type { AnonymousExtraRoute, AnonymousExtraRouteDeps, ExtraRouteDefinition, ExtraRouteEntry, ExtraRouteRejectionOptions, ExtraRouteRejectionStatus, RoleDispatchArgs, SignatureExtraRoute, SignatureExtraRouteDeps, SignatureExtraRouteVerifyDeps, SignatureExtraRouteVerifyRequest, SystemDispatchArgs, UserExtraRoute, UserExtraRouteDeps, } from "./extra-route.js";
 export { ExtraRouteEntries, ExtraRouteRejection, signatureRoute } from "./extra-route.js";
 export type { CachedResponseInit, CachePolicy } from "./http-cache.js";
 export { cacheControlHeader, cachedResponse, computeRevisionEtag, computeStrongEtag, computeWeakEtag, etagMatches, parseIfNoneMatch, } from "./http-cache.js";
@@ -26,7 +26,7 @@ export type { MetricsRouteOptions } from "./route-registrars.js";
 export { createMetricsApp, DEFAULT_MAX_REQUEST_BYTES, isPrometheusMeter, } from "./route-registrars.js";
 export { createApiRoutes } from "./routes.js";
 export type { KumikoServer, ServerOptions } from "./server.js";
-export { buildServer, makeDispatchSystemQuery, makeDispatchSystemWrite } from "./server.js";
+export { buildServer, makeDispatchSystemQuery, makeDispatchSystemWrite, makeDispatchWriteAs, withFileProviderResolver, } from "./server.js";
 export type { ResolvedSessionCookies, SessionCookieBase, SessionCookieNames, } from "./session-cookies.js";
 export { AUTH_COOKIE_BASE, CSRF_COOKIE_BASE, getSessionCookies, HOST_COOKIE_PREFIX, isHostPrefixedCookieName, resolveSessionCookieNames, resolveSessionCookies, sessionCookieName, sessionCookiesMiddleware, TENANT_COOKIE_BASE, } from "./session-cookies.js";
 export type { SseBroker, SseClient, SseEvent } from "./sse-broker.js";

package/dist/api/index.js

@@ -15,7 +15,7 @@ export { readonlyRequestContext as requestContext, } from "./request-context.js"
 export { buildRequestContextDataFromRequest, requestIdMiddleware, } from "./request-id-middleware.js";
 export { createMetricsApp, DEFAULT_MAX_REQUEST_BYTES, isPrometheusMeter, } from "./route-registrars.js";
 export { createApiRoutes } from "./routes.js";
-export { buildServer, makeDispatchSystemQuery, makeDispatchSystemWrite } from "./server.js";
+export { buildServer, makeDispatchSystemQuery, makeDispatchSystemWrite, makeDispatchWriteAs, withFileProviderResolver, } from "./server.js";
 export { AUTH_COOKIE_BASE, CSRF_COOKIE_BASE, getSessionCookies, HOST_COOKIE_PREFIX, isHostPrefixedCookieName, resolveSessionCookieNames, resolveSessionCookies, sessionCookieName, sessionCookiesMiddleware, TENANT_COOKIE_BASE, } from "./session-cookies.js";
 export { createSseBroker } from "./sse-broker.js";
 export { createSseRoute, SSE_HEARTBEAT_INTERVAL_MS } from "./sse-route.js";

package/dist/api/routes.js

@@ -3,6 +3,7 @@ import { HTTPException } from "hono/http-exception";
 import { streamSSE } from "hono/streaming";
 import { AccessDeniedError, reraiseAsKumikoError, serializeError, toKumikoError, ValidationError, } from "../errors/index.js";
 import { createFallbackLogger } from "../logging/index.js";
+import { isPlainObject } from "../utils/is-plain-object.js";
 import { stringifyJson } from "../utils/safe-json.js";
 import { Routes } from "./api-constants.js";
 import { getAuthTokenExpiry, getUser } from "./auth-middleware.js";
@@ -43,7 +44,9 @@ export function createApiRoutes(dispatcher, options = {}) {
     api.post(Routes.batch, async (c) => {
         const user = getUser(c);
         const body = await readJsonObject(c);
-        if (!Array.isArray(body.commands)) {
+        const requestId = parseRequestId(body["requestId"]);
+        const rawCommands = body["commands"];
+        if (!Array.isArray(rawCommands)) {
             // Client-shape violation → ValidationError (400, code=validation_error)
             // matches what a Zod-level schema failure would produce if /batch had
             // one. Client SDKs can key off the uniform validation contract.
@@ -53,25 +56,27 @@ export function createApiRoutes(dispatcher, options = {}) {
                         path: "commands",
                         code: "invalid_type",
                         i18nKey: "errors.validation.invalid_type",
-                        params: { expected: "array", received: typeof body.commands },
+                        params: { expected: "array", received: typeof rawCommands },
                     },
                 ],
             }));
         }
+        const commands = rawCommands.map((raw, index) => parseDispatchCommand(raw, `commands.${index}`));
         try {
-            for (const cmd of body.commands)
+            for (const cmd of commands)
                 assertPayloadDepthAllowed(cmd.payload);
             if (user.pat) {
-                for (const cmd of body.commands)
+                for (const cmd of commands)
                     assertPatAllowed(user, cmd.type);
             }
-            const result = await dispatcher.batch(body.commands, user, body.requestId);
+            const result = await dispatcher.batch(commands, user, requestId);
             if (!result.isSuccess) {
                 const err = reraiseAsKumikoError(result.error);
-                const requestId = requestContext.get()?.requestId;
-                const failedType = result.failedIndex != null ? body.commands[result.failedIndex]?.type : undefined;
-                logServerFault(err, requestId, failedType);
-                const { error } = serializeError(err, requestId, requestContext.get()?.errorDocs);
+                const ctxRequestId = requestContext.get()?.requestId;
+                const failedType = result.failedIndex != null ? commands[result.failedIndex]?.type : undefined;
+                logServerFault(err, ctxRequestId, failedType);
+                const { error } = serializeError(err, ctxRequestId, requestContext.get()?.errorDocs);
+                setRetryAfterHeader(c, err);
                 // Keep failedIndex + results alongside the error envelope so callers
                 // can tell which command in the batch failed and inspect the partial
                 // results from the successful commands before the rollback.
@@ -86,7 +91,7 @@ export function createApiRoutes(dispatcher, options = {}) {
         }
         catch (e) {
             // single "type" doesn't apply to a batch; command types keep the fault context.
-            return writeErrorResponse(c, toKumiko(e), body.commands?.map((cmd) => cmd.type).join(","));
+            return writeErrorResponse(c, toKumiko(e), commands.map((cmd) => cmd.type).join(","));
         }
     });
     api.post(Routes.query, async (c) => {
@@ -270,23 +275,37 @@ function invalidBodyError(path, expected, received) {
     });
 }
 // Malformed or non-object JSON is a client error; letting c.req.json() throw
-// would surface as an unclassified 500.
-// @cast-boundary request-body — shape is validated per route right after
+// would surface as an unclassified 500. Callers validate the fields they read.
 async function readJsonObject(c) {
     const raw = await c.req.json().catch(() => undefined);
     if (raw === undefined)
         throw invalidBodyError("body", "json", "malformed");
-    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    if (!isPlainObject(raw)) {
         throw invalidBodyError("body", "object", raw === null ? "null" : typeof raw);
     }
     return raw;
 }
+function parseRequestId(raw) {
+    if (raw === undefined || typeof raw === "string")
+        return raw;
+    throw invalidBodyError("requestId", "string", typeof raw);
+}
+// `path` prefixes the reported field path; empty for a top-level body.
+function parseDispatchCommand(raw, path) {
+    const at = (key) => (path === "" ? key : `${path}.${key}`);
+    if (!isPlainObject(raw)) {
+        throw invalidBodyError(path === "" ? "body" : path, "object", raw === null ? "null" : typeof raw);
+    }
+    const type = raw["type"];
+    if (typeof type !== "string" || type === "") {
+        throw invalidBodyError(at("type"), "string", typeof type);
+    }
+    return { type, payload: raw["payload"] };
+}
 async function readDispatchBody(c) {
     const body = await readJsonObject(c);
-    if (typeof body.type !== "string" || body.type === "") {
-        throw invalidBodyError("type", "string", typeof body.type);
-    }
-    return { type: body.type, payload: body.payload, requestId: body.requestId };
+    const command = parseDispatchCommand(body, "");
+    return { ...command, requestId: parseRequestId(body["requestId"]) };
 }
 // Rejects payloads nested deeper than MAX_PAYLOAD_DEPTH before they reach
 // per-handler Zod validation — recursive Zod parsing (and any downstream
@@ -381,6 +400,13 @@ function logServerFault(err, requestId, type) {
         stack: cause instanceof Error ? cause.stack : err.stack,
     });
 }
+// Same floor of 1 as the rate-limit middleware: "Retry-After: 0" invites an instant retry loop.
+function setRetryAfterHeader(c, err) {
+    // skip: most errors carry no retry hint, so the response gets no Retry-After header
+    if (err.retryAfterSeconds === undefined)
+        return;
+    c.header("Retry-After", String(Math.max(1, Math.ceil(err.retryAfterSeconds))));
+}
 // For /write + /batch: keep the isSuccess flag so clients can flip on a single
 // boolean (mirrors the success shape). The actual error body is the
 // error-contract payload nested under .error.
@@ -388,6 +414,7 @@ function writeErrorResponse(c, err, type) {
     const requestId = requestContext.get()?.requestId;
     logServerFault(err, requestId, type);
     const { error } = serializeError(err, requestId, requestContext.get()?.errorDocs);
+    setRetryAfterHeader(c, err);
     return c.json({ isSuccess: false, error }, err.httpStatus); // @cast-boundary engine-payload
 }
 function clientAbortResponse(c, requestId, type) {
@@ -404,6 +431,7 @@ function queryErrorResponse(c, err, type) {
         return clientAbortResponse(c, requestId, type);
     logServerFault(err, requestId, type);
     const body = serializeError(err, requestId, requestContext.get()?.errorDocs);
+    setRetryAfterHeader(c, err);
     return c.json(body, err.httpStatus); // @cast-boundary engine-payload
 }
 // A raw throw under the request signal (signal.throwIfAborted(), an aborted
@@ -424,5 +452,6 @@ export function handleUncaughtRouteError(err, c) {
         return clientAbortResponse(c, requestId);
     const kumikoError = toKumiko(err);
     logServerFault(kumikoError, requestId);
+    setRetryAfterHeader(c, kumikoError);
     return c.json(serializeError(kumikoError, requestId, requestContext.get()?.errorDocs), kumikoError.httpStatus); // @cast-boundary engine-payload
 }

package/dist/api/server.d.ts

@@ -1,6 +1,6 @@
 import type { CacheSyncBus } from "@cosmicdrift/kumiko-types/cache-sync-types";
 import { Hono } from "hono";
-import type { PgClient } from "../db/connection.js";
+import type { PgListenClient } from "../db/connection.js";
 import { type AppContext, type Registry, type RunIn, type WriteResult } from "../engine/types/index.js";
 import type { ErrorDocsConfig } from "../errors/docs-url.js";
 import type { Lifecycle } from "../lifecycle/index.js";
@@ -13,7 +13,7 @@ import { type SystemHooks } from "../pipeline/lifecycle-pipeline.js";
 import { type AuthEndpointRateLimitOptions, type GlobalIpRateLimitOptions } from "../rate-limit/index.js";
 import { type AnonymousAccessResolved } from "./auth-middleware.js";
 import { type AuthRoutesConfig } from "./auth-routes.js";
-import { type ExtraRouteDefinition, type SystemDispatchArgs } from "./extra-route.js";
+import { type ExtraRouteDefinition, type RoleDispatchArgs, type SystemDispatchArgs } from "./extra-route.js";
 import { type JwtHelper, type JwtKeyring } from "./jwt.js";
 import type { SseBroker } from "./sse-broker.js";
 export type ServerOptions = {
@@ -43,7 +43,7 @@ export type ServerOptions = {
             jobTrigger?: boolean;
             accessInvalidation?: boolean;
         };
-        pgClient?: PgClient;
+        pgClient?: PgListenClient;
     };
     observability?: ObservabilityProvider;
     observabilityOptions?: ObservabilityOptions;
@@ -82,4 +82,5 @@ export type KumikoServer = {
 export declare function withFileProviderResolver(registry: Registry, context: AppContext, cacheSync?: CacheSyncBus): AppContext;
 export declare function buildServer(options: ServerOptions): KumikoServer;
 export declare function makeDispatchSystemWrite(dispatcher: Dispatcher): (args: SystemDispatchArgs) => Promise<WriteResult>;
+export declare function makeDispatchWriteAs(dispatcher: Dispatcher): (args: RoleDispatchArgs) => Promise<WriteResult>;
 export declare function makeDispatchSystemQuery(dispatcher: Dispatcher): (args: SystemDispatchArgs) => Promise<unknown>;