@cosmicdrift/kumiko-framework 0.371.1 → 0.373.0

package/dist/rate-limit/resolver.js

@@ -1,5 +1,5 @@
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
-import { RateLimitError } from "../errors/index.js";
+import { InternalError, RateLimitError } from "../errors/index.js";
 import { RedisKeys } from "../pipeline/redis-keys.js";
 import { toPublicBucketName } from "./bucket.js";
 // Token-Bucket rate limiter, atomic via Redis Lua. One round-trip per
@@ -105,6 +105,64 @@ end
 
 return { math.floor(tokens), retryAfterMs }
 `;
+// All-or-nothing variant for several buckets. Every bucket is refilled and
+// checked first; tokens are deducted only when each one has enough, so a
+// rejected request charges no bucket. Multi-key EVAL needs all keys in one
+// hash slot on Redis Cluster; the framework uses standalone Redis.
+//
+// KEYS[i]  — bucket keys
+// ARGV[1]  — nowMs
+// ARGV[2 + 4(i-1) .. 5 + 4(i-1)] — limit, refillRatePerMs, cost, ttlSeconds of KEYS[i]
+//
+// Returns the flat list { allAllowed (1|0), remaining_1, retryAfterMs_1, remaining_2, ... }.
+// retryAfterMs_i is 0 for buckets that had enough tokens.
+const TOKEN_BUCKET_ALL_LUA = `
+local nowMs = tonumber(ARGV[1])
+local count = #KEYS
+local tokens = {}
+local costs = {}
+local retries = {}
+local allAllowed = 1
+
+for i = 1, count do
+  local base = 2 + (i - 1) * 4
+  local limit = tonumber(ARGV[base])
+  local refillRatePerMs = tonumber(ARGV[base + 1])
+  costs[i] = tonumber(ARGV[base + 2])
+
+  local data = redis.call('HMGET', KEYS[i], 'tokens', 'ts')
+  local current = tonumber(data[1])
+  local ts = tonumber(data[2])
+  if current == nil then
+    current = limit
+  else
+    local elapsed = math.max(0, nowMs - ts)
+    current = math.min(limit, current + elapsed * refillRatePerMs)
+  end
+  tokens[i] = current
+
+  if current >= costs[i] then
+    retries[i] = 0
+  else
+    retries[i] = math.ceil((costs[i] - current) / refillRatePerMs)
+    allAllowed = 0
+  end
+end
+
+local result = { allAllowed }
+for i = 1, count do
+  if allAllowed == 1 then
+    tokens[i] = tokens[i] - costs[i]
+  end
+  local base = 2 + (i - 1) * 4
+  redis.call('HMSET', KEYS[i], 'tokens', tokens[i], 'ts', nowMs)
+  redis.call('EXPIRE', KEYS[i], tonumber(ARGV[base + 3]))
+  result[#result + 1] = math.floor(tokens[i])
+  result[#result + 1] = retries[i]
+end
+
+return result
+`;
 const REGISTERED = new WeakSet();
 function ensureCommand(redis) {
     if (!REGISTERED.has(redis)) {
@@ -116,6 +174,7 @@ function ensureCommand(redis) {
             numberOfKeys: 1,
             lua: TOKEN_BUCKET_PEEK_LUA,
         });
+        redis.defineCommand("kumikoRateLimitAll", { lua: TOKEN_BUCKET_ALL_LUA });
         REGISTERED.add(redis);
     }
     return redis; // @cast-boundary engine-bridge
@@ -154,6 +213,49 @@ export function createRateLimitResolver(opts) {
             resetAt: decision.resetAt.toString(),
         });
     }
+    async function enforceAll(requests) {
+        if (requests.length === 0)
+            return [];
+        const nowMs = now();
+        const keys = requests.map(({ bucket }) => `${prefix}${bucket}`);
+        // The script writes each key back once, so a repeated key would deduct only one of its costs.
+        const duplicate = keys.find((key, index) => keys.indexOf(key) !== index);
+        if (duplicate !== undefined) {
+            throw new InternalError({
+                message: `enforceAll received the bucket "${duplicate.slice(prefix.length)}" more than once — merge the requests into one.`,
+            });
+        }
+        const perBucketArgs = requests.flatMap(({ config }) => [
+            String(config.limit),
+            String(config.limit / (config.windowSeconds * 1000)),
+            String(config.cost ?? 1),
+            String(Math.max(1, config.windowSeconds * 2)),
+        ]);
+        const [allAllowedFlag, ...flat] = await client.kumikoRateLimitAll(keys.length, ...keys, String(nowMs), ...perBucketArgs);
+        const outcomes = requests.map(({ bucket, config }, index) => {
+            const retryAfterMs = flat[index * 2 + 1] ?? 0;
+            const decision = {
+                allowed: retryAfterMs === 0,
+                limit: config.limit,
+                remaining: flat[index * 2] ?? 0,
+                retryAfterSeconds: Math.ceil(retryAfterMs / 1000),
+                windowSeconds: config.windowSeconds,
+                resetAt: Temporal.Instant.fromEpochMilliseconds(nowMs + retryAfterMs),
+            };
+            return { bucket, retryAfterMs, decision };
+        });
+        if (allAllowedFlag === 1)
+            return outcomes.map(({ decision }) => decision);
+        const rejected = outcomes.reduce((worst, outcome) => outcome.retryAfterMs > worst.retryAfterMs ? outcome : worst);
+        throw new RateLimitError({
+            bucket: toPublicBucketName(rejected.bucket),
+            limit: rejected.decision.limit,
+            windowSeconds: rejected.decision.windowSeconds,
+            remaining: rejected.decision.remaining,
+            retryAfterSeconds: rejected.decision.retryAfterSeconds,
+            resetAt: rejected.decision.resetAt.toString(),
+        });
+    }
     async function peek(bucket, config) {
         const refillRatePerMs = config.limit / (config.windowSeconds * 1000);
         const nowMs = now();
@@ -171,5 +273,5 @@ export function createRateLimitResolver(opts) {
             resetAt,
         };
     }
-    return { check, enforce, peek };
+    return { check, enforce, enforceAll, peek };
 }

package/dist/rate-limit/unlimited-resolver.d.ts

@@ -0,0 +1,2 @@
+import type { RateLimitResolver } from "@cosmicdrift/kumiko-types/rate-limit-types";
+export declare function createUnlimitedRateLimitResolver(): RateLimitResolver;

package/dist/rate-limit/unlimited-resolver.js

@@ -0,0 +1,22 @@
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+// Resolver for callers that are bootstrap work rather than tenant traffic (boot seeds,
+// seed migrations): a handler's `rateLimit` declaration must not fail them, and they must not
+// drain the buckets real requests share. Nothing is stored, so the decision is always "full bucket".
+export function createUnlimitedRateLimitResolver() {
+    function fullBucket(config) {
+        return {
+            allowed: true,
+            limit: config.limit,
+            remaining: config.limit,
+            retryAfterSeconds: 0,
+            windowSeconds: config.windowSeconds,
+            resetAt: Temporal.Instant.fromEpochMilliseconds(Date.now()),
+        };
+    }
+    return {
+        check: async (_bucket, config) => fullBucket(config),
+        enforce: async (_bucket, config) => fullBucket(config),
+        enforceAll: async (requests) => requests.map(({ config }) => fullBucket(config)),
+        peek: async (_bucket, config) => fullBucket(config),
+    };
+}

package/dist/schema-cli.js

@@ -35,6 +35,41 @@ function withFileStoragePresence(env) {
         ? { ...env, [FILE_STORAGE_PROVIDER_ENV]: FILE_STORAGE_PROVIDER_BOOT_SENTINEL }
         : { ...env };
 }
+function isStringSet(value) {
+    return value instanceof Set && [...value].every((entry) => typeof entry === "string");
+}
+function isBoolean(value) {
+    return typeof value === "boolean";
+}
+function validateBootOptionsError(detail) {
+    return new Error(`kumiko/schema.ts: \`VALIDATE_BOOT_OPTIONS\` ${detail}`);
+}
+function readOptionalOption(raw, key, isValid, expected) {
+    const value = Reflect.get(raw, key);
+    if (value === undefined)
+        return undefined;
+    if (!isValid(value))
+        throw validateBootOptionsError(`\`${key}\` must be ${expected}.`);
+    return value;
+}
+// Boundary check for `export const VALIDATE_BOOT_OPTIONS` in kumiko/schema.ts.
+// Only the options that change what validateBoot reports are honoured; `env` and
+// `entityFieldCipher` are runner-injected and deliberately ignored here.
+function parseValidateBootOptions(raw) {
+    if (raw === undefined)
+        return {};
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        throw validateBootOptionsError("must be an object (ValidateBootOptions).");
+    }
+    const navAllowlist = readOptionalOption(raw, "navAllowlist", isStringSet, "a Set<string>");
+    const navAllowlistExempt = readOptionalOption(raw, "navAllowlistExempt", isStringSet, "a Set<string>");
+    const warnOnUniqueAccessRoles = readOptionalOption(raw, "warnOnUniqueAccessRoles", isBoolean, "a boolean");
+    return {
+        ...(navAllowlist !== undefined && { navAllowlist }),
+        ...(navAllowlistExempt !== undefined && { navAllowlistExempt }),
+        ...(warnOnUniqueAccessRoles !== undefined && { warnOnUniqueAccessRoles }),
+    };
+}
 // Single load-path for kumiko/schema.ts (512/3) — `generate` and `validate`
 // both need ENTITY_METAS (and validate additionally wants FEATURES); this is
 // the one place that enforces "ENTITY_METAS must be an array" so the two
@@ -42,13 +77,17 @@ function withFileStoragePresence(env) {
 // want a graceful exit code (validate) catch it themselves.
 async function loadSchemaModFromApp(schemaFile) {
     // bun imports TS directly — no spawn needed.
-    const mod = (await import(__rewriteRelativeImportExtension(schemaFile)));
-    if (!Array.isArray(mod.ENTITY_METAS)) {
+    const mod = await import(__rewriteRelativeImportExtension(schemaFile));
+    if (!Array.isArray(mod["ENTITY_METAS"])) {
         throw new Error(`Schema file ${schemaFile} muss \`export const ENTITY_METAS: EntityTableMeta[]\` haben.`);
     }
-    const entityMetas = mod.ENTITY_METAS;
+    const entityMetas = mod["ENTITY_METAS"];
     assertUniqueTableNames(entityMetas);
-    return { entityMetas, features: mod.FEATURES };
+    return {
+        entityMetas,
+        features: mod["FEATURES"],
+        validateBootOptions: mod["VALIDATE_BOOT_OPTIONS"],
+    };
 }
 function nextSequenceNumber(migrationsDir) {
     if (!existsSync(migrationsDir))
@@ -201,7 +240,8 @@ export async function runSchemaCli(argv, appCwd, out, options = {}) {
             //   1. schema drift: would `generate` write a migration? (= an entity was
             //      added/changed but never generated → missing table → prod 500)
             //   2. boot validity: validateBoot over the composed FEATURES (QN/screen/
-            //      nav/role refs). Runs only if kumiko/schema.ts exports FEATURES.
+            //      nav/role refs). Runs only if kumiko/schema.ts exports FEATURES;
+            //      honours its optional VALIDATE_BOOT_OPTIONS export.
             //   3. migration-content drift: replay every committed *.sql file and
             //      diff the result against .snapshot.json — catches a migration
             //      file whose SQL body doesn't match what its own snapshot entry
@@ -257,6 +297,7 @@ export async function runSchemaCli(argv, appCwd, out, options = {}) {
             if (Array.isArray(mod.FEATURES)) {
                 try {
                     validateBoot(mod.FEATURES, {
+                        ...parseValidateBootOptions(schemaMod.validateBootOptions),
                         env: withFileStoragePresence(process.env),
                     });
                     out.log("  ✓ boot: feature configuration is valid");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.371.1",
+  "version": "0.373.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -199,8 +199,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.371.1",
-    "@cosmicdrift/kumiko-types": "0.371.1",
+    "@cosmicdrift/kumiko-http": "0.373.0",
+    "@cosmicdrift/kumiko-types": "0.373.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -216,8 +216,8 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.371.1",
-    "@cosmicdrift/kumiko-testing": "0.371.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.373.0",
+    "@cosmicdrift/kumiko-testing": "0.373.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,59 @@
 [
+  {
+    "version": "0.373.0",
+    "type": "improvement",
+    "title": "loadPendingFileRef and bindPendingFileRef bind a caller's own pending upload from a custom handler",
+    "detail": "Additive. fileName is not part of PendingFileRef because it is personal data; read it via the fileRef executor's detail. Unexpected update errors throw; version_conflict and unique_violation map to \"version-conflict\"."
+  },
+  {
+    "version": "0.373.0",
+    "type": "breaking",
+    "title": "rateLimit accepts a list of buckets that are enforced all-or-nothing",
+    "detail": "RateLimitDeclaration is now a single option, a non-empty list of options or the disabled form. RateLimitResolver gains the required method enforceAll(requests: readonly RateLimitBucketRequest[]); createRateLimitResolver and createUnlimitedRateLimitResolver implement it. Payload buckets in additionalRateLimits are charged through the same call.",
+    "migration": "Custom RateLimitResolver implementations and test fakes need an enforceAll method (check every bucket, then deduct from all or none, and throw RateLimitError for the rejected bucket with the largest retryAfter). Existing rateLimit declarations stay valid. A duplicate payloadField in additionalRateLimits is now a boot error; merge the entries into one."
+  },
+  {
+    "version": "0.372.0",
+    "type": "improvement",
+    "title": "kumiko check validates the boot configuration with the validateBootOptions from kumiko.config.ts",
+    "detail": "Set validateBootOptions in defineAppConfig (navAllowlist, navAllowlistExempt, warnOnUniqueAccessRoles); the managed kumiko/schema.ts exports it as VALIDATE_BOOT_OPTIONS and kumiko check validates with it. Apps with a hand-written kumiko/schema.ts can export VALIDATE_BOOT_OPTIONS themselves.",
+    "migration": "Existing apps get the new line in kumiko/schema.ts through `kumiko-upgrade --apply` (managed file). The bin files belong to the app: pass `...(appConfig.validateBootOptions && { validateBootOptions: appConfig.validateBootOptions })` to runProdApp in bin/main.ts and to runDevApp in bin/server.ts (import appConfig from \"../kumiko.config\") so runtime and kumiko check agree."
+  },
+  {
+    "version": "0.372.0",
+    "type": "fix",
+    "title": "createEntity no longer collapses to never for inline field literals such as { type: \"reference\", entity }",
+    "detail": "The fields type parameter is const, so the literal type of each inline field survives without as const."
+  },
+  {
+    "version": "0.372.0",
+    "type": "breaking",
+    "title": "executor.detail() and executor.list() return EntityRow<E>, derived from the entity definition",
+    "detail": "Rows of createEntityExecutor / createEventStoreExecutor are typed per entity; wide entities keep Record<string, unknown>. createBooleanField is typed non-null. UserMfaRow in the bundled auth-mfa feature now declares enabledAt and lastUsedAt as Temporal.Instant, which is what the row always held.",
+    "migration": "Remove the `row as T` casts on executor.detail() / executor.list() results with `bun kumiko-upgrade --apply` (codemod remove-engine-payload-casts). Casts to a type the row does not satisfy stay and are listed as manual; replace them with a field-level check or a narrower type.",
+    "codemod": "scripts/codemod/remove-engine-payload-casts.ts",
+    "manualAfterCodemod": true
+  },
+  {
+    "version": "0.372.0",
+    "type": "fix",
+    "title": "A save cannot reference a file that belongs to another record",
+    "detail": "Creating or updating a record with a file id that is already bound to a different record of the same tenant is now rejected with invalid_element on that field, the same error as for a foreign tenant. Pending uploads, ids the record already holds and moves between its own file fields are unaffected."
+  },
+  {
+    "version": "0.372.0",
+    "type": "breaking",
+    "title": "Tokens carrying system or all lose those roles on verify",
+    "detail": "jwt.verify strips the system and all roles that session minting never grants, so a self-signed or leaked-key token cannot act as System.",
+    "migration": "Apps that mint their own tokens with the `system` role must stop doing so and use `createSystemUser` or system dispatch in-process instead. Tokens issued by the framework are unaffected. Tests that send a system user over `stack.http.*` must switch to `stack.dispatcher.write/query`."
+  },
+  {
+    "version": "0.372.0",
+    "type": "breaking",
+    "title": "http.route and the metric route label carry the route pattern, http.target is removed",
+    "detail": "Spans are named \"METHOD pattern\" instead of \"http.request\"; paths no route matched are labelled \"unmatched\". The PII ciphertext guard message names the pattern as well.",
+    "migration": "Dashboards, alerts and trace queries keyed on raw paths or on the span name \"http.request\" must switch to route patterns and the \"METHOD pattern\" span name. Read the query string from your access logs if you relied on http.target."
+  },
   {
     "version": "0.371.0",
     "type": "improvement",

package/src/scripts/codemod/README.md

@@ -118,3 +118,25 @@ bun node_modules/@cosmicdrift/kumiko-framework/src/scripts/codemod/import-extens
 Runs via `bun kumiko-upgrade --apply`. Without a mode flag it writes. `--check` exits 1 while any
 rewritable or manual site is left. The `import-extensions` guard (`kumiko check guards`) reports
 sites that are still on `.js`.
+
+## remove-engine-payload-casts.ts
+
+`executor.detail()` and `executor.list()` from `createEntityExecutor` / `createEventStoreExecutor`
+return the entity's own row type (`EntityRow<E>`), so `row["f"] as T`, `row as T` and
+`(await executor.detail(…)) as unknown as T` are usually redundant. The codemod removes such a cast,
+and its `@cast-boundary` marker comment when no other cast stays in the statement, only when the
+operand derives from an executor read (directly, through `rows[0]`, property access, `??` or a
+single-assignment variable) and the type checker says its type is assignable to the cast target. A
+file is left untouched if removing the casts would add type errors to it.
+
+It type-checks against the tsconfig at or above each file, so run it with the new framework version
+installed. Reported as `manual` and left alone: casts the row type does not satisfy (for example a
+nullable column cast to a non-null type, or `rows[0]` under `noUncheckedIndexedAccess`), and files
+without a tsconfig. A call site that still needs a narrower type than the row gives keeps its cast.
+
+```bash
+bun node_modules/@cosmicdrift/kumiko-framework/src/scripts/codemod/remove-engine-payload-casts.ts <dir> [--check | --dry-run | --write] [--no-format]
+```
+
+Runs via `bun kumiko-upgrade --apply`. Without a mode flag it writes, then formats the changed files
+with Biome. `--check` exits 1 while any rewritable or manual site is left.