@cosmicdrift/kumiko-dev-server 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/dist/build-server-bundle.d.ts

@@ -3,10 +3,10 @@ export type BuildServerBundleOptions = {
     readonly cwd?: string;
     /** Output-Folder relativ zu cwd. Default: "dist-server". */
     readonly outDir?: string;
-    /** Zusätzliche Pakete die zur Laufzeit installiert sein müssen
-     *  (beyond RUNTIME_EXTERNALS). App-spezifisch — Default leer. */
+    /** Additional packages that must be installed at runtime
+     *  (beyond RUNTIME_EXTERNALS). App-specific; defaults to empty. */
     readonly extraRuntimeExternals?: readonly string[];
-    /** Zusätzliche Build-only-Externals. App-spezifisch — Default leer. */
+    /** Additional build-only externals. App-specific; defaults to empty. */
     readonly extraBuildOnlyExternals?: readonly string[];
     /** Additional entry points (paths relative to cwd, e.g. "bin/remote-probe.ts"),
      *  each emitted as `<basename>.js` next to server.js and sharing its chunks.
@@ -22,9 +22,9 @@ export type BuildServerBundleResult = {
     readonly outDir: string;
     /** Named entry files (server.js, plus kumiko.js, worker.js, bootstrap.js and extra entries when present). */
     readonly entries: readonly BuildServerBundleEntry[];
-    /** Geteilte Framework-Chunks (von splitting). */
+    /** Shared framework chunks (from splitting). */
     readonly chunks: readonly BuildServerBundleEntry[];
-    /** Gesamt-Größe aller Outputs (entries + chunks) in Bytes. */
+    /** Total size of all outputs (entries + chunks) in bytes. */
     readonly totalBytes: number;
     readonly runtimeDeps: Readonly<Record<string, string>>;
 };
@@ -37,7 +37,7 @@ export type KumikoBuildArgs = {
 /** Parse `kumiko-build [app-dir] [--entry <path>]...` (also `--entry=<path>`).
  *  Unknown flags and a missing `--entry` value throw instead of being ignored. */
 export declare function parseKumikoBuildArgs(args: readonly string[]): KumikoBuildArgs;
-/** Read `package.json#kumiko.extraRuntimeExternals` for kumiko-build (#1484).
+/** Read `package.json#kumiko.extraRuntimeExternals` for kumiko-build.
  *  Invalid / missing shapes → empty list (CLI stays convention-driven). */
 export declare function readExtraRuntimeExternals(cwd: string): readonly string[];
 export declare function formatServerBuildResult(result: BuildServerBundleResult, durationMs: number): string;

package/dist/build-server-bundle.js

@@ -1,20 +1,20 @@
-// buildServerBundle — Production-Server-Bundle für Kumiko-Apps. Pendant zu
-// buildProdBundle (Client). Convention-Driven Discovery liest bin/main.ts
-// (+ optional <repo>/bin/kumiko.ts) und produziert ein runtime-self-contained
-// dist-server/ aus dem ein Bun-Alpine-Container ohne Monorepo bootet.
+// buildServerBundle — Production server bundle for Kumiko apps. Counterpart to
+// buildProdBundle (client). Convention-driven discovery reads bin/main.ts
+// (+ optional <repo>/bin/kumiko.ts) and produces a runtime-self-contained
+// dist-server/ from which a Bun-Alpine container can boot without the monorepo.
 //
 // Convention:
 //
-//   bin/main.ts            →  dist-server/server.js   (App-Boot, ruft runProdApp)
-//   <repo>/bin/kumiko.ts   →  dist-server/kumiko.js   (Migrate-CLI: `schema apply`,
-//                             gefunden via walk-up bis bin/kumiko.ts)
+//   bin/main.ts            →  dist-server/server.js   (app boot, calls runProdApp)
+//   <repo>/bin/kumiko.ts   →  dist-server/kumiko.js   (migration CLI: `schema apply`,
+//                             found by walking up to bin/kumiko.ts)
 //   bin/worker.ts          →  dist-server/worker.js   (optional, next to bin/main.ts:
 //                             background worker as its own process from the same image)
 //   bin/bootstrap.ts       →  dist-server/bootstrap.js (optional, next to bin/main.ts:
 //                             one-shot runBootstrap provisioning, run as a k8s Job)
 //   extraEntries[i]        →  dist-server/<basename>.js (opt-in, e.g. a probe script
 //                             `bin/remote-probe.ts`; CLI: repeatable `--entry <path>`)
-//   dist-server/package.json → runtime-deps mit gepinnten Versionen
+//   dist-server/package.json → runtime dependencies with pinned versions
 //
 // All entries are built in ONE Bun.build call with `splitting`: the framework
 // lands once as shared chunk-*.js and server.js, kumiko.js, worker.js,
@@ -24,41 +24,41 @@
 // Output:
 //
 //   dist-server/
-//     server.js            ← App-Boot-Entry
-//     kumiko.js            ← Migrate-CLI-Entry (wenn bin/kumiko.ts gefunden)
+//     server.js            ← app boot entry
+//     kumiko.js            ← migration CLI entry (if bin/kumiko.ts is found)
 //     worker.js            ← worker entry (if bin/worker.ts sits next to main.ts)
 //     bootstrap.js         ← provisioning entry (if bin/bootstrap.ts sits next to main.ts)
 //     <basename>.js        ← one per extraEntries path
-//     chunk-*.js           ← geteilte Framework-Chunks
-//     package.json         ← runtime-deps mit gepinnten Versionen
+//     chunk-*.js           ← shared framework chunks
+//     package.json         ← runtime dependencies with pinned versions
 //     bun.lock             ← written by writeServerLockfile (kumiko-build), not by buildServerBundle
 //
-// Externals — Pakete die NICHT ins Bundle gebakt werden, sondern via
-// `bun install` im Runtime-Container nachgeholt werden:
+// Externals — packages that are NOT bundled, but installed via
+// `bun install` in the runtime container:
 //
-//   RUNTIME_EXTERNALS — wird zur Laufzeit gebraucht (native bindings,
-//                       worker-threads, dynamic-require). Landet in
+//   RUNTIME_EXTERNALS — needed at runtime (native bindings,
+//                       worker threads, dynamic require). Added to
 //                       dist-server/package.json#dependencies.
 //
-//   BUILD_ONLY_EXTERNALS — referenziert nur transitiv im Framework, vom
-//                          App-Code aber nie. Tree-Shake wirft sie aus dem
-//                          Bundle, der external-Marker schaltet nur das
-//                          resolution-during-build ab. NICHT in runtime-deps.
+//   BUILD_ONLY_EXTERNALS — referenced only transitively in the framework,
+//                          never by app code. Tree-shaking removes them from
+//                          the bundle; the external marker only disables
+//                          resolution during the build. NOT in runtime dependencies.
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { parseJsonOrThrow, parseJsonSafe } from "@cosmicdrift/kumiko-framework/utils";
 const hasBun = typeof Bun !== "undefined";
-// Pakete die das Bundle zur Laufzeit weiter referenziert (`from "<pkg>"` nach
-// Tree-Shake). Native bindings (argon2), worker-thread-Loader (bullmq,
-// ioredis), dynamic-require (postgres, temporal-polyfill) — alles was unter
-// Bun-bundling bricht. (drizzle-kit/drizzle-orm sind raus: der Migrate-Pfad
-// nutzt jetzt den framework-eigenen runMigrationsFromDir, kein drizzle-kit.)
-// meilisearch: deliberately here, not in BUILD_ONLY_EXTERNALS below — apps
+// Packages that the bundle still references at runtime (`from "<pkg>"` after
+// tree-shaking). Native bindings (argon2), worker-thread loaders (bullmq,
+// ioredis), and dynamic require (postgres, temporal-polyfill) — anything that
+// breaks under Bun bundling. (drizzle-kit/drizzle-orm are excluded: the
+// migration path now uses the framework's runMigrationsFromDir, not drizzle-kit.)
+// meilisearch is deliberately here, not in BUILD_ONLY_EXTERNALS below — apps
 // that import createMeilisearchAdapter (kumiko-framework/search/meilisearch)
 // reference the package at runtime (no native binding, plain HTTP client,
-// but a real runtime import). Found 2026-07-19: money-horse prod crash
-// "Cannot find package 'meilisearch'" because it used to sit in
+// but a real runtime import). A production crash in money-horse,
+// "Cannot find package 'meilisearch'", occurred because it used to be in
 // BUILD_ONLY_EXTERNALS instead.
 const RUNTIME_EXTERNALS = [
     "@node-rs/argon2",
@@ -71,11 +71,11 @@ const RUNTIME_EXTERNALS = [
     "pino-pretty",
     "meilisearch",
 ];
-// Pakete die nur im Build-Stack erscheinen (transitive Imports im Framework),
-// aber vom App-Code nicht referenziert werden. Ohne external-Markierung
-// scheitert bun build an dynamic-imports. Tree-Shake wirft sie eh aus dem
-// Bundle — der Marker schaltet nur das resolution-during-build ab. NICHT in
-// runtime-deps.
+// Packages that appear only in the build stack (transitive framework imports),
+// but are not referenced by app code. Without the external marker,
+// bun build fails on dynamic imports. Tree-shaking removes them from the
+// bundle; the marker only disables resolution during the build. NOT in
+// runtime dependencies.
 const BUILD_ONLY_EXTERNALS = [
     "@planetscale/database",
     "@libsql/client",
@@ -86,9 +86,9 @@ const BUILD_ONLY_EXTERNALS = [
     // ink (kumiko-tui) hat react-devtools-core als dev-only transitive import.
     "react-devtools-core",
 ];
-// Bun benennt Entries nach Source-Basename (bin/main.ts → main.js). server.js
-// ist die Runtime-Convention; der Entry wird von nichts importiert (nur die
-// chunks werden referenziert, per relativem Pfad), darum ist der Rename sicher.
+// Bun names entries after the source basename (bin/main.ts → main.js). server.js
+// is the runtime convention; the entry is not imported by anything (only the
+// chunks are referenced by relative path), so renaming it is safe.
 const ENTRY_RENAMES = { "main.js": "server.js" };
 const OPTIONAL_SIBLING_ENTRY_NAMES = ["worker", "bootstrap"];
 // Output names the built-in entries occupy ("main" is renamed to server.js).
@@ -141,8 +141,8 @@ export async function buildServerBundle(options = {}) {
     ];
     await rm(outDir, { recursive: true, force: true });
     await mkdir(outDir, { recursive: true });
-    // Ein Bun.build-Call mit allen Entries + splitting → das Framework wird
-    // einmal als shared chunk abgelegt statt pro Entry inlined.
+    // One Bun.build call with all entries plus splitting stores the framework
+    // once as a shared chunk instead of inlining it into every entry.
     const optionalSiblingEntries = OPTIONAL_SIBLING_ENTRY_NAMES.map((baseName) => discoverSiblingEntry(dirname(serverEntry), baseName)).filter((path) => path !== undefined);
     const entrypoints = [
         serverEntry,
@@ -164,8 +164,8 @@ export async function buildServerBundle(options = {}) {
         const logs = result.logs.map(String).join("\n");
         throw new Error(`[buildServerBundle] build FAILED:\n${logs}`);
     }
-    // Größe von Disk lesen, nicht aus out.size — letzteres ist für gesplittete
-    // Entry-Points unzuverlässig (meldet teils ~0 für den Entry-Stub).
+    // Read the size from disk rather than out.size — the latter is unreliable for
+    // split entry points and sometimes reports ~0 for the entry stub.
     const entries = [];
     const chunks = [];
     for (const out of result.outputs) {
@@ -209,9 +209,9 @@ function discoverSiblingEntry(dir, baseName) {
     }
     return undefined;
 }
-// Walking up vom App-cwd bis ein Verzeichnis mit `bin/kumiko.ts` gefunden wird.
-// Failsafe: nach 8 Levels aufgeben — nichts gefunden, kein Repo-Root, dann
-// liefert die Funktion undefined und der Caller skippt das CLI-Bundle.
+// Walk up from the app cwd until a directory containing `bin/kumiko.ts` is found.
+// Failsafe: stop after 8 levels. If nothing is found, there is no repo root,
+// so the function returns undefined and the caller skips the CLI bundle.
 function findRepoRoot(start) {
     let cur = start;
     for (let i = 0; i < 8; i++) {
@@ -252,7 +252,7 @@ export function parseKumikoBuildArgs(args) {
     }
     return { appDir, extraEntries };
 }
-/** Read `package.json#kumiko.extraRuntimeExternals` for kumiko-build (#1484).
+/** Read `package.json#kumiko.extraRuntimeExternals` for kumiko-build.
  *  Invalid / missing shapes → empty list (CLI stays convention-driven). */
 export function readExtraRuntimeExternals(cwd) {
     const pkgJson = join(cwd, "package.json");
@@ -271,11 +271,11 @@ export function readExtraRuntimeExternals(cwd) {
         return [];
     return list.filter((x) => typeof x === "string" && x.trim().length > 0);
 }
-// Versionen für RUNTIME_EXTERNALS auflösen: erst aus den installierten
-// node_modules/@cosmicdrift/*-Packages (relativ zu cwd — funktioniert für
-// jede Consumer-App), dann als Zusatz aus packages/framework + bundled-
-// features (Workspace-Checkout des Frameworks selbst). Fallback auf "*"
-// wenn keine Quelle den Namen kennt.
+// Resolve versions for RUNTIME_EXTERNALS: first from installed
+// node_modules/@cosmicdrift/*-packages (relative to cwd, which works for
+// any consumer app), then additionally from packages/framework + bundled-
+// features (the framework's own workspace checkout). Fall back to "*"
+// when no source knows the package name.
 async function resolveRuntimeDepsVersions(cwd, repoRoot, packages) {
     const out = {};
     const pinSources = [
@@ -286,7 +286,7 @@ async function resolveRuntimeDepsVersions(cwd, repoRoot, packages) {
             ]
             : []),
         // node_modules applied last among framework sources so installed versions
-        // win over the repo-root fallback (#1217).
+        // win over the repo-root fallback.
         join(cwd, "node_modules/@cosmicdrift/kumiko-framework/package.json"),
         join(cwd, "node_modules/@cosmicdrift/kumiko-bundled-features/package.json"),
     ];
@@ -299,7 +299,7 @@ async function resolveRuntimeDepsVersions(cwd, repoRoot, packages) {
         Object.assign(allDeps, parsed.dependencies ?? {}, parsed.optionalDependencies ?? {});
     }
     // App package.json fills gaps only — pins extraRuntimeExternals without
-    // overriding framework-native pins the app may also list (#1484 / review).
+    // overriding framework-native pins the app may also list.
     const appPkg = join(cwd, "package.json");
     if (existsSync(appPkg)) {
         const raw = await readFile(appPkg, "utf-8");

package/dist/build.js

@@ -1,6 +1,6 @@
-// Build-Toolchain Public-API. Eigener Sub-Path-Export `@cosmicdrift/kumiko-dev-server/build`
-// damit der Main-Barrel kein Bun-Toolchain-Bundle in Production-Reads zieht
-// (z.B. wenn drizzle-kit die App-Config unter Node lädt).
+// Build-toolchain public API. The dedicated subpath export `@cosmicdrift/kumiko-dev-server/build`
+// keeps the main barrel from pulling the Bun toolchain bundle into production reads
+// (for example, when drizzle-kit loads the app config under Node).
 export { ASSETS_DIR, buildProdBundle, discoverHtmlTemplate, formatBuildResult, injectAssetTags, readClientEntriesConfig, resolveClientEntries, } from "@cosmicdrift/kumiko-server-runtime/build-prod-bundle";
 export { buildServerBundle, discoverServerEntry, formatServerBuildResult, parseKumikoBuildArgs, readExtraRuntimeExternals, } from "./build-server-bundle.js";
 export { writeServerLockfile, } from "./write-server-lockfile.js";

package/dist/compose-stacks.d.ts

@@ -37,7 +37,7 @@ export type GdprStackOptions = {
     };
     /** Optional tokenVerifier provider(s) (e.g. PAT) when `sessions` is on.
      *  Session-only stacks need none — sessions registers sessionStore, which
-     *  satisfies auth-foundation's boot check (#1570). Pass providers when the
+     *  satisfies auth-foundation's boot check. Pass providers when the
      *  app also wants Bearer/PAT auth. */
     readonly providers?: readonly FeatureDefinition[];
     /** Roles allowed to use the compliance-profiles handlers; default access.admin. */
@@ -59,7 +59,7 @@ export type OpsStackOptions = {
  *  on composeFeatures(includeBundled). Pass `mfa` options to mount TOTP.
  *  When `sessions` is on (the default), auth-foundation is mounted alongside it —
  *  the framework's registry now hard-requires it (sessions.requires("auth-foundation")).
- *  Session-only is enough for boot (#1570); optional Bearer/PAT still needs a
+ *  Session-only is enough for boot; optional Bearer/PAT still needs a
  *  tokenVerifier provider from the caller (e.g. createPersonalAccessTokensFeature
  *  ({ scopes })) — PAT scopes are app-specific, so they stay caller-owned. */
 export type IdentityStackOptions = {

package/dist/compose-stacks.js

@@ -1,8 +1,7 @@
 // @runtime runtime
 // Despite living in this "dev"-marked package, every preset here composes
 // @cosmicdrift/kumiko-bundled-features factories, and run-config.ts in every
-// app repo feeds it into the runProdApp boot path, not just runDevApp
-// (kumiko-framework#2337).
+// app repo feeds it into the runProdApp boot path, not just runDevApp.
 //
 // Composable SaaS stack presets — explicit opt-in blocks for run-config.ts.
 // Presets export feature instances only; no implicit PAT scopes or

package/dist/crash-tracker.d.ts

@@ -3,15 +3,11 @@ export type CrashTrackerOptions = {
     readonly windowMs: number;
 };
 export type CrashTracker = {
-    /** Crash bei `now` registrieren. Returns `true` wenn der Wrapper
-     *  noch respawnen darf, `false` wenn das Limit überschritten ist.
+    /** Registers a crash at `now`. Returns `true` if the wrapper may still respawn and `false` if the limit has been exceeded.
      *
-     *  Der Crash wird IMMER aufgenommen, auch wenn `false` zurückkommt —
-     *  der Caller terminiert in dem Fall normalerweise eh. Reuse mit
-     *  "rejected → state unchanged"-Semantik wird nicht unterstützt. */
+     * The crash is always recorded, even when `false` is returned; the caller normally terminates in that case anyway. Reuse with "rejected → state unchanged" semantics is not supported. */
     readonly noteCrash: (now: number) => boolean;
-    /** Anzahl Crashes im Fenster relativ zu `now` — prunt lazy, damit
-     *  der Aufruf auch ohne vorheriges noteCrash konsistent ist. */
+    /** Counts crashes in the window relative to `now`. Prunes lazily so the call is consistent even without a preceding noteCrash. */
     readonly crashCountInWindow: (now: number) => number;
 };
 export declare function createCrashTracker(options: CrashTrackerOptions): CrashTracker;

package/dist/crash-tracker.js

@@ -1,20 +1,11 @@
-// Tracks server-Crashes in einem rollenden Zeitfenster und entscheidet,
-// ob der dev-wrapper noch respawnen darf oder den Crash-Loop aufgeben
-// muss. Liegt als eigener File, damit `kumiko-dev.ts` (bin-Script ohne
-// Test-Setup) eine pure, injizierbare API bekommt — die Logik ist
-// testbar via createCrashTracker, ohne den Wrapper-Prozess fahren zu
-// müssen.
+// Tracks server crashes in a rolling time window and decides whether the dev wrapper may respawn or must stop the crash loop.
+// It lives in a separate file so `kumiko-dev.ts` (a bin script without test setup) has a pure, injectable API; the logic can be tested via createCrashTracker without running the wrapper process.
 //
-// Semantik: ein Crash "zählt im Fenster", wenn er innerhalb der letzten
-// `windowMs` ms vor `now` registriert wurde. Wenn nach Aufnahme des
-// neuen Crashes mehr als `maxCrashes` im Fenster liegen, gibt der
-// Tracker `false` zurück → Wrapper soll aufgeben.
+// A crash counts as being in the window if it was registered within the last `windowMs` ms before `now`. If, after recording the new crash, more than `maxCrashes` are in the window, the tracker returns `false`, so the wrapper must stop.
 export function createCrashTracker(options) {
     const timestamps = [];
     const pruneBefore = (cutoff) => {
-        // Crashes älter als `cutoff` raus. Gleicher Timestamp wie cutoff
-        // bleibt drin (`<` statt `<=`) — symmetrisch zur Fenster-Definition
-        // "innerhalb der letzten windowMs", also Endpoint inklusive.
+        // Removes crashes older than `cutoff`. A timestamp equal to cutoff remains (`<` rather than `<=`) to match the window definition "within the last windowMs", whose endpoint is inclusive.
         while (timestamps.length > 0) {
             const head = timestamps[0];
             if (head !== undefined && head < cutoff)

package/dist/create-kumiko-server.d.ts

@@ -22,10 +22,9 @@ export type DevClientEntry = {
      *  `kumiko.clientEntries[].name` so dev and prod produce identical
      *  asset URLs (`/client-<name>.js`). */
     readonly name: string;
-    /** Absoluter Pfad zur Browser-Entry-Datei. */
+    /** Absolute path to the browser entry file. */
     readonly sourceFile: string;
-    /** Optional eigenes HTML-Template für diesen Entry. Wenn nicht gesetzt,
-     *  wird `htmlPath` (das default-Template) für alle Entries genutzt. */
+    /** Optional HTML template for this entry. If omitted, `htmlPath` (the default template) is used for all entries. */
     readonly htmlPath?: string;
 };
 /** Dev counterpart of `runProdApp.hostDispatch`. Not the same shape: dev names
@@ -58,8 +57,7 @@ export type DevHostDispatchResult = {
     readonly entryName?: string;
     readonly file?: string;
 };
-/** Picks an entry by inspecting the incoming request. Wird von
- *  Multi-Entry-Apps gesetzt; im Single-Entry-Mode irrelevant. */
+/** Picks an entry by inspecting the incoming request. Set by multi-entry apps; irrelevant in single-entry mode. */
 export type DevHostDispatch = (req: Request, deps: {
     readonly systemQuery: PageHeadSystemQuery;
     /** Always empty: dev serves no per-host CSP. */
@@ -69,27 +67,26 @@ export type CreateKumikoServerOptions = {
     /** Features whose entities, handlers, and screens get wired into the
      *  dev stack. Pass every feature the app is supposed to run. */
     readonly features: readonly FeatureDefinition[];
-    /** Absolute path to the browser entry module. The dev-server runs
+    /** Absolute path to the browser entry module. The dev server runs
      *  `Bun.build` on it and serves the output at `/client.js`. Omit to
-     *  run a headless API-only dev-stack (rare — every sample has one).
-     *  Mutually exclusive mit `clientEntries`. */
+     *  run a headless API-only dev stack. Mutually exclusive with
+     *  `clientEntries`. */
     readonly clientEntry?: string;
-    /** Multi-Entry-Mode: mehrere getrennte Bundles, jeweils unter
-     *  `/client-<name>.js`. Mutually exclusive mit `clientEntry`. Setze
-     *  `hostDispatch` mit, sonst bleibt unklar welches Template zurück-
-     *  geht. */
+    /** Multi-entry mode: separate bundles served at
+     *  `/client-<name>.js`. Mutually exclusive with `clientEntry`. Set
+     *  `hostDispatch` as well; otherwise the server cannot determine which
+     *  template to return. */
     readonly clientEntries?: readonly DevClientEntry[];
-    /** Multi-Entry-Mode: Routing pro Request. Inspiziert `Host` (oder
-     *  was auch immer) und liefert eine Discriminated-Union zurück
-     *  (html → entry-bundle, redirect → 30x, not-found → 404).
-     *  Symmetric zu `runProdApp.hostDispatch` damit dev/prod-Drift
-     *  beim Routing unmöglich ist. */
+    /** Multi-entry request routing. Inspects `Host` (or another request
+     *  property) and returns a discriminated union
+     *  (`html` → entry bundle, `redirect` → 30x, `not-found` → 404).
+     *  Mirrors `runProdApp.hostDispatch` so dev and production routing
+     *  remain aligned. */
     readonly hostDispatch?: DevHostDispatch;
-    /** @internal — ersetzt `Bun.build` für Tests. Default ruft die echte
-     *  Bun-Toolchain. Tests unter Node injizieren einen Stub damit der
-     *  Routing-Pfad treibbar bleibt ohne Bun.build aufzurufen.
-     *  KEIN Public-API-Surface — präfixiert mit `_` damit Konsumenten
-     *  wissen dass das ein Test-Seam ist. */
+    /** @internal — replaces `Bun.build` in tests. The default uses the real
+     *  Bun toolchain; Node-based tests inject a stub so the routing path can
+     *  run without calling Bun.build.
+     *  Not part of the public API; the `_` prefix identifies this test seam. */
     readonly _buildBundle?: (sourceFile: string) => Promise<{
         readonly js: string;
         readonly map: string;
@@ -128,41 +125,40 @@ export type CreateKumikoServerOptions = {
      *  this so repeated `createKumikoServer` calls don't accumulate
      *  listeners on the process. Default true (dev-server behaviour). */
     readonly installSignalHandlers?: boolean;
-    /** Auth-Route-Config (login, tenants, switch-tenant, logout). Wenn
-     *  gesetzt wird die Auto-JWT-Mint auf GET / abgeschaltet — der
-     *  Client ist dann selbst fürs Login zuständig. Zur echten Wirkung
-     *  brauchen die dazugehörigen Features (user/tenant/auth-email-
-     *  password) via `features` drin sein. */
+    /** Auth route configuration (login, tenants, switch-tenant, logout). When
+     *  set, disables automatic JWT minting on GET /; the client is responsible
+     *  for login. The corresponding features (user/tenant/auth-email-password)
+     *  must also be included through `features` for these routes to work. */
     readonly auth?: AuthRoutesConfig;
-    /** Extra-AppContext-Keys (z.B. configResolver für config-feature).
-     *  Wird an setupTestStack weitergereicht. Siehe TestStackOptions
-     *  für die erlaubten Shapes (object oder factory-function). */
+    /** Additional AppContext keys, such as `configResolver` for the config
+     *  feature. Forwarded to `setupTestStack`; see `TestStackOptions` for
+     *  the accepted shapes (object or factory function). */
     readonly extraContext?: TestStackOptions["extraContext"];
-    /** Anonymous-Access aktivieren — Requests ohne JWT werden als
-     *  Pseudo-User mit Rolle `anonymous` durchgelassen, sofern der
-     *  Handler `roles: ["anonymous"]` deklariert. Tenant-Resolution per
-     *  Header/Cookie/Default; siehe AnonymousAccessConfig. */
+    /** Enables anonymous access: requests without a JWT proceed as a
+     *  pseudo-user with the `anonymous` role when the handler declares
+     *  `roles: ["anonymous"]`. Tenant resolution uses a header, cookie, or
+     *  default; see `AnonymousAccessConfig`. */
     readonly anonymousAccess?: TestStackOptions["anonymousAccess"];
-    /** File-Storage-Provider — durchgereicht an setupTestStack. Wenn gesetzt,
-     *  mountet der Stack die Upload-Routes (POST/GET/DELETE /api/files) +
-     *  `ctx.files` und legt die file_refs-Tabelle an. Für Demos:
+    /** File-storage provider forwarded to `setupTestStack`. When set, the
+     *  stack mounts the upload routes (POST/GET/DELETE /api/files), exposes
+     *  `ctx.files`, and creates the `file_refs` table. Example:
      *  `{ storageProvider: createInMemoryFileProvider() }`. */
     readonly files?: TestStackOptions["files"];
-    /** Feature-toggle resolver — durchgereicht an setupTestStack. Wenn
-     *  gesetzt, konsultiert der dispatcher-feature-gate, hook-filter, MSP-
-     *  filter den callback; absent = alle features always-on. Erforderlich
-     *  für Tier-Composition (Sprint 8) wo per-Tenant unterschiedliche
-     *  features aktiv sein sollen. Die typische produktive Implementierung
-     *  ist `() => globalFeatureToggleRuntime.effectiveFeatures` post-boot
-     *  (createLateBoundHolder-pattern, weil runtime stack.db braucht). */
+    /** Feature-toggle resolver forwarded to `setupTestStack`. When set, the
+     *  dispatcher feature gate, hook filter, and MSP filter consult it;
+     *  absent means all features remain enabled. Required for per-tenant
+     *  feature composition. The typical production implementation is
+     *  `() => globalFeatureToggleRuntime.effectiveFeatures` after boot,
+     *  using the createLateBoundHolder pattern because the runtime needs
+     *  `stack.db`. */
     readonly effectiveFeatures?: TestStackOptions["effectiveFeatures"];
-    /** Wird nach dem Aufsetzen der Entity-Tabellen aufgerufen. Hook für
-     *  non-entity-tables (unsafePushTables) und Seeding (admin user, initial
-     *  tenant, …). Muss idempotent sein — im persistent-DB-Modus läuft
-     *  es bei jedem Boot. */
+    /** Called after entity tables are set up. Use this hook for non-entity
+     *  tables (`unsafePushTables`) and seeding (admin user, initial tenant,
+     *  and so on). Must be idempotent because persistent-DB mode runs it on
+     *  every boot. */
     readonly onAfterSetup?: (stack: TestStack) => Promise<void>;
     /** Declarative HTTP-routes outside the /api/write|query|batch pipeline —
-     *  symmetric to runProdApp.extraRoutes (kumiko-framework#3050). Mounted
+     *  symmetric to runProdApp.extraRoutes. Mounted
      *  inside buildServer (setupTestStack), before the Static/HTML-fallback,
      *  so an own GET (/feed.xml, /og-image, …) wins over the dev-asset path. */
     readonly extraRoutes?: readonly ExtraRouteDefinition[];
@@ -179,8 +175,8 @@ export type CreateKumikoServerOptions = {
     /** Per-request head-metadata resolver (Open-Graph/title/description) —
      *  same option, same `PageHeadResolver` signature, and same shared
      *  resolve+inject call (`resolveAndInjectPageHead`) as `runProdApp`'s
-     *  `resolvePageHead`, so dev and e2e exercise the exact code prod does
-     *  (kumiko-framework#3026). Consulted for every templated HTML response
+     *  `resolvePageHead`, so dev and e2e exercise the exact code prod does.
+     *  Consulted for every templated HTML response
      *  (the default single-entry shell and a host-dispatched `"html"` entry),
      *  right before it's served. On error, `null`, or a timeout, the shell
      *  ships unchanged with status 200 — never a 500. `systemQuery` inside