@cosmicdrift/kumiko-framework 0.399.0 → 0.401.0

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

@@ -0,0 +1,140 @@
+import { validateAccessDeclarations } from "./access-declarations.js";
+import { validateActionWiring, validateFieldWiring } from "./action-wiring.js";
+import { validateApiExposureMatching, validateExtensionUsages } from "./api-ext.js";
+import { collectExposedApis } from "./boot-context.js";
+import { validateCircularDeps, validateConfigKeyAllowPerRequest, validateConfigKeyBacking, validateConfigKeyBounds, validateConfigKeyComputed, validateConfigKeyOptionsQuery, validateConfigKeyPiiEncrypted, validateConfigKeyRequired, } from "./config-deps.js";
+import { validateSqlDerivedFields } from "./derived-sql-fields.js";
+import { collectDetailForScreens } from "./detail-screens.js";
+import { validateDerivedFieldCollisions, validateEmbeddedFields, validateEncryptedFields, validateEntityIndexes, validateEntitySelectAvailabilityQuery, validateEntitySelectConditionalOptions, validateEntitySelectOptionsQuery, validateExtendSchemaCollisions, validateFileFields, validateHandlerAccess, validateImageVariants, validateLocatedTimestamps, validateLockedWhen, validateMultiSelectFields, validateMultiStreamProjections, validateReferenceFields, validateSearchableFieldReadAccess, validateTransitions, } from "./entity-handler.js";
+import { validateFieldConditions } from "./field-conditions.js";
+import { validateHandlerFieldReferences } from "./handler-field-references.js";
+import { validateNavs } from "./nav.js";
+import { validateOwnershipRules } from "./ownership.js";
+import { validateParentRefs } from "./parent-ref.js";
+import { validatePiiAndRetention } from "./pii-retention.js";
+import { validateQueryRefs } from "./query-refs.js";
+import { validateReadGates } from "./read-gate.js";
+import { validateRecordOwnedSubjects } from "./record-owned.js";
+import { validateScreenShortIdCollisions, validateScreens } from "./screens.js";
+import { validateTransferGraph } from "./transfer-graph.js";
+import { validateWorkspaces } from "./workspaces.js";
+function runFeatureChecks(report, checks, feature, ctx) {
+    for (const { check, run } of checks) {
+        report.check(check, feature.name, () => run(feature, ctx));
+    }
+}
+// Phase 1 breaks the shared lookup tables later checks resolve against; if it
+// finds anything, the later phases would only report follow-up noise.
+const STRUCTURE_FEATURE_CHECKS = [
+    { check: "validateCircularDeps", run: (f, c) => validateCircularDeps(f.name, c.featureMap) },
+    {
+        check: "validateExtensionUsages",
+        run: (f, c) => validateExtensionUsages(f, c.extensionProviders),
+    },
+    {
+        check: "validateReferenceFields",
+        run: (f, c) => validateReferenceFields(f, c.featureMap, c.queryHandlerQns),
+    },
+    { check: "validateParentRefs", run: (f, c) => validateParentRefs(f, c.featureMap) },
+];
+export function runStructurePhase(report, ctx) {
+    const { features, featureMap } = ctx;
+    const built = {};
+    report.check("validateScreenShortIdCollisions", undefined, () => validateScreenShortIdCollisions(ctx.screensByShortId));
+    report.check("collectDetailForScreens", undefined, () => {
+        built.detailForScreens = collectDetailForScreens(features, featureMap);
+    });
+    report.check("validateSqlDerivedFields", undefined, () => validateSqlDerivedFields(features));
+    report.check("collectExposedApis", undefined, () => {
+        built.exposedApis = collectExposedApis(features);
+    });
+    report.check("validateQueryRefs", undefined, () => validateQueryRefs(features));
+    for (const feature of features) {
+        // Without a unique API map the matching would report every API as missing.
+        const apis = built.exposedApis;
+        if (apis !== undefined) {
+            report.check("validateApiExposureMatching", feature.name, () => validateApiExposureMatching(feature, apis, featureMap));
+        }
+        runFeatureChecks(report, STRUCTURE_FEATURE_CHECKS, feature, ctx);
+    }
+    report.endPhase();
+    return built.detailForScreens ?? new Map();
+}
+const FEATURE_CHECKS = [
+    { check: "validateSearchableFieldReadAccess", run: (f) => validateSearchableFieldReadAccess(f) },
+    { check: "validatePiiAndRetention", run: (f) => validatePiiAndRetention(f) },
+    { check: "validateRecordOwnedSubjects", run: (f) => validateRecordOwnedSubjects(f) },
+    { check: "validateEntitySelectOptionsQuery", run: (f) => validateEntitySelectOptionsQuery(f) },
+    {
+        check: "validateEntitySelectAvailabilityQuery",
+        run: (f, c) => validateEntitySelectAvailabilityQuery(f, c.queryHandlerQns),
+    },
+    {
+        check: "validateEntitySelectConditionalOptions",
+        run: (f) => validateEntitySelectConditionalOptions(f),
+    },
+    {
+        check: "validateEmbeddedFields",
+        run: (f, c) => validateEmbeddedFields(f, c.featureMap, c.queryHandlerQns),
+    },
+    { check: "validateMultiSelectFields", run: (f) => validateMultiSelectFields(f) },
+    { check: "validateImageVariants", run: (f) => validateImageVariants(f) },
+    {
+        check: "validateHandlerFieldReferences",
+        run: (f, c) => validateHandlerFieldReferences(f, c.featureMap),
+    },
+    { check: "validateTransitions", run: (f) => validateTransitions(f) },
+    { check: "validateLockedWhen", run: (f) => validateLockedWhen(f) },
+    { check: "validateFieldConditions", run: (f) => validateFieldConditions(f) },
+    { check: "validateExtendSchemaCollisions", run: (f) => validateExtendSchemaCollisions(f) },
+    { check: "validateDerivedFieldCollisions", run: (f) => validateDerivedFieldCollisions(f) },
+    { check: "validateHandlerAccess", run: (f) => validateHandlerAccess(f) },
+    { check: "validateAccessDeclarations", run: (f) => validateAccessDeclarations(f) },
+    { check: "validateLocatedTimestamps", run: (f) => validateLocatedTimestamps(f) },
+    { check: "validateEntityIndexes", run: (f) => validateEntityIndexes(f) },
+    { check: "validateConfigKeyBounds", run: (f) => validateConfigKeyBounds(f) },
+    { check: "validateConfigKeyRequired", run: (f) => validateConfigKeyRequired(f) },
+    { check: "validateConfigKeyComputed", run: (f) => validateConfigKeyComputed(f) },
+    { check: "validateConfigKeyAllowPerRequest", run: (f) => validateConfigKeyAllowPerRequest(f) },
+    { check: "validateConfigKeyBacking", run: (f) => validateConfigKeyBacking(f) },
+    { check: "validateConfigKeyOptionsQuery", run: (f) => validateConfigKeyOptionsQuery(f) },
+    { check: "validateConfigKeyPiiEncrypted", run: (f) => validateConfigKeyPiiEncrypted(f) },
+    {
+        check: "validateOwnershipRules",
+        run: (f, c) => validateOwnershipRules(f, c.allClaimKeys, c.knownRoles),
+    },
+    { check: "validateReadGates", run: (f, c) => validateReadGates(f, c.featureMap) },
+    { check: "validateTransferGraph", run: (f, c) => validateTransferGraph(f, c.featureMap) },
+    { check: "validateMultiStreamProjections", run: (f) => validateMultiStreamProjections(f) },
+];
+function validateScreensOfFeature(feature, ctx, detailForScreens) {
+    validateScreens(feature, ctx.featureMap, ctx.allWriteHandlerQns, ctx.allScreenQns, ctx.configKeyDefsByQn, ctx.screensByShortId, detailForScreens);
+}
+// validateScreens flags a Function-valued visible/entityId as "unknown field
+// undefined" before the clear wiring message could surface, so a wiring
+// violation in a feature suppresses its screens check.
+function runWiringAndScreens(report, feature, ctx, detailForScreens) {
+    const actionWiringOk = report.check("validateActionWiring", feature.name, () => validateActionWiring(feature));
+    const fieldWiringOk = report.check("validateFieldWiring", feature.name, () => validateFieldWiring(feature));
+    if (actionWiringOk && fieldWiringOk) {
+        report.check("validateScreens", feature.name, () => validateScreensOfFeature(feature, ctx, detailForScreens));
+    }
+    report.check("validateNavs", feature.name, () => validateNavs(feature, ctx.allScreenQns, ctx.allNavQns, ctx.allWorkspaceQns));
+    report.check("validateWorkspaces", feature.name, () => validateWorkspaces(feature, ctx.allNavQns));
+}
+export function runFeaturePhase(report, ctx, detailForScreens) {
+    const flags = { hasEncryptedFields: false, hasFileFields: false };
+    for (const feature of ctx.features) {
+        report.check("validateEncryptedFields", feature.name, () => {
+            if (validateEncryptedFields(feature))
+                flags.hasEncryptedFields = true;
+        });
+        report.check("validateFileFields", feature.name, () => {
+            if (validateFileFields(feature))
+                flags.hasFileFields = true;
+        });
+        runFeatureChecks(report, FEATURE_CHECKS, feature, ctx);
+        runWiringAndScreens(report, feature, ctx, detailForScreens);
+    }
+    return flags;
+}

package/dist/engine/boot-validator/boot-report.d.ts

@@ -0,0 +1,6 @@
+export type BootReport = {
+    check(checkName: string, feature: string | undefined, fn: () => unknown): boolean;
+    endPhase(): void;
+    finish(): void;
+};
+export declare function createBootReport(): BootReport;

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

@@ -0,0 +1,47 @@
+import { BootValidationError } from "./boot-rule.js";
+// A runtime crash is a bug in a validator (or in the input it assumed), not a
+// rule violation: it must surface as itself instead of masquerading as a finding.
+function isRuntimeCrash(thrown) {
+    return (!(thrown instanceof Error) ||
+        thrown instanceof TypeError ||
+        thrown instanceof RangeError ||
+        thrown instanceof ReferenceError ||
+        thrown instanceof SyntaxError ||
+        thrown instanceof EvalError ||
+        thrown instanceof URIError);
+}
+export function createBootReport() {
+    const violations = [];
+    let firstCrash;
+    function endPhase() {
+        // Crashes are discarded next to violations: they are most likely follow-ups of the broken input.
+        if (violations.length > 0)
+            throw new BootValidationError([...violations]);
+        if (firstCrash !== undefined)
+            throw firstCrash.thrown;
+    }
+    return {
+        check(checkName, feature, fn) {
+            try {
+                fn();
+                return true;
+            }
+            catch (thrown) {
+                if (isRuntimeCrash(thrown)) {
+                    firstCrash ??= { thrown };
+                }
+                else if (thrown instanceof Error) {
+                    violations.push({
+                        ruleId: `unclassified/${checkName}`,
+                        check: checkName,
+                        ...(feature === undefined ? {} : { feature }),
+                        message: thrown.message,
+                    });
+                }
+                return false;
+            }
+        },
+        endPhase,
+        finish: endPhase,
+    };
+}

package/dist/engine/boot-validator/boot-rule.d.ts

@@ -0,0 +1,12 @@
+export type BootViolation = {
+    readonly ruleId: string;
+    readonly check: string;
+    readonly feature?: string;
+    readonly message: string;
+    readonly fix?: string;
+};
+export declare class BootValidationError extends Error {
+    readonly violations: readonly BootViolation[];
+    readonly name = "BootValidationError";
+    constructor(violations: readonly BootViolation[]);
+}

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

@@ -0,0 +1,14 @@
+function describeViolation(violation) {
+    const line = `- [${violation.ruleId}] ${violation.message}`;
+    return violation.fix === undefined ? line : `${line}\n  Fix: ${violation.fix}`;
+}
+export class BootValidationError extends Error {
+    violations;
+    name = "BootValidationError";
+    constructor(violations) {
+        const count = violations.length;
+        const header = `Boot validation failed: ${count} violation${count === 1 ? "" : "s"}`;
+        super([header, ...violations.map(describeViolation)].join("\n"));
+        this.violations = violations;
+    }
+}

package/dist/engine/boot-validator/boot-warnings.d.ts

@@ -0,0 +1,2 @@
+import type { BootContext } from "./boot-context.ts";
+export declare function emitBootWarnings(ctx: BootContext): void;

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

@@ -0,0 +1,20 @@
+import { warnOnUniqueAccessRoles } from "./access-roles.js";
+import { warnOnToggleableDependencies } from "./config-deps.js";
+import { warnOnNavAccessInversion, warnOnUnreachableNavScreens } from "./nav.js";
+import { warnOnMissingSecurityBaseline } from "./security-baseline.js";
+import { resolveNavAllowlist } from "./workspaces.js";
+// Warnings only make sense for a valid composition, so they run after every
+// validation phase passed.
+export function emitBootWarnings(ctx) {
+    const { features, options, allNavQns, allWorkspaceQns } = ctx;
+    warnOnNavAccessInversion(allNavQns);
+    const effectiveNavAllowlist = resolveNavAllowlist(options?.navAllowlist, allNavQns, allWorkspaceQns);
+    if (effectiveNavAllowlist !== undefined) {
+        warnOnUnreachableNavScreens(allNavQns, effectiveNavAllowlist, options?.navAllowlistExempt, options?.navAllowlist === undefined ? "workspaces" : "explicit");
+    }
+    warnOnToggleableDependencies(features, ctx.featureMap);
+    warnOnMissingSecurityBaseline(features);
+    if (options?.warnOnUniqueAccessRoles === true) {
+        warnOnUniqueAccessRoles(features);
+    }
+}

package/dist/engine/boot-validator/derived-sql-fields.d.ts

@@ -0,0 +1,4 @@
+import { type EntityDefinition } from "@cosmicdrift/kumiko-types/fields";
+import type { FeatureDefinition } from "../types/index.ts";
+export declare function isSortableSqlDerivedField(entity: EntityDefinition, name: string): boolean;
+export declare function validateSqlDerivedFields(features: readonly FeatureDefinition[]): void;

package/dist/engine/boot-validator/derived-sql-fields.js

@@ -0,0 +1,184 @@
+import { isSqlDerivedField, } from "@cosmicdrift/kumiko-types/fields";
+import { holdsCiphertextOrSecret } from "../../db/entity-field-encryption.js";
+import { parseRefTargetEntityName } from "../parse-ref-target.js";
+export function isSortableSqlDerivedField(entity, name) {
+    const def = entity.derivedFields?.[name];
+    return def !== undefined && isSqlDerivedField(def) && def.sortable === true;
+}
+const VALUE_TYPE_OF_FIELD_TYPE = {
+    text: "text",
+    longText: "text",
+    select: "text",
+    tz: "text",
+    reference: "text",
+    number: "number",
+    bigInt: "number",
+    decimal: "decimal",
+    boolean: "boolean",
+    date: "date",
+    timestamp: "timestamp",
+};
+function valueTypeOfField(entity, field) {
+    if (field === "id")
+        return "text";
+    const def = entity.fields[field];
+    return def === undefined ? undefined : VALUE_TYPE_OF_FIELD_TYPE[def.type];
+}
+function requireUsableField(site, entity, field, role) {
+    if (field !== "id" && entity.fields[field] === undefined) {
+        throw new Error(`${site.where}: ${role} "${field}" is not a field of the entity.`);
+    }
+    if (valueTypeOfField(entity, field) === undefined) {
+        throw new Error(`${site.where}: ${role} "${field}" has type "${entity.fields[field]?.type}", which a SQL derived field cannot read (compound types are not supported; money only as the measure of a related first).`);
+    }
+    if (holdsCiphertextOrSecret(entity, field)) {
+        throw new Error(`${site.where}: ${role} "${field}" is encrypted or secret; a SQL derived field would expose or order by it.`);
+    }
+}
+function requireValueType(site, def, expected) {
+    if (def.valueType !== expected) {
+        throw new Error(`${site.where}: valueType must be "${expected}", got "${def.valueType}".`);
+    }
+}
+function requireMoneyMeasure(site, def, related, measure) {
+    if (measure.label === true) {
+        throw new Error(`${site.where}: label: true needs a reference field, not money.`);
+    }
+    if (holdsCiphertextOrSecret(related, measure.field)) {
+        throw new Error(`${site.where}: measure field "${measure.field}" is encrypted or secret; a SQL derived field would expose or order by it.`);
+    }
+    requireUsableField(site, related, measure.orderBy, "measure orderBy");
+    requireValueType(site, def, "money");
+}
+function validateCondition(site, related, condition) {
+    if ("activeOn" in condition) {
+        for (const field of [condition.activeOn.from, condition.activeOn.to]) {
+            requireUsableField(site, related, field, "activeOn field");
+            if (valueTypeOfField(related, field) !== "date") {
+                throw new Error(`${site.where}: activeOn field "${field}" must be a date field.`);
+            }
+        }
+        // skip: activeOn carries no op/value to check
+        return;
+    }
+    requireUsableField(site, related, condition.field, "where field");
+    const { value, op } = condition;
+    const isList = Array.isArray(value);
+    if ((op === "in") !== isList) {
+        throw new Error(`${site.where}: where "${condition.field}": op "in" takes a list, and only "in" does.`);
+    }
+    if (value === null && op !== "eq" && op !== "ne") {
+        throw new Error(`${site.where}: where "${condition.field}": null is only valid with eq/ne.`);
+    }
+    if (typeof value === "object" && value !== null && !isList) {
+        const expected = "today" in value ? "date" : "timestamp";
+        if (valueTypeOfField(related, condition.field) !== expected) {
+            throw new Error(`${site.where}: where "${condition.field}": ${expected === "date" ? "today" : "now"} needs a ${expected} field.`);
+        }
+    }
+}
+// A sortable derived value runs its subquery for every row of the page, so the join column of
+// the related table needs an index; buildEntityTable creates none for a plain reference field.
+function requireJoinIndex(site, related, field, relations) {
+    const indexed = related.fields[field]?.type === "file" ||
+        related.fields[field]?.type === "image" ||
+        Object.values(relations ?? {}).some((relation) => relation.type === "belongsTo" && relation.foreignKey === field) ||
+        (related.indexes ?? []).some(({ columns }) => {
+            const [first, second] = columns;
+            return first === field || (first === "tenantId" && second === field);
+        });
+    if (!indexed) {
+        throw new Error(`${site.where}: sortable needs an index on the related table's "${field}"; declare indexes: [{ columns: ["${field}"] }] (or ["tenantId", "${field}"]) on that entity.`);
+    }
+}
+function validateRelated(site, own, def, spec, allEntities, relations) {
+    const relatedName = parseRefTargetEntityName(spec.entity);
+    const related = allEntities.get(relatedName);
+    if (related === undefined) {
+        throw new Error(`${site.where}: related entity "${spec.entity}" is not registered.`);
+    }
+    requireUsableField(site, related, spec.on.field, "on.field");
+    if (def.sortable === true) {
+        requireJoinIndex(site, related, spec.on.field, relations.get(relatedName));
+    }
+    requireUsableField(site, own, spec.on.outer ?? "id", "on.outer");
+    for (const condition of spec.where ?? [])
+        validateCondition(site, related, condition);
+    requireMeasureValueType(site, def, spec.measure, related);
+}
+function requireMeasureValueType(site, def, measure, related) {
+    if (measure.kind === "count") {
+        requireValueType(site, def, "number");
+        // skip: count measures no field
+        return;
+    }
+    if (measure.kind === "first" && related.fields[measure.field]?.type === "money") {
+        requireMoneyMeasure(site, def, related, measure);
+        // skip: money is checked in full above
+        return;
+    }
+    requireUsableField(site, related, measure.field, "measure field");
+    if (measure.kind === "countDistinct") {
+        requireValueType(site, def, "number");
+        // skip: countDistinct has no orderBy or label
+        return;
+    }
+    requireUsableField(site, related, measure.orderBy, "measure orderBy");
+    if (measure.label === true) {
+        const measured = related.fields[measure.field];
+        if (measured?.type !== "reference" || measured.labelField === undefined) {
+            throw new Error(`${site.where}: label: true needs a reference field with a labelField.`);
+        }
+        requireValueType(site, def, "text");
+        // skip: a label is always text, the measured field's own type does not apply
+        return;
+    }
+    const expected = valueTypeOfField(related, measure.field);
+    if (expected !== undefined)
+        requireValueType(site, def, expected);
+}
+function validateCoalesce(site, own, def, fields) {
+    if (fields.length === 0)
+        throw new Error(`${site.where}: coalesce needs at least one field.`);
+    const types = new Set();
+    for (const field of fields) {
+        requireUsableField(site, own, field, "coalesce field");
+        types.add(valueTypeOfField(own, field));
+    }
+    if (types.size !== 1) {
+        throw new Error(`${site.where}: coalesce fields must all have the same type.`);
+    }
+    const [only] = types;
+    if (only !== undefined)
+        requireValueType(site, def, only);
+}
+export function validateSqlDerivedFields(features) {
+    const allEntities = new Map();
+    const relations = new Map();
+    for (const feature of features) {
+        for (const [name, entity] of Object.entries(feature.entities ?? {})) {
+            allEntities.set(name, entity);
+            const entityRelations = feature.relations[name];
+            if (entityRelations !== undefined)
+                relations.set(name, entityRelations);
+        }
+    }
+    for (const [entityName, entity] of allEntities) {
+        for (const [key, def] of Object.entries(entity.derivedFields ?? {})) {
+            const site = { where: `Entity "${entityName}" derived field "${key}"` };
+            if (!isSqlDerivedField(def)) {
+                if (def.valueType === "money") {
+                    throw new Error(`${site.where}: valueType "money" needs a sql derived field (related first on a money field); a JS derive has no currency column.`);
+                }
+                if ("sortable" in def) {
+                    throw new Error(`${site.where}: sortable needs a sql derived field; a JS derive cannot order in SQL.`);
+                }
+                continue;
+            }
+            if (def.sql.kind === "coalesce")
+                validateCoalesce(site, entity, def, def.sql.fields);
+            else
+                validateRelated(site, entity, def, def.sql, allEntities, relations);
+        }
+    }
+}

package/dist/engine/boot-validator/entity-handler.d.ts

@@ -1,4 +1,5 @@
 import type { QueryHandlerDef } from "@cosmicdrift/kumiko-types/handlers";
+import type { FieldCondition } from "@cosmicdrift/kumiko-types/screen";
 import type { FeatureDefinition } from "../types/index.ts";
 export declare const FILE_FIELD_TYPES: Set<string>;
 export declare const PII_DIRECT_NAME_HINTS: ReadonlySet<string>;
@@ -23,9 +24,11 @@ export declare function validateReferenceFields(feature: FeatureDefinition, feat
 export declare function validateEmbeddedFields(feature: FeatureDefinition, featureMap: ReadonlyMap<string, FeatureDefinition>, queryHandlers: ReadonlyMap<string, QueryHandlerDef>): void;
 export declare function validateEntitySelectOptionsQuery(feature: FeatureDefinition): void;
 export declare function validateEntitySelectAvailabilityQuery(feature: FeatureDefinition, queryHandlers: ReadonlyMap<string, QueryHandlerDef>): void;
+export declare function conditionComparisonValues(when: Exclude<FieldCondition, boolean>): readonly unknown[];
 export declare function validateEntitySelectConditionalOptions(feature: FeatureDefinition): void;
 export declare function validateMultiSelectFields(feature: FeatureDefinition): void;
 export declare function validateImageVariants(feature: FeatureDefinition): void;
+export declare const LOCKABLE_FIELD_TYPES: ReadonlySet<string>;
 export declare function validateLockedWhen(feature: FeatureDefinition): void;
 export declare function validateTransitions(feature: FeatureDefinition): void;
 export declare function validateExtendSchemaCollisions(feature: FeatureDefinition): void;

package/dist/engine/boot-validator/entity-handler.js

@@ -2,6 +2,7 @@ import { SELECT_OPTION_TONES } from "@cosmicdrift/kumiko-types/fields";
 import { declaredRateLimitOptions, isRateLimitDisabled } from "@cosmicdrift/kumiko-types/handlers";
 import { ZodObject } from "zod";
 import { VARIANT_NAME_PATTERN } from "../../derivatives/variant-key.js";
+import { holdsFileRefs } from "../../files/file-field-slots.js";
 import { access as accessPresets } from "../config-helpers.js";
 import { parseRefTarget } from "../parse-ref-target.js";
 import { isSelectOptionTone } from "./select-option-tone.js";
@@ -469,7 +470,7 @@ export function validateEncryptedFields(feature) {
 export function validateFileFields(feature) {
     for (const entity of Object.values(feature.entities ?? {})) {
         for (const field of Object.values(entity.fields)) {
-            if (FILE_FIELD_TYPES.has(field.type))
+            if (holdsFileRefs(field))
                 return true;
         }
     }
@@ -486,6 +487,8 @@ const VALID_EMBEDDED_SUB_TYPES = new Set([
     "select",
     "reference",
     "timestamp",
+    "images",
+    "files",
 ]);
 const NUMERIC_EMBEDDED_SUB_TYPES = new Set(["number", "money", "decimal"]);
 // 15 is where 10^scale exhausts a double's integer range — beyond it the
@@ -786,7 +789,7 @@ export function validateEntitySelectAvailabilityQuery(feature, queryHandlers) {
         }
     }
 }
-function conditionComparisonValues(when) {
+export function conditionComparisonValues(when) {
     if ("eq" in when)
         return [when.eq];
     if ("ne" in when)
@@ -949,7 +952,7 @@ function isCiphertextAtRest(field) {
 // Types whose stored value is a plain scalar that the condition's `===` can match.
 // Compound, temporal, array and bigint columns come back in another shape than the
 // literal an author writes, so such a lock would silently never hold.
-const LOCKABLE_FIELD_TYPES = new Set([
+export const LOCKABLE_FIELD_TYPES = new Set([
     "text",
     "longText",
     "boolean",

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

@@ -1,5 +1,6 @@
 import { LIST_ROW_META_COLUMNS } from "../../ui-types/list-row-meta.js";
 import { normalizeListColumn } from "../screen-helpers.js";
+import { isSortableSqlDerivedField } from "./derived-sql-fields.js";
 /** Operator lists default searchable; low-cardinality audit trails stay opt-out. */
 export const SEARCHABLE_FALSE_WHITELIST = new Set(["download-attempt-list", "cap-list"]);
 // Same set computeListViewModel (headless) can actually render — NOT
@@ -38,7 +39,8 @@ function validateOneEntityListScreen(feature, screen) {
         }
         const entityDef = feature.entities?.[screen.entity];
         const fieldDef = entityDef?.fields[sortField];
-        const isSortable = fieldDef !== undefined && "sortable" in fieldDef && fieldDef.sortable === true;
+        const isSortable = (entityDef !== undefined && isSortableSqlDerivedField(entityDef, sortField)) ||
+            (fieldDef !== undefined && "sortable" in fieldDef && fieldDef.sortable === true);
         if (!isSortable) {
             throw new Error(`${prefix}: defaultSort column "${sortField}" must be sortable`);
         }

package/dist/engine/boot-validator/field-conditions.d.ts

@@ -0,0 +1,2 @@
+import type { FeatureDefinition } from "../types/index.ts";
+export declare function validateFieldConditions(feature: FeatureDefinition): void;