@cosmicdrift/kumiko-framework 0.362.0 → 0.364.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

@@ -1,3 +1,4 @@
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { getCookie } from "hono/cookie";
 import { TENANT_TEARDOWN_STATUSES } from "../engine/active-membership.js";
 import { createAnonymousUser } from "../engine/system-user.js";
@@ -7,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
@@ -160,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 },
                 });
@@ -235,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
@@ -482,17 +490,18 @@ async function requestsCancelDestruction(c) {
         return false;
     try {
         const path = c.req.path;
-        const body = (await c.req.raw.clone().json());
+        const body = await c.req.raw.clone().json();
         if (path === "/api/write") {
-            return body.type === TENANT_LIFECYCLE_CANCEL_QN;
+            return propertyOf(body, "type") === TENANT_LIFECYCLE_CANCEL_QN;
         }
         if (path === "/api/batch") {
+            const commands = propertyOf(body, "commands");
             // every(), not some(): a batch mixing the cancel command with other
             // writes must NOT wave the whole batch through the teardown gate —
             // only a batch consisting solely of cancel-destruction is exempt.
-            return (Array.isArray(body.commands) &&
-                body.commands.length > 0 &&
-                body.commands.every((command) => command.type === TENANT_LIFECYCLE_CANCEL_QN));
+            return (Array.isArray(commands) &&
+                commands.length > 0 &&
+                commands.every((command) => propertyOf(command, "type") === TENANT_LIFECYCLE_CANCEL_QN));
         }
     }
     catch {

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

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, } 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, } 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/redis-sse-broker.js

@@ -1,3 +1,4 @@
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { redisChannelPrefixFromEnv, redisClientOptionsFromEnv, } from "../redis/client.js";
 import { createRedisPubSubSignal } from "../redis/pubsub-signal.js";
 import { createSseBroker, readNonEmptyStringArray, } from "./sse-broker.js";
@@ -37,7 +38,9 @@ export function createDefaultSseBroker(env = process.env) {
 function isSseEvent(value) {
     return (typeof value === "object" &&
         value !== null &&
+        "type" in value &&
         typeof value.type === "string" &&
+        "data" in value &&
         typeof value.data === "object" &&
         value.data !== null);
 }
@@ -50,25 +53,24 @@ function isSseEvent(value) {
 // sparing something it doesn't understand: fail-closed on a mixed rolling
 // deploy. Anything malformed also falls back to userwide.
 function parseInvalidationScope(payload) {
-    if (typeof payload !== "object" || payload === null)
+    if (!isPlainObject(payload))
         return { kind: "user" };
-    const record = payload;
-    if ("scope" in record) {
-        const { scope } = record;
+    if ("scope" in payload) {
+        const { scope } = payload;
         if (scope === "sessions") {
-            const sessionIds = readNonEmptyStringArray(record["sessionIds"]);
+            const sessionIds = readNonEmptyStringArray(payload["sessionIds"]);
             if (sessionIds)
                 return { kind: "sessions", sessionIds };
         }
         if (scope === "pat-tokens") {
-            const tokenIds = readNonEmptyStringArray(record["tokenIds"]);
+            const tokenIds = readNonEmptyStringArray(payload["tokenIds"]);
             if (tokenIds)
                 return { kind: "pat-tokens", tokenIds };
         }
         return { kind: "user" };
     }
-    if ("keptSessionId" in record) {
-        const { keptSessionId } = record;
+    if ("keptSessionId" in payload) {
+        const { keptSessionId } = payload;
         if (typeof keptSessionId === "string" && keptSessionId.length > 0) {
             return { kind: "all-except-session", keptSessionId };
         }

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) => {
@@ -172,7 +177,7 @@ export function createApiRoutes(dispatcher, options = {}) {
             // in-flight .next(), so awaiting here would block the response until
             // that pending pull resolves (which may be never for an idle stream).
             void generator.return(undefined).catch(() => { });
-            return c.body(null, CLIENT_CLOSED_REQUEST_STATUS); // @cast-boundary non-standard client-closed-request status, Hono's union doesn't include it
+            return c.body(null, CLIENT_CLOSED_REQUEST_STATUS); // @cast-boundary third-party-type-gap — non-standard client-closed-request status, Hono's union doesn't include it
         }
         return streamSSE(c, async (stream) => {
             stream.onAbort(() => {
@@ -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,13 +414,14 @@ 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) {
     logClientWarn("request aborted by client", requestId, type, {
         status: CLIENT_CLOSED_REQUEST_STATUS,
     });
-    return c.body(null, CLIENT_CLOSED_REQUEST_STATUS); // @cast-boundary non-standard client-closed-request status, Hono's union doesn't include it
+    return c.body(null, CLIENT_CLOSED_REQUEST_STATUS); // @cast-boundary third-party-type-gap — non-standard client-closed-request status, Hono's union doesn't include it
 }
 // For /query + /command: no isSuccess on success (just { data } / {ok}), so we
 // keep the same lean shape on failure — only the `error` key.
@@ -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

@@ -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 = {
@@ -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>;

package/dist/api/server.js

@@ -217,9 +217,7 @@ export function buildServer(options) {
     // Master for the payload-bucket HMAC: the current signing secret (the
     // keyring's signKid for rotation setups). buildServer always has one, so
     // the digest is available whenever a handler declares additionalRateLimits.
-    const payloadDigest = createPayloadDigest(typeof options.jwtSecret === "string"
-        ? options.jwtSecret
-        : (options.jwtSecret.keys[options.jwtSecret.signKid] ?? ""));
+    const payloadDigest = createPayloadDigest(payloadDigestMasterSecret(options.jwtSecret));
     const rateLimitResolver = options.context.rateLimit ??
         (wrappedRedis && wantsResolver ? createRateLimitResolver({ redis: wrappedRedis }) : undefined);
     if (!rateLimitResolver) {
@@ -836,9 +834,7 @@ export function buildServer(options) {
                 dispatchSystemQuery,
                 clientIpResolver,
             });
-            mountHonoRoute(app, route.method, route.path, honoHandler, route.entry === ExtraRouteEntries.signature
-                ? bodyLimitForRoutePath(route.path, options.maxRequestBytes ?? DEFAULT_MAX_REQUEST_BYTES)
-                : []);
+            mountHonoRoute(app, route.method, route.path, honoHandler, bodyLimitForRoutePath(route.path, options.maxRequestBytes ?? DEFAULT_MAX_REQUEST_BYTES));
         }
     }
     // /version-Default registriert NACH feature-routes — Hono "first match
@@ -949,6 +945,13 @@ c, dispatcher, clientIpResolver) {
 export function makeDispatchSystemWrite(dispatcher) {
     return ({ handlerQn, payload, tenantId }) => dispatcher.write(handlerQn, payload, createSystemUser(tenantId, [ROLES.SystemAdmin]));
 }
+// Privilege-scope: the system user gets exactly the roles the caller names —
+// no implicit SystemAdmin — so a seed can write data gated on app roles.
+// Same trust requirement as makeDispatchSystemWrite: never expose to a raw
+// request, only to code that already proved its own authenticity.
+export function makeDispatchWriteAs(dispatcher) {
+    return ({ handlerQn, payload, tenantId, roles }) => dispatcher.write(handlerQn, payload, createSystemUser(tenantId, roles));
+}
 export function makeDispatchSystemQuery(dispatcher) {
     return ({ handlerQn, payload, tenantId }) => dispatcher.query(handlerQn, payload, createSystemUser(tenantId, [ROLES.SystemAdmin]));
 }
@@ -1199,3 +1202,12 @@ function entitiesWithSearchableScreen(registry) {
     }
     return [...entities];
 }
+function payloadDigestMasterSecret(jwtSecret) {
+    if (typeof jwtSecret === "string")
+        return jwtSecret;
+    const signingSecret = jwtSecret.keys[jwtSecret.signKid];
+    if (signingSecret === undefined) {
+        throw new Error(`[kumiko] jwtSecret.signKid "${jwtSecret.signKid}" not found in jwtSecret.keys`);
+    }
+    return signingSecret;
+}

package/dist/api/session-cookies.d.ts

@@ -19,5 +19,6 @@ export declare function hostOnlyDeleteOptions(name: string): {
     path: "/";
     secure?: true;
 };
+export declare function expireLegacySessionCookieVariants(c: Context, cookies: ResolvedSessionCookies): void;
 export declare function clearSessionCookies(c: Context, cookies: ResolvedSessionCookies): void;
 export declare function hasDuplicateSessionCookie(c: Context, names: SessionCookieNames): boolean;

package/dist/api/session-cookies.js

@@ -1,4 +1,4 @@
-import { AUTH_COOKIE_BASE, CSRF_COOKIE_BASE, isHostPrefixedCookieName, resolveSessionCookieNames, } from "@cosmicdrift/kumiko-types/session-cookies";
+import { AUTH_COOKIE_BASE, CSRF_COOKIE_BASE, isHostPrefixedCookieName, resolveSessionCookieNames, sessionCookieName, } from "@cosmicdrift/kumiko-types/session-cookies";
 import { deleteCookie } from "hono/cookie";
 export { AUTH_COOKIE_BASE, CSRF_COOKIE_BASE, HOST_COOKIE_PREFIX, isHostPrefixedCookieName, resolveSessionCookieNames, sessionCookieName, TENANT_COOKIE_BASE, } from "@cosmicdrift/kumiko-types/session-cookies";
 const SESSION_COOKIES_KEY = "sessionCookies";
@@ -41,6 +41,24 @@ export function getSessionCookies(c, fallback) {
 export function hostOnlyDeleteOptions(name) {
     return isHostPrefixedCookieName(name) ? { path: "/", secure: true } : { path: "/" };
 }
+// Expires the name variant the current config does not write, in both
+// directions: unprefixed leftovers when names are `__Host-` prefixed, and the
+// `__Host-` cookies when a later cookieDomain or secureCookies:false resolves
+// to unprefixed names. Browsers prefer the prefixed csrf cookie when reading
+// the token, so a leftover one would 403 every write until it expires.
+export function expireLegacySessionCookieVariants(c, cookies) {
+    if (isHostPrefixedCookieName(cookies.names.auth)) {
+        deleteCookie(c, AUTH_COOKIE_BASE, { path: "/" });
+        deleteCookie(c, CSRF_COOKIE_BASE, { path: "/" });
+        // skip: the unprefixed names are the only legacy variant when the config writes __Host- names.
+        return;
+    }
+    if (cookies.secure) {
+        deleteCookie(c, sessionCookieName(AUTH_COOKIE_BASE, { secure: true }), hostPrefixedDelete);
+        deleteCookie(c, sessionCookieName(CSRF_COOKIE_BASE, { secure: true }), hostPrefixedDelete);
+    }
+}
+const hostPrefixedDelete = { path: "/", secure: true };
 // Expire every variant: the Domain cookie (current) and the host-only one
 // (from before cookieDomain), otherwise a cookie left over from an earlier
 // config keeps the session alive after logout. With __Host- names the
@@ -50,10 +68,7 @@ export function clearSessionCookies(c, cookies) {
     const { names, domain } = cookies;
     deleteCookie(c, names.auth, hostOnlyDeleteOptions(names.auth));
     deleteCookie(c, names.csrf, hostOnlyDeleteOptions(names.csrf));
-    if (isHostPrefixedCookieName(names.auth)) {
-        deleteCookie(c, AUTH_COOKIE_BASE, { path: "/" });
-        deleteCookie(c, CSRF_COOKIE_BASE, { path: "/" });
-    }
+    expireLegacySessionCookieVariants(c, cookies);
     if (domain !== undefined) {
         deleteCookie(c, AUTH_COOKIE_BASE, { path: "/", domain });
         deleteCookie(c, CSRF_COOKIE_BASE, { path: "/", domain });