@cosmicdrift/kumiko-framework 0.387.0 → 0.389.0

package/src/changes.json

@@ -1,4 +1,559 @@
 [
+  {
+    "version": "0.389.0",
+    "type": "breaking",
+    "title": "Bun.SQL replaces postgres-js as the only Postgres driver",
+    "detail": "createDbConnection opens a Bun.SQL pool and needs Bun 1.4.4 or newer, the first release that drops a cached statement plan after DDL on the same connection. The handle gains listenClient for LISTEN/NOTIFY. Server errors carry the code ERR_POSTGRES_SERVER_ERROR with the SQLSTATE in errno and the constraint name in constraint; connection failures carry ERR_POSTGRES_CONNECTION_CLOSED, ERR_POSTGRES_CONNECTION_REFUSED, ERR_POSTGRES_CONNECTION_TIMEOUT or ERR_POSTGRES_CONNECTION_FAILED. extractPgError, isUniqueViolation, isTableAlreadyExists, constraintOf and the newly exported isUndefinedTable read that shape. The onNotice option is removed, because Bun.SQL has no notice hook and drops server notices. The ssl option takes Bun's tls value (a boolean, \"disable\", \"prefer\", \"require\", \"verify-ca\", \"verify-full\" or a TLS options object); ssl true and a TLS object without rejectUnauthorized still verify the server certificate, as they did with postgres-js. DB_PROVIDER is refused at boot for every non-empty value, \"postgres\" included.",
+    "migration": "Read SQLSTATE and constraint only through extractPgError or the is* helpers from @cosmicdrift/kumiko-framework/db; a direct err.code === \"23505\" check or an err.constraint_name read no longer matches. Replace checks for CONNECTION_CLOSED, CONNECTION_ENDED, CONNECTION_DESTROYED or CONNECT_TIMEOUT with the ERR_POSTGRES_CONNECTION_* codes. Drop onNotice from createDbConnection calls. Remove DB_PROVIDER from every environment. Run on Bun 1.4.4 or newer in engines, CI and images. Code that imports postgres itself must declare its own dependency or move to Bun.SQL, since the framework no longer installs it. Manual migration, there is no codemod."
+  },
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "schema status and baseline use one connection, bun-types is a peer dependency",
+    "detail": "kumiko schema status and baseline open a pool of one connection instead of the default size, because Bun.SQL dials every pool connection on the first query. bun-types is now a peer dependency (^1.4.4) of framework, types, server-runtime and dev-server instead of a regular dependency, so install it next to the framework."
+  },
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "validateBundledListsOptions and the BundledListsOptions type",
+    "detail": "BundledListsOptions is exported from the types package and the engine barrel. validateBundledListsOptions rejects unknown keys, grouping, totals and pinFirstColumn without table.pinning with a message that names the key, and checks the remaining keys like a screen's own table block."
+  },
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "r.adoptsBundledLists() marks features that take the bundledLists block",
+    "detail": "The registrar method r.adoptsBundledLists() marks a feature whose list screens take the app-wide bundledLists block; the flag appears as FeatureDefinition.adoptsBundledLists and in feature-manifest.json, and the feature-ast parser knows the call as an opaque singleton pattern."
+  },
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "table block on entityList, projectionList and relatedList",
+    "detail": "The new optional table block (rememberState, resetAll, columnPicker, density with default and userChoice) is validated at boot; unknown keys, hidden columns without columnPicker and invalid density values are rejected. Columns accept hidden: true. Remembered state lives in sessionStorage per tenant and user and is cleared on logout or identity change."
+  },
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "table.pinning, table.resizing and table.keyboardNavigation, column pinned, width and minWidth",
+    "detail": "The boot validator rejects pinned without table.pinning, a pinned value other than left or right, width or minWidth without table.resizing, values that are not finite numbers above 0, and a minWidth above the width."
+  },
+  {
+    "version": "0.389.0",
+    "type": "breaking",
+    "title": "Money list aggregates answer one value per currency",
+    "detail": "A sum, avg, min or max measure over a money field in a list aggregate now answers [{ currency, value }] with value in minor units, one entry per currency in the matching rows, and never adds amounts of different currencies. Before, it answered one plain number over all currencies.",
+    "migration": "code reading measures of a money field from a list aggregate answer (executor.aggregate, answerListAggregate or the list query with aggregate) reads an array of { currency, value } instead of a number; take the entry of the wanted currency, value stays in minor units"
+  },
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "table.grouping, table.totals and range facets validated at boot",
+    "detail": "The table block takes grouping ({ field, label?, labels?, collapsedWhen?, userChoice?, fields? }) and totals ([{ field, kind }]). The boot validator checks the fields against the entity or the columns, rejects measures a field type cannot carry and requires the list query to accept aggregate (entityListSchema does; hand-written queries answer it with answerListAggregate). facets.<field>.display \"range\" needs a filterable number, decimal, money or bigInt field."
+  },
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "bulkActions on entityList, projectionList and relatedList",
+    "detail": "Each entry is { id, rowAction, confirm? } and points at a writeHandler entry of the same screen's rowActions. The boot validator rejects unknown keys, a non-kebab or duplicate id, an unknown rowAction and a rowAction of kind clientAction, navigate or drawer."
+  },
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "XLSX export for entityList and projectionList via table.export",
+    "detail": "The new table.export block ({ xlsx: true, maxRows? }) is validated at boot and is only accepted on entityList and projectionList. POST /api/export/xlsx runs the list query again with the caller's session, pages through the whole filtered list and answers 413 above maxRows (default 10000, hard cap 100000). Encrypted, sensitive, write-only and unreadable fields and virtual columns are left out of the sheet. Reference columns export the label of the target (joined with commas for multiple references), not the id. Timestamp cells use the browser time zone sent with the request, else the profile zone, else UTC. Personal access tokens are rejected. A projectionList query must honor offset or return nextCursor. Adds the write-excel-file dependency."
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "Executor writes on a pool runner are atomic",
+    "detail": "executor.create/update/delete/forget/restore on a TenantDb that is not inside a transaction used to run append, projection and custom projections as separate autocommit statements, so a failing projection left an event without its row. They now run in their own transaction, and a returned failure such as version_conflict rolls it back too. Calls inside a handler transaction keep their savepoint behavior. Callers that wrapped executor writes in runInOwnTransaction as a workaround can drop it."
+  },
+  {
+    "version": "0.389.0",
+    "type": "breaking",
+    "title": "FeatureRegistrar types moved to @cosmicdrift/kumiko-types/feature-registrar",
+    "migration": "Import FeatureRegistrar, HookDefinition, EntityObjectDefinition and RequiresApi from @cosmicdrift/kumiko-types/feature-registrar or from the engine barrel of @cosmicdrift/kumiko-framework; @cosmicdrift/kumiko-types/feature no longer exports them."
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "maxPerTenant counts active and waiting jobs in one snapshot",
+    "detail": "The guard read the active and the waiting list with separate Redis calls, so a job that moved from waiting to active between them was missing from both and a dispatch over the cap got through. It now reads both lists with one getJobs snapshot per queue. The integration tests hold the cap jobs on a release gate instead of sleeping."
+  },
+  {
+    "version": "0.389.0",
+    "type": "breaking",
+    "title": "relatedList groupBy replaced by table.grouping",
+    "detail": "The groupBy key on a relatedList section and an entityList expandableRow is removed together with the RelatedListGroupBy type. Both group through table.grouping ({ field, label?, labels?, collapsedWhen? }): groups, counts and header measures come from one aggregate query over all matching rows instead of the loaded page, and each open group loads its own rows. An expandableRow takes only table.grouping with a fixed field; userChoice, fields and every other table option stay boot errors there. The boot validator reports a leftover groupBy with a pointer to table.grouping. ExpandableRowGrouping is the new type of an expandableRow's grouping.",
+    "migration": "move groupBy { field, collapsedWhen, label, labels } to table: { grouping: { field, collapsedWhen, label, labels } }; the bound query must accept aggregate (entityListSchema does, a hand-written query answers it with answerListAggregate). dateField and the {lastDate} placeholder have no replacement on an expandableRow, where totals stay off; on a relatedList a max measure in table.totals shows the latest date. Every group now gets a header: a group without label or labels entry shows its value instead of rendering headerless."
+  },
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "ctx.loadAggregate can read a single event by version",
+    "detail": "The new atVersion option returns the event at that version of the stream (or nothing), with upcasting and the tenant filter. It cannot be combined with asOf. Workflow resume uses it for event references."
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "Access invalidation survives a Redis outage",
+    "detail": "The consumer that pushes session, token and membership revocations to open streams does not count failed publishes towards the attempt limit and backs off between them, instead of dying after 10 failed deliveries and silently dropping later revocations. Other failures keep the limit. New EventConsumerErrorPolicy.isTransientError."
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "file upload rechecks the record lock when inserting the row",
+    "detail": "POST /files with an entityId reads the stored row again through the inserting transaction and refuses with 409 record_locked when lockedWhen holds. The window between that read and the commit stays open, like for any other write that checks the lock before its own commit."
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "Meilisearch default upgrade cannot tell a narrowed configure() from an older default",
+    "detail": "A tenant that called configure() with a strict subset of the default attributes gets the full default back after the next process restart, because Meilisearch stores no marker for an explicit configure(). Configure the full attribute set, or a set that contains an attribute outside the default, to keep it."
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "Cross-tenant-read crons audit once per day, not once per foreign row",
+    "detail": "The process dedup key of a declared system cron hatch includes the target only for global-write (a table). Row targets of cross-tenant-read no longer grow the in-memory map or write one audit event per row."
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "Failed job-runner start waits for the timed-out boot gate",
+    "detail": "start() now waits a bounded time for an abandoned boot gate before throwing, instead of leaving that to stop(). The scheduler-seen timer is only started after every step that can fail, so no timer outlives a failed start."
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "disabled feature no longer removes another feature's workspace with the same id",
+    "detail": "buildAppSchema records which feature owns each workspace and the feature strip removes only the workspaces of the disabled features. Two features that use the same short workspace id keep their own entries."
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "upload ledger uses the injected clock",
+    "detail": "createFileUploadLedger and withUploadLedger take an optional now function, and the file provider resolver wires AppContext.clock into it. Without a clock the system time is used as before."
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "anonymous save leaves foreign pending uploads unbound",
+    "detail": "Integration test through the real write route with anonymous access, covering the save pipeline path of the pending-upload ownership check."
+  },
+  {
+    "version": "0.389.0",
+    "type": "breaking",
+    "title": "Unused ProviderPluginContext helpers removed",
+    "detail": "ProviderPluginContext, providerPluginContextFromHandler and providerPluginContextFromJob are gone. No plugin type or resolver used them, and the type exposed db handles without an audit user. Provider contexts stay the narrow FileProviderContext, MailTransportContext and InboundMailContext.",
+    "migration": "no known callers; use FileProviderContext, MailTransportContext or InboundMailContext"
+  },
+  {
+    "version": "0.389.0",
+    "type": "breaking",
+    "title": "provider selector option labels are unique per owner",
+    "detail": "The selector field id of a provider form is qualified with its owner feature, so the translation keys of its option labels change.",
+    "migration": "move app translation overrides from config:entity:__config-edit__:field:provider:option:<value> to the owner-qualified field id, field:mail-foundation-provider:option:<value> or field:file-foundation-provider:option:<value>"
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "live signals hide row ids from row-filtered roles",
+    "detail": "createSseRoute takes an optional entityRowReadMaps option, built from entity access.read by the server routes. A signed-in connection receives id and version only if the entity has no read ownership map or one of its roles is mapped to all; otherwise the signal carries just the entity and event type so the client refetches."
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "write handlers that spread the executor result keep projections and postSave hooks",
+    "detail": "The event is stripped from lifecycle results when the dispatcher masks the response, no longer made non-enumerable on the result, so copying the result does not lose it. Responses still carry no event."
+  },
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "event-free write results proven for non-HTTP entry points",
+    "detail": "Integration tests assert that dispatcher.write, dispatcher.batch and the agent tool dispatch return no event. No runtime change: all of them already pass through the dispatcher masking."
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "reference-data seed adopts rows that have no event stream",
+    "detail": "Rows from installs that seeded reference data by direct insert are re-created under the same id through the executor on the next boot, so updates apply and the rows survive a rebuild. No action is needed; the row id is unchanged, only its version restarts at 1."
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "client-errors route keeps an in-memory floor limit",
+    "detail": "The in-memory per-IP limiter now runs in front of the Redis-backed limiter instead of only when no resolver is wired, so a failing resolver can no longer lift the limit on the public client-errors endpoint."
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "reindex job batches are no longer cut off by the server statement timeout",
+    "detail": "reindexEntity reads each batch in its own transaction with statement_timeout lifted for that transaction, on the caller's own runner, so the job path through ctx.systemDb.unsafeRaw() keeps its gates."
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "files meta batch route is rate limited by id count",
+    "detail": "createFileRoutes takes an optional metaBatchRateLimitResolver, wired by the server from the rate-limit resolver or Redis. A user over 1000 requested ids per minute gets 429 rate_limited; a failing limiter fails open and is reported like the other limiters."
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "kumiko-upgrade explains that --apply writes the CHANGELOG",
+    "detail": "The preview run never wrote the upgrade CHANGELOG or the marker, and consumers running it without --apply got no entry and no explanation. It now prints a hint; the exit code is unchanged."
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "Codemod imports no longer land inside header comments",
+    "detail": "ensureNamedImport appends the new import after the last existing import, so a file with a header comment block keeps the comment intact."
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "Database now is rounded to milliseconds",
+    "detail": "The Postgres clock read behind readDatabaseNow is cast to timestamptz(3), the precision of events.created_at, so a comparison with a stored event time is exact."
+  },
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "E2E seeders and signature routes can write with explicit roles",
+    "detail": "dispatchWriteAs on signature route deps and writeAs on the E2E seeder context run a write as the tenant's system user with the \"system\" role plus the given roles, without SystemAdmin. write() keeps running as SystemAdmin."
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "List filter on multiple references matches array contents",
+    "detail": "eq, ne and in on a multi-reference field now check jsonb containment instead of scalar equality, and screen filters on such fields allow the equality operators. Consumers no longer need a full scan."
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "kumiko-upgrade --resolve updates CHANGELOG.md",
+    "detail": "The Manual migrations lines of every CHANGELOG.md section change from [open] to the chosen resolution for the resolved ids; other entries and files without a CHANGELOG.md are left alone."
+  },
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "ctx.scheduleAfterRollback for outside-transaction compensation",
+    "detail": "ctx.scheduleAfterRollback(fn) runs fn when the handler transaction does not commit, or when the enclosing savepoint of a nested ctx.write rolls back (after the outer transaction ends). It never runs on commit, errors are logged and do not change the write result, and it is absent outside a transaction scope (perCommand, post-commit, beforeTransaction, member resolution). A failed COMMIT also triggers it, so callbacks must be idempotent and outcome-safe, for example releasing a reservation row that may already be gone."
+  },
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "Tenant-safe upsert on ctx.db",
+    "detail": "ctx.db.upsert(table, values, { conflictTarget, update? }) requires tenantId in conflictTarget and the target to match a declared unique index or primary key. The update only touches the row of the inserted tenant, update may not set tenantId, and the default update leaves conflict, primary-key and tenant columns alone. Event-fed tables are rejected. Replaces unsafeRaw plus upsertOnConflict for tenant-scoped upserts."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "runProdApp passes errorDocs and instanceId to the server",
+    "detail": "ApiEntrypointOptions now carries errorDocs and instanceId and createApiEntrypoint forwards them to the server. Before, runProdApp dropped its errorDocs option, and a KUMIKO_INSTANCE_ID set only in a custom envSource never reached the server, which fell back to process.env. The boot-abort cleanup of runProdApp also moved into a helper that swallows synchronously throwing cleanups."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Physical-table collisions use the DDL table name",
+    "detail": "createRegistry compared entity tables under a feature-prefixed name that no DDL path creates, so an entity whose explicit table equals another feature's derived table name, or two entities with the same explicit table in different features, registered fine and then emitted the same CREATE TABLE twice. The check now uses the unprefixed physical name, the same as the store-table check and the migrate runner.",
+    "migration": "Apps where two entities share a physical table name fail at boot with \"has physical table ... which collides with entity ...\". Give one of them a different `table`."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Worker entrypoint takes instanceId",
+    "detail": "WorkerEntrypointOptions now carries instanceId (moved to BaseEntrypointOptions, so the API and all-in-one options keep it) and createWorkerEntrypoint forwards it to the server. runWorkerApp reads KUMIKO_INSTANCE_ID from its envSource like runProdApp, so with KUMIKO_INSTANCE_ID set, per-instance consumers in the worker and its app.started event use the same id. Before, the worker server only saw process.env."
+  },
+  {
+    "version": "0.388.0",
+    "type": "improvement",
+    "title": "PII, retention and cascade-delete rules as tables, English dev messages",
+    "detail": "validatePiiAndRetention runs one checker per rule in a fixed order, and the cascade-delete hook dispatches each relation through a table of onDelete strategies. Error and warning texts, their order, transaction boundaries and event order are unchanged. buildAppSchema forwards field properties through an ordered table, and kumiko-upgrade and the pii-personal-migration codemod run one function per step; their output is byte-identical. The dev warnings of normalizeListColumn and buildAppSchema are now English."
+  },
+  {
+    "version": "0.388.0",
+    "type": "improvement",
+    "title": "Named steps for list reads, field columns, table metadata and table diffs",
+    "detail": "The list read verb runs search, sort, cursor boundary, filters, stream-version projection, row rehydration and the next cursor as named steps in their own files next to event-store-executor-read.ts, and detail() shares the ownership and row rehydration steps. Field columns come from one emitter per field type in a typed table, so a new field type fails the typecheck until it has an emitter, and an unknown type from untyped input still throws \"unhandled field type\". deriveEntityTableMeta collects columns, foreign-key, blind-index and declared indexes in separate steps with the same overloads and error texts. diffOneTable compares columns and indexes through one comparator per kind and keeps the order of added, dropped and changed entries."
+  },
+  {
+    "version": "0.388.0",
+    "type": "improvement",
+    "title": "Per-kind tables for feature-AST id matching, editability and rendering",
+    "detail": "callMatchesId() looks up one matcher per PatternId kind in a typed table in feature-ast/pattern-id-matchers.ts next to patch.ts. getEditability() reads a table keyed by pattern kind, and renderPattern() dispatches through one renderer per pattern kind. All three tables are typed over their kind union, so a new kind does not compile until it has an entry. The feature-ast barrel exports the same names as before."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Boot enforces the projection allowlist",
+    "detail": "The projection allowlist validator existed but was never called from validateBoot. It now runs as the last cross-feature check. It also keys aggregate tables by the physical table name (entity.table or the derived read_* name) instead of the entity name, so unsafeProjection steps on the table of an entity without an explicit table, and duplicate tables between a derived and an explicit name, are detected.",
+    "migration": "Apps with such violations fail at boot. Add the missing r.requires.projection or r.requires.step declaration, or use r.step.aggregate.* for aggregate tables."
+  },
+  {
+    "version": "0.388.0",
+    "type": "improvement",
+    "title": "Recipe for Input kind \"code\" in a confirmation step",
+    "detail": "samples/recipes/auth-mfa has a ConfirmationCodeStep for e-mail or invite codes that uses Input kind \"code\" with length, autoFocus and onComplete, clears and refocuses after a rejected code, and has a DOM test. The agent example for auth-mfa includes it."
+  },
+  {
+    "version": "0.388.0",
+    "type": "improvement",
+    "title": "Groups and sums on the entity list query",
+    "detail": "Pass aggregate with an optional groupBy field and up to 20 measures (sum, avg, count, min, max per field) to a list query. The answer is groups with key, count, one value per measure in request order and, for a reference groupBy, the label of the referenced row. Screen filters, search, ownership and field read access apply exactly as for rows; a field the caller may not read yields null or no groups, and encrypted, personal or secret fields and unsuitable field types are rejected with a validation error. At most 200 groups are returned, with truncated set beyond that. Custom query handlers use executor.aggregate or answerListAggregate."
+  },
+  {
+    "version": "0.388.0",
+    "type": "improvement",
+    "title": "buildServer split into middleware installers and route mounters",
+    "detail": "buildServer() keeps its signature and behavior. Boot checks, pre-app wiring, the event dispatcher, middleware installers and route mounters now live in server-*.ts files next to server.ts. withFileProviderResolver and makeDispatchSystemWrite/makeDispatchWriteAs/makeDispatchSystemQuery are still exported from the api barrel under the same names."
+  },
+  {
+    "version": "0.388.0",
+    "type": "improvement",
+    "title": "Where-clause emitters, coercer table and named write steps",
+    "detail": "buildWhereClause() now dispatches through one emitter per WhereOperator key in a typed table, and coerceDriverRow() looks up one coercer per pgType. Table introspection, value preparation, row coercion, closed-connection handling and aggregate SQL live in their own files next to db/query.ts. The create and update write verbs run preSave, field and ownership checks, the record-lock guard, select-option checks, the version check, the append and the projection as named steps. The db barrel exports the same names as before."
+  },
+  {
+    "version": "0.388.0",
+    "type": "improvement",
+    "title": "Job runner run path split into named steps",
+    "detail": "handleJob() in jobs/job-runner.ts now composes the perTenant fan-out, the unknown-job check, the maxPerTenant defer gate and the sequential lock (job-runner-gates.ts), the run context with its db, service and dispatch facets (job-runner-context.ts), the job.execute span with success and failure recording (job-runner-execution.ts) and the handler deferral. The runner's shared state travels in one scope object (job-runner-scope.ts). The jobs barrel exports the same names as before. New integration tests cover unknown jobs taken from the queue, a perTenant wrapper for an unknown job, a perTenant job without a tenant resolver and ctx.defer with a non-positive delay."
+  },
+  {
+    "version": "0.388.0",
+    "type": "improvement",
+    "title": "Handler context and write pipeline split into named steps",
+    "detail": "buildHandlerContext() in pipeline/dispatch-shared.ts now composes one builder per facet of the flat HandlerContext: the shared scope (handler-context-scope.ts), the tenant-scoped db handles, forTenant and file contexts (handler-context-db.ts), the commit sinks with ctx.query/write/queryAs/writeAs and nested writes in savepoints (handler-context-dispatch.ts), ctx.notify (handler-context-notify.ts), config, configFor, tz and locale (handler-context-config.ts), the event store surfaces and ctx.queryProjection (handler-context-events.ts), the identity-gated auth surfaces and ctx.hasFeature (handler-context-auth.ts) and log, tracer and metrics (handler-context-observability.ts). executeWriteInner() in pipeline/dispatch-write.ts runs the entry checks, the pre-handler gates with the reservation, the transition guard, the handler call and the settle step with reservation confirm, lifecycle and after-commit hooks as separate functions; executeNestedWrite() checks the nested foreign keys, verifies the parent row and writes the children in their own steps. Public exports are unchanged. New tests cover the ctx.snapshotAggregate/ctx.loadAggregateWithSnapshot roundtrip with tenant isolation and the no-database error text of the event store surfaces."
+  },
+  {
+    "version": "0.388.0",
+    "type": "improvement",
+    "title": "kumiko-schema output in English, schema CLI and screen key collection split per kind",
+    "detail": "Visible change: kumiko-schema (and the dev `kumiko schema` command) now prints \"is missing\", \"App convention\", \"No schema changes detected — no new migration file written.\", \"Review, hand-edit if needed, then git add + commit.\", \"is missing — run schema generate <name> first.\", \"No kumiko/migrations/ — the app is still on the legacy drizzle path.\", \"Unknown subcommand\" / \"Allowed\", \"must declare `export const ENTITY_METAS: EntityTableMeta[]`\" and an English help text instead of the German lines. The standalone `kumiko schema apply` of production bundles prints \"Creating framework infrastructure tables (idempotent)…\", \"Applying kumiko migrations (…)…\", \"… is missing — kumiko/migrations/ must be part of the image.\" and \"Unknown command: kumiko … / The standalone bundle only supports 'kumiko schema apply'.\". Scripts that matched the German text need the English one. Exit codes, the order of the output lines and which lines go to stderr are unchanged. runSchemaCli() keeps its signature; each subcommand lives in its own file under schema-cli/. requiredKeysFromScreen() returns the same keys in the same order; a screen with an unknown type (only reachable through a cast) yields just its title key."
+  },
+  {
+    "version": "0.388.0",
+    "type": "improvement",
+    "title": "validateScreens split into one validator per screen kind",
+    "detail": "validateScreens() keeps its signature, its error messages and the order in which it reports the first error. The per-kind validators live in screens-kind-*.ts next to screens.ts, and checks shared by several kinds (empty columns or sections, header actions, write-handler registration) live in screens-kind-shared.ts and screens-actions.ts. A screen whose type is not a known kind now fails boot with an explicit \"unknown type\" error."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Sequential job lock released when run setup fails",
+    "detail": "handleJob() claimed the sequential lock before prepareJobRun() and the onJobStart hook, but only released it in the finally block that started after them. A throwing onJobStart left the lock until its TTL (305 s) and every further invocation of that job was requeued behind it. Both calls now run inside the try and the lock is released by job name. A failure there is logged and, on the final attempt, reported through onJobFailed. The seed-migration failure message starts with systemWriteAs(...) instead of the duplicated [es-ops/seed-migration] prefix."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Reconnect after an outage no longer waits out connect_timeout",
+    "detail": "The postgres.js fork left the write buffer of a dead socket in place, so the first query after a database outage queued its startup message behind stale bytes and failed with CONNECT_TIMEOUT after 30 seconds. The fork now resets the buffer when the socket closes, and the next query opens a fresh connection immediately."
+  },
+  {
+    "version": "0.388.0",
+    "type": "improvement",
+    "title": "rateLimitCost for write handlers",
+    "detail": "A write handler can declare `rateLimitCost: (payload) => number`. The result is booked on every declared `rateLimit` bucket instead of the options' static `cost`; values below 1 count as 1 and non-finite values fail the request. The bucket is charged after schema validation, so an invalid payload costs nothing, and a rejected request consumes no tokens. Boot fails when `rateLimitCost` is set without an active `rateLimit`, or on an anonymous or ip-limited handler, because the cost books after the parse and such a handler would lose its pre-parse protection.",
+    "migration": "Optional. Bulk handlers should add `rateLimitCost: (p) => p.files.length` so a request with many items is not counted as one."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Codemods no longer drop side-effect imports or miss moved index files",
+    "detail": "The testing-move codemod repoints side-effect and empty imports instead of deleting them. The feature-layout codemod rewrites directory imports such as \"./components\" when the moved file is components/index.ts."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Review fixes for notify, form derivations, i18n keys, feature AST, nav stripping and escape-hatch audit",
+    "detail": "A deferred ctx.notify with Temporal values in data no longer fails the write. Form derivations take the literal currency or the source currency before the client value, reject mixed-currency operands, and the boot validator now rejects derive definitions that mix money with number/decimal units or use non-numeric sources. Metric labels of projectionDetail screens are required i18n keys. The feature AST keeps backingTable on spread entity definitions. Pure grouping navs emptied by disabled features are removed. db.global() writes are audited per table."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Client-error rate limit survives address rotation",
+    "detail": "Without Redis, the per-process limiter now drops the least recently seen IPs when more than 10000 are tracked, so a flood of fresh addresses no longer resets the window of every other IP."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Stalled SSE clients are dropped without further broadcasts",
+    "detail": "The heartbeat ping is written and tracked like entity frames instead of awaited, so a client that stopped reading is aborted at the next heartbeat after the stall timeout and releases its broker slot."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Leftover __Host- cookies are expired with secureCookies:false too",
+    "detail": "Clearing the session cookies now always sends the Secure delete for the __Host- auth and csrf variants when the configured names are unprefixed, so an app switched to secureCookies:false behind a TLS proxy no longer keeps a stale __Host- csrf cookie."
+  },
+  {
+    "version": "0.388.0",
+    "type": "breaking",
+    "title": "runAsDirectCallEntry renamed to runAsAgentToolCallEntry",
+    "detail": "The internal request-context helper also marks its scope as an agent tool call, so the name now says so; it stays reserved for dispatchToolCall.",
+    "migration": "replace imports of runAsDirectCallEntry from @cosmicdrift/kumiko-framework/internal/request-context with runAsAgentToolCallEntry; the signature is unchanged"
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Version conflicts skip the extra stream-version lookup",
+    "detail": "The CRUD executor reports the current version carried by the event store conflict and queries the stream again only when the conflict carries none."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "distinctOn documents that system reference rows compete for newest",
+    "detail": "The tenant-scoped read set includes system reference rows, so they take part in the newest-row pick; the docs name the tenantId filter that restricts it to own rows, and tests pin both behaviours. Tests also cover the createDbConnection ssl and onNotice options, the version-conflict race over HTTP, and the advisory-lock waiter probe is scoped to its own lock."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Empty and exclusion tenant filters no longer widen a read",
+    "detail": "A where.tenantId of { in: [] } now returns no rows, and { ne } or { notIn } keep excluding the named tenants instead of falling back to the caller's full scope. scopeTenantDbToTenant keeps the write denial of its source TenantDb."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Boot seeding re-creates soft-deleted reference rows",
+    "detail": "The seed lookup only considers live system-tenant rows, so a soft-deleted reference row is created anew instead of aborting the boot with a not-found error."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Version conflict on update reports the appended-against version",
+    "detail": "The racing update path now reports expectedVersion as the stream version it appended against, also with skipOptimisticLock or an expect precondition. A failed advisory unlock after a dropped session no longer hides the migration error."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Unknown keys in a handler field references meta fail the boot",
+    "detail": "A references meta such as `{ entity: \"channel\", bY: \"key\" }` is reported as invalid instead of silently reading as an id reference, so a misspelled `by` can no longer turn a business-key field into an id field."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "r.requires rejects malformed arguments",
+    "detail": "`r.requires` now throws when called with more than one argument or without a `features` string array, instead of dropping extra arguments or registering the object as a dependency name."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "r.bootCheck failures keep the check's own message",
+    "detail": "The boot error no longer appends a generic sentence, so messages ending in a period are not doubled and the check's text is the whole explanation."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Embedded list minimum stays in the JSON schema",
+    "detail": "A required or `minItems` embedded list again reports `minItems` in `z.toJSONSchema` output, so agent manifests tell callers that at least one row is needed."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Failing trial gate no longer breaks GET /api/schema",
+    "detail": "The trial gates of all disabled toggleable features run in parallel; a gate that throws counts as not unlocked, hides the add-on and is logged, so the client still boots."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "No docsUrl for app error codes without a framework page",
+    "detail": "An app subclass that overrides the error code with an uncovered reason no longer links to a framework page that does not exist; the field is absent unless errorDocs covers the reason."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Anonymous sessions cannot bind pending uploads on save",
+    "detail": "The save pipeline now applies the same anonymous-session exclusion as the pending file ref helpers, so one visitor cannot attach another visitor's pending upload to their record."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Failed uploads drop their upload ledger row",
+    "detail": "When the fileRef create fails after the bytes were written, POST /files and createFileRefFromBytes now delete the bytes and forget the ledger row instead of leaving it for the next sweep."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "More HTML roots are kept out of the XML content type",
+    "detail": "Uploads without a declared content type whose root element is a common HTML element (form, iframe, input, table parts, media and others) are no longer labelled application/xml."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "POST /files uses the tenant file context and a transaction-safe upload ledger",
+    "detail": "The upload route records and forgets upload bytes through the resolver's ledger like every other file context, and createFileUploadLedger throws when given a connection already inside a transaction."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "A failed runner start no longer leaves a scheduler refresh timer behind",
+    "detail": "The scheduler-seen refresh timer starts only after the rest of start() succeeded, so a failed start does not keep stamping for a runner that is not running."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Job runs survive a failing tenant timezone config read",
+    "detail": "A throwing tenant timezone config read now logs a warning and falls back to UTC for ctx.tz instead of failing a job that never uses ctx.tz."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Escape-hatch process dedup no longer grows without bound",
+    "detail": "Entries older than the daily re-audit interval are swept, so row-level cross-tenant read targets in long-lived workers are not kept forever."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Handler cross-tenant reads count in the escape-hatch metric",
+    "detail": "Handlers now report to the escape-hatch meter like jobs do, so every ctx.crossTenantReads call is counted while the audit event stays deduplicated per report window."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "beforeTransaction phase and handler share one parsed payload",
+    "detail": "The payload parsed for the pre-transaction phases is handed to the handler as is, so schema defaults or transforms that generate values no longer differ between the phase and the handler."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Cascade delete and set-null load only child ids",
+    "detail": "The cascade handler selects the id column instead of full child rows before calling the executor per child."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Codemods stop miscompiling or skipping ambiguous sites",
+    "detail": "testing-injection rewrites named re-exports of moved names and reports export-star, testing-move reports namespace destructuring and qualified type references of split names, and object-form no longer rewrites r.requires(identifier) but reports it for a manual check."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "schema validate names the violated FeatureDefinition key",
+    "detail": "A malformed FEATURES entry now reports the first key that is missing or has the wrong type instead of always pointing at the name."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Upgrade check names the codemod an improvement runs on apply",
+    "detail": "kumiko-upgrade without --apply now prints the codemod of each improvement entry, the same way it prints the migration of breaking entries."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Package-merge codemod keeps one entry per target package",
+    "detail": "When the merge target is already listed in dependencies, the old devDependencies entry is dropped; when the old entry is in dependencies and the target only in devDependencies, the target moves to dependencies so the runtime entry wins."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "NotificationTemplateMeta declares senderName and replyTo",
+    "detail": "The type now matches the mail template meta schema of the template resolver, which accepts senderName and replyTo."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Seed writes run the save lifecycle, so seeded files bind to their records",
+    "detail": "runProdApp built the boot seed dispatcher without lifecycle hooks, so seed writes and seed migrations skipped file binding (entity_id stayed null, other users got 404), the pre/post save and delete hooks, the tenant check of file references and the disposal of removed file references. The seed dispatcher now reuses the lifecycle hooks of the API dispatcher, exposed as lifecycleHooks on the entrypoints and on KumikoServer. A hook that throws inside the transaction now fails the seed and the boot."
+  },
   {
     "version": "0.387.0",
     "type": "improvement",

package/src/scripts/codemod/codemod-support.ts

@@ -155,7 +155,7 @@ export function ensureNamedImport(
       declaration.getNamedImports().length > 0,
   );
   if (target === undefined) {
-    sourceFile.insertImportDeclaration(declarations.length, {
+    sourceFile.addImportDeclaration({
       moduleSpecifier: specifier,
       namedImports: [name],
       isTypeOnly,

package/src/scripts/codemod/db-factory.ts

@@ -623,7 +623,7 @@ function reportRemovedProviderEnv(
       file: filePath,
       line: node.getStartLineNumber(),
       kind: "call",
-      description: `${REMOVED_ENV_NAME}: the Bun.SQL provider is gone, postgres-js is the only driver`,
+      description: `${REMOVED_ENV_NAME}: DB_PROVIDER is gone, Bun.SQL is the only driver`,
     });
   };
   for (const literal of sourceFile.getDescendantsOfKind(SyntaxKind.StringLiteral)) {

package/src/scripts/codemod/feature-layout.ts

@@ -122,16 +122,24 @@ function movedTargetOf(
   moved: ReadonlyMap<string, string>,
 ): string | undefined {
   const { base, extension } = stripScriptExtension(absoluteSpecifier);
-  const candidates =
+  const candidates: string[] =
     extension === ".js" || extension === ".ts" || extension === ".tsx" || extension === ""
       ? [absoluteSpecifier, `${base}.ts`, `${base}.tsx`]
       : [absoluteSpecifier];
+  if (extension === "")
+    candidates.push(`${absoluteSpecifier}/index.ts`, `${absoluteSpecifier}/index.tsx`);
   for (const candidate of candidates) {
     if (moved.has(candidate)) return candidate;
   }
   return undefined;
 }
 
+// A moved `<dir>/index.ts` is imported as `<dir>`, so the file name alone never appears in the importer.
+function importableNameOf(file: string): string {
+  const { base } = stripScriptExtension(baseName(file));
+  return base === "index" ? baseName(dirname(file)) : base;
+}
+
 function relativeSpecifierFrom(fromDir: string, target: string): string {
   const path = relative(fromDir, target).split("\\").join("/");
   return path.startsWith(".") ? path : `./${path}`;
@@ -258,7 +266,7 @@ function buildWrites(
   importRewrites: CodemodSite[],
 ): Map<string, string> {
   const writes = new Map<string, string>();
-  const basenames = [...moved.keys()].map((file) => stripScriptExtension(baseName(file)).base);
+  const basenames = [...moved.keys()].map(importableNameOf);
   for (const [file, original] of files) {
     const content = stripped.get(file) ?? original;
     const newFile = moved.get(file) ?? file;