@cosmicdrift/kumiko-framework 0.386.0 → 0.388.0

package/dist/engine/schema-builder.js

@@ -16,10 +16,11 @@ export function isRepresentableAtScale(n, scale) {
     const tolerance = Math.abs(scaled) * 8 * Number.EPSILON + Number.EPSILON;
     return Math.abs(scaled - Math.round(scaled)) <= tolerance;
 }
-// Lexikografischer ISO-Vergleich — exakt für `yyyy-mm-dd` (date) und korrekt
-// für ISO-Datetime in konsistenter Repräsentation (gleiche Offset-/Präzisions-
-// Form). Bewusst ohne Date-API (no-date-api-Guard); die Tag-genaue Grenze
-// reicht für min/max-Use-Cases (z.B. Geburtsdatum nicht in der Zukunft).
+// Lexicographic ISO comparison — exact for `yyyy-mm-dd` (date) and correct
+// for ISO datetimes in a consistent representation (same offset/precision
+// form). Deliberately avoids the Date API (no-date-api-Guard); day-level
+// comparison is sufficient for min/max use cases (e.g. a birth date not in
+// the future).
 function withDateBounds(schema, min, max) {
     if (min === undefined && max === undefined)
         return schema;
@@ -76,257 +77,275 @@ function embeddedSubFieldToZod(subField) {
             assertUnreachable(subField, "embedded sub-field type");
     }
 }
-// kumiko-lint-ignore complexity-budget field→zod switch is the single schema source of truth
+function textFieldToZod(field, { applyDefaults, isUpdate }) {
+    let schema = z.string();
+    if (field.maxLength)
+        schema = schema.max(field.maxLength);
+    if (field.minLength) {
+        // "" must stay valid for optional fields and writeOnly updates (""
+        // = unchanged); `required` rejects it separately via min(1) below.
+        const minLength = field.minLength;
+        schema = schema.refine((value) => value.length === 0 || value.length >= minLength, {
+            message: `at least ${minLength} characters`,
+        });
+    }
+    if (field.writeOnly === true) {
+        // Update: "" = unchanged (dropped before the executor), null = clear,
+        // unless required. Create: "" would leave a required field unset.
+        if (!isUpdate)
+            return field.required ? schema.min(1) : schema;
+        return field.required ? schema : schema.nullable();
+    }
+    if (field.format === "email")
+        schema = schema.email();
+    if (field.format === "url")
+        schema = schema.url();
+    if (field.format === "iban") {
+        // "" stays valid for an optional field; `required` rejects it via min(1) below.
+        schema = schema.superRefine((value, ctx) => {
+            if (value !== "" && !isValidIban(value)) {
+                ctx.addIssue({ code: "invalid_format", format: "iban", input: value });
+            }
+        });
+    }
+    if (field.format === "month") {
+        // "" stays valid for an optional field; `required` rejects it via min(1) below.
+        schema = schema.refine((value) => value === "" || MONTH_PATTERN.test(value), {
+            message: "expected a month as YYYY-MM",
+        });
+    }
+    if (field.required)
+        schema = schema.min(1);
+    return field.default !== undefined && applyDefaults ? schema.default(field.default) : schema;
+}
+function longTextFieldToZod(field, applyDefaults) {
+    // longText has no `format` variant (by type design). Only optional
+    // maxLength and required are supported; otherwise it is an unrestricted
+    // z.string().
+    let schema = z.string();
+    if (field.maxLength)
+        schema = schema.max(field.maxLength);
+    if (field.required)
+        schema = schema.min(1);
+    return field.default !== undefined && applyDefaults ? schema.default(field.default) : schema;
+}
+function selectFieldToZod(field, applyDefaults) {
+    const [first, ...rest] = field.options;
+    if (!first)
+        return z.string();
+    const enumSchema = z.enum([first, ...rest]);
+    if (field.default !== undefined) {
+        // Untouched <select> sends "" too; with a default that maps to the
+        // default (same semantics as undefined) instead of the invalid-value
+        // rejection. A field with a default is never "unset" —
+        // true on both insert AND update, so this branch (and its "" → default
+        // mapping) fires regardless of applyDefaults; only the `.default(...)`
+        // schema-level fallback for OMITTED input is update-gated below.
+        // `null` maps the same way: the no-default branch below normalizes
+        // an untouched select to null, and a client that reuses that value
+        // against a defaulted field must not get rejected either.
+        const mapped = z.preprocess((value) => (value === "" || value === null ? field.default : value), enumSchema);
+        return applyDefaults ? mapped.default(field.default) : mapped;
+    }
+    if (field.required)
+        return enumSchema;
+    // Optional select without a default: an untouched HTML <select> submits
+    // "" for its placeholder option. Treat that as "unset" (null) instead of
+    // an invalid enum value — null (not undefined) so the value survives the
+    // JSON-serialized event payload and an update can actually clear a
+    // previously-set select back to unset, not just skip validation.
+    return z.preprocess((value) => (value === "" ? null : value), enumSchema.nullable());
+}
+function multiSelectFieldToZod(field, applyDefaults) {
+    const [first, ...rest] = field.options;
+    if (!first)
+        return z.array(z.string());
+    // `required: true` means non-empty, as with a `text` field.
+    // An empty array is rejected; the global `.optional()` wrapping
+    // in buildInsertSchema determines whether the field may be omitted.
+    let schema = z.array(z.enum([first, ...rest]));
+    if (field.required)
+        schema = schema.min(1);
+    return field.default !== undefined && applyDefaults ? schema.default([...field.default]) : schema;
+}
+function numberFieldToZod(field, applyDefaults) {
+    let schema = z.number();
+    // `integer: true` maps to a Postgres int4 column (entity-table-meta.ts)
+    // — bound it here so an out-of-range write fails loud (400) at the
+    // schema boundary instead of dying in Postgres (22003 → 500).
+    if (field.integer)
+        schema = schema.int().min(-2147483648).max(2147483647);
+    if (field.min !== undefined)
+        schema = schema.min(field.min);
+    if (field.max !== undefined)
+        schema = schema.max(field.max);
+    return field.default !== undefined && applyDefaults ? schema.default(field.default) : schema;
+}
+function decimalFieldToZod(field, applyDefaults) {
+    // Stored as numeric(precision, scale), surfaced as JS number. Bound the
+    // value at the write boundary so an over-range or over-scale input fails
+    // loud here instead of being silently rounded/rejected by Postgres.
+    const limit = 10 ** (field.precision - field.scale);
+    const schema = z
+        .number()
+        .gt(-limit)
+        .lt(limit)
+        .refine((n) => isRepresentableAtScale(n, field.scale), {
+        message: `at most ${field.scale} decimal places`,
+    });
+    return field.default !== undefined && applyDefaults ? schema.default(field.default) : schema;
+}
+function moneyFieldToZod(currencies) {
+    const [first, ...rest] = currencies;
+    if (!first)
+        throw new Error("No currencies configured");
+    return z.object({
+        amount: z.number(),
+        currency: z.enum([first, ...rest]),
+    });
+}
+function embeddedFieldToZod(field) {
+    const shape = {};
+    for (const [subName, subField] of Object.entries(field.schema)) {
+        const zodSub = embeddedSubFieldToZod(subField);
+        shape[subName] = subField.required ? zodSub : zodSub.optional();
+    }
+    const baseRow = z.object(shape);
+    const derived = field.derived;
+    // The server is the authority for derived cells: a row is recomputed
+    // here, overwriting whatever the client sent, instead of merely
+    // being checked against it.
+    const row = derived === undefined
+        ? baseRow
+        : z.preprocess((value) => withDerivedCells(value, derived, field.schema), baseRow);
+    if (field.multiple !== true)
+        return row;
+    // `required: true` means non-empty, same reading as multiSelect —
+    // whether the key may be omitted at all is decided by buildInsertSchema
+    // off the same flag. `minItems` overrides that default when set.
+    let list = z.array(row);
+    if (field.maxItems !== undefined)
+        list = list.max(field.maxItems);
+    const min = field.minItems ?? (field.required === true ? 1 : undefined);
+    if (min === undefined)
+        return list;
+    // A custom issue rather than min(): other arrays (multiSelect) share zod's
+    // too_small and must not read "rows"; the bridge honours params.i18nKey.
+    // The refinement is invisible to z.toJSONSchema; the meta keeps minItems for agent manifests.
+    return list.meta({ minItems: min }).superRefine((rows, ctx) => {
+        // skip: the minimum is met, nothing to report
+        if (rows.length >= min)
+            return;
+        ctx.addIssue({
+            code: "custom",
+            input: rows,
+            params: {
+                i18nKey: `errors.validation.list_min_rows.${min === 1 ? "one" : "other"}`,
+                minimum: min,
+            },
+        });
+    });
+}
+function timestampFieldToZod(field) {
+    // When locatedBy is set: wall-clock time without an offset (ISO datetime
+    // without `Z`). Otherwise: ISO UTC datetime (with `Z`). Both are validated
+    // against the ISO-8601 schema through z.iso.datetime; precision (with or
+    // without an offset) depends on locatedBy.
+    const schema = field.locatedBy !== undefined ? z.iso.datetime({ local: true }) : z.iso.datetime();
+    return withDateBounds(schema, field.min, field.max);
+}
+function locatedTimestampToZod() {
+    // Combined wall-clock and time-zone object. On write, either
+    // { at, tz } (typical for a UI form, with utc calculated) or { utc, tz }
+    // (typical for server-to-server communication, with at calculated) is
+    // accepted. On read, the read wrapper provides all three fields.
+    //
+    // The schema guarantees only tz plus at least one of at or utc.
+    const at = z.iso.datetime({ local: true });
+    const tz = z.string().refine(isValidIanaTimeZone, { message: "invalid IANA time zone" });
+    const utc = z.iso.datetime();
+    return z.union([
+        z.object({ at, tz, utc: utc.optional() }),
+        z.object({ utc, tz, at: at.optional() }),
+    ]);
+}
+function fileListFieldToZod(field) {
+    // Multi file: array of fileRef UUIDs. Same story as the singular
+    // variant — the element type has to match the UUID column on
+    // fileRefsTable.id.
+    const ids = z.array(z.uuid());
+    return field.maxCount === undefined ? ids : ids.max(field.maxCount);
+}
 export function fieldToZod(field, currencies, opts = {}) {
     // Insert callers want `.default(...)` applied so an omitted field falls
     // back to it; buildUpdateSchema passes applyDefaults: false so an omitted
     // field on update stays omitted (a `{ title }` patch must not clobber
     // other columns with their defaults) while a field's own default value is
-    // still known here for "" → default mapping (select case below).
+    // still known here for "" → default mapping (selectFieldToZod).
     const applyDefaults = opts.applyDefaults ?? true;
+    const ctx = { applyDefaults, isUpdate: opts.isUpdate === true };
     switch (field.type) {
-        case "text": {
-            let schema = z.string();
-            if (field.maxLength)
-                schema = schema.max(field.maxLength);
-            if (field.minLength) {
-                // "" must stay valid for optional fields and writeOnly updates (""
-                // = unchanged); `required` rejects it separately via min(1) below.
-                const minLength = field.minLength;
-                schema = schema.refine((value) => value.length === 0 || value.length >= minLength, {
-                    message: `at least ${minLength} characters`,
-                });
-            }
-            if (field.writeOnly === true) {
-                // Update: "" = unchanged (dropped before the executor), null = clear,
-                // unless required. Create: "" would leave a required field unset.
-                if (opts.isUpdate !== true)
-                    return field.required ? schema.min(1) : schema;
-                return field.required ? schema : schema.nullable();
-            }
-            if (field.format === "email")
-                schema = schema.email();
-            if (field.format === "url")
-                schema = schema.url();
-            if (field.format === "iban") {
-                // "" stays valid for an optional field; `required` rejects it via min(1) below.
-                schema = schema.superRefine((value, ctx) => {
-                    if (value !== "" && !isValidIban(value)) {
-                        ctx.addIssue({ code: "invalid_format", format: "iban", input: value });
-                    }
-                });
-            }
-            if (field.format === "month") {
-                // "" stays valid for an optional field; `required` rejects it via min(1) below.
-                schema = schema.refine((value) => value === "" || MONTH_PATTERN.test(value), {
-                    message: "expected a month as YYYY-MM",
-                });
-            }
-            if (field.required)
-                schema = schema.min(1);
-            return field.default !== undefined && applyDefaults ? schema.default(field.default) : schema;
-        }
-        case "longText": {
-            // longText hat keine `format`-Variante (per type-design). Nur
-            // optional maxLength + required, sonst ein offener z.string().
-            let schema = z.string();
-            if (field.maxLength)
-                schema = schema.max(field.maxLength);
-            if (field.required)
-                schema = schema.min(1);
-            return field.default !== undefined && applyDefaults ? schema.default(field.default) : schema;
-        }
+        case "text":
+            return textFieldToZod(field, ctx);
+        case "longText":
+            return longTextFieldToZod(field, applyDefaults);
         case "boolean": {
             const schema = z.boolean();
             return field.default !== undefined && applyDefaults ? schema.default(field.default) : schema;
         }
-        case "select": {
-            const [first, ...rest] = field.options;
-            if (!first)
-                return z.string();
-            const enumSchema = z.enum([first, ...rest]);
-            if (field.default !== undefined) {
-                // Untouched <select> sends "" too; with a default that maps to the
-                // default (same semantics as undefined) instead of the invalid-value
-                // rejection from #1702. A field with a default is never "unset" —
-                // true on both insert AND update, so this branch (and its "" → default
-                // mapping) fires regardless of applyDefaults; only the `.default(...)`
-                // schema-level fallback for OMITTED input is update-gated below.
-                // `null` maps the same way: the no-default branch below normalizes
-                // an untouched select to null, and a client that reuses that value
-                // against a since-defaulted field must not get rejected either.
-                const mapped = z.preprocess((value) => (value === "" || value === null ? field.default : value), enumSchema);
-                return applyDefaults ? mapped.default(field.default) : mapped;
-            }
-            if (field.required)
-                return enumSchema;
-            // Optional select without a default: an untouched HTML <select> submits
-            // "" for its placeholder option. Treat that as "unset" (null) instead of
-            // an invalid enum value — null (not undefined) so the value survives the
-            // JSON-serialized event payload and an update can actually clear a
-            // previously-set select back to unset, not just skip validation.
-            return z.preprocess((value) => (value === "" ? null : value), enumSchema.nullable());
-        }
-        case "multiSelect": {
-            const [first, ...rest] = field.options;
-            if (!first)
-                return z.array(z.string());
-            // `required: true` heißt non-empty — Analogie zu `text`-Field.
-            // Leeres Array wird rejected; das globale `.optional()`-Wrapping
-            // in buildInsertSchema kümmert sich um „darf fehlen".
-            let schema = z.array(z.enum([first, ...rest]));
-            if (field.required)
-                schema = schema.min(1);
-            return field.default !== undefined && applyDefaults
-                ? schema.default([...field.default])
-                : schema;
-        }
-        case "number": {
-            let schema = z.number();
-            // `integer: true` maps to a Postgres int4 column (entity-table-meta.ts)
-            // — bound it here so an out-of-range write fails loud (400) at the
-            // schema boundary instead of dying in Postgres (22003 → 500).
-            if (field.integer)
-                schema = schema.int().min(-2147483648).max(2147483647);
-            if (field.min !== undefined)
-                schema = schema.min(field.min);
-            if (field.max !== undefined)
-                schema = schema.max(field.max);
-            return field.default !== undefined && applyDefaults ? schema.default(field.default) : schema;
-        }
-        case "decimal": {
-            // Stored as numeric(precision, scale), surfaced as JS number. Bound the
-            // value at the write boundary so an over-range or over-scale input fails
-            // loud here instead of being silently rounded/rejected by Postgres.
-            const limit = 10 ** (field.precision - field.scale);
-            const schema = z
-                .number()
-                .gt(-limit)
-                .lt(limit)
-                .refine((n) => isRepresentableAtScale(n, field.scale), {
-                message: `at most ${field.scale} decimal places`,
-            });
-            return field.default !== undefined && applyDefaults ? schema.default(field.default) : schema;
-        }
+        case "select":
+            return selectFieldToZod(field, applyDefaults);
+        case "multiSelect":
+            return multiSelectFieldToZod(field, applyDefaults);
+        case "number":
+            return numberFieldToZod(field, applyDefaults);
+        case "decimal":
+            return decimalFieldToZod(field, applyDefaults);
         case "bigInt": {
-            // JS-`number`-Round-trip via mode:"number"; sicher bis 2^53.
-            // safe-integer-Cap ist explizit damit ein Caller, der einen
-            // Float reinwirft (z.B. parseFloat-Bug), beim Insert sofort
-            // failed statt silent-Truncation zu kassieren.
+            // JS-`number` round-trip via mode:"number"; exact up to 2^53.
+            // The safe-integer cap ensures that a caller passing a float (for example,
+            // due to a parseFloat bug) fails immediately at insert instead of being
+            // silently truncated.
             const schema = z.number().int().safe();
             return field.default !== undefined && applyDefaults ? schema.default(field.default) : schema;
         }
-        case "money": {
-            const [first, ...rest] = currencies;
-            if (!first)
-                throw new Error("No currencies configured");
-            return z.object({
-                amount: z.number(),
-                currency: z.enum([first, ...rest]),
-            });
-        }
-        case "embedded": {
-            const shape = {};
-            for (const [subName, subField] of Object.entries(field.schema)) {
-                const zodSub = embeddedSubFieldToZod(subField);
-                shape[subName] = subField.required ? zodSub : zodSub.optional();
-            }
-            const baseRow = z.object(shape);
-            const derived = field.derived;
-            // The server is the authority for derived cells: a row is recomputed
-            // here, overwriting whatever the client sent, instead of merely
-            // being checked against it.
-            const row = derived === undefined
-                ? baseRow
-                : z.preprocess((value) => withDerivedCells(value, derived, field.schema), baseRow);
-            if (field.multiple !== true)
-                return row;
-            // `required: true` means non-empty, same reading as multiSelect —
-            // whether the key may be omitted at all is decided by buildInsertSchema
-            // off the same flag. `minItems` overrides that default when set.
-            let list = z.array(row);
-            if (field.maxItems !== undefined)
-                list = list.max(field.maxItems);
-            const min = field.minItems ?? (field.required === true ? 1 : undefined);
-            if (min === undefined)
-                return list;
-            // A custom issue rather than min(): other arrays (multiSelect) share zod's
-            // too_small and must not read "rows"; the bridge honours params.i18nKey.
-            return list.superRefine((rows, ctx) => {
-                // skip: the minimum is met, nothing to report
-                if (rows.length >= min)
-                    return;
-                ctx.addIssue({
-                    code: "custom",
-                    input: rows,
-                    params: {
-                        i18nKey: `errors.validation.list_min_rows.${min === 1 ? "one" : "other"}`,
-                        minimum: min,
-                    },
-                });
-            });
-        }
-        case "jsonb": {
-            // Free-form jsonb — keys sind tenant-/runtime-defined. Validation
-            // passthrough: any plain object passt durch.
+        case "money":
+            return moneyFieldToZod(currencies);
+        case "embedded":
+            return embeddedFieldToZod(field);
+        case "jsonb":
+            // Free-form jsonb — keys are tenant-/runtime-defined. Validation
+            // passes through any plain object.
             return z.record(z.string(), z.unknown());
-        }
-        case "date": {
-            const schema = z.string().date();
-            return withDateBounds(schema, field.min, field.max);
-        }
-        case "timestamp": {
-            // Wenn locatedBy gesetzt: Wall-Clock OHNE Offset (ISO-Datetime ohne `Z`).
-            // Sonst: ISO-UTC-Datetime (mit `Z`). Beide werden über z.iso.datetime
-            // gegen das ISO-8601-Schema validiert; die Präzision (mit/ohne Offset)
-            // hängt von locatedBy ab.
-            const schema = field.locatedBy !== undefined ? z.iso.datetime({ local: true }) : z.iso.datetime();
-            return withDateBounds(schema, field.min, field.max);
-        }
-        case "tz": {
-            // IANA-Zonenname, validiert gegen die Runtime-Zonenliste
-            // (isValidIanaTimeZone). Ein ungültiger Name failt hier am
-            // Write-Boundary statt erst später in ctx.tz.parse / Temporal.
+        case "date":
+            return withDateBounds(z.string().date(), field.min, field.max);
+        case "timestamp":
+            return timestampFieldToZod(field);
+        case "tz":
+            // IANA time-zone name, validated against the runtime's zone list
+            // (isValidIanaTimeZone). An invalid name fails at the write boundary
+            // instead of later in ctx.tz.parse / Temporal.
             return z.string().refine(isValidIanaTimeZone, { message: "invalid IANA time zone" });
-        }
-        case "locatedTimestamp": {
-            // Combined Wall-Clock+TZ Object. Beim Write akzeptieren wir entweder
-            // { at, tz } (typisch UI-Form, utc wird berechnet) oder { utc, tz }
-            // (typisch Server-zu-Server, at wird berechnet). Beim Read liefert
-            // der Read-Wrapper alle drei Felder (siehe Phase D in MIGRATION.md).
-            //
-            // Hier nur die Schema-Garantie: mindestens tz + (at ODER utc).
-            const at = z.iso.datetime({ local: true });
-            const tz = z.string().refine(isValidIanaTimeZone, { message: "invalid IANA time zone" });
-            const utc = z.iso.datetime();
-            return z.union([
-                z.object({ at, tz, utc: utc.optional() }),
-                z.object({ utc, tz, at: at.optional() }),
-            ]);
-        }
+        case "locatedTimestamp":
+            return locatedTimestampToZod();
         case "file":
-        case "image": {
+        case "image":
             // Single file: stores a fileRef UUID — must match fileRefsTable.id
             // (uuid column). Pre-fix this was z.number() from an era when the
             // column was (wrongly) integer; the table-builder fix to uuid needs
             // a matching validation-layer fix here or the CRUD pipeline rejects
             // every valid UUID with "expected number".
             return z.uuid();
-        }
         case "files":
-        case "images": {
-            // Multi file: array of fileRef UUIDs. Same story as the singular
-            // variant — the element type has to match the UUID column on
-            // fileRefsTable.id.
-            const ids = z.array(z.uuid());
-            return field.maxCount === undefined ? ids : ids.max(field.maxCount);
-        }
+        case "images":
+            return fileListFieldToZod(field);
         case "reference":
-            // Tier 2.7e-3: Validiert UUID-shape. Existenz-Check der Reference
-            // (Row im referenced Table existiert + Tenant-Scope) ist Server-
-            // side-Verantwortung im Handler / Foreign-Key-Constraint, nicht
-            // im Schema-Validator (würde sonst Round-trip zur DB beim Parse).
-            // Multi-Mode (Tier 2.7e-Multi): Array von UUIDs.
+            // Validates the UUID shape. Checking that the reference exists
+            // (the row exists in the referenced table and belongs to the tenant) is
+            // the handler / foreign-key constraint's responsibility, not the schema
+            // validator's; checking it here would require a database round trip during
+            // parsing.
+            // Multi-mode accepts an array of UUIDs.
             return field.multiple === true ? z.array(z.uuid()) : z.uuid();
         default:
             assertUnreachable(field, "field type");
@@ -342,8 +361,7 @@ export function fieldToZod(field, currencies, opts = {}) {
 // fails the check even if the raw minor-unit amounts happen to match.
 //
 // Known limitation: compares against rounded `derived` cells, i.e.
-// "sum-of-rounded" not "round-of-sum" (kumiko-framework#1866). Follow-up
-// for a computed, read-only sibling total: kumiko-framework#1873.
+// "sum-of-rounded" not "round-of-sum".
 // kumiko-lint-ignore complexity-budget currency-equality check on sibling money payloads
 function applyTotalsMatchRefinements(entity, schema) {
     let result = schema;
@@ -360,7 +378,7 @@ function applyTotalsMatchRefinements(entity, schema) {
                     continue;
                 // One side of a totalsMatch pair without the other → reject. Update
                 // payloads only carry `changes`, so omitting the sibling would otherwise
-                // silently leave sum ≠ total (fw#1841).
+                // silently leave sum ≠ total.
                 if (rawRows === undefined || siblingRaw === undefined) {
                     ctx.addIssue({
                         code: "custom",
@@ -478,7 +496,7 @@ export function buildUpdateSchema(entity, currencies = [...DEFAULT_CURRENCIES],
         // sends only `{ title }` means "only change title"; zod defaults would
         // silently inject default values for every omitted field and clobber
         // existing data via the event-store-executor's `changes` payload.
-        // The field is passed through un-stripped (unlike before fw#1703) so
+        // The field is passed through un-stripped so
         // fieldToZod still knows the default for its "" → default mapping
         // (e.g. select) — applyDefaults: false only suppresses the schema-level
         // `.default(...)` fallback for a genuinely omitted key.

package/dist/engine/screen-filter-ops.js

@@ -1,18 +1,16 @@
-// Screen-Filter (Tier 2.7c) — Op-vs-Field-Type-Compatibility.
+// Screen-Filter — operator-to-field-type compatibility.
 //
-// Wer darf was filtern?
-//   - text/select/multiSelect: nur equality-Ops (eq, ne, in). lt/gt
-//     auf Strings ist semantisch fast immer Tippfehler (lexicographic
-//     compare nutzt der Author selten bewusst); Author kann den
-//     Filter dann einfach nicht setzen.
-//   - boolean: eq, ne (in/lt/gt sinnlos für 2-Werte-Type).
-//   - number/money/decimal/date/timestamp/locatedTimestamp: alle 7
-//     Ops — die Felder sind natürlich vergleichbar.
+// Allowed operators depend on the field type:
+//   - text/select/multiSelect: equality operators only (eq, ne, in). lt/gt
+//     on strings are usually accidental; authors can simply omit the filter.
+//   - boolean: eq, ne (in/lt/gt are meaningless for a two-value type).
+//   - number/money/decimal/date/timestamp/locatedTimestamp: all 7 operators,
+//     because these fields are naturally comparable.
 //
-// Boot-Validator nutzt diese Map um Author-Fehler früh zu fangen
-// ("filter mit op:lt auf einem text-Feld" → Boot-Fail). Erweitert sich
-// transparent: neuer Field-Type → hier eintragen + sortable/filterable-
-// Flag im Type-Def, sonst lehnt der Validator das Field generell ab.
+// The boot validator uses this map to catch authoring errors early
+// ("filter with op:lt on a text field" → boot failure). When adding a field
+// type, add it here and set its sortable/filterable flag in the type definition;
+// otherwise the validator rejects the field entirely.
 const EQUALITY_ONLY = ["eq", "ne", "in"];
 const COMPARABLE = [
     "eq",
@@ -39,17 +37,16 @@ export function getAllowedFilterOps(field) {
         case "timestamp":
         case "locatedTimestamp":
             return COMPARABLE;
-        // tz/embedded/file/image/files/images: nicht filterbar — Author
-        // kann das Feld nicht als filterable: true markieren (Boot-
-        // Validator weist `filterable: true` auf den Types ohnehin schon
-        // ab, weil das Flag dort gar nicht im Type-Def steht).
+        // tz/embedded/file/image/files/images: not filterable — authors cannot
+        // mark the field as filterable: true because the boot validator already
+        // rejects `filterable: true` for these types; the flag is not present in
+        // their type definitions.
         default:
             return [];
     }
 }
-// Author hat das Feld als filterable markiert? Tz/Embedded/File-Types
-// haben das Flag gar nicht im Type-Def, also fangen wir das per
-// `"filterable" in field`-Narrow ab.
+// If an author marked the field as filterable, catch types without that
+// flag in their type definition with the `"filterable" in field` narrowing.
 export function isFieldFilterable(field) {
     return "filterable" in field && field.filterable === true;
 }

package/dist/engine/screen-helpers.js

@@ -1,3 +1,5 @@
+import { createFallbackLogger } from "../logging/utils.js";
+const log = createFallbackLogger("kumiko");
 // Entity name the renderer gives the synthesized entity of an actionForm, secretMint or confirm
 // step. It is not registered, so nothing server-side may treat it as a real entity.
 export const ACTION_FORM_PSEUDO_ENTITY = "__action-form__";
@@ -71,7 +73,7 @@ export function isWriteFormEditSection(section) {
 }
 // Union of both sources, unlike the boot-validator's either-or flattening: that
 // one runs after the fields-XOR-groups check, collectors run without it and must
-// not drop a source (fw#2986).
+// not drop a source.
 export function sectionFieldSpecs(section) {
     return [...(section.fields ?? []), ...(section.groups?.flatMap((group) => group.fields) ?? [])];
 }
@@ -90,8 +92,7 @@ export function normalizeListColumn(c) {
         process.env.NODE_ENV !== "production" &&
         col.renderer !== undefined &&
         typeof col.renderer === "function") {
-        // biome-ignore lint/suspicious/noConsole: dev-only warning
-        console.warn(`[kumiko] normalizeListColumn: Feld "${col.field}" hat einen Funktions-Renderer — dieser wird von JSON.stringify verworfen. Bitte auf FormatSpec ({ format: "..." }) migrieren.`);
+        log.warn(`normalizeListColumn: field "${col.field}" has a function renderer, which JSON.stringify drops. Migrate it to a FormatSpec ({ format: "..." }).`);
     }
     return col;
 }

package/dist/engine/screen-kind.d.ts

@@ -0,0 +1,7 @@
+import type { ScreenDefinition } from "./types/screen.ts";
+export type ScreenKind = ScreenDefinition["type"];
+export type ScreenOfKind = {
+    readonly [K in ScreenKind]: Extract<ScreenDefinition, {
+        readonly type: K;
+    }>;
+};

package/dist/engine/screen-kind.js

@@ -0,0 +1 @@
+export {};