@cosmicdrift/kumiko-framework 0.398.0 → 0.400.0

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

@@ -0,0 +1,33 @@
+import type { EnvelopeCipher } from "../../secrets/envelope-cipher.ts";
+export type ValidateBootOptions = {
+    /** Warn when an access role is used by exactly one handler/config-key/
+     *  field across the whole boot scan — often a typo, but also the normal
+     *  shape of a legitimate fine-grained role (one role scoped to one admin
+     *  endpoint on purpose). Opt-in (default false): a default-on
+     *  prod warning that nobody can silence per-role isn't worth the noise
+     *  it generates on every boot. */
+    readonly warnOnUniqueAccessRoles?: boolean;
+    /** QNs the app's sidebar allowlist admits. When set, every declared nav
+     *  whose screen isn't reachable from any allowlisted nav entry gets a
+     *  boot-time warning — that screen would otherwise be silently
+     *  unreachable via the sidebar. When omitted and the app has
+     *  workspaces, the allowlist is derived from `r.workspace({ nav })` and
+     *  `r.nav({ workspaces })` assignments instead. */
+    readonly navAllowlist?: ReadonlySet<string>;
+    /** Nav QNs deliberately left out of the sidebar allowlist because their
+     *  screen is reachable another way (e.g. as a sub-page of a generated
+     *  settings hub). Suppresses the navAllowlist warning for these QNs. */
+    readonly navAllowlistExempt?: ReadonlySet<string>;
+    /** Env the encrypted-field master-key probe reads. Defaults to
+     *  `process.env`; runners pass their resolved env so a ciphertext-only
+     *  key (already decrypted at boot) is visible to the probe. */
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    /** The cipher the runner injects after validation (built from the app's
+     *  `masterKey` or the env keyring). Satisfies the availability check for
+     *  `encrypted: true` fields without an env KEK. */
+    readonly entityFieldCipher?: EnvelopeCipher;
+    /** Locales every translation key must carry across all mounted features
+     *  (locale packages count). Without it a key can ship in one language and
+     *  silently fall back at runtime for users of the others. */
+    readonly requiredLocales?: readonly string[];
+};

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

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

package/dist/engine/boot-validator/boot-phases-app.d.ts

@@ -0,0 +1,5 @@
+import type { BootContext } from "./boot-context.ts";
+import type { FeatureFlags } from "./boot-phases.ts";
+import type { BootReport } from "./boot-report.ts";
+export declare function runAppWidePhase(report: BootReport, ctx: BootContext): void;
+export declare function runEnvironmentPhase(report: BootReport, ctx: BootContext, flags: FeatureFlags): void;

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

@@ -0,0 +1,103 @@
+import { validateEntityFieldEncryptionAvailable } from "../../db/entity-field-encryption.js";
+import { FILE_STORAGE_PROVIDER_ENV } from "../extension-names.js";
+import { createRegistry } from "../registry.js";
+import { validateProjectionAllowlist } from "../validate-projection-allowlist.js";
+import { runFeatureBootCheck } from "./boot-check.js";
+import { validateCardMetaOverflow } from "./card-meta-overflow.js";
+import { validateConfigReads } from "./config-deps.js";
+import { validateExtensionPreSaveWiring } from "./entity-handler.js";
+import { validateEntityListScreens } from "./entity-list-screens.js";
+import { validateGdprStoragePersistence } from "./gdpr-storage.js";
+import { validateGlobalTenancyEntities } from "./global-tenancy.js";
+import { validateI18nSurfaceKeys, validateRequiredLocales, validateTranslationLocaleConsistency, } from "./i18n-keys.js";
+import { validateNavCycles } from "./nav.js";
+import { validateProjectionListScreens, validateRelatedListSectionQueries, } from "./projection-list-screens.js";
+import { validateQueryOutputColumns } from "./query-output-columns.js";
+import { validateExtensionSelectorPanels } from "./selector-owner-panels.js";
+import { validateSubmitPrefilledHiddenFields } from "./url-prefill-fields.js";
+import { validateDefaultWorkspaceUniqueness } from "./workspaces.js";
+const APP_CHECKS_AFTER_I18N = [
+    {
+        check: "validateTranslationLocaleConsistency",
+        run: (c) => validateTranslationLocaleConsistency(c.features),
+    },
+    {
+        check: "validateRequiredLocales",
+        run: (c) => validateRequiredLocales(c.features, c.options?.requiredLocales),
+    },
+    { check: "validateEntityListScreens", run: (c) => validateEntityListScreens(c.features) },
+    {
+        check: "validateSubmitPrefilledHiddenFields",
+        run: (c) => validateSubmitPrefilledHiddenFields(c.features),
+    },
+    { check: "validateCardMetaOverflow", run: (c) => validateCardMetaOverflow(c.features) },
+    {
+        check: "validateExtensionSelectorPanels",
+        run: (c) => validateExtensionSelectorPanels(c.features),
+    },
+    // Column/field checks assume every `query` string already resolves (validateQueryRefs, phase 1).
+    { check: "validateQueryOutputColumns", run: (c) => validateQueryOutputColumns(c.features) },
+    {
+        check: "validateProjectionListScreens",
+        run: (c) => validateProjectionListScreens(c.features),
+    },
+    {
+        check: "validateRelatedListSectionQueries",
+        run: (c) => validateRelatedListSectionQueries(c.features),
+    },
+    {
+        check: "validateExtensionPreSaveWiring",
+        run: (c) => validateExtensionPreSaveWiring(c.features),
+    },
+    {
+        check: "validateGdprStoragePersistence",
+        run: (c) => validateGdprStoragePersistence(c.features),
+    },
+    {
+        check: "validateGlobalTenancyEntities",
+        run: (c) => validateGlobalTenancyEntities(c.features),
+    },
+];
+function runFeatureBootChecks(report, ctx) {
+    for (const feature of ctx.features) {
+        for (const check of feature.bootChecks) {
+            report.check("runFeatureBootCheck", feature.name, () => runFeatureBootCheck(feature, check, ctx.features));
+        }
+    }
+}
+export function runAppWidePhase(report, ctx) {
+    const { features } = ctx;
+    report.check("validateNavCycles", undefined, () => validateNavCycles(ctx.allNavQns));
+    report.check("validateDefaultWorkspaceUniqueness", undefined, () => validateDefaultWorkspaceUniqueness(ctx.allWorkspaceQns));
+    const built = {};
+    report.check("createRegistry", undefined, () => {
+        built.registry = createRegistry(features);
+    });
+    const registry = built.registry;
+    if (registry !== undefined) {
+        report.check("validateI18nSurfaceKeys", undefined, () => validateI18nSurfaceKeys(features, registry));
+    }
+    for (const { check, run } of APP_CHECKS_AFTER_I18N) {
+        report.check(check, undefined, () => run(ctx));
+    }
+    runFeatureBootChecks(report, ctx);
+    report.check("validateProjectionAllowlist", undefined, () => validateProjectionAllowlist(features));
+    report.check("validateConfigReads", undefined, () => validateConfigReads(features, ctx.allConfigKeys));
+}
+// Independent of the earlier phases: whether the environment can serve the app is
+// a separate question from whether its definitions are consistent.
+export function runEnvironmentPhase(report, ctx, flags) {
+    const { options } = ctx;
+    if (flags.hasEncryptedFields) {
+        // Availability check, not env-presence: eagerly building the keyring
+        // catches malformed keys (wrong length, bad base64) at boot instead of
+        // on the first encrypted read in prod. An injected cipher (test seam,
+        // custom KMS provider) satisfies the requirement without env keys.
+        report.check("validateEntityFieldEncryptionAvailable", undefined, () => validateEntityFieldEncryptionAvailable(options?.env, options?.entityFieldCipher));
+    }
+    report.check("fileStorageProvider", undefined, () => {
+        if (flags.hasFileFields && !(options?.env ?? process.env)[FILE_STORAGE_PROVIDER_ENV]) {
+            throw new Error(`${FILE_STORAGE_PROVIDER_ENV} environment variable is required (file/image fields in use)`);
+        }
+    });
+}

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

@@ -0,0 +1,11 @@
+import type { BootContext } from "./boot-context.ts";
+import type { BootReport } from "./boot-report.ts";
+import { collectDetailForScreens } from "./detail-screens.ts";
+export type FeatureFlags = {
+    hasEncryptedFields: boolean;
+    hasFileFields: boolean;
+};
+type DetailForScreens = ReturnType<typeof collectDetailForScreens>;
+export declare function runStructurePhase(report: BootReport, ctx: BootContext): DetailForScreens;
+export declare function runFeaturePhase(report: BootReport, ctx: BootContext, detailForScreens: DetailForScreens): FeatureFlags;
+export {};

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;