@cosmicdrift/kumiko-framework 0.336.1 → 0.337.1

package/dist/api/auth-middleware.js

@@ -33,15 +33,29 @@ function middlewareReject(c, opts) {
         },
     }, opts.status);
 }
-// @wrapper-known error-helper
-function sessionInvalid(c, reason) {
-    return middlewareReject(c, {
+function sessionInvalidRejection(reason) {
+    return {
         code: "session_invalid",
         status: 401,
         message: `session ${reason}`,
         i18nKey: "auth.errors.sessionInvalid",
         details: { reason },
-    });
+    };
+}
+const INVALID_TOKEN_REJECTION = {
+    code: "invalid_token",
+    status: 401,
+    message: "token verification failed",
+    i18nKey: "auth.errors.invalidToken",
+};
+// A stale auth cookie (revoked session, rotated signing key) must not lock the
+// browser out of public handlers until the cookie expires, so with
+// anonymousAccess on the request continues anonymously and protected handlers
+// answer 401 unauthenticated in the dispatcher. Bearer clients own their header
+// and keep the explicit reject; /api/auth/* keeps it for the same reason as the
+// missing-token branch.
+function isStaleCookieDowngradable(c, transport, anonymousAccess) {
+    return (transport === "cookie" && anonymousAccess !== undefined && !c.req.path.startsWith("/api/auth/"));
 }
 // Extract the JWT from either the kumiko_auth cookie (web) or the
 // Authorization Bearer header (native / server-to-server). The two paths
@@ -136,17 +150,20 @@ export function authMiddleware(jwt, options = {}) {
                 return await handleVerifiedBearerUser(c, verifiedUser, next, resolveTenantLifecycleStatus);
             }
         }
+        const rejectInvalidCredential = async (rejection) => {
+            if (isStaleCookieDowngradable(c, transport, anonymousAccess)) {
+                return await handleAnonymous(c, anonymousAccess, next, resolveTenantLifecycleStatus, {
+                    rejectionIfTenantUnresolved: rejection,
+                });
+            }
+            return middlewareReject(c, rejection);
+        };
         let payload;
         try {
             payload = await jwt.verify(token);
         }
         catch {
-            return middlewareReject(c, {
-                code: "invalid_token",
-                status: 401,
-                message: "token verification failed",
-                i18nKey: "auth.errors.invalidToken",
-            });
+            return await rejectInvalidCredential(INVALID_TOKEN_REJECTION);
         }
         // Session liveness check — only when both a checker is wired AND the
         // token carries a sid.
@@ -158,14 +175,14 @@ export function authMiddleware(jwt, options = {}) {
                 const result = await sessionChecker(payload.jti, payload.sub);
                 const status = sessionCheckStatus(result);
                 if (status !== "live") {
-                    return sessionInvalid(c, status);
+                    return await rejectInvalidCredential(sessionInvalidRejection(status));
                 }
                 if (typeof result === "object") {
                     derivedRoles = result.roles;
                 }
             }
             else {
-                return sessionInvalid(c, "no_sid");
+                return await rejectInvalidCredential(sessionInvalidRejection("no_sid"));
             }
         }
         // Tenant-mismatch guard: if the caller sends BOTH a JWT (carrying a
@@ -254,17 +271,21 @@ async function handleVerifiedBearerUser(c, user, next, resolveTenantLifecycleSta
 //   5. Synthesise the anonymous SessionUser. The transport flag stays unset
 //      so csrf-middleware skips the double-submit check (no auth-cookie ⇒
 //      no CSRF vector to defend against).
-async function handleAnonymous(c, config, next, resolveTenantLifecycleStatus) {
+async function handleAnonymous(c, config, next, resolveTenantLifecycleStatus, staleCredential) {
+    // A downgraded stale credential whose anonymous tenant can't be resolved or
+    // is torn down answers with the credential's own 401: a tenant error would
+    // hide the session end from the client.
+    const rejectTenant = (tenantError) => middlewareReject(c, staleCredential?.rejectionIfTenantUnresolved ?? tenantError);
     // Step 1+2: parse client-supplied tenant. Reject malformed values before
     // they touch any downstream consumer (DB, cache, audit row).
     const headerRaw = c.req.header(TENANT_HEADER_NAME);
     const cookieRaw = getCookie(c, TENANT_COOKIE_NAME);
     const headerCheck = parseClientTenant(headerRaw, "X-Tenant header");
     if (headerCheck.error)
-        return middlewareReject(c, headerCheck.error);
+        return rejectTenant(headerCheck.error);
     const cookieCheck = parseClientTenant(cookieRaw, "kumiko_tenant cookie");
     if (cookieCheck.error)
-        return middlewareReject(c, cookieCheck.error);
+        return rejectTenant(cookieCheck.error);
     const clientTenant = headerCheck.tenantId !== null
         ? { id: headerCheck.tenantId, source: "header" }
         : cookieCheck.tenantId !== null
@@ -273,12 +294,12 @@ async function handleAnonymous(c, config, next, resolveTenantLifecycleStatus) {
     // Step 3: pick the authoritative tenant.
     const resolved = await resolveTenant(c, config, clientTenant);
     if ("error" in resolved)
-        return middlewareReject(c, resolved.error);
+        return rejectTenant(resolved.error);
     // Step 4: existence check for untrusted sources.
     if (resolved.source !== "default" && config.tenantExists) {
         const exists = await config.tenantExists(resolved.tenantId);
         if (!exists) {
-            return middlewareReject(c, {
+            return rejectTenant({
                 code: "tenant_not_found",
                 status: 404,
                 message: `tenant "${resolved.tenantId}" does not exist`,
@@ -289,8 +310,11 @@ async function handleAnonymous(c, config, next, resolveTenantLifecycleStatus) {
     }
     // Step 5: synthesise + continue.
     const lifecycleReject = await rejectIfTenantTeardown(c, resolved.tenantId, resolveTenantLifecycleStatus);
-    if (lifecycleReject)
-        return lifecycleReject;
+    if (lifecycleReject) {
+        return staleCredential
+            ? middlewareReject(c, staleCredential.rejectionIfTenantUnresolved)
+            : lifecycleReject;
+    }
     c.set(USER_KEY, createAnonymousUser(resolved.tenantId));
     await next();
     // skip: anonymous path completed — Hono middleware contract returns void

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

@@ -19,6 +19,7 @@ export type SessionRevoker = (sid: string) => Promise<void>;
 export type SessionMassRevoker = (userId: string) => Promise<number>;
 export type SessionChecker = AuthSessionChecker;
 export type { AuthSessionStatus };
+export declare function assertSessionCallbacksPaired(auth: Pick<AuthRoutesConfig, "sessionCreator" | "sessionRevoker" | "sessionChecker"> | undefined): void;
 export type AuthRoutesConfig = {
     membershipQuery: string;
     userQuery?: string;

package/dist/api/auth-routes.js

@@ -159,6 +159,26 @@ function switchTenantRejectionResponse(c, reason) {
             return assertUnreachable(reason, "ActiveMembershipRejection");
     }
 }
+// A sid minted by sessionCreator is only revocable when logout can revoke it
+// (sessionRevoker) AND every request re-checks it (sessionChecker). Wiring the
+// first without the other two would make logout look effective while the JWT
+// stays valid until expiry. A checker alone stays allowed: it fails closed.
+export function assertSessionCallbacksPaired(auth) {
+    const issuesSessions = auth?.sessionCreator !== undefined || auth?.sessionRevoker !== undefined;
+    const missing = issuesSessions
+        ? [
+            ...(auth?.sessionCreator === undefined ? ["sessionCreator"] : []),
+            ...(auth?.sessionRevoker === undefined ? ["sessionRevoker"] : []),
+            ...(auth?.sessionChecker === undefined ? ["sessionChecker"] : []),
+        ]
+        : [];
+    if (missing.length > 0) {
+        throw new Error(`[kumiko:boot] auth session callbacks are wired partially — missing ${missing.join(", ")}. ` +
+            "Server sessions need sessionCreator, sessionRevoker and sessionChecker together, " +
+            "otherwise logout leaves the JWT valid until it expires. Wire all three (the sessions " +
+            "feature's sessionStore provides them) or none for stateless JWTs.");
+    }
+}
 // Second rate-limit axis for preauth-enable-start: unlike the IP, a
 // preauthSetupToken isn't freely choosable by the attacker (it's minted by
 // login.write.ts), so hashing it into a bucket key still caps the replay

package/dist/api/redis-sse-broker.d.ts

@@ -5,6 +5,7 @@ export type RedisSseBrokerOptions = {
     readonly clientOptions?: RedisClientOptions;
 };
 export type RedisSseBroker = SseBroker & {
+    readonly kind: "redis";
     close(): Promise<void>;
 };
 export declare function isRedisSseBroker(broker: SseBroker): broker is RedisSseBroker;

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

@@ -9,12 +9,10 @@ import { createSseBroker, readNonEmptyStringArray, } from "./sse-broker.js";
 const CHANNEL_PREFIX = "kumiko:sse:ch:";
 const INVALIDATION_PREFIX = "kumiko:sse:inval:";
 const PSUBSCRIBE_PATTERN = "kumiko:sse:*";
-// The one property RedisSseBroker adds over SseBroker — cheap and reliable
-// to narrow on, so callers that only hold an SseBroker (e.g. a test that
-// pulled it back out of a generic ServerOptions.sseBroker slot) can tell
-// which lifecycle they own without an unsound `as` cast.
+// Narrows on the `kind` discriminant, not on `close`: an app-owned SseBroker
+// may have its own close() and must not be mistaken for the Redis one.
 export function isRedisSseBroker(broker) {
-    return "close" in broker;
+    return "kind" in broker && broker.kind === "redis";
 }
 // Single decision point for "which SseBroker should a caller default to
 // when it doesn't inject its own": REDIS_URL present → cross-replica
@@ -117,6 +115,7 @@ export function createRedisSseBroker(opts) {
         }
     });
     return {
+        kind: "redis",
         addClient: inner.addClient,
         removeClient: inner.removeClient,
         getClientCount: inner.getClientCount,

package/dist/api/server.js

@@ -25,7 +25,7 @@ import { assertUnreachable, generateId } from "../utils/index.js";
 import { collectAnonymousLiveEntities } from "./anonymous-live-entities.js";
 import { NO_ROUTE_MATCH_HEADER_NAME, PUBLIC_API_PATHS, Routes } from "./api-constants.js";
 import { authMiddleware, getAuthTokenExpiry, getUser, } from "./auth-middleware.js";
-import { createAuthRoutes } from "./auth-routes.js";
+import { assertSessionCallbacksPaired, createAuthRoutes, } from "./auth-routes.js";
 import { assertValidTrustedProxyHops, clientIpSourceFromHonoContext, createClientIpResolver, } from "./client-ip.js";
 import { csrfMiddleware } from "./csrf-middleware.js";
 import { ExtraRouteEntries, ExtraRouteRejection, } from "./extra-route.js";
@@ -505,6 +505,7 @@ export function buildServer(options) {
     // without an allowlist and without an explicit opt-out — that config is the
     // unguarded-subdomain-XSS footgun, not a warn-and-continue case.
     assertOriginGuardConfig(options.auth);
+    assertSessionCallbacksPaired(options.auth);
     const allowedOrigins = options.auth?.allowedOrigins;
     const originGuard = allowedOrigins && allowedOrigins.length > 0 ? originMiddleware(allowedOrigins) : undefined;
     if (originGuard) {
@@ -527,11 +528,10 @@ export function buildServer(options) {
             return next();
         return csrfGuard(c, next);
     });
-    // Same order as /api/* above: auth → PAT route scope → PAT rate-limit → origin → CSRF.
+    // No PAT rate-limit here: patRouteGuardMiddleware rejects every PAT on httpRoutes before it could count.
     const sessionOnlyHttpRouteGuards = [
         sessionOnlyGuard,
         patRouteGuardMiddleware,
-        ...(patRateLimitGuard ? [patRateLimitGuard] : []),
         ...(originGuard ? [originGuard] : []),
         csrfGuard,
     ];

package/dist/api/sse-route.js

@@ -45,6 +45,16 @@ function toEntitySignalWire(event, data) {
         createdAt: data["createdAt"],
     };
 }
+// The signal covers every row of the entity, including rows the anonymous
+// query hides, so id and version would leak which hidden rows exist and
+// change. Anonymous clients refetch the whole query anyway.
+function toAnonymousEntitySignalWire(event, data) {
+    return {
+        aggregateType: data.aggregateType,
+        eventType: event.type,
+        createdAt: data["createdAt"],
+    };
+}
 // The tenant channel fans out to every member, so a frame without an entity
 // (e.g. channel-in-app:event:delivered) reaches only its addressee; a frame
 // lacking userId is dropped (fail-closed).
@@ -61,7 +71,10 @@ function decideWireFrame(event, user, options) {
         // skip: anonymous connections only get signals for entities an anonymous query declares
         if (!mayReceiveEntitySignal(user, data.aggregateType, options))
             return undefined;
-        return { name: data.aggregateType, data: toEntitySignalWire(event, data) };
+        const signal = isAnonymousSessionUser(user)
+            ? toAnonymousEntitySignalWire(event, data)
+            : toEntitySignalWire(event, data);
+        return { name: data.aggregateType, data: signal };
     }
     // skip: frames without an entity belong to their addressee only
     if (!isAddressedTo(event, user.id))

package/dist/bun-db/query.js

@@ -735,10 +735,11 @@ async function unsafeLoggingClosedConnection(db, sqlText, params, context) {
         throw err;
     }
 }
+const DEFAULT_POOL_MAX = 10;
 function poolMaxOf(raw) {
     // @cast-boundary driver pool options — both postgres-js and Bun.SQL expose options.max
     const max = raw.options?.max;
-    return typeof max === "number" && Number.isInteger(max) && max > 0 ? max : 10;
+    return typeof max === "number" && Number.isInteger(max) && max > 0 ? max : DEFAULT_POOL_MAX;
 }
 // Exported so raw-SQL query modules outside bun-db (e.g. bundled-features'
 // db/queries/*.ts) can opt into the same closed-connection retry instead of
@@ -754,9 +755,10 @@ export async function unsafeReadRetrying(db, sqlText, params) {
             logClosedConnection(raw, err, 1);
             throw err;
         }
-        const maxAttempts = poolMaxOf(raw) + 1;
+        // Enough retries to flush every dead pooled connection plus one fresh one; total calls = maxRetries + 1.
+        const maxRetries = poolMaxOf(raw) + 1;
         let lastErr = err;
-        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        for (let attempt = 0; attempt < maxRetries; attempt++) {
             try {
                 return (await raw.unsafe(sqlText, params));
             }
@@ -768,7 +770,7 @@ export async function unsafeReadRetrying(db, sqlText, params) {
                 }
             }
         }
-        logClosedConnection(raw, lastErr, maxAttempts + 1);
+        logClosedConnection(raw, lastErr, maxRetries + 1);
         throw lastErr;
     }
 }

package/dist/crypto/kek-source.js

@@ -43,6 +43,7 @@ async function decryptCiphertext(ciphertext, keyId, token, region, fetchImpl, lo
         }
         if (!response.ok) {
             if (isRetryableStatus(response.status) && attempt < maxAttempts) {
+                await response.body?.cancel();
                 await sleep(RETRY_DELAYS_MS[attempt - 1] ?? 0);
                 continue;
             }

package/dist/db/blind-index-cleanup.js

@@ -55,7 +55,7 @@ export async function nullBlindIndexesForSubject(db, features, subjectKey) {
 async function existingTableNames(db, tableNames) {
     if (tableNames.length === 0)
         return new Set();
-    const rows = await executeRawQueryRead(db, `SELECT t.name FROM unnest($1::text[]) AS t(name) WHERE to_regclass(quote_ident(t.name)) IS NOT NULL`, [tableNames]);
+    const rows = await executeRawQueryRead(db, `SELECT t.name FROM unnest($1::text[]) AS t(name) WHERE to_regclass('public.' || quote_ident(t.name)) IS NOT NULL`, [tableNames]);
     return new Set(rows.map((r) => r.name));
 }
 // Tenant-scope oracle for crypto-shredding's forget-subject (mh#349): a

package/dist/db/event-store-executor-read.js

@@ -249,11 +249,16 @@ function collectReferenceSearchDescriptors(table, referenceSearch, dbMode) {
     }
     return descriptors;
 }
+// Matches the main list's own default: soft-deleted rows are invisible, so a
+// deleted target must neither match a search nor influence an ordering.
+function isSoftDeletedTargetHidden(targetEntity, targetTable) {
+    return targetEntity.softDelete === true && targetTable["isDeleted"] !== undefined;
+}
 // Tenant-scoped ILIKE lookup against one reference target — never raw/
 // unscoped SQL, a match in a foreign tenant must never surface a row here
 // (fw#2660's hard constraint). Mirrors the main table's own tenant filter
 // (see the `table["tenantId"]` check further down in list()).
-async function resolveReferenceMatchesViaIlike(descriptor, searchTerm, targetTable, targetTableName, db) {
+async function resolveReferenceMatchesViaIlike(descriptor, searchTerm, targetEntity, targetTable, targetTableName, db) {
     const labelCol = physicalColumnName(targetTable, descriptor.labelField);
     const subParams = [`%${escapeLikePattern(searchTerm)}%`];
     let tenantClause = "";
@@ -261,9 +266,12 @@ async function resolveReferenceMatchesViaIlike(descriptor, searchTerm, targetTab
         subParams.push(db.tenantId, SYSTEM_TENANT_ID);
         tenantClause = ` AND "${physicalColumnName(targetTable, "tenantId")}" IN ($2, $3)`;
     }
+    const deletedClause = isSoftDeletedTargetHidden(targetEntity, targetTable)
+        ? ` AND "${physicalColumnName(targetTable, "isDeleted")}" = FALSE`
+        : "";
     // ::text cast covers a non-text labelField (e.g. a number/select column
     // used as label) — Postgres has no ILIKE for those types otherwise.
-    const sql = `SELECT "id" FROM "${targetTableName}" WHERE ("${labelCol}")::text ILIKE $1${tenantClause} ` +
+    const sql = `SELECT "id" FROM "${targetTableName}" WHERE ("${labelCol}")::text ILIKE $1${tenantClause}${deletedClause} ` +
         `LIMIT ${MAX_REFERENCE_SEARCH_IDS + 1}`;
     const rows = await executeRawQueryRead(tenantDbRunner(db), sql, subParams);
     if (rows.length === 0 || rows.length > MAX_REFERENCE_SEARCH_IDS) {
@@ -320,7 +328,7 @@ async function resolveReferenceMatches(descriptor, searchTerm, resolveEntity, db
     const targetTable = referenceTargetTable(descriptor.targetEntityName, targetEntity);
     const targetTableName = String(targetTable[KUMIKO_NAME_SYMBOL]);
     if (!isSensitiveLabelField(targetEntity, descriptor.labelField)) {
-        return resolveReferenceMatchesViaIlike(descriptor, searchTerm, targetTable, targetTableName, db);
+        return resolveReferenceMatchesViaIlike(descriptor, searchTerm, targetEntity, targetTable, targetTableName, db);
     }
     if (!hasSearchablePlaintext(targetEntity, descriptor.labelField)) {
         // skip: no plaintext anywhere to match — boot rejects this normally,
@@ -373,6 +381,9 @@ function buildReferenceSortExpr(outerTableName, ownColumnSql, descriptor, resolv
     const tenantScoped = targetTable["tenantId"] !== undefined && db.mode === "tenant";
     const tenantCol = tenantScoped ? physicalColumnName(targetTable, "tenantId") : "";
     const tenantId = db.mode === "tenant" ? db.tenantId : undefined;
+    const deletedClause = isSoftDeletedTargetHidden(targetEntity, targetTable)
+        ? ` AND t."${physicalColumnName(targetTable, "isDeleted")}" = FALSE`
+        : "";
     // No ::text cast (unlike the ILIKE search path): a non-text label must keep
     // its native collation/numeric order, and the keyset param infers its type
     // from the comparison anyway.
@@ -383,7 +394,7 @@ function buildReferenceSortExpr(outerTableName, ownColumnSql, descriptor, resolv
             tenantClause = ` AND t."${tenantCol}" IN ($${params.length - 1}, $${params.length})`;
         }
         return (`(SELECT t."${labelCol}" FROM "${targetTableName}" t ` +
-            `WHERE t."id" = "${outerTableName}".${ownColumnSql}${tenantClause})`);
+            `WHERE t."id" = "${outerTableName}".${ownColumnSql}${tenantClause}${deletedClause})`);
     };
 }
 export function createReadVerbs(ctx) {

package/dist/db/queries/event-consumer.d.ts

@@ -1,4 +1,4 @@
-import type { PendingGapEntry } from "../../pipeline/event-consumer-state.js";
+import type { ConsumerStatuses, PendingGapEntry } from "../../pipeline/event-consumer-state.js";
 import type { AnyDb } from "../query.js";
 export declare function selectSnapshotXmin(db: AnyDb): Promise<string>;
 export declare function selectSnapshotXmax(db: AnyDb): Promise<string>;
@@ -10,7 +10,7 @@ export declare function selectEventIdHorizonWithMissingRanges(db: AnyDb): Promis
 }>;
 export declare function insertConsumerIfAbsent(db: AnyDb, name: string, instanceId: string, startFrom?: "beginning" | "now"): Promise<void>;
 export declare function deleteOrphanedPerInstanceConsumerRows(db: AnyDb, consumerNames: readonly string[], sharedInstanceSentinel: string): Promise<void>;
-export declare function selectProvablyIdleConsumerPairs(db: AnyDb, names: readonly string[], instanceIds: readonly string[], deadStatus: string): Promise<ReadonlyArray<{
+export declare function selectProvablyIdleConsumerPairs(db: AnyDb, names: readonly string[], instanceIds: readonly string[], deadStatus: typeof ConsumerStatuses.dead): Promise<ReadonlyArray<{
     readonly name: string;
     readonly instanceId: string;
 }>>;

package/dist/db/queries/event-consumer.js

@@ -112,10 +112,11 @@ sharedInstanceSentinel) {
 // exists past its cursor. Paired via unnest so the two positional arrays
 // zip element-wise into rows instead of a cartesian product.
 //
-// `deadStatus` is passed in rather than imported from event-consumer-state.ts
-// (which defines ConsumerStatuses) — that module already imports from this
-// one, so importing back would be a require cycle (same pattern as
-// deleteOrphanedPerInstanceConsumerRows above).
+// `deadStatus` is passed in rather than imported as a value from
+// event-consumer-state.ts (which defines ConsumerStatuses) — that module
+// already imports from this one, so a value import back would be a require
+// cycle (same pattern as deleteOrphanedPerInstanceConsumerRows above). The
+// type-only import keeps the parameter pinned to the "dead" literal.
 export async function selectProvablyIdleConsumerPairs(db, names, instanceIds, deadStatus) {
     const rows = (await asRawClient(db).unsafe(`SELECT c."name" AS name, c."instance_id" AS instance_id
      FROM "kumiko_event_consumers" c

package/dist/db/queries/event-store.js

@@ -130,16 +130,16 @@ export async function insertSubsequentEventRow(db, params) {
     return rows[0];
 }
 export async function selectStreamMaxVersion(db, aggregateId, tenantId) {
-    const rows = (await unsafeReadRetrying(db, `SELECT MAX("version") AS v FROM "kumiko_events" WHERE "aggregate_id" = $1 AND "tenant_id" = $2`, [aggregateId, tenantId]));
+    const rows = await unsafeReadRetrying(db, `SELECT MAX("version") AS v FROM "kumiko_events" WHERE "aggregate_id" = $1 AND "tenant_id" = $2`, [aggregateId, tenantId]);
     return rows[0]?.v ?? 0;
 }
 /** MAX(version) for one aggregate stream — no tenant filter (seed idempotency). */
 export async function selectAggregateMaxVersion(db, aggregateId) {
-    const rows = (await unsafeReadRetrying(db, `SELECT MAX("version") AS v FROM "kumiko_events" WHERE "aggregate_id" = $1`, [aggregateId]));
+    const rows = await unsafeReadRetrying(db, `SELECT MAX("version") AS v FROM "kumiko_events" WHERE "aggregate_id" = $1`, [aggregateId]);
     return rows[0]?.v ?? 0;
 }
 export async function selectEventsHighWaterMark(db) {
-    const rows = (await unsafeReadRetrying(db, `SELECT COALESCE(MAX("id"), 0)::bigint AS max FROM "kumiko_events"`, []));
+    const rows = await unsafeReadRetrying(db, `SELECT COALESCE(MAX("id"), 0)::bigint AS max FROM "kumiko_events"`, []);
     const raw = rows[0]?.max;
     if (typeof raw === "bigint")
         return raw;
@@ -153,7 +153,7 @@ export async function selectEventsHeadId(db) {
     return selectEventsHighWaterMark(db);
 }
 export async function selectNextEventIdAfter(db, afterId) {
-    const rows = (await unsafeReadRetrying(db, `SELECT "id" FROM "kumiko_events" WHERE "id" > $1 ORDER BY "id" ASC LIMIT 1`, [afterId]));
+    const rows = await unsafeReadRetrying(db, `SELECT "id" FROM "kumiko_events" WHERE "id" > $1 ORDER BY "id" ASC LIMIT 1`, [afterId]);
     const row = rows[0];
     if (!row)
         return null;
@@ -222,10 +222,10 @@ export async function selectPendingAndNewEventRows(db, cursor, pendingRanges, ba
 export async function selectSmallestVisibleIdInRanges(db, pendingRanges) {
     if (pendingRanges.length === 0)
         return null;
-    const rows = (await unsafeReadRetrying(db, `SELECT MIN("id")::text AS id FROM "kumiko_events"
+    const rows = await unsafeReadRetrying(db, `SELECT MIN("id")::text AS id FROM "kumiko_events"
      WHERE EXISTS (
        SELECT 1 FROM unnest($1::bigint[], $2::bigint[]) AS g(f, t) WHERE "id" BETWEEN g.f AND g.t
-     )`, [pendingRanges.map((r) => r.from.toString()), pendingRanges.map((r) => r.to.toString())]));
+     )`, [pendingRanges.map((r) => r.from.toString()), pendingRanges.map((r) => r.to.toString())]);
     const id = rows[0]?.id;
     return id === null || id === undefined ? null : BigInt(id);
 }

package/dist/db/queries/projection-rebuild.js

@@ -14,7 +14,7 @@ export async function selectEventsForProjectionRebuildBatch(db, aggregateTypes,
     // Archived streams don't replay (Marten-aligned): their aggregates are
     // frozen ops-tombstones — replaying them would resurrect rows (or, for
     // stranded duplicate-aggregates like fw#832, collide on unique indexes).
-    return (await unsafeReadRetrying(db, `SELECT * FROM "kumiko_events" e
+    return unsafeReadRetrying(db, `SELECT * FROM "kumiko_events" e
      WHERE e."aggregate_type" = ANY($1::text[])
        AND e."type" = ANY($2::text[])
        AND e."id" > $3
@@ -23,7 +23,7 @@ export async function selectEventsForProjectionRebuildBatch(db, aggregateTypes,
           WHERE a."tenant_id" = e."tenant_id" AND a."aggregate_id" = e."aggregate_id"
        )
      ORDER BY e."id" ASC
-     LIMIT $4`, [aggregateTypes, eventTypes, afterId, limit]));
+     LIMIT $4`, [aggregateTypes, eventTypes, afterId, limit]);
 }
 // Total subscribed events in the log — same source/type filter as
 // selectEventsForProjectionRebuildBatch, no id cursor. Under the cutover fence
@@ -33,13 +33,13 @@ export async function countSubscribedEvents(db, aggregateTypes, eventTypes) {
     // Same archived-streams exclusion as the batch query — the #443 recompute
     // compares this count against applied events; a filter mismatch would make
     // every rebuild with an archived stream loop the full-re-replay forever.
-    const rows = (await unsafeReadRetrying(db, `SELECT count(*)::bigint AS n FROM "kumiko_events" e
+    const rows = await unsafeReadRetrying(db, `SELECT count(*)::bigint AS n FROM "kumiko_events" e
      WHERE e."aggregate_type" = ANY($1::text[])
        AND e."type" = ANY($2::text[])
        AND NOT EXISTS (
          SELECT 1 FROM "kumiko_archived_streams" a
           WHERE a."tenant_id" = e."tenant_id" AND a."aggregate_id" = e."aggregate_id"
-       )`, [aggregateTypes, eventTypes]));
+       )`, [aggregateTypes, eventTypes]);
     const raw = rows[0]?.n;
     if (typeof raw === "bigint")
         return raw;

package/dist/db/queries/seed-context.js

@@ -1,25 +1,25 @@
 import { unsafeReadRetrying } from "../query.js";
 export async function selectUserByEmail(db, email) {
-    const rows = (await unsafeReadRetrying(db, `SELECT id::text AS id, email, tenant_id::text AS tenant_id
+    const rows = await unsafeReadRetrying(db, `SELECT id::text AS id, email, tenant_id::text AS tenant_id
      FROM read_users
      WHERE email = $1
-     LIMIT 1`, [email]));
+     LIMIT 1`, [email]);
     const row = rows[0];
     if (!row)
         return null;
     return { id: row.id, email: row.email, tenantId: row.tenant_id };
 }
 export async function selectMembershipsOfUser(db, userId) {
-    return (await unsafeReadRetrying(db, `SELECT m.user_id::text AS user_id,
+    return unsafeReadRetrying(db, `SELECT m.user_id::text AS user_id,
             m.tenant_id::text AS tenant_id,
             e.tenant_id::text AS stream_tenant_id,
             m.roles
      FROM read_tenant_memberships m
      JOIN kumiko_events e ON e.aggregate_id = m.id AND e.version = 1
-     WHERE m.user_id = $1`, [userId]));
+     WHERE m.user_id = $1`, [userId]);
 }
 export async function selectAllTenants(db) {
-    return (await unsafeReadRetrying(db, `SELECT id::text AS id, name, key AS tenant_key
+    return unsafeReadRetrying(db, `SELECT id::text AS id, name, key AS tenant_key
      FROM read_tenants
-     ORDER BY inserted_at`, []));
+     ORDER BY inserted_at`, []);
 }

package/dist/derivatives/derivatives-context.js

@@ -97,8 +97,11 @@ function resolveOverlayLayer(layer, qrContext, tenantId) {
 // the spec, so a resolver whose target changes (e.g. a base-URL rotation)
 // invalidates the cache instead of serving a stale target under the old key.
 async function resolveOverlaySpec(spec, row, registry, tenantId) {
-    if (!spec.overlays || spec.overlays.length === 0)
-        return spec;
+    // `resolvedOverlays` is framework-internal; a caller-supplied value must
+    // never reach the renderer past the token resolution below.
+    if (!spec.overlays || spec.overlays.length === 0) {
+        return spec.resolvedOverlays === undefined ? spec : { ...spec, resolvedOverlays: undefined };
+    }
     const qrContext = spec.overlays.some((layer) => layer.kind === "qr")
         ? resolveQrOverlayContext(row, registry)
         : undefined;

package/dist/engine/boot-validator/projection-list-screens.d.ts

@@ -1,4 +1,4 @@
-import type { FeatureDefinition, QueryHandlerDef } from "../types/index.js";
+import { type FeatureDefinition, type QueryHandlerDef } from "../types/index.js";
 export declare function buildQueryHandlerMap(features: readonly FeatureDefinition[]): ReadonlyMap<string, QueryHandlerDef>;
 export declare function validateProjectionListScreens(features: readonly FeatureDefinition[]): void;
 export declare function validateRelatedListSectionQueries(features: readonly FeatureDefinition[]): void;

package/dist/engine/boot-validator/projection-list-screens.js

@@ -1,6 +1,7 @@
 import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handlers";
 import { parseQn, QnTypes, qualifyEntityName } from "../qualified-name.js";
 import { isEditLayoutScreen } from "../screen-helpers.js";
+import { relatedListGroupHeaderLabel, relatedListGroupKey, } from "../types/index.js";
 import { SEARCHABLE_FALSE_WHITELIST } from "./entity-list-screens.js";
 import { findEntity } from "./parent-ref.js";
 import { getZodObjectShape } from "./zod-shape.js";
@@ -198,6 +199,17 @@ function validateRelatedListParentFilter(prefix, section, schema, handler, featu
             `entity behind query "${section.query}". Known fields: ${Object.keys(entity.fields).sort().join(", ")}.`);
     }
 }
+// A collapsed group without a header has no toggle, so its rows could never be opened.
+function validateRelatedListGroupBy(prefix, section) {
+    const groupBy = section.groupBy;
+    const collapsedKey = groupBy?.collapsedWhen === undefined ? undefined : relatedListGroupKey(groupBy.collapsedWhen);
+    if (groupBy !== undefined &&
+        collapsedKey !== undefined &&
+        relatedListGroupHeaderLabel(groupBy, collapsedKey) === undefined) {
+        throw new Error(`${prefix}: groupBy.collapsedWhen "${collapsedKey}" names a group without a header; ` +
+            `set groupBy.label or groupBy.labels["${collapsedKey}"], or drop collapsedWhen.`);
+    }
+}
 // relatedList sections declare search/facets the same way a projectionList
 // screen does, and hit the same 422 footgun: definePagedQueryHandler doesn't
 // auto-merge params into the handler's own Zod schema (fw#2165/#2224), so an
@@ -214,6 +226,7 @@ export function validateRelatedListSectionQueries(features) {
         validateRelatedListSearchable(prefix, section, schema);
         validateRelatedListFacets(prefix, section, schema);
         validateRelatedListParentFilter(prefix, section, schema, handler, featureMap);
+        validateRelatedListGroupBy(prefix, section);
     };
     for (const feature of features) {
         for (const screen of Object.values(feature.screens)) {

package/dist/engine/boot-validator/screens.js

@@ -620,6 +620,15 @@ function validateRedirectTarget(feature, screenId, screenKind, redirect, allScre
     }
     validateScreenNavTarget(feature.name, screenId, screenKind, "redirect", redirectTarget, allScreenQns, feature.screens);
 }
+// redirect is only honored on record actions; on list/related-list row
+// actions it would be silently dropped, so the author would believe it works.
+function rejectRedirectOnListRowAction(featureName, screenId, screenKind, action) {
+    if (action.kind !== "navigate" && action.kind !== "drawer" && action.redirect !== undefined) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenKind}) rowAction "${action.id}" sets redirect — ` +
+            `redirect is only honored on record actions (projectionDetail/entityEdit header and section ` +
+            `actions) and is ignored on list row actions. Remove it.`);
+    }
+}
 // A writeHandler record action's redirect (projectionDetail/entityEdit
 // header and section actions) follows the entityEdit.redirect rule.
 function validateRecordActionRedirect(feature, screenId, screenKind, action, allScreenQns) {
@@ -780,6 +789,7 @@ function validateRelatedListSection(args) {
 function validateRelatedListRowActions(args, rowActions) {
     const { featureName, screenId, screenType, where, section, screens, allWriteHandlerQns, allScreenQns, navTargetShortIds, screensByShortId, detailForScreens, } = args;
     for (const action of rowActions) {
+        rejectRedirectOnListRowAction(featureName, screenId, screenType, action);
         if (action.kind === "navigate") {
             const target = resolveRowActionNavigateTarget(featureName, screenId, screenType, "rowAction", action, allScreenQns, navTargetShortIds, screensByShortId, detailForScreens);
             validateRowActionNavigateParams(featureName, screenId, screenType, undefined, action, target);
@@ -899,6 +909,7 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
             }
             if (screen.rowActions !== undefined) {
                 for (const action of screen.rowActions) {
+                    rejectRedirectOnListRowAction(feature.name, screenId, "projectionList", action);
                     if (action.kind === "navigate") {
                         const target = resolveRowActionNavigateTarget(feature.name, screenId, "projectionList", "rowAction", action, allScreenQns, navTargetShortIds, screensByShortId, detailForScreens);
                         validateRowActionNavigateParams(feature.name, screenId, "projectionList", undefined, action, target);
@@ -1414,6 +1425,7 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
             // erst beim ersten Klick als "Screen not found" / 404 auf.
             if (screen.rowActions !== undefined) {
                 for (const action of screen.rowActions) {
+                    rejectRedirectOnListRowAction(feature.name, screenId, "entityList", action);
                     if (action.kind === "navigate") {
                         const target = resolveRowActionNavigateTarget(feature.name, screenId, "entityList", "rowAction", action, allScreenQns, navTargetShortIds, screensByShortId, detailForScreens);
                         // The renderer's default-entityId fallback (row["id"]) only fires