@cosmicdrift/kumiko-framework 0.385.0 → 0.387.0

package/LICENSE

@@ -1,57 +1,21 @@
-Business Source License 1.1
-
-Parameters
-
-Licensor:             Marc Frost
-
-Licensed Work:        @cosmicdrift/kumiko-framework
-                      The Licensed Work is © 2026 Marc Frost.
-
-Additional Use Grant: 
-You may use the Licensed Work in production for any purpose, including 
-commercially, EXCEPT for the Restricted Use. 
-
-"Restricted Use" is defined as using the Licensed Work to provide a platform 
-or service to third parties that allows them to host, deploy, or run their 
-own applications built with the Licensed Work. This includes, but is not 
-limited to: managed hosting services, software-as-a-service (SaaS) platforms, 
-platform-as-a-service (PaaS), developer platforms, or any multi-tenant 
-managed offering of the Licensed Work.
-
-This restriction does not apply to the Licensor, any entity controlled by, 
-controlling, or under common control with the Licensor ("Affiliates"), or 
-contractors acting on their behalf. The Licensor remains free to use the 
-Licensed Work for any purpose, including for the operation of kumiko.rocks.
-
-Change Date:          2030-05-05
-Change License:       Apache License, Version 2.0
-
-
-Terms
-
-The Licensor hereby grants you the right to copy, modify, create derivative works, 
-redistribute, and make non-production use of the Licensed Work. The Licensor may 
-make an Additional Use Grant, above, permitting limited production use.
-
-Effective on the Change Date, or the fourth anniversary of the first publicly 
-available distribution of the Licensed Work under this License, whichever comes 
-first, this License will convert to the Change License.
-
-This Business Source License governs use of the Licensed Work in all cases, except 
-as to any use that is explicitly granted in the Additional Use Grant above or 
-under the Change License after the Change Date.
-
-If your use of the Licensed Work does not comply with the requirements of this 
-License, you must cease use of the Licensed Work immediately.
-
-All copies of the Licensed Work, and all derivative works thereof, must include 
-this License.
-
-This License does not grant you any right, title, or interest in any trademark, 
-logo, or branding of the Licensor, except as required to comply with this License.
-
-TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN 
-“AS IS” BASIS. LICENSOR DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 
-WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, 
-TITLE, AND NON-INFRINGEMENT. IN NO EVENT WILL LICENSOR BE LIABLE FOR ANY DAMAGES 
-ARISING OUT OF OR RELATED TO THIS LICENSE OR THE USE OF THE LICENSED WORK.
+MIT License
+
+Copyright (c) 2026 Marc Frost
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,6 @@
 # @cosmicdrift/kumiko-framework
 
-[![License: BUSL-1.1](https://img.shields.io/badge/License-BUSL--1.1-blue.svg)](../../LICENSE)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../../LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/)
 
 Framework core for Kumiko — engine, pipeline, API, DB, event-store, and
@@ -131,4 +131,4 @@ sample under `samples/`; the roadmap lives in [docs/plans/uebersicht.md](../../d
 
 ## License
 
-BUSL-1.1 — see [LICENSE](../../LICENSE).
+MIT, see [LICENSE](../../LICENSE).

package/agents/widgets.md

@@ -16,11 +16,11 @@ Value exports of `@cosmicdrift/kumiko-renderer/web`.
 | `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. |
+| `CollapsibleSection` | Collapsible section using native <details> with React-controlled state; otherwise the open attribute resets to its initial value on every parent re-render. |
+| `ComparisonTable` | Transposed comparison table: row = metric, column = variant, with the best column optionally highlighted for each metric. |
+| `DateField` | Date field = 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). |
+| `DetailList` | Read-only key-value list for detail views (dimmed label on the left, value on the right). |
 | `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` |  |
@@ -32,10 +32,10 @@ Value exports of `@cosmicdrift/kumiko-renderer/web`.
 | `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. |
+| `EmptyState` | Empty state with an optional icon and CTA, using the dashed-box style of entityList empty states as a standalone widget for custom screens. |
+| `ErrorState` | Error state based on the Banner primitive, with a retry button. |
+| `FeedList` | Non-tabular compact list (e.g. "upcoming appointments") — primary text plus an optional right-aligned trailing value for each row. |
+| `FileField` | File upload = Field + Input(kind:"file"\|"image"), based on FileRef. |
 | `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` |  |
@@ -46,14 +46,14 @@ Value exports of `@cosmicdrift/kumiko-renderer/web`.
 | `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. |
+| `LoadingState` | Loading state with skeleton rows styled like cards; `rows` controls the height. |
 | `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>. |
+| `MiniStat` | Compact metric tile (without an icon) — for dense KPI grids. |
+| `ModeSwitch` | Segmented control for mutually exclusive modes—the prominent alternative to the buried <select>. |
 | `MoneyField` |  |
 | `NavProvider` |  |
 | `NavTree` |  |
-| `NumberField` | Zahlenfeld = Field + Input(kind:"number") in einem — nimmt der Screen die wiederholte id/name/value/onChange-Verdrahtung ab. |
+| `NumberField` | Number field = Field + Input(kind:"number"); avoids repeating the id/name/value/onChange wiring at each screen. |
 | `PageSection` |  |
 | `PdfPreview` |  |
 | `PercentField` |  |
@@ -64,22 +64,22 @@ Value exports of `@cosmicdrift/kumiko-renderer/web`.
 | `PrimitivesProvider` |  |
 | `ProfileMenu` |  |
 | `ProgressBar` | Progress bar, `value` 0..1 (clamped). |
-| `ProgressList` | Liste aus Label/Wert-Kopfzeile + Fortschrittsbalken pro Eintrag (z.B. |
+| `ProgressList` | Label/value header and progress bar for each entry (for example, loan repayment progress). |
 | `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"). |
+| `RangeField` | Slider = 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). |
+| `ResultPanel` | Result section for a calculator: SectionCard with an empty state (Banner) or a metric list (DetailList) plus optional extras (table, notes). |
+| `ResultTable` | Static, prop-driven result table for calculated rows (tranches, scenarios). |
 | `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"). |
+| `SectionCard` | Section with a title and optional action slot (range switcher, filter) — replaces repeated `<section className={CARD}>…<h2>` blocks in custom screens. |
+| `SelectField` | Select field = 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` |  |
@@ -91,15 +91,15 @@ Value exports of `@cosmicdrift/kumiko-renderer/web`.
 | `SidebarUser` |  |
 | `Sparkline` |  |
 | `Stack` |  |
-| `StatCard` | Icon-tragende Kennzahl-Kachel mit optionalem Delta-Chip, Trend-Zeile und Sparkline. |
+| `StatCard` | Icon-bearing metric tile with an optional delta chip, trend line, and 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"). |
+| `TextField` | Text field = Field + Input(kind:"text"). |
+| `TextareaField` | Multi-line text field = 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). |
+| `TimeseriesChart` | Time-series line chart (smoothed line with area fill). |
 | `ToastProvider` |  |
 | `TokensProvider` |  |
 | `Topbar` |  |
@@ -112,16 +112,16 @@ Value exports of `@cosmicdrift/kumiko-renderer/web`.
 
 | Name | Description |
 | --- | --- |
-| `useBrowserNavApi` | React-Hook der eine NavApi aus der Browser-History baut. |
-| `useBrowserTokensApi` | Hook der eine TokensApi für den Browser baut. |
+| `useBrowserNavApi` | React hook that builds a NavApi from browser history. |
+| `useBrowserTokensApi` | Builds a TokensApi for the browser. |
 | `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. |
+| `useDraft` | Form state for calculator screens: a draft object plus `patch` for partial updates, and `field(name)` that provides `{ id, name, value, onChange }` props ready for field widgets (NumberField/MoneyField/PercentField). |
 | `useForm` |  |
 | `useIsNarrowViewport` |  |
 | `useIsViewportBelow` |  |
-| `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. |
+| `useLiveEvents` | Hook for a useQuery-like consumer. |
+| `useLocale` | Provides the current LocaleResolver and automatically subscribes to locale changes — the calling component re-renders when the language changes. |
 | `useNav` |  |
 | `usePrimitives` |  |
 | `useQuery` |  |
@@ -129,8 +129,8 @@ Value exports of `@cosmicdrift/kumiko-renderer/web`.
 | `useStore` |  |
 | `useStoreSelector` |  |
 | `useToast` |  |
-| `useTokenController` | Volle API inkl. |
-| `useTokens` | Read-only Tokens-Hook. |
+| `useTokenController` | Full API including theme toggling, for a dark/light switch button. |
+| `useTokens` | Read-only tokens hook. |
 | `useTranslation` | `t("key", params)` resolves in this order: 1. |
 | `useUserRoles` |  |
 
@@ -138,17 +138,17 @@ Value exports of `@cosmicdrift/kumiko-renderer/web`.
 
 | Name | Description |
 | --- | --- |
-| `applyTokensToCssVars` | Historisch: schrieb Tokens auf :root als CSS-vars. |
+| `applyTokensToCssVars` | Historically wrote tokens to :root as CSS variables. |
 | `buildFileUploadFormData` |  |
 | `buildNavRegistrySlice` |  |
 | `buildNavRegistrySliceForApp` |  |
-| `cn` | shadcn-Standard-Helper: clsx für konditionales Zusammenstecken, tailwind-merge für Konfliktauflösung (z.B. |
+| `cn` | Standard shadcn helper: `clsx` combines conditional classes, while `tailwind-merge` resolves conflicts (for example, `px-2 px-4` → `px-4`). |
 | `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. |
+| `createBrowserLocaleResolver` | Default resolver when createKumikoApp is booted without a `locale` option. |
+| `createEventSourceLiveEvents` | Returns an EventSource-backed `LiveEventSubscriber`. |
 | `createKumikoApp` |  |
 | `createPublicSurface` |  |
-| `createStaticLocaleResolver` | Default-Resolver für Apps ohne eigene i18n-Schicht. |
+| `createStaticLocaleResolver` | Default resolver for apps without their own i18n layer. |
 | `downloadFileRef` |  |
 | `fetchFileRefBlob` |  |
 | `fileNameFromContentDisposition` |  |
@@ -157,16 +157,16 @@ Value exports of `@cosmicdrift/kumiko-renderer/web`.
 | `formatMoney` |  |
 | `formatPath` |  |
 | `parsePath` |  |
-| `parseTargetFromSearchParams` | Inverse — parse the current search-params back into a TargetRef. |
+| `parseTargetFromSearchParams` | Parses the current search parameters back into a TargetRef. |
 | `postWithDownload` |  |
 | `qualifyScreenId` |  |
 | `readLoadedBuild` |  |
 | `reparentAppSchemaNavs` |  |
 | `resolveDefaultId` |  |
 | `saveBlobAsFile` |  |
-| `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. |
+| `smoothPath` | Quadratic midpoint technique: smooths the zigzag line without overshoot (~5 lines instead of a Catmull-Rom/Bezier fit). |
+| `synthesizeActionFormEntity` | Builds a minimal EntityDefinition from the inline fields of an ActionForm or SecretMint screen. |
+| `synthesizeActionFormScreen` | Converts an ActionFormScreenDefinition or SecretMintScreenDefinition to the EntityEditScreen shape expected by RenderEdit. |
 | `uploadFileRef` | Posts one file to the stack's file endpoint (double-submit CSRF) and returns the new FileRef id. |
 
 ## Constants
@@ -177,7 +177,7 @@ Value exports of `@cosmicdrift/kumiko-renderer/web`.
 | `STATUS_TONE_TEXT` |  |
 | `cssVarTokens` | Tokens with var-string values. |
 | `defaultPrimitives` |  |
-| `defaultTokens` | Default-Tokens — identisch zu `cssVarTokens` (var-string-refs). |
+| `defaultTokens` | Default tokens—identical to `cssVarTokens` (variable-string references). |
 | `lightTokens` |  |
 
 ## Classes

package/dist/api/api-constants.js

@@ -137,8 +137,8 @@ export const TENANT_HEADER_NAME = "X-Tenant";
 export const LOCALE_HEADER_NAME = "X-Locale";
 // Internal-only signal set by buildServer's app.notFound() to mark "no
 // route matched" 404s so tryHonoFirst (server-runtime) can tell them apart
-// from a matched route's own deliberate 404 (e.g. default-deny reads) —
-// see kumiko-framework#2435. Never reaches a client: tryHonoFirst and every
+// from a matched route's own deliberate 404 (e.g. default-deny reads).
+// Never reaches a client: tryHonoFirst and every
 // direct app.fetch() passthrough strip it before the response leaves the
 // process, since its presence would otherwise let a caller distinguish
 // "unregistered path" from "registered path, access denied" — a leak the

package/dist/api/auth-middleware.js

@@ -126,13 +126,13 @@ export function authMiddleware(jwt, options = {}) {
             // No JWT → either fall through as anonymous (when the server opts in)
             // or reject with 401 (preserving the pre-anonymous default).
             //
-            // Auth-routes-Sonderfall: `/api/auth/*`-Pfade die NICHT in
-            // PUBLIC_API_PATHS sind (tenants, switch-tenant, logout) brauchen
-            // einen JWT — aber keinen Tenant-Resolve. Würden sie durch
-            // handleAnonymous laufen, wirft resolveTenant 400 tenant_required
-            // wenn kein Tenant declared ist. Falsche Diagnose: das Problem ist
-            // missing authentication, nicht missing tenant. Daher hier direkt
-            // 401, ohne den anonymous-Tenant-Flow zu durchlaufen.
+            // Special case for auth routes: `/api/auth/*` paths that are NOT in
+            // PUBLIC_API_PATHS (tenants, switch-tenant, logout) require a JWT —
+            // but not tenant resolution. If they went through handleAnonymous,
+            // resolveTenant would throw 400 tenant_required when no tenant is
+            // declared. That would be the wrong diagnosis: the problem is missing
+            // authentication, not a missing tenant. Therefore, return 401 here
+            // without entering the anonymous-tenant flow.
             if (anonymousAccess) {
                 if (isSessionRequiredApiPath(c.req.path)) {
                     return middlewareReject(c, {

package/dist/api/auth-rate-limiters.js

@@ -93,10 +93,14 @@ export function createRedisLoginRateLimiter(redis, maxAttempts = 10, windowMs =
             // shipped (PTTL returns -1 for "no expiry set, key exists") — without
             // it, those pre-existing keys would grow forever with no way back to
             // a normal window.
-            const count = (await redis.eval(`local c = redis.call('INCR', KEYS[1])
+            const count = await redis.eval(`local c = redis.call('INCR', KEYS[1])
          if c == 1 or redis.call('PTTL', KEYS[1]) < 0 then redis.call('PEXPIRE', KEYS[1], ARGV[1]) end
-         return c`, 1, redisKey, windowMs));
-            return count <= maxAttempts;
+         return c`, 1, redisKey, windowMs);
+            const attempts = typeof count === "string" && /^\d+$/.test(count) ? Number(count) : count;
+            if (typeof attempts !== "number" || !Number.isInteger(attempts)) {
+                throw new TypeError(`redis INCR script returned ${String(count)}, expected an integer`);
+            }
+            return attempts <= maxAttempts;
         },
         async reset(key) {
             await redis.del(`${prefix}${key}`);

package/dist/api/auth-routes-mfa.js

@@ -130,7 +130,7 @@ export function registerMfaPreauthEnableStartRoute(ctx) {
                 // Second axis, independent of the IP-derived bucket above: the
                 // preauthSetupToken is minted by login.write.ts and not freely
                 // choosable, so this cap survives an attacker rotating
-                // x-forwarded-for to bypass the IP bucket (kumiko-framework#1522).
+                // x-forwarded-for to bypass the IP bucket.
                 const tokenAllowed = await rateLimiter.check(preauthTokenKeyOf(body.preauthSetupToken));
                 if (!tokenAllowed) {
                     return c.json({ isSuccess: false, error: "rate_limited" }, 429);

package/dist/api/auth-routes-session.js

@@ -121,7 +121,7 @@ export function registerSessionRoutes(ctx) {
             id: user.id,
             tenantId: targetTenantId,
             roles: sessionRoles,
-            // Tenant-independent prefs must survive the switch (fw#2343).
+            // Tenant-independent prefs must survive the switch.
             ...tenantIndependentPrefs(user),
         };
         const claims = await dispatcher.resolveAuthClaims(targetSession);

package/dist/api/auth-routes-shared.js

@@ -2,8 +2,9 @@ import * as z from "zod";
 import { createAnonymousUser } from "../engine/system-user.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/index.js";
 import { NotFoundError } from "../errors/index.js";
-// Cross-device try-first handover (kumiko-framework#3035 follow-up,
-// offlot-app#454): an optional tenant-handover grant the signup-request
+import { createFallbackLogger } from "../logging/utils.js";
+const log = createFallbackLogger("kumiko");
+// Cross-device try-first handover: an optional tenant-handover grant the signup-request
 // route forwards to the handler for server-side verification and binding —
 // the grant itself never appears anywhere else (URL, mail, log, response).
 export const SignupRequestBody = z.object({
@@ -68,7 +69,10 @@ export function registerTokenRequestRoute(opts) {
         // rate_limited is an expected, attacker-triggerable outcome; logging it
         // would flood the sink and bury real misconfiguration errors.
         if (!result.isSuccess && result.error.code !== "rate_limited") {
-            console.error(`[kumiko] token request handler "${opts.requestHandler}" failed: ${result.error.code}`);
+            log.error("token request handler failed", {
+                handler: opts.requestHandler,
+                code: result.error.code,
+            });
         }
         return c.json({ isSuccess: true });
     });

package/dist/api/auth-routes-signup.js

@@ -63,7 +63,7 @@ export function registerSignupRoutes(ctx) {
                 // switcher), signup knows exactly ONE membership — the frontend UI uses
                 // it directly as the redirect target.
                 tenantKey: data.tenantKey,
-                // Cross-device try-first handover (kumiko-framework#3035 follow-up):
+                // Cross-device try-first handover:
                 // present only when signup-confirm actually claimed a bound grant —
                 // absent, not null, so a client that doesn't know the field sees
                 // nothing unusual.

package/dist/api/client-ip.js

@@ -1,3 +1,5 @@
+import { createFallbackLogger } from "../logging/utils.js";
+const log = createFallbackLogger("kumiko");
 // Single source for client-IP extraction, shared by every IP-keyed rate
 // limit and audit field. Deriving the caller IP independently per call site
 // makes it easy for one to silently trust the first XFF entry, which is
@@ -70,7 +72,7 @@ export function createClientIpResolver(trustedProxyHops, context = "resolveClien
         if (trustedProxyHops === 0) {
             if (xff !== undefined && xff.trim().length > 0 && !warnedUnexpectedForwardedFor) {
                 warnedUnexpectedForwardedFor = true;
-                console.warn("[kumiko] received X-Forwarded-For but trustedProxyHops is 0 (no proxy trusted) — " +
+                log.warn("received X-Forwarded-For but trustedProxyHops is 0 (no proxy trusted) — " +
                     "ignoring it. Running behind a proxy? Set trustedProxyHops, otherwise all clients " +
                     "share one rate-limit bucket.");
             }

package/dist/api/extra-route.js

@@ -1,5 +1,5 @@
 // ExtraRoute — declarative replacement for the old `extraRoutes: (app, deps)
-// => void` closure (kumiko-framework#3050). Every entry declares its access
+// => void` closure. Every entry declares its access
 // tier (`entry`) up front; buildServer wires the matching guard + deps
 // instead of handing every route a raw db/redis escape hatch.
 export const ExtraRouteEntries = {

package/dist/api/pii-leak-guard.js

@@ -1,5 +1,7 @@
 import { PII_CIPHERTEXT_PREFIX } from "../crypto/index.js";
+import { createFallbackLogger } from "../logging/utils.js";
 import { resolveRouteLabel } from "./route-label.js";
+const log = createFallbackLogger("kumiko:pii-leak-guard");
 const isProductionEnv = () => process.env["NODE_ENV"] === "production";
 // Version-agnostic: catches both the current PII_CIPHERTEXT_PREFIX and any
 // older/decrypt-only format version still present in unmigrated rows.
@@ -28,7 +30,7 @@ export function piiCiphertextResponseGuard() {
         // skip: clean response — the common case
         if (!CIPHERTEXT_RE.test(text))
             return;
-        const detail = `[api] JSON response for ${c.req.method} ${resolveRouteLabel(c)} contains a PII ciphertext ` +
+        const detail = `JSON response for ${c.req.method} ${resolveRouteLabel(c)} contains a PII ciphertext ` +
             `("${PII_CIPHERTEXT_PREFIX}…") — a raw DB read leaked to the API surface. ` +
             `Decrypt before returning (decryptStoredPii / executor read path).`;
         if (!isProductionEnv()) {
@@ -36,7 +38,7 @@ export function piiCiphertextResponseGuard() {
             // skip: response replaced with the loud 500 above — nothing left to do
             return;
         }
-        console.error(detail);
+        log.error(detail);
         const headers = new Headers(c.res.headers);
         headers.delete("content-length");
         c.res = new Response(text.replace(CIPHERTEXT_REDACT_RE, "[pii-redacted]"), {

package/dist/api/readiness.js

@@ -74,11 +74,11 @@ export function redisPingCheck(redis) {
         },
     };
 }
-// Lag-Check für den Async-Event-Dispatcher. Liest HWM + Consumer-Cursor aus
-// der DB — kein extra Redis/Runtime-State. Fail-Schwelle ist in EventIds
-// (bigint), weil das die natürliche Einheit ist (events sind monoton id'd).
-// Ein Tuning-Beispiel: maxLagEvents = 1_000 bedeutet "wenn die Projection
-// mehr als 1k Events hinter HWM ist, stoppe neue Traffic-Zuweisung".
+// Lag check for the asynchronous event dispatcher. Reads the HWM and consumer cursor from
+// the database, without relying on extra Redis or runtime state. The failure threshold is
+// measured in event IDs (`bigint`), the natural unit because events have monotonically
+// increasing IDs. For example, `maxLagEvents = 1_000` stops routing new traffic when the
+// projection falls more than 1,000 events behind the HWM.
 export function dispatcherLagCheck(db, consumerNames, maxLagEvents) {
     return {
         name: "dispatcher_lag",

package/dist/api/redis-sse-broker.js

@@ -1,8 +1,10 @@
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import { createFallbackLogger } from "../logging/utils.js";
 import { redisChannelPrefixFromEnv, redisClientOptionsFromEnv, } from "../redis/client.js";
 import { createRedisPubSubSignal } from "../redis/pubsub-signal.js";
 import { createSseBroker, readNonEmptyStringArray, } from "./sse-broker.js";
-// Channel namespace for cross-replica fanout (fw#2625). Every pod publishes
+const log = createFallbackLogger("kumiko:sse-broker");
+// Channel namespace for cross-replica fanout. Every pod publishes
 // here and every pod's psubscribe listens here, so a push on one instance
 // reaches SSE clients connected to any other instance without a shared
 // cursor — Pub/Sub for connected-client fanout, the event-store's shared
@@ -21,9 +23,9 @@ export function isRedisSseBroker(broker) {
 // runProdApp must funnel through this rather than each deciding on their
 // own — runProdApp doing exactly that (building an in-memory broker
 // unconditionally, then passing it in as ServerOptions.sseBroker) is why
-// fw#2625's fanout fix (fw#2630) shipped without ever taking effect in
-// production: an explicit ServerOptions.sseBroker always wins in
-// buildServer, so its own REDIS_URL-based default never ran.
+// the fanout fix shipped without ever taking effect in production: an
+// explicit ServerOptions.sseBroker always wins in buildServer, so its own
+// REDIS_URL-based default never ran.
 export function createDefaultSseBroker(env = process.env) {
     const redisUrl = env["REDIS_URL"];
     const ownedRedisSseBroker = redisUrl
@@ -109,7 +111,7 @@ export function createRedisSseBroker(opts) {
     signal.onMessage((channel, payload) => {
         if (channel.startsWith(channelPrefix)) {
             if (!isSseEvent(payload)) {
-                console.error(`[kumiko:sse-broker] dropping malformed event on "${channel}"`);
+                log.error(`dropping malformed event on "${channel}"`);
                 // skip: malformed payload already logged above, nothing to deliver
                 return;
             }
@@ -132,7 +134,7 @@ export function createRedisSseBroker(opts) {
         pushToChannel(channel, event) {
             return signal.publishConfirmed(`${channelPrefix}${channel}`, event);
         },
-        // fw#1601: this is the security-critical call — a revoked session's
+        // This is the security-critical call — a revoked session's
         // stream must close on every replica, not just the one that observed
         // the revocation event. Publishing (rather than calling inner directly,
         // like the in-memory broker does) is what makes that true here.

package/dist/api/request-context.d.ts

@@ -21,6 +21,7 @@ export type RequestContextData = {
         readonly risk: AgentRisk;
     };
     readonly chargedRateLimitBuckets?: Set<string>;
+    readonly agentToolCall?: true;
 };
 export declare const requestContext: {
     run<T>(data: RequestContextData, fn: () => T): T;
@@ -41,4 +42,5 @@ export declare function runWithOrigin<T>(origin: {
     };
 }, fn: () => T): T;
 export declare function runAsDirectCallEntry<T>(fn: () => T): T;
+export declare function isAgentToolCallScope(): boolean;
 export declare function runWithWriteOrigin<T>(origin: WriteOrigin, fn: () => T): T;

package/dist/api/request-context.js

@@ -48,15 +48,24 @@ export function runWithOrigin(origin, fn) {
             : new Set(),
     }, fn);
 }
-// Clears entryHandler so the next dispatch inside fn becomes the new entry —
-// used by dispatchToolCall so the invoked tool handler, not the surrounding
-// turn/approve handler, is what the irreversible-operation gate sees.
+// Clears entryHandler so the next dispatch inside fn becomes the new entry, letting
+// the irreversible-operation gate see the invoked tool handler instead of the
+// surrounding turn/approve handler. Reserved for dispatchToolCall, so it also marks
+// the scope as an agent tool call; it always mints a scope, because an agent loop
+// running outside any request must still carry that marker.
 export function runAsDirectCallEntry(fn) {
     const current = requestContext.get();
-    if (!current)
-        return fn();
-    const { entryHandler: _entryHandler, ...rest } = current;
-    return requestContext.run(rest, fn);
+    const requestId = current?.requestId ?? requestContext.generateId();
+    const { entryHandler: _entryHandler, ...rest } = current ?? {};
+    return requestContext.run({
+        ...rest,
+        requestId,
+        correlationId: current?.correlationId ?? requestId,
+        agentToolCall: true,
+    }, fn);
+}
+export function isAgentToolCallScope() {
+    return requestContext.get()?.agentToolCall === true;
 }
 // An ungated origin never mints a scope: seeds and boot writes keep their missing context.
 export function runWithWriteOrigin(origin, fn) {

package/dist/api/routes.js

@@ -129,7 +129,7 @@ export function createApiRoutes(dispatcher, options = {}) {
     // dispatch gates (feature/rate-limit/access/validation) plus the handler's
     // first yield — is raced against a heartbeat timeout BEFORE streamSSE, so
     // a gate failure that settles in time maps to its real HTTP status via
-    // queryErrorResponse instead of a flushed-200 error frame (framework#1517).
+    // queryErrorResponse instead of a flushed-200 error frame.
     api.post(Routes.stream, async (c) => {
         const user = getUser(c);
         const body = await readDispatchBody(c);
@@ -149,7 +149,7 @@ export function createApiRoutes(dispatcher, options = {}) {
         // Hook the raw request signal directly so a client disconnect during the
         // pre-pull still reclaims the generator instead of leaking a Redis
         // subscription/DB cursor held open inside its still-unresolved first
-        // `.next()` (framework#1528).
+        // `.next()`.
         const signal = c.req.raw.signal;
         const onPrePullAbort = () => void generator.return(undefined);
         signal.addEventListener("abort", onPrePullAbort);