@cosmicdrift/kumiko-framework 0.385.0 → 0.387.0

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

@@ -23,7 +23,7 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
     // features (a declarative list in the entity's owning feature navigates to
     // the consumer app's custom editors this way). The validator mirrors that:
     // same feature OR any feature. redirect/cancelTarget additionally accept a
-    // fully qualified cross-feature QN (resolveScreenTargetQn, #1946); short IDs
+    // fully qualified cross-feature QN (resolveScreenTargetQn); short IDs
     // stay same-feature as before.
     const navTargetShortIds = screenShortIdsFrom(allScreenQns);
     const navigateLookups = {
@@ -91,7 +91,7 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                     assertRefTargetRegistered(`[Feature ${feature.name}] Screen "${screenId}" (projectionList)`, `column "${normalizedCol.field}" (refEntity)`, normalizedCol.refEntity, feature.name, featureMap);
                 }
             }
-            // Screen filter (fw#2224) — field existence can't be checked without
+            // Screen filter — field existence can't be checked without
             // an entity (columns aren't a complete field inventory of the
             // underlying query), so only pin the structure: "in" requires an
             // array. Field validity is documented in the PR body.
@@ -156,7 +156,7 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                     `is no row id to send under idParam. Remove idParam.`);
             }
             // singleton has no row id in the path, but the auto-generated "Edit"
-            // action (fw#2166, defaultEditAction in kumiko-screen.tsx) navigates
+            // action (defaultEditAction in kumiko-screen.tsx) navigates
             // to the detailFor entity's entityEdit screen using that path id —
             // under singleton it would silently open that screen in CREATE mode
             // instead of editing the singleton row. Reject rather than let that
@@ -285,7 +285,7 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                     // extension that persists through the host's Save button has
                     // nothing to save against. Extensions that persist themselves
                     // (e.g. notes-history NotesSection, via their own dispatcher
-                    // writes) are fine (solon#264).
+                    // writes) are fine.
                     if (section.contributesToFormSubmit === true) {
                         throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) extension section ` +
                             `"${section.title}" sets contributesToFormSubmit: true, but projectionDetail has no ` +
@@ -420,9 +420,8 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
             continue;
         }
         if (screen.type === "configEdit") {
-            // configEdit: layout/fields wie actionForm validieren, plus
-            // Cross-Check dass jeder qualifizierte Config-Key registriert
-            // ist und der scope mit dem Key matcht.
+            // Validate configEdit layout and fields like actionForm, then verify that
+            // every qualified config key is registered and its scope matches the key.
             const fieldNames = new Set(Object.keys(screen.fields));
             if (fieldNames.size === 0) {
                 throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (configEdit) has empty fields map — ` +
@@ -473,8 +472,8 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                     throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (configEdit) secretKeys names unknown field "${fname}".`);
                 }
             }
-            // configKeys: jeder fieldName muss einen Mapping-Eintrag haben,
-            // jeder qualifizierte Key muss in der Registry existieren.
+            // configKeys: every fieldName must have a mapping entry, and every
+            // qualified key must exist in the registry.
             for (const fname of fieldNames) {
                 const secretQn = screen.secretKeys?.[fname];
                 if (secretQn !== undefined) {
@@ -593,9 +592,8 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                     assertRefTargetRegistered(`[Feature ${feature.name}] Screen "${screenId}" (entityList)`, `column "${normalized.field}" (refEntity)`, normalized.refEntity, feature.name, featureMap);
                 }
             }
-            // Pagination/Sort/Search-Validierung: Author-Fehler beim Boot
-            // fangen, damit kein "warum kommt die Liste leer / falsch
-            // sortiert"-Debug-Cycle zur Laufzeit losgeht.
+            // Validate pagination, sorting, and search at boot so authoring errors
+            // fail before runtime debugging of empty or incorrectly sorted lists.
             if (screen.pageSize !== undefined && screen.pageSize <= 0) {
                 throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (entityList) has pageSize=${screen.pageSize} — ` +
                     `must be a positive integer.`);
@@ -606,15 +604,13 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                     throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (entityList) defaultSort references unknown ` +
                         `field "${sortField}". Known fields: ${[...fieldNames].sort().join(", ")}`);
                 }
-                // sortable: true Pflicht — verhindert dass das UI auf einer
-                // Spalte sortiert, die Server-Side gar keinen DB-Index hat
-                // oder im Schema absichtlich nicht sortiert werden soll
-                // (Audit-Felder, Computed-Werte). `sortable` lebt heute nur
-                // auf TextFieldDef; "in"-narrow lässt das auch für andere
-                // Field-Types ohne explizites Flag durchfallen, was ok ist:
-                // Number/Date sind natürlich sortierbar, der Author kann sie
-                // im Author-Code als sortable markieren wenn das Field-Type
-                // es trägt (Erweiterung folgt).
+                // `sortable: true` is required so the UI never sorts on a column that has
+                // no server-side DB index or that the schema deliberately keeps unsortable
+                // (audit fields, computed values). `sortable` currently
+                // exists only on TextFieldDef; the `in` narrowing also permits other
+                // field types without an explicit flag, which is acceptable because
+                // Number/Date fields are naturally sortable. Authors can mark them
+                // sortable when their field type supports it.
                 const fieldDef = entityDef.fields[sortField];
                 const isSortable = fieldDef !== undefined && "sortable" in fieldDef && fieldDef.sortable === true;
                 if (!isSortable) {
@@ -628,15 +624,14 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                     `"${screen.createScreen}" does not resolve to a registered screen in this feature. ` +
                     `Known screens in this feature: ${Object.keys(feature.screens).sort().join(", ") || "(none)"}.`);
             }
-            // Screen-Filter (Tier 2.7c) — drei Layer Author-Code-Check:
-            //   1) Field existiert auf der Entity (Tippfehler = leere Liste
-            //      statt Crash; Boot-Fail ist deutlich besser).
-            //   2) Field hat `filterable: true` (Author opt-in, analog zu
-            //      `sortable`). Verhindert dass Audit-/Computed-/encrypted-
-            //      Felder unbeabsichtigt filterbar werden.
-            //   3) Op passt zum Field-Type. Lt/gt auf text-Feldern → Boot-
-            //      Fail mit Hinweis statt String-Sort-Surprise zur Laufzeit.
-            // Außerdem: "in" verlangt readonly Array.
+            // Screen filters are checked in three layers:
+            //   1) The field exists on the entity; a typo would otherwise produce an
+            //      empty list instead of a clear boot failure.
+            //   2) The field has `filterable: true`, preventing accidental filtering
+            //      of audit, computed, or encrypted fields.
+            //   3) The operation matches the field type, so lt/gt on text fields
+            //      fails at boot instead of causing surprising runtime behavior.
+            // Additionally, "in" requires a readonly array.
             if (screen.filter !== undefined) {
                 const filterField = screen.filter.field;
                 if (!fieldNames.has(filterField)) {
@@ -668,9 +663,9 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                         `filter.value to be a readonly array. Pass an array as filter.value.`);
                 }
             }
-            // Tier 2.7e-1: rowActions pinnen — navigate-target existiert (selbes
-            // Feature), writeHandler-QN ist registriert. Tippfehler fallen sonst
-            // erst beim ersten Klick als "Screen not found" / 404 auf.
+            // Pin rowActions at boot: a navigate target must exist in the same feature
+            // and a writeHandler QN must be registered. Typos would otherwise only
+            // surface on the first click as "Screen not found" or a 404.
             if (screen.rowActions !== undefined) {
                 for (const action of screen.rowActions) {
                     rejectRedirectOnListRowAction(feature.name, screenId, "entityList", action);
@@ -681,7 +676,7 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                         // the id for a screen owned by a different feature. Cross-feature
                         // + entityEdit therefore MUST set an explicit entityId, or the
                         // edit screen silently opens with no entity context at runtime.
-                        // Entity-targets (fw#2228) are exempt: the renderer always
+                        // Entity-targets are exempt: the renderer always
                         // supplies an id for them (explicit entityId, else row["id"]),
                         // regardless of which feature the resolved detailFor screen
                         // belongs to.
@@ -730,9 +725,8 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                 }
                 validateAtMostOneRowClick(feature.name, screenId, "entityList", screen.rowActions);
             }
-            // Tier 2.7e-2: toolbarActions — analog zu rowActions, aber bisher
-            // ohne Validator. Typo'd navigate-targets und unregistrierte
-            // writeHandler-QNs fallen bis hierhin erst beim Klick auf.
+            // toolbarActions, analogous to rowActions: misspelled navigate targets and
+            // unregistered writeHandler QNs fail at boot instead of on the first click.
             if (screen.toolbarActions !== undefined) {
                 for (const action of screen.toolbarActions) {
                     if (action.kind === "navigate") {
@@ -895,9 +889,9 @@ export function collectScreenQns(features) {
     }
     return set;
 }
-// Bare Screen-ids (ohne `<feature>:screen:`-Prefix) aus den qualifizierten
-// QNs — für die app-weite Auflösung von navigate-Targets (s. validateScreens).
-// Spiegelt den Runtime-Router, der bare ids feature-übergreifend matcht.
+// Extract bare screen IDs (without the `<feature>:screen:` prefix) from
+// qualified QNs for app-wide navigate-target resolution (see validateScreens).
+// This mirrors the runtime router, which matches bare IDs across features.
 export function screenShortIdsFrom(allScreenQns) {
     const marker = ":screen:";
     const set = new Set();

package/dist/engine/boot-validator/security-baseline.js

@@ -1,3 +1,5 @@
+import { createFallbackLogger } from "../../logging/utils.js";
+const log = createFallbackLogger("kumiko:boot");
 export const SECURITY_BASELINE_FEATURE_NAMES = [
     "sessions",
     "crypto-shredding",
@@ -13,6 +15,5 @@ export function warnOnMissingSecurityBaseline(features, nodeEnv = process.env["N
     // skip: every baseline feature is mounted
     if (missing.length === 0)
         return;
-    // biome-ignore lint/suspicious/noConsole: boot-time hint, no logger available yet
-    console.warn(`[kumiko:boot] NODE_ENV=production but the security baseline is incomplete — missing feature(s): ${missing.join(", ")}. Mount securityBaselineFeatures() from @cosmicdrift/kumiko-bundled-features/presets (or the missing features individually).`);
+    log.warn(`NODE_ENV=production but the security baseline is incomplete — missing feature(s): ${missing.join(", ")}. Mount securityBaselineFeatures() from @cosmicdrift/kumiko-bundled-features/presets (or the missing features individually).`);
 }

package/dist/engine/boot-validator/transfer-graph.js

@@ -1,12 +1,12 @@
 import { parseRefTargetEntityName } from "../parse-ref-target.js";
 import { findOverDeepTransferChain, MAX_TRANSFER_DEPTH, resolveTransferAdjacency, } from "../transfer-adjacency.js";
-// --- Transfer-graph boot validation (fw#3088) ---
+// --- Transfer-graph boot validation ---
 //
 // tenant-handover walks an entity graph across the tenant boundary along two
 // declared edge kinds: `parentRef` and plain `reference` fields. Two shapes
 // cannot be walked, and both have to fail loudly here rather than silently
 // leaving rows behind in the source tenant — the partial move is exactly what
-// #3088 exists to end.
+// this validation exists to end.
 //
 // Scoped to entities declaring `transferable: true`, so a consumer that has
 // one of these shapes but never hands that entity over is unaffected.

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

@@ -33,9 +33,9 @@ export function validateWorkspaces(feature, allNavQns) {
     }
 }
 const SETTINGS_HUB_AUDIENCE_NAV_QN_SET = new Set(SETTINGS_HUB_AUDIENCE_NAV_QNS);
-// fw#3019: apps that assign navs to workspaces via `r.workspace({ nav })`
-// or `r.nav({ workspaces })` never pass an explicit navAllowlist (solon#113)
-// — without this, warnOnUnreachableNavScreens never runs for them. Both
+// Apps that assign navs to workspaces via `r.workspace({ nav })`
+// or `r.nav({ workspaces })` never pass an explicit navAllowlist — without
+// this, warnOnUnreachableNavScreens never runs for them. Both
 // `WorkspaceDefinition.nav` and `NavDefinition.workspaces` already hold
 // fully-qualified QNs (validateWorkspaces/validateNavs compare them
 // directly against allNavQns/allWorkspaceQns), so no re-qualification is

package/dist/engine/bridge-stub.js

@@ -12,7 +12,7 @@ import { createAnonymousUser } from "./system-user.js";
 // anything downstream accidentally reaches for them.
 //
 // Use: `{ db, registry, ...bridgeStub() }`
-const notAvailable = (what) => async () => {
+const notAvailable = (what) => async (..._args) => {
     throw new Error(`ctx.${what} not available in this context — use the dispatcher, not a stubbed handler context`);
 };
 // Noop observability — hand back the shared fallback tracer so ctx.tracer has
@@ -24,11 +24,10 @@ export function bridgeStub(opts) {
     // anonymous default values when no user is passed explicitly. Test code
     // that cares about identity passes its own SessionUser here and gets it
     // back on ctx.
-    const stubUser = opts?.user ??
-        createAnonymousUser("00000000-0000-0000-0000-000000000000"); // @cast-boundary engine-bridge
+    const stubUser = opts?.user ?? createAnonymousUser("00000000-0000-0000-0000-000000000000");
     return {
         user: stubUser,
-        query: notAvailable("query"), // @cast-boundary engine-bridge
+        query: notAvailable("query"),
         queryAs: notAvailable("queryAs"),
         write: notAvailable("write"),
         writeAs: notAvailable("writeAs"),

package/dist/engine/build-app-schema.js

@@ -1,22 +1,22 @@
-// Erzeugt aus einer Server-Registry das client-safe AppSchema das die
-// Browser-Renderer-Pipeline konsumiert. Genauer Zweck: dev-server kann
-// die ganze hand-geschriebene `clientSchema`-Spiegelung abschaffen, der
-// Server schickt einfach das aufgelöste AppSchema beim Boot mit.
+// Builds the client-safe AppSchema from a server registry for the
+// browser renderer pipeline. The dev server can therefore drop its entire
+// hand-written `clientSchema` mirror and simply send the resolved AppSchema
+// during boot.
 //
-// JSON-Safety: Wir projezieren explizit auf eine Whitelist statt
-// JSON.stringify-roundtripping. Functions würden silent gedroppt und
-// Zod-Schemas (v4 hat .toJSON, aber emittiert ein _zod-Envelope) würden
-// als komische Ghost-Properties auftauchen. Das hier ist ein bewusster
-// Vertrag: was die Browser-Renderer-Pipeline liest, taucht hier auf.
-// Neue Browser-needed-Fields müssen explizit erweitert werden.
+// JSON safety: project explicitly onto a whitelist instead of round-tripping
+// through JSON.stringify. Functions would be silently dropped, and Zod schemas
+// (v4 has .toJSON, but emits a _zod envelope) would appear as strange ghost
+// properties. This is an intentional contract: everything read by the browser
+// renderer pipeline must appear here. New fields needed by the browser must be
+// added explicitly.
 //
-// Aktuell projeziert (Stand 2026-04-25):
+// Currently projected:
 //   Entity:    { table?, fields: { type, required?, sortable?, default? } }
-//   Screen:    verbatim (ScreenDefinition ist von Haus aus JSON-safe —
-//              custom-screens haben keine functions, layout/columns/etc.
-//              sind plain literals)
-//   Nav:       verbatim (NavDefinition ist nur strings + literals)
-//   Workspace: verbatim definition + getWorkspaceNavs() von der Registry
+//   Screen:    verbatim (ScreenDefinition is JSON-safe by design —
+//              custom screens have no functions; layout/columns/etc. are
+//              plain literals)
+//   Nav:       verbatim (NavDefinition contains only strings + literals)
+//   Workspace: verbatim definition + getWorkspaceNavs() from the registry
 //   Translations: verbatim feature.translations (raw r.translations keys,
 //                 unfiltered — see FeatureSchema.translations doc)
 //
@@ -24,11 +24,13 @@
 // The schema route strips features the caller's tenant has switched off
 // (r.toggleable) via stripDisabledFeaturesFromAppSchema.
 import { ZodObject } from "zod";
+import { createFallbackLogger } from "../logging/utils.js";
 import { collectUrlPrefillFieldsByScreenQn } from "./boot-validator/url-prefill-fields.js";
 import { buildConfigFeatureSchema, SETTINGS_HUB_FEATURE, } from "./build-config-feature-schema.js";
 import { isEncryptedAtRest } from "./config-helpers.js";
 import { isListQueryWithoutSearchableFields } from "./entity-list-searchability.js";
 import { QnTypes, qualifyEntityName } from "./qualified-name.js";
+const log = createFallbackLogger("kumiko");
 export function buildAppSchema(registry, options = {}) {
     const features = [];
     const urlPrefillFieldsByScreenQn = collectUrlPrefillFieldsByScreenQn([
@@ -52,7 +54,7 @@ export function buildAppSchema(registry, options = {}) {
             screens: projectScreens(featureName, feature.screens, registry, urlPrefillFieldsByScreenQn, encryptedConfigKeyQns),
             ...(navs.length > 0 && { navs }),
             ...(contentCollections.length > 0 && { contentCollections }),
-            // #1059: verbatim r.translations({keys}) — see FeatureSchema.translations
+            // Verbatim r.translations({keys}) — see FeatureSchema.translations
             // doc for why this must NOT go through registry.getAllTranslations()
             // (double-prefixes features that already qualify their own keys).
             ...(Object.keys(feature.translations ?? {}).length > 0 && {
@@ -62,12 +64,12 @@ export function buildAppSchema(registry, options = {}) {
         };
         features.push(featureSchema);
     }
-    // Workspaces: getAllWorkspaces() liefert mit QUALIFIZIERTEN ids (das
-    // schreibt die Registry beim Store-Overwrite ein). Die Browser-
-    // Renderer erwartet aber kurze ids (matcht gegen URL-Segment, gegen
-    // navigate({ workspaceId })). Wir gehen direkt durch `feature.workspaces`
-    // — dort sind die ids noch in der Autor-Form (short) — und ziehen die
-    // pre-resolved navMembers aus der Registry.
+    // Workspaces: getAllWorkspaces() returns QUALIFIED ids (the Registry writes
+    // them during store overwrite). The browser renderer expects short ids
+    // (matching the URL segment and navigate({ workspaceId })). We therefore
+    // read directly from `feature.workspaces`, where the ids are still in the
+    // author's short form, and obtain the pre-resolved navMembers from the
+    // registry.
     let workspaces = [];
     for (const [featureName, feature] of registry.features) {
         for (const [shortId, definition] of Object.entries(feature.workspaces)) {
@@ -78,16 +80,16 @@ export function buildAppSchema(registry, options = {}) {
             });
         }
     }
-    // Self-Populating Settings-Hub: aus den deklarierten Config-Keys mit `mask`
-    // werden Screens/Navs (+ eine Workspace) abgeleitet und hier eingehängt —
-    // kein manuelles r.screen/r.nav am App-Author.
+    // Self-populating Settings Hub: screens/navs (plus one workspace) are
+    // derived from the declared config keys with `mask` and attached here,
+    // so the app author does not need manual r.screen/r.nav declarations.
     const appHadWorkspaces = workspaces.length > 0;
     const generated = buildConfigFeatureSchema(registry);
     if (generated.screens.length > 0) {
         mergeSettingsHubIntoConfigFeature(features, generated);
-        // Flip-Schutz: nur für Apps die schon Workspaces nutzen. Bei einer
-        // workspace-losen App bleibt app.workspaces undefined → der Renderer zeigt
-        // alle Navs ungefiltert, die Hub-Navs inklusive.
+        // Flip protection: applies only to apps that already use workspaces. For an
+        // app without workspaces, app.workspaces remains undefined, so the renderer
+        // shows all navs without filtering, including the Hub navs.
         if (appHadWorkspaces) {
             const placed = placeSettingsHub(workspaces, generated);
             workspaces = placed.workspaces;
@@ -109,16 +111,16 @@ export function buildAppSchema(registry, options = {}) {
         // instead so a leaked function renderer is actually caught.
         const offender = findNonJsonSafePath(schema, "schema");
         if (offender !== null) {
-            // biome-ignore lint/suspicious/noConsole: dev-only assertion
-            console.error(`[kumiko] buildAppSchema: Output ist nicht JSON-safe — nicht-serialisierbarer Wert bei "${offender}" (Funktions-Renderer oder Klassen-Instanz im Schema?).`, schema);
+            log.error(`buildAppSchema: Output ist nicht JSON-safe — nicht-serialisierbarer Wert bei "${offender}" (Funktions-Renderer oder Klassen-Instanz im Schema?).`, { offender });
         }
     }
     return schema;
 }
-// Hängt die generierten Hub-Screens/Navs an die config-FeatureSchema (qualified
-// dann als config:screen:* / config:nav:*). Existiert sie noch nicht (config
-// bundled-feature nicht gemountet), wird sie angelegt. find-or-create statt
-// fixem Push verhindert eine zweite FeatureSchema mit demselben featureName.
+// Attaches the generated Hub screens/navs to the config FeatureSchema
+// (qualified as config:screen:* / config:nav:*). If it does not yet exist
+// (because the config bundled feature is not mounted), it is created. Using
+// find-or-create instead of an unconditional push prevents a second
+// FeatureSchema with the same featureName.
 function mergeSettingsHubIntoConfigFeature(features, generated) {
     const existing = features.find((f) => f.featureName === SETTINGS_HUB_FEATURE);
     if (existing === undefined) {
@@ -202,8 +204,7 @@ function warnUnplacedAudiences(unplaced) {
     // skip: every audience placed — nothing to warn about
     if (unplaced.length === 0)
         return;
-    // biome-ignore lint/suspicious/noConsole: dev-only authoring hint
-    console.warn(`[kumiko] Settings-Hub: ${unplaced.join(", ")} nicht in einer App-Workspace platziert — ` +
+    log.warn(`Settings-Hub: ${unplaced.join(", ")} nicht in einer App-Workspace platziert — ` +
         `erscheint im Standalone-"Einstellungen"-Tab. Referenziere ` +
         `${unplaced.map((id) => `${SETTINGS_HUB_FEATURE}:nav:${id}`).join(", ")} ` +
         `in einer r.workspace.nav, um die Gruppe inline zu zeigen.`);
@@ -212,8 +213,7 @@ function warnDanglingAudienceRefs(dangling) {
     // skip: no dangling refs — nothing to warn about
     if (dangling.length === 0)
         return;
-    // biome-ignore lint/suspicious/noConsole: dev-only authoring hint
-    console.warn(`[kumiko] Settings-Hub: ${dangling
+    log.warn(`Settings-Hub: ${dangling
         .map((id) => `${SETTINGS_HUB_FEATURE}:nav:${id}`)
         .join(", ")} in einer Workspace referenziert, aber nie generiert — ` +
         `keine Config-Keys für diesen Scope registriert. Tippfehler oder ` +
@@ -260,8 +260,8 @@ export function findNonJsonSafePath(value, path) {
 }
 // projectionList screens don't declare searchable/sortable/paginated as
 // authoring intent — they're derived here from the bound query handler's
-// Zod schema, the source of truth for what parameters it actually accepts
-// (fw#2165). A hand-written `searchable: true` still wins over the derived
+// Zod schema, the source of truth for what parameters it actually accepts.
+// A hand-written `searchable: true` still wins over the derived
 // default (screen.searchable ?? derived); the boot-validator (3a) rejects
 // one that contradicts the schema.
 function projectScreens(featureName, screens, registry, urlPrefillFieldsByScreenQn, encryptedConfigKeyQns) {
@@ -372,30 +372,30 @@ function projectEntities(entities) {
     }
     return out;
 }
-// EntityDefinition ist eine Discriminated-Union an Field-Types — wir
-// kennen alle JSON-safe Properties pro Field-Type. Statt jede Variante
-// einzeln auszuhandeln, walken wir die Field-Map und filtern auf die
-// Whitelist. Was nicht durchkommt: Server-only-runtime wie ZodValidate-
-// Functions, Computed-Functions, Default-Functions.
+// EntityDefinition is a discriminated union of field types, and we know the
+// JSON-safe properties for each type. Rather than handling every variant
+// separately, walk the field map and filter it through the whitelist. Values
+// that do not pass through include server-only runtime values such as
+// ZodValidate functions, computed functions, and default functions.
 function projectEntity(entityName, entity) {
     const fieldsOut = {};
     for (const [fieldName, fieldDef] of Object.entries(entity.fields)) {
         assertValidMultilineRows(`Entity "${entityName}"`, fieldName, fieldDef);
         fieldsOut[fieldName] = projectField(fieldDef);
     }
-    // derivedFields MÜSSEN mit ins Client-Schema (nur die Metadaten, nicht die
-    // derive-fn): computeListViewModel löst eine entityList-Spalte über
-    // `entity.derivedFields[field].valueType` auf — fehlt der Eintrag, wirft es
-    // "references unknown field". Der executor hat den Wert server-seitig schon
-    // an die Row gehängt; der Client braucht nur den valueType für den Renderer.
+    // derivedFields MUST be included in the client schema (metadata only, not the
+    // derive function): computeListViewModel resolves an entityList column via
+    // `entity.derivedFields[field].valueType`; without the entry it throws
+    // "references unknown field". The executor has already attached the value
+    // server-side to the row; the client only needs valueType for rendering.
     const derivedOut = {};
     for (const [name, derivedDef] of Object.entries(entity.derivedFields ?? {})) {
         derivedOut[name] = projectDerivedField(derivedDef);
     }
-    // EntityDefinition akzeptiert idType/access/searchWeight als optional —
-    // wir lassen die weg weil der Browser-Renderer sie nicht liest. `table`
-    // schicken wir mit, falls Apps `entity.table` direkt referenzieren.
-    // Kein Cast nötig: alle weggelassenen Felder sind `?`-optional.
+    // EntityDefinition accepts idType/access/searchWeight as optional, but we omit
+    // them because the browser renderer does not read them. `table` is included
+    // in case apps reference `entity.table` directly.
+    // No cast is needed: all omitted fields are optional (`?`).
     return {
         fields: fieldsOut,
         // @cast-boundary schema-walk: EntityDefinition.derivedFields is typed for
@@ -413,10 +413,10 @@ function projectEntity(entityName, entity) {
         ...(entity.lockedWhen !== undefined && { lockedWhen: entity.lockedWhen }),
     };
 }
-// Nur valueType durch — die derive-fn ist Server-only und NICHT JSON-safe
-// (würde sonst die Output-Walk-Guard triggern). Gibt ehrlich
-// ClientDerivedFieldDef zurück statt eine DerivedFieldDef vorzutäuschen,
-// die keine derive-fn hat.
+// Only valueType is forwarded — the derive function is server-only and is not
+// JSON-safe (it would otherwise trigger the output-walk guard). Return
+// ClientDerivedFieldDef honestly instead of pretending to return a
+// DerivedFieldDef without its derive function.
 function projectDerivedField(derivedDef) {
     return { valueType: derivedDef.valueType };
 }
@@ -470,28 +470,28 @@ function projectField(fieldDef) {
         out["required"] = def["required"];
     if (typeof def["sortable"] === "boolean")
         out["sortable"] = def["sortable"];
-    // filterable steuert die Faceted-Filter-Dropdowns im Renderer (select/
-    // boolean) — muss daher ins Client-Schema.
+    // filterable controls the faceted filter dropdowns in the renderer (select/
+    // boolean), so it must be included in the client schema.
     if (typeof def["filterable"] === "boolean")
         out["filterable"] = def["filterable"];
     if (typeof def["searchable"] === "boolean")
         out["searchable"] = def["searchable"];
     if (isJsonSafeValue(def["default"]))
         out["default"] = def["default"];
-    // Select: options-Liste ist plain JSON, durchschicken.
+    // Select: the options list is plain JSON, so forward it.
     if (Array.isArray(def["options"]))
         out["options"] = def["options"];
     if (isJsonSafeObject(def["optionTones"]))
         out["optionTones"] = def["optionTones"];
-    // Reference: entity-Target + labelField + multiple müssen zum Renderer.
-    // Der ReferenceInput baut die Options-Query aus refEntity/refFeature und
-    // resolved das Label über labelField — ohne diese Properties fällt das
-    // Dropdown leer aus (QN wird `<feature>:query::list` → 404).
+    // Reference: entity target, labelField, and multiple are required by the
+    // renderer. ReferenceInput builds the options query from refEntity/refFeature
+    // and resolves the label through labelField; without these properties, the
+    // dropdown is empty (the QN becomes `<feature>:query::list` → 404).
     if (typeof def["entity"] === "string")
         out["entity"] = def["entity"];
     if (typeof def["labelField"] === "string")
         out["labelField"] = def["labelField"];
-    // fw#2780: author-supplied picker source — without it the client falls back to the list handler.
+    // Author-supplied picker source — without it the client falls back to the list handler.
     if (typeof def["optionsQuery"] === "string")
         out["optionsQuery"] = def["optionsQuery"];
     // Select: tier/tenant availability of the static options, loaded by the renderer.
@@ -504,7 +504,7 @@ function projectField(fieldDef) {
         out["multiple"] = def["multiple"];
     // MultiSelect: display picks checkboxes vs. combobox in the renderer,
     // columns/maxRows size the checkbox grid — without these the renderer
-    // always falls back to the combobox (fw#2494). Select: display picks
+    // always falls back to the combobox. Select: display picks
     // "radio" | "dropdown" the same way.
     if (typeof def["display"] === "string")
         out["display"] = def["display"];
@@ -513,19 +513,19 @@ function projectField(fieldDef) {
     if (typeof def["maxRows"] === "number")
         out["maxRows"] = def["maxRows"];
     // text/longText: textarea row count — DefaultInput renders a single-line
-    // input otherwise (fw#2497).
+    // input otherwise.
     if (typeof def["multiline"] === "boolean" || isJsonSafeObject(def["multiline"]))
         out["multiline"] = def["multiline"];
     // number: Zod write-boundary bounds. date/timestamp/locatedTimestamp:
-    // ISO-string picker bounds — same keys, different literal type (fw#2497).
+    // ISO-string picker bounds — same keys, different literal type.
     if (typeof def["min"] === "number" || typeof def["min"] === "string")
         out["min"] = def["min"];
     if (typeof def["max"] === "number" || typeof def["max"] === "string")
         out["max"] = def["max"];
-    // date/timestamp/locatedTimestamp: display/parsing locale override (fw#2497).
+    // date/timestamp/locatedTimestamp: display/parsing locale override.
     if (typeof def["locale"] === "string")
         out["locale"] = def["locale"];
-    // image/images: which camera a mobile capture opens (fw#2497).
+    // image/images: which camera a mobile capture opens.
     if (typeof def["capture"] === "string")
         out["capture"] = def["capture"];
     // number: display-only suffix, static or read from a sibling field of the row.
@@ -559,13 +559,13 @@ function projectField(fieldDef) {
     // decimal, incl. embedded sub-fields: rounding of derived embedded-list cells.
     if (typeof def["scale"] === "number")
         out["scale"] = def["scale"];
-    // money: declared currency source (MoneyCurrencySource, fw#2933) — without
+    // money: declared currency source (MoneyCurrencySource) — without
     // it the renderer can't tell a "currency: { kind: 'tenant' }" field apart
     // from an undeclared one and always falls back to entity.defaultCurrency.
     if (isJsonSafeObject(def["currency"]))
         out["currency"] = def["currency"];
     // embedded lists: row-count bounds, computed cells, totals row, and the
-    // sibling-money-field totals check (fw#2497).
+    // sibling-money-field totals check.
     if (typeof def["minItems"] === "number")
         out["minItems"] = def["minItems"];
     if (typeof def["maxItems"] === "number")
@@ -577,7 +577,7 @@ function projectField(fieldDef) {
     if (isJsonSafeObject(def["totalsMatch"]))
         out["totalsMatch"] = def["totalsMatch"];
     // embedded lists: the sub-field map itself — without it the client-side
-    // edit view-model iterates `undefined` and the screen crashes (fw#2507).
+    // edit view-model iterates `undefined` and the screen crashes.
     // Recursive per sub-field, NOT a blanket isJsonSafeValue gate: a single
     // sub-field carrying a validator fn would otherwise drop the whole map,
     // and a blanket copy would ship server internals.