@cosmicdrift/kumiko-framework 0.381.0 → 0.383.0

package/dist/redis/client.js

@@ -11,6 +11,7 @@
 // Split out of index.ts (fw#2625) so pubsub-signal.ts can import this
 // without a same-directory cycle back through the barrel.
 import { Redis } from "ioredis";
+import { scrubLogText } from "../logging/scrub.js";
 import { readPositiveIntEnv } from "../utils/env-parse.js";
 const DEFAULT_CONNECT_TIMEOUT_MS = 5_000;
 const DEFAULT_COMMAND_TIMEOUT_MS = 10_000;
@@ -26,6 +27,25 @@ export function createRedisClient(url, options = {}) {
         maxRetriesPerRequest,
     });
 }
+// ioredis reconnects on its own and re-emits "error" for every failed attempt; only the
+// transitions are worth a log line. A Redis outage degrades the app, it must not crash it.
+export function logRedisConnectionState(redis, logger) {
+    let connectionLost = false;
+    redis.on("error", (err) => {
+        // skip: only the transition is logged, ioredis repeats the error on every retry
+        if (connectionLost)
+            return;
+        connectionLost = true;
+        logger.warn("redis connection lost, reconnecting", { error: scrubLogText(err.message) });
+    });
+    redis.on("ready", () => {
+        // skip: the initial connect is not a recovery
+        if (!connectionLost)
+            return;
+        connectionLost = false;
+        logger.info("redis recovered");
+    });
+}
 // Redis Pub/Sub ignores the DB index and ioredis keyPrefix, so apps or environments sharing one
 // Redis instance would see each other's SSE and toggle-sync traffic. An optional prefix
 // namespaces those channels; unset keeps the unprefixed channel names.

package/dist/redis/index.d.ts

@@ -3,6 +3,6 @@ export { createCacheSyncBusOverSignal, createDefaultCacheSyncBus, createLocalCac
 export type { TenantConfigSyncMessage, TierAssignmentSyncMessage } from "./cache-sync-topics.ts";
 export { CACHE_SYNC_TOPICS, isTenantConfigSyncMessage, isTierAssignmentSyncMessage, } from "./cache-sync-topics.ts";
 export type { RedisClientOptions } from "./client.ts";
-export { createRedisClient, redisChannelPrefixFromEnv, redisClientOptionsFromEnv, } from "./client.ts";
+export { createRedisClient, logRedisConnectionState, redisChannelPrefixFromEnv, redisClientOptionsFromEnv, } from "./client.ts";
 export type { PubSubSignal, PubSubSignalOptions } from "./pubsub-signal.ts";
 export { createRedisPubSubSignal } from "./pubsub-signal.ts";

package/dist/redis/index.js

@@ -1,4 +1,4 @@
 export { createCacheSyncBusOverSignal, createDefaultCacheSyncBus, createLocalCacheSyncBus, createRedisCacheSyncBus, resolveCacheSyncBus, } from "./cache-sync-bus.js";
 export { CACHE_SYNC_TOPICS, isTenantConfigSyncMessage, isTierAssignmentSyncMessage, } from "./cache-sync-topics.js";
-export { createRedisClient, redisChannelPrefixFromEnv, redisClientOptionsFromEnv, } from "./client.js";
+export { createRedisClient, logRedisConnectionState, redisChannelPrefixFromEnv, redisClientOptionsFromEnv, } from "./client.js";
 export { createRedisPubSubSignal } from "./pubsub-signal.js";

package/dist/search/purge-subject.js

@@ -104,22 +104,20 @@ function ownershipPredicates(entity, searchableFields, entityName, subject, next
         }
     }
 }
-// ponytail: LIMIT/OFFSET, not a keyset cursor — mirrors reindexEntity's same
-// tradeoff (id type varies uuid/serial across entities). A tenant-destroy
-// purge is a one-time sweep, not a hot path.
 const PURGE_BATCH_SIZE = 500;
 async function collectMatchingRowsForEntity(db, tableName, whereSql, params) {
     const rows = [];
-    let offset = 0;
+    let lastId;
     for (;;) {
-        const offsetN = params.length + 1;
-        const page = await executeRawQueryRead(db, `SELECT id, tenant_id FROM ${quoteIdent(tableName)} WHERE ${whereSql}
+        // Keyset, not OFFSET: rows deleted or changed while the loop runs must not shift the window.
+        const afterLastId = lastId === undefined ? "" : ` AND ${quoteIdent("id")} > $${params.length + 1}`;
+        const page = await executeRawQueryRead(db, `SELECT id, tenant_id FROM ${quoteIdent(tableName)} WHERE (${whereSql})${afterLastId}
         ORDER BY ${quoteIdent("id")} ASC
-        LIMIT ${PURGE_BATCH_SIZE} OFFSET $${offsetN}`, [...params, offset]);
+        LIMIT ${PURGE_BATCH_SIZE}`, lastId === undefined ? params : [...params, lastId]);
         if (page.length === 0)
             break;
         rows.push(...page);
-        offset += page.length;
+        lastId = page[page.length - 1]?.id;
         if (page.length < PURGE_BATCH_SIZE)
             break;
     }

package/dist/search/reindex-entity.js

@@ -6,6 +6,7 @@
 // existing row and indexes it, same as a live write would.
 import { resolveTableName } from "../db/entity-table-meta.js";
 import { executeRawQueryRead } from "../db/queries/raw-sql.js";
+import { withoutStatementTimeout } from "../db/statement-timeout.js";
 import { buildSearchDocument, decryptSearchableSubjectFields, hasErasedSearchableSubjectField, } from "../pipeline/system-hooks.js";
 import { toSnakeCase } from "../utils/case.js";
 function quoteIdent(name) {
@@ -25,7 +26,10 @@ function rowToState(row, fieldNames) {
     }
     return state;
 }
-export async function reindexEntity(db, registry, searchAdapter, entityName, tenantId, options = {}) {
+export function reindexEntity(db, registry, searchAdapter, entityName, tenantId, options = {}) {
+    return withoutStatementTimeout(db, (unboundedDb) => scanAndIndexEntity(unboundedDb, registry, searchAdapter, entityName, tenantId, options));
+}
+async function scanAndIndexEntity(db, registry, searchAdapter, entityName, tenantId, options) {
     const entity = registry.getEntity(entityName);
     if (!entity) {
         throw new Error(`reindexEntity: unknown entity "${entityName}"`);
@@ -49,7 +53,7 @@ export async function reindexEntity(db, registry, searchAdapter, entityName, ten
         wouldIndexRows: 0,
         failures: [],
     };
-    let offset = 0;
+    let lastId;
     // Whether a searchable field lacks a matching read-table column depends
     // only on the table's column set (rowToState/Object.hasOwn), not on any
     // particular row's data — every row from the same SELECT * has the same
@@ -59,15 +63,12 @@ export async function reindexEntity(db, registry, searchAdapter, entityName, ten
     // entries, and the real schema problem is buried in "x failed").
     let uncheckedSchema = true;
     for (;;) {
-        // ponytail: LIMIT/OFFSET, not a keyset cursor — id can be uuid or
-        // serial depending on the entity, and a uniform cursor comparison
-        // across both types needs a text cast that breaks integer ordering.
-        // This is a one-time backfill over existing rows, not a live hot path;
-        // switch to keyset if it ever needs to run against a churning table.
+        // Keyset, not OFFSET: rows deleted or changed while the loop runs must not shift the window.
+        const afterLastId = lastId === undefined ? "" : `AND ${quoteIdent("id")} > $3`;
         const rows = await executeRawQueryRead(db, `SELECT * FROM ${quoteIdent(tableName)}
-        WHERE ${quoteIdent("tenant_id")} = $1 ${deletedFilter}
+        WHERE ${quoteIdent("tenant_id")} = $1 ${deletedFilter} ${afterLastId}
         ORDER BY ${quoteIdent("id")} ASC
-        LIMIT $2 OFFSET $3`, [tenantId, batchSize, offset]);
+        LIMIT $2`, lastId === undefined ? [tenantId, batchSize] : [tenantId, batchSize, lastId]);
         if (rows.length === 0)
             break;
         if (uncheckedSchema) {
@@ -130,7 +131,7 @@ export async function reindexEntity(db, registry, searchAdapter, entityName, ten
         else if (options.dryRun) {
             result.wouldIndexRows += docs.length;
         }
-        offset += rows.length;
+        lastId = rows[rows.length - 1]?.["id"];
         if (rows.length < batchSize)
             break;
     }

package/dist/ui-types/index.d.ts

@@ -12,7 +12,7 @@ export type { AccessRule, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPe
 export { isOpenToAllGranted, isUiAccessGranted } from "../engine/types/handlers.ts";
 export type { IconKey, NavDefinition, NavIconKey } from "../engine/types/nav.ts";
 export type { ActionFormFooterAction, ActionFormLoad, ActionFormRedirect, ActionFormScreenDefinition, ActionFormSuccessFact, ActionFormSuccessLink, ConfigEditScreenDefinition, CustomScreenDefinition, CustomScreenRoute, DashboardChartKind, DashboardChartMarkerKind, DashboardChartPanel, DashboardChartRangeOption, DashboardChartRanges, DashboardChartTone, DashboardCurrencyFormat, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelEmptyState, DashboardPanelGate, DashboardPanelQueryOptions, DashboardPanelSpan, DashboardPanelVisibility, DashboardProgressListPanel, DashboardProgressTone, DashboardRecordBinding, DashboardRefresh, DashboardRelativeTimeFormat, DashboardRelativeTimeParam, DashboardScopeDefinition, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextBlock, DashboardTextPanel, DashboardTextParam, DashboardTimeRangeDefinition, DashboardValueFormat, EditExtensionSection, EditFieldPrefill, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditWriteFormSection, EmbeddedListEditSpec, EntityEditAction, EntityEditActionPlacement, EntityEditScreenDefinition, EntityListExpandableRow, EntityListFacetConfig, EntityListFacetExtraOption, EntityListScreenDefinition, EntityWriteExcludedFields, FieldAffix, FieldCondition, FieldFillAction, FieldIconKey, FieldRenderer, FormWidth, ListBadgeTone, ListColumnDisplay, ListColumnSpec, ListEmptyStateSpec, ListFacetSpec, ListSortSpec, MetricNavigate, MetricSpec, PlatformComponent, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordHeaderSubtitlePart, RelatedListGroupBy, RelatedListRowTone, RelatedListToolbarAction, RowAction, RowActionClientAction, RowActionDisplay, RowActionDrawer, RowActionMode, RowActionNavigate, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenSlots, SecretMintConfirmStep, SecretMintScreenDefinition, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, ToolbarAction, } from "../engine/types/screen.ts";
-export { metricField, relatedListGroupHeaderLabel, relatedListGroupKey, } from "../engine/types/screen.ts";
+export { relatedListGroupHeaderLabel, relatedListGroupKey, } from "../engine/types/screen.ts";
 export type { TargetRef } from "../engine/types/target-ref.ts";
 export type { TreeAction, TreeNode, TreeNodeState } from "../engine/types/tree-node.ts";
 export type { WorkspaceDefinition } from "../engine/types/workspace.ts";

package/dist/ui-types/index.js

@@ -25,7 +25,7 @@ export { applyFormDerivations, isFormDerivationInputMode, isUnusedFallbackOperan
 export { parseRefTarget } from "../engine/parse-ref-target.js";
 export { ACTION_FORM_PSEUDO_ENTITY, availableSelectOptions, evalFieldCondition, explicitListScreenId, findUnavailableSelectOptions, isExtensionEditSection, isFieldsEditSection, isFormatSpec, isRecordLocked, isUnchangedValue, isWriteFormEditSection, normalizeEditField, normalizeListColumn, resolveNavParentScreen, sectionFieldSpecs, } from "../engine/screen-helpers.js";
 export { isOpenToAllGranted, isUiAccessGranted } from "../engine/types/handlers.js";
-export { metricField, relatedListGroupHeaderLabel, relatedListGroupKey, } from "../engine/types/screen.js";
+export { relatedListGroupHeaderLabel, relatedListGroupKey, } from "../engine/types/screen.js";
 export { ACTION_FORM_ENTITY, handlerFieldLabelKey, handlerTitleKey, PROJECTION_DETAIL_ENTITY, WRITE_FORM_SECTION_ENTITY, } from "../i18n/required-surface-keys.js";
 export { CARD_META_MAX, cardColumnRoles, cardFileDisplayKind } from "./card-column-roles.js";
 export { formalLocaleTag } from "./formality.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.381.0",
+  "version": "0.383.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,7 +199,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.381.0",
+    "@cosmicdrift/kumiko-types": "0.383.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -215,7 +215,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-testing": "0.381.0",
+    "@cosmicdrift/kumiko-testing": "0.383.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,68 @@
 [
+  {
+    "version": "0.383.0",
+    "type": "breaking",
+    "title": "Placeholder reasons are rejected at boot and at runtime",
+    "detail": "An empty, whitespace-only or placeholder reason (\"todo\", \"tbd\", \"fixme\", \"legacy\", \"temp\", \"wip\", \"n/a\", \"none\", \"xxx\", a \"todo:\" / \"fixme:\" / \"tbd:\" prefix, or the migrate-cross-tenant codemod marker) now fails boot for `openToAll.reason` and `escapeHatch.reason`, and throws at call time for `ctx.systemDb.unsafeRaw(reason)`, `acknowledgeCrossTenant(reason)`, `unsafeAllTenants: { reason }` on read steps and `declareEscapeHatch({ reason })`, which is no longer a no-op. The Escape-Hatch-Declared and Open-To-All-Reason guards that checked this statically are removed.",
+    "migration": "Replace every placeholder reason with the real justification (why this access is needed and on whose right). Reasons held in imported constants were never judged by the guards and surface now, at boot or on first use."
+  },
+  {
+    "version": "0.383.0",
+    "type": "breaking",
+    "title": "loadAllEventsByType and LOAD_ALL_EVENTS_ROW_LIMIT are removed",
+    "detail": "loadAllEventsByType buffered every event of an aggregate type in memory and had no production caller. It is removed together with LOAD_ALL_EVENTS_ROW_LIMIT and the Loadall-Events guard.",
+    "migration": "Use `await Array.fromAsync(streamAllEventsByType(db, aggregateType))`, or iterate the stream with `for await` to stay memory-bounded. The stream is ordered by event id; loadAllEventsByType ordered by (createdAt, id)."
+  },
+  {
+    "version": "0.383.0",
+    "type": "breaking",
+    "title": "metricField is removed from the screen type exports",
+    "detail": "metricField is removed from the engine types and ui-types exports because MetricSpec is always an object now.",
+    "migration": "Replace `metricField(metric)` with `metric.field`."
+  },
+  {
+    "version": "0.383.0",
+    "type": "improvement",
+    "title": "Text field format \"iban\"",
+    "detail": "createTextField({ format: \"iban\" }) validates the value server-side (spaces ignored, case-insensitive, country and check digits shape plus mod-97) and reports invalid_format with format iban, which the form maps to errors.validation.invalid_format.iban (texts in en, de, es, fr, it). The value is stored as typed."
+  },
+  {
+    "version": "0.383.0",
+    "type": "improvement",
+    "title": "Process logger, request context fields and redaction",
+    "detail": "runProdApp and runWorkerApp install a pino process logger (JSON in production) that every createFallbackLogger without an explicit logger resolves lazily, with a component field. Log lines carry requestId, correlationId, tenantId, userId, feature and handler from the request context; jobs carry tenantId and userId too. Keys such as password, token, secret, apiKey, authorization, cookie, set-cookie, x-api-key, sessionToken, privateKey, credentials, otp, iban and email are redacted to [redacted] up to depth 2. New scrubLogText masks e-mail addresses, JWTs, bearer tokens and Postgres key details in server-fault, job-failure and client-error logs."
+  },
+  {
+    "version": "0.383.0",
+    "type": "improvement",
+    "title": "POST /api/client-errors collects browser error reports",
+    "detail": "Anonymous endpoint with a strict body (errorId, kind, message, stack, screen, path, buildVersion), an 8 KB cap (413), 400 without echo, a per-IP limit of 10 per minute (429, in memory per process when Redis is absent) and 204 on success. The report is logged as a scrubbed warning; the query and hash of the path are cut. With a session the report carries tenantId and userId."
+  },
+  {
+    "version": "0.383.0",
+    "type": "improvement",
+    "title": "Global IP and http-route limits fail open when Redis is down",
+    "detail": "Behavior change: previously a Redis error answered 503 on these two limits. The l1-global-ip and http-route limits let the request through on a Redis error instead of answering 503, count it in kumiko_rate_limit_fail_open_total{label} and log a warning at most every 30 s. The l2-auth-endpoints and login/MFA limits stay fail-closed. A Redis client that is not ready fails fast instead of waiting for the command timeout. Redis connection loss and recovery are logged once per state change."
+  },
+  {
+    "version": "0.383.0",
+    "type": "breaking",
+    "title": "globalIpRateLimit and httpRouteRateLimit option onFailClosed is now onFailOpen",
+    "detail": "The option is renamed because both limits now let the request through on a Redis error; the callback receives the error and is throttled to one warning per 30 s. Both limits also accept a meter for kumiko_rate_limit_fail_open_total.",
+    "migration": "rename onFailClosed to onFailOpen in globalIpRateLimit and httpRouteRateLimit options; the callback no longer implies a 503, the request continues"
+  },
+  {
+    "version": "0.383.0",
+    "type": "improvement",
+    "title": "Prod and worker pools cap statements at 60 s and idle transactions at 300 s",
+    "detail": "Behavior change, not an API break. runProdApp and runWorkerApp now open their Postgres pools with statement_timeout 60 s and idle_in_transaction_session_timeout 300 s (handlers that await external calls inside a transaction are not killed early, leaked transactions still end), so one runaway query or a transaction left open no longer holds a connection indefinitely. lock_timeout stays off. Opt out per limit by setting the variable to 0, or change it, with DATABASE_STATEMENT_TIMEOUT_MS, DATABASE_IDLE_IN_TRANSACTION_TIMEOUT_MS and DATABASE_LOCK_TIMEOUT_MS (for example DATABASE_STATEMENT_TIMEOUT_MS=0); createDbConnection takes statementTimeoutMs, idleInTransactionSessionTimeoutMs and lockTimeoutMs. Migrations, projection and multi-stream rebuilds, search reindex, PII backfills and the CREATE INDEX CONCURRENTLY helpers run without the statement cap (withoutStatementTimeout). A custom long-running statement on the app pool now needs the same helper or a higher limit."
+  },
+  {
+    "version": "0.383.0",
+    "type": "fix",
+    "title": "Reindex and subject purge scan by keyset instead of OFFSET",
+    "detail": "reindexEntity and the subject purge page with WHERE id > last ORDER BY id LIMIT n, so rows deleted or changed while the scan runs no longer make it skip later rows."
+  },
   {
     "version": "0.380.0",
     "type": "breaking",