@cosmicdrift/kumiko-framework 0.399.0 → 0.401.0

package/dist/engine/boot-validator/field-conditions.js

@@ -0,0 +1,196 @@
+import { isFileSubField } from "../../files/file-field-slots.js";
+import { parseMaxSize } from "../../files/types.js";
+import { conditionComparisonValues, LOCKABLE_FIELD_TYPES } from "./entity-handler.js";
+const STATE_KEYS = ["visibleWhen", "requiredWhen"];
+const SUB_CONDITION_TYPES = new Set([
+    "text",
+    "number",
+    "decimal",
+    "money",
+    "boolean",
+    "date",
+    "select",
+    "reference",
+]);
+const NUMERIC_SUB_TYPES = new Set(["number", "decimal", "money"]);
+function assertNoRequiredConflict(where, def, required) {
+    // skip: a field that is not statically required cannot conflict with requiredWhen
+    if (!required)
+        return;
+    if (def.requiredWhen !== undefined) {
+        throw new Error(`${where} sets required: true together with requiredWhen — drop required (requiredWhen covers the conditional case).`);
+    }
+    if (def.visibleWhen !== undefined) {
+        throw new Error(`${where} sets required: true together with visibleWhen — a hidden field cannot be required; use requiredWhen with the same condition.`);
+    }
+}
+function assertComparisonValuesAreOptions(where, key, condition, options) {
+    for (const value of conditionComparisonValues(condition)) {
+        if (typeof value !== "string" || !options.includes(value)) {
+            throw new Error(`${where} has ${key} value "${String(value)}" which is not an option of "${condition.field}" (${options.join(", ")}).`);
+        }
+    }
+}
+function assertTopLevelCondition(where, key, fieldName, condition, entity) {
+    const target = entity.fields[condition.field];
+    if (condition.field === fieldName) {
+        throw new Error(`${where} has ${key} on its own field. Make the condition depend on a different field.`);
+    }
+    if (target === undefined) {
+        throw new Error(`${where} has ${key}.field "${condition.field}" which is not a field of the entity. Use an existing field of the entity.`);
+    }
+    if (!LOCKABLE_FIELD_TYPES.has(target.type)) {
+        throw new Error(`${where} has ${key}.field "${condition.field}" of type "${target.type}", which does not store a plain scalar the condition can compare. Use a text, select, boolean, number or reference field.`);
+    }
+    if (target.type === "select") {
+        assertComparisonValuesAreOptions(where, key, condition, target.options);
+    }
+}
+function assertSubFieldCondition(where, key, subName, condition, embedded) {
+    const target = embedded.schema[condition.field];
+    if (condition.field === subName) {
+        throw new Error(`${where} has ${key} on its own sub-field. Make the condition depend on a sibling.`);
+    }
+    if (target === undefined) {
+        throw new Error(`${where} has ${key}.field "${condition.field}" which is not a sub-field of the same row. Use a sibling sub-field.`);
+    }
+    if (!SUB_CONDITION_TYPES.has(target.type)) {
+        throw new Error(`${where} has ${key}.field "${condition.field}" of type "${target.type}", which cannot be compared. Use a text, number, decimal, money, boolean, date, select or reference sub-field.`);
+    }
+    if (target.type === "select") {
+        const stateKey = key === "when" ? "visibleWhen" : key;
+        assertComparisonValuesAreOptions(where, stateKey, condition, target.options);
+    }
+}
+function assertFileSubField(where, sub) {
+    if (sub.searchable === true) {
+        throw new Error(`${where} is a ${sub.type} sub-field and cannot be searchable.`);
+    }
+    if (sub.maxCount !== undefined && !(Number.isInteger(sub.maxCount) && sub.maxCount > 0)) {
+        throw new Error(`${where} has invalid maxCount ${sub.maxCount}. Must be a positive integer.`);
+    }
+    if (sub.maxSize !== undefined) {
+        try {
+            parseMaxSize(sub.maxSize);
+        }
+        catch {
+            throw new Error(`${where} has invalid maxSize "${sub.maxSize}". Use e.g. "10mb", "500kb".`);
+        }
+    }
+    assertAcceptEntries(where, sub.accept);
+}
+// validateFile compares accept entries with the lower-cased last file-name segment, so only
+// bare lower-case extensions can ever match.
+const BARE_EXTENSION = /^[a-z0-9]+$/;
+function assertAcceptEntries(where, accept) {
+    if (accept?.some((ext) => ext.length === 0)) {
+        throw new Error(`${where} has an empty entry in accept. List file extensions like "pdf".`);
+    }
+    const offender = accept?.find((entry) => !BARE_EXTENSION.test(entry));
+    if (offender !== undefined) {
+        throw new Error(`${where} has accept entry "${offender}", which can never match an uploaded file. accept takes bare lower-case file extensions without dot, MIME type or wildcard: use "pdf" instead of ".pdf" or "application/pdf".`);
+    }
+}
+function assertSelectSubFieldTones(where, sub) {
+    // skip: only select sub-fields with declared tones have tones to check
+    if (sub.type !== "select" || sub.optionTones === undefined)
+        return;
+    for (const option of Object.keys(sub.optionTones)) {
+        if (!sub.options.includes(option)) {
+            throw new Error(`${where} has optionTones["${option}"] which is not an option (${sub.options.join(", ")}).`);
+        }
+    }
+}
+function assertSubFields(where, embedded) {
+    for (const [subName, sub] of Object.entries(embedded.schema)) {
+        const subWhere = `${where}.${subName}`;
+        assertNoRequiredConflict(subWhere, sub, sub.required === true);
+        for (const key of STATE_KEYS) {
+            const condition = sub[key];
+            if (condition !== undefined)
+                assertSubFieldCondition(subWhere, key, subName, condition, embedded);
+        }
+        assertSelectSubFieldTones(subWhere, sub);
+        if (isFileSubField(sub))
+            assertFileSubField(subWhere, sub);
+    }
+}
+function assertNumericSources(where, derivedName, embedded, from) {
+    for (const source of from) {
+        const sourceType = embedded.schema[source]?.type;
+        if (sourceType === undefined || !NUMERIC_SUB_TYPES.has(sourceType)) {
+            throw new Error(`${where} has a derived cell "${derivedName}" reading "${source}", which is not a number, decimal or money sub-field.`);
+        }
+    }
+}
+function assertDerivedCells(where, embedded) {
+    for (const [name, cell] of Object.entries(embedded.derived ?? {})) {
+        const target = embedded.schema[name];
+        assertNumericSources(where, name, embedded, cell.from);
+        if (cell.op === "inRange") {
+            if (cell.from.length !== 3) {
+                throw new Error(`${where} has a derived cell "${name}" with op "inRange", which needs exactly three sources (value, min, max).`);
+            }
+            if (target?.type !== "select" ||
+                !target.options.includes(cell.inside) ||
+                !target.options.includes(cell.outside)) {
+                throw new Error(`${where} has a derived cell "${name}" with op "inRange", whose target must be a select sub-field with the options "${cell.inside}" and "${cell.outside}".`);
+            }
+        }
+        else if (target === undefined || !NUMERIC_SUB_TYPES.has(target.type)) {
+            throw new Error(`${where} has a derived cell "${name}" with op "${cell.op}", whose target must be a number, decimal or money sub-field.`);
+        }
+        if (cell.when !== undefined) {
+            assertSubFieldCondition(`${where}.${name}`, "when", undefined, cell.when, embedded);
+            if (cell.when.field in (embedded.derived ?? {})) {
+                throw new Error(`${where} has a derived cell "${name}" whose when reads the derived cell "${cell.when.field}". Read a stored sub-field.`);
+            }
+        }
+    }
+}
+function assertFileSubFieldsAreNotWired(where, embedded) {
+    const fileSubs = new Set(Object.entries(embedded.schema).flatMap(([name, sub]) => (isFileSubField(sub) ? [name] : [])));
+    // skip: without file sub-fields there is nothing that could be wired into derived or conditions
+    if (fileSubs.size === 0)
+        return;
+    const wired = [
+        ...Object.entries(embedded.derived ?? {}).flatMap(([name, cell]) => [name, ...cell.from]),
+        ...Object.keys(embedded.totalsMatch ?? {}),
+        ...(embedded.totals ?? []).flatMap((total) => typeof total === "string" ? [total] : total.from),
+    ];
+    const offender = wired.find((name) => fileSubs.has(name));
+    if (offender !== undefined) {
+        throw new Error(`${where} uses file sub-field "${offender}" in derived or totals, which only take number, decimal or money sub-fields.`);
+    }
+}
+function assertEmbeddedField(where, embedded) {
+    assertSubFields(where, embedded);
+    assertFileSubFieldsAreNotWired(where, embedded);
+    assertDerivedCells(where, embedded);
+}
+function assertField(feature, entityName, entity, fieldName, field) {
+    const where = `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}"`;
+    assertNoRequiredConflict(where, field, "required" in field && field.required === true);
+    for (const key of STATE_KEYS) {
+        const condition = field[key];
+        if (condition !== undefined)
+            assertTopLevelCondition(where, key, fieldName, condition, entity);
+    }
+    if (field.type === "embedded")
+        assertEmbeddedField(where, field);
+    if (isFileAcceptField(field))
+        assertAcceptEntries(where, field.accept);
+}
+function isFileAcceptField(field) {
+    return (field.type === "file" ||
+        field.type === "files" ||
+        field.type === "image" ||
+        field.type === "images");
+}
+export function validateFieldConditions(feature) {
+    for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
+        for (const [fieldName, field] of Object.entries(entity.fields)) {
+            assertField(feature, entityName, entity, fieldName, field);
+        }
+    }
+}

package/dist/engine/boot-validator/i18n-keys.d.ts

@@ -1,4 +1,5 @@
-import type { FeatureDefinition } from "../types/index.ts";
-export declare function validateI18nSurfaceKeys(features: readonly FeatureDefinition[]): void;
+import type { FeatureDefinition, Registry } from "../types/index.ts";
+export declare function validateI18nSurfaceKeys(features: readonly FeatureDefinition[], registry: Registry): void;
 export declare function validateTranslationLocaleConsistency(features: readonly FeatureDefinition[]): void;
 export declare function validateRequiredLocales(features: readonly FeatureDefinition[], requiredLocales: readonly string[] | undefined): void;
+export declare function validateFieldValueTranslations(features: readonly FeatureDefinition[], enabled: boolean | undefined): void;

package/dist/engine/boot-validator/i18n-keys.js

@@ -1,7 +1,6 @@
-import { buildEffectiveTranslationKeys, featureHasI18nSurface, findRequiredLocaleGaps, findTranslationLocaleGaps, requiredKeysFromFeature, requiredKeysFromNav, requiredKeysFromScreen, requiredKeysFromWorkspace, screenTitleKey, } from "../../i18n/required-surface-keys.js";
+import { buildEffectiveTranslationKeys, featureHasI18nSurface, fieldValueTranslationKeysFromFeature, findRequiredLocaleGaps, findTranslationLocaleGaps, requiredKeysFromFeature, requiredKeysFromNav, requiredKeysFromScreen, requiredKeysFromWorkspace, screenTitleKey, } from "../../i18n/required-surface-keys.js";
 import { buildConfigFeatureSchema, SETTINGS_HUB_FEATURE, } from "../build-config-feature-schema.js";
 import { EXTENSION_SELECTOR_HINT_KEY } from "../extension-selector-plugins.js";
-import { createRegistry } from "../registry.js";
 function isDormantSecretsScreen(screen) {
     return screen.type === "secretsEdit" && screen.dormant === true;
 }
@@ -60,9 +59,8 @@ function hasDefinedTranslation(defined, key) {
     }
     return false;
 }
-export function validateI18nSurfaceKeys(features) {
+export function validateI18nSurfaceKeys(features, registry) {
     const defined = buildEffectiveTranslationKeys(features);
-    const registry = createRegistry(features);
     const generatedConfigHub = buildConfigFeatureSchema(registry);
     // The secrets screen's labels/hints come from the `r.secret()` declaration
     // itself, not from r.translations — without this, every app with a
@@ -102,3 +100,19 @@ export function validateRequiredLocales(features, requiredLocales) {
         throw new Error(`${lines.join("\n")}\nThe app requires locales [${requiredLocales.join(", ")}] for every translation key; load the matching locale package or add the missing translations.`);
     }
 }
+export function validateFieldValueTranslations(features, enabled) {
+    // skip: opt-in rule, off unless the app enables requireFieldValueTranslations
+    if (enabled !== true)
+        return;
+    const defined = buildEffectiveTranslationKeys(features);
+    const missing = [];
+    for (const feature of features) {
+        for (const key of fieldValueTranslationKeysFromFeature(feature)) {
+            if (!hasDefinedTranslation(defined, key))
+                missing.push(`  - ${feature.name}: ${key}`);
+        }
+    }
+    if (missing.length > 0) {
+        throw new Error(`[i18n] ${missing.length} select option / embedded-cell translation key(s) missing (requireFieldValueTranslations):\n${missing.join("\n")}\nAdd them via r.translations(...) in the owning feature.`);
+    }
+}

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

@@ -1,42 +1,11 @@
-import type { EnvelopeCipher } from "../../secrets/envelope-cipher.ts";
 import type { FeatureDefinition } from "../types/index.ts";
+import type { ValidateBootOptions } from "./boot-options.ts";
+export type { ValidateBootOptions } from "./boot-options.ts";
 export { type CardMetaOverflow, collectCardMetaOverflow } from "./card-meta-overflow.ts";
 export { validateAppCustomScreenWriteQns } from "./custom-screen-write-qns.ts";
 export { collectWriteHandlerQns } from "./nav.ts";
 export { SECURITY_BASELINE_FEATURE_NAMES } from "./security-baseline.ts";
 export { MAX_TRANSFER_DEPTH } from "./transfer-graph.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[];
-};
 /**
  * Subset-safe slice of validateBoot for test stacks: nav references (screen,
  * parent, workspace, tree actions), workspaces and nav cycles. The checks that
@@ -45,6 +14,8 @@ export type ValidateBootOptions = {
 export declare function validateNavBootSubset(rawFeatures: readonly FeatureDefinition[]): void;
 /**
  * Validates all feature configurations at boot time.
- * Throws on the first error found — fail fast.
+ * Collects violations per phase and throws them as one BootValidationError, so a
+ * single run reports everything fixable at once. Structural violations (phase 1)
+ * abort before the later phases, whose checks would only echo them as follow-ups.
  */
 export declare function validateBoot(rawFeatures: readonly FeatureDefinition[], options?: ValidateBootOptions): void;

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

@@ -1,36 +1,12 @@
-import { validateEntityFieldEncryptionAvailable } from "../../db/entity-field-encryption.js";
 import { dedupeFeatures } from "../dedupe-features.js";
-import { FILE_STORAGE_PROVIDER_ENV } from "../extension-names.js";
-import { QnTypes, qualifyEntityName } from "../qualified-name.js";
-import { validateProjectionAllowlist } from "../validate-projection-allowlist.js";
-import { validateAccessDeclarations } from "./access-declarations.js";
-import { warnOnUniqueAccessRoles } from "./access-roles.js";
-import { validateActionWiring, validateFieldWiring } from "./action-wiring.js";
-import { validateApiExposureMatching, validateExtensionUsages } from "./api-ext.js";
-import { validateFeatureBootChecks } from "./boot-check.js";
-import { validateCardMetaOverflow } from "./card-meta-overflow.js";
-import { validateCircularDeps, validateConfigKeyAllowPerRequest, validateConfigKeyBacking, validateConfigKeyBounds, validateConfigKeyComputed, validateConfigKeyOptionsQuery, validateConfigKeyPiiEncrypted, validateConfigKeyRequired, validateConfigReads, warnOnToggleableDependencies, } from "./config-deps.js";
-import { collectDetailForScreens } from "./detail-screens.js";
-import { validateDerivedFieldCollisions, validateEmbeddedFields, validateEncryptedFields, validateEntityIndexes, validateEntitySelectAvailabilityQuery, validateEntitySelectConditionalOptions, validateEntitySelectOptionsQuery, validateExtendSchemaCollisions, validateExtensionPreSaveWiring, validateFileFields, validateHandlerAccess, validateImageVariants, validateLocatedTimestamps, validateLockedWhen, validateMultiSelectFields, validateMultiStreamProjections, validateReferenceFields, validateSearchableFieldReadAccess, validateTransitions, } from "./entity-handler.js";
-import { validateEntityListScreens } from "./entity-list-screens.js";
-import { validateGdprStoragePersistence } from "./gdpr-storage.js";
-import { validateGlobalTenancyEntities } from "./global-tenancy.js";
-import { validateHandlerFieldReferences } from "./handler-field-references.js";
-import { validateI18nSurfaceKeys, validateRequiredLocales, validateTranslationLocaleConsistency, } from "./i18n-keys.js";
-import { collectKnownRoles, collectNavQns, collectWriteHandlerQns, validateNavCycles, validateNavs, warnOnNavAccessInversion, warnOnUnreachableNavScreens, } from "./nav.js";
-import { collectClaimKeys, validateOwnershipRules } from "./ownership.js";
-import { validateParentRefs } from "./parent-ref.js";
-import { validatePiiAndRetention } from "./pii-retention.js";
-import { buildQueryHandlerMap, validateProjectionListScreens, validateRelatedListSectionQueries, } from "./projection-list-screens.js";
-import { validateQueryOutputColumns } from "./query-output-columns.js";
-import { validateQueryRefs } from "./query-refs.js";
-import { validateRecordOwnedSubjects } from "./record-owned.js";
-import { collectScreenQns, collectScreensByShortId, validateScreenShortIdCollisions, validateScreens, } from "./screens.js";
-import { warnOnMissingSecurityBaseline } from "./security-baseline.js";
-import { validateExtensionSelectorPanels } from "./selector-owner-panels.js";
-import { validateTransferGraph } from "./transfer-graph.js";
-import { validateSubmitPrefilledHiddenFields } from "./url-prefill-fields.js";
-import { collectWorkspaceQns, resolveNavAllowlist, validateDefaultWorkspaceUniqueness, validateWorkspaces, } from "./workspaces.js";
+import { buildBootContext } from "./boot-context.js";
+import { runFeaturePhase, runStructurePhase } from "./boot-phases.js";
+import { runAppWidePhase, runEnvironmentPhase } from "./boot-phases-app.js";
+import { createBootReport } from "./boot-report.js";
+import { emitBootWarnings } from "./boot-warnings.js";
+import { collectNavQns, validateNavCycles, validateNavs } from "./nav.js";
+import { collectScreenQns } from "./screens.js";
+import { collectWorkspaceQns, validateWorkspaces } from "./workspaces.js";
 // Re-export: run-dev-app.ts needs this to pass write-handler QNs
 // to codegen. It is not part of validateBoot, but uses the same
 // extraction logic.
@@ -77,183 +53,27 @@ export function validateNavBootSubset(rawFeatures) {
     const tolerantScreens = new PrefixTolerantSet(collectScreenQns(features), mounted);
     const tolerantNavs = new PrefixTolerantMap(allNavQns, mounted);
     const tolerantWorkspaces = new PrefixTolerantMap(collectWorkspaceQns(features), mounted);
+    const report = createBootReport();
     for (const feature of features) {
-        validateNavs(feature, tolerantScreens, tolerantNavs, tolerantWorkspaces);
-        validateWorkspaces(feature, tolerantNavs);
+        report.check("validateNavs", feature.name, () => validateNavs(feature, tolerantScreens, tolerantNavs, tolerantWorkspaces));
+        report.check("validateWorkspaces", feature.name, () => validateWorkspaces(feature, tolerantNavs));
     }
-    validateNavCycles(allNavQns);
+    report.check("validateNavCycles", undefined, () => validateNavCycles(allNavQns));
+    report.finish();
 }
 /**
  * Validates all feature configurations at boot time.
- * Throws on the first error found — fail fast.
+ * Collects violations per phase and throws them as one BootValidationError, so a
+ * single run reports everything fixable at once. Structural violations (phase 1)
+ * abort before the later phases, whose checks would only echo them as follow-ups.
  */
 export function validateBoot(rawFeatures, options) {
-    const features = dedupeFeatures(rawFeatures);
-    const featureMap = new Map();
-    for (const f of features) {
-        featureMap.set(f.name, f);
-    }
-    // Collect all extension names and their schema extensions
-    const extensionProviders = new Map();
-    for (const f of features) {
-        for (const extName of Object.keys(f.registrarExtensions)) {
-            extensionProviders.set(extName, f.name);
-        }
-    }
-    // Collect all config keys across features (for cross-feature reference validation)
-    const allConfigKeys = new Set();
-    // Qualified config-key set for ConfigEditScreen validation. MUST be
-    // canonicalized via qualifyEntityName (toKebab on feature + key), exactly
-    // as define-feature/registry builds the QN. The raw f.configKeys key is
-    // the camelCase object key (`brandingTitle`), but the actual QN is
-    // `…:config:branding-title`; without toKebab, every configEdit screen
-    // with a multi-word config key would fail incorrectly. allConfigKeys above
-    // uses the older `feature.short` format for validateConfigReads.
-    const configKeyDefsByQn = new Map();
-    for (const f of features) {
-        for (const [key, def] of Object.entries(f.configKeys)) {
-            allConfigKeys.add(`${f.name}.${key}`);
-            configKeyDefsByQn.set(qualifyEntityName(f.name, QnTypes.config, key), def);
-        }
-    }
-    // Collect all claim keys — the ownership-rule validator below resolves
-    // `from("claim:<feature>:<key>")` strings against this map. Qualified name
-    // is how the resolver / readClaim / ownership system all reference claims,
-    // so we key on the qualifiedName here too.
-    const allClaimKeys = collectClaimKeys(features);
-    // Cross-feature role set — derived from handler-access rules + framework
-    // built-ins ("all", "system"). We don't have a dedicated role-registry
-    // (r.defineRoles is a type-level helper, not a runtime export), so we
-    // use "referenced in any handler access rule" as the corpus of known
-    // roles. The ownership-validator checks OwnershipMap keys + legacy
-    // string[] field-access entries against this set — typos like "Admi"
-    // instead of "Admin" fail at boot if nothing else ever mentions "Admi".
-    const knownRoles = collectKnownRoles(features);
-    // Cross-feature screen + nav registry — built once up front so per-feature
-    // validators can check nav-ref targets + parent chains without re-scanning
-    // every feature's navs map.
-    const allScreenQns = collectScreenQns(features);
-    const allNavQns = collectNavQns(features);
-    const allWorkspaceQns = collectWorkspaceQns(features);
-    const allWriteHandlerQns = collectWriteHandlerQns(features);
-    const screensByShortId = collectScreensByShortId(features);
-    validateScreenShortIdCollisions(screensByShortId);
-    // Cross-feature entity → detailFor-screen map — built (+ uniqueness-
-    // validated) up front so per-feature rowAction entity-targets
-    // resolve against it inside the loop below, instead of at the very end
-    // where this used to run.
-    const detailForScreens = collectDetailForScreens(features, featureMap);
-    // Cross-feature API exposure map — each feature declares markers via
-    // r.exposesApi(name). Per-feature validateApiExposureMatching walks the
-    // usedApis set and checks that every entry has a match here.
-    // This prevents typoed or removed QN calls from causing a runtime crash
-    // instead of a boot failure.
-    const allExposedApis = new Map(); // apiName → providerFeature
-    for (const f of features) {
-        for (const apiName of f.exposedApis) {
-            const existing = allExposedApis.get(apiName);
-            if (existing && existing !== f.name) {
-                throw new Error(`Cross-feature API "${apiName}" exposed by both "${existing}" and "${f.name}" — API names must be globally unique.`);
-            }
-            allExposedApis.set(apiName, f.name);
-        }
-    }
-    // Registered query-handler QNs, built once for the per-feature reference
-    // checks below (a reference field's `optionsQuery` may target any feature).
-    const queryHandlerQns = buildQueryHandlerMap(features);
-    let hasEncryptedFields = false;
-    let hasFileFields = false;
-    for (const feature of features) {
-        validateCircularDeps(feature.name, featureMap);
-        if (validateEncryptedFields(feature))
-            hasEncryptedFields = true;
-        validateSearchableFieldReadAccess(feature);
-        if (validateFileFields(feature))
-            hasFileFields = true;
-        validatePiiAndRetention(feature);
-        validateRecordOwnedSubjects(feature);
-        validateApiExposureMatching(feature, allExposedApis, featureMap);
-        validateEntitySelectOptionsQuery(feature);
-        validateEntitySelectAvailabilityQuery(feature, queryHandlerQns);
-        validateEntitySelectConditionalOptions(feature);
-        validateEmbeddedFields(feature, featureMap, queryHandlerQns);
-        validateMultiSelectFields(feature);
-        validateImageVariants(feature);
-        validateReferenceFields(feature, featureMap, queryHandlerQns);
-        validateHandlerFieldReferences(feature, featureMap);
-        validateTransitions(feature);
-        validateLockedWhen(feature);
-        validateExtensionUsages(feature, extensionProviders);
-        validateExtendSchemaCollisions(feature);
-        validateDerivedFieldCollisions(feature);
-        validateHandlerAccess(feature);
-        validateAccessDeclarations(feature);
-        validateLocatedTimestamps(feature);
-        validateEntityIndexes(feature);
-        validateConfigKeyBounds(feature);
-        validateConfigKeyRequired(feature);
-        validateConfigKeyComputed(feature);
-        validateConfigKeyAllowPerRequest(feature);
-        validateConfigKeyBacking(feature);
-        validateConfigKeyOptionsQuery(feature);
-        validateConfigKeyPiiEncrypted(feature);
-        validateOwnershipRules(feature, allClaimKeys, knownRoles);
-        validateParentRefs(feature, featureMap);
-        validateTransferGraph(feature, featureMap);
-        validateMultiStreamProjections(feature);
-        // Before validateScreens: its visible/entityId field-reference checks throw
-        // for a Function value first, with the confusing "unknown field undefined"
-        // message (because `typeof fn !== "boolean"` is true), before the clear
-        // Function check here can run.
-        validateActionWiring(feature);
-        validateFieldWiring(feature);
-        validateScreens(feature, featureMap, allWriteHandlerQns, allScreenQns, configKeyDefsByQn, screensByShortId, detailForScreens);
-        validateNavs(feature, allScreenQns, allNavQns, allWorkspaceQns);
-        validateWorkspaces(feature, allNavQns);
-    }
-    validateNavCycles(allNavQns);
-    warnOnNavAccessInversion(allNavQns);
-    const effectiveNavAllowlist = resolveNavAllowlist(options?.navAllowlist, allNavQns, allWorkspaceQns);
-    if (effectiveNavAllowlist !== undefined) {
-        warnOnUnreachableNavScreens(allNavQns, effectiveNavAllowlist, options?.navAllowlistExempt, options?.navAllowlist === undefined ? "workspaces" : "explicit");
-    }
-    validateDefaultWorkspaceUniqueness(allWorkspaceQns);
-    validateI18nSurfaceKeys(features);
-    validateTranslationLocaleConsistency(features);
-    validateRequiredLocales(features, options?.requiredLocales);
-    validateEntityListScreens(features);
-    validateSubmitPrefilledHiddenFields(features);
-    validateCardMetaOverflow(features);
-    // Must run before validateProjectionListScreens: an unresolvable query
-    // there is silently treated as "capability absent" and surfaces as a
-    // misleading "no search parameter in its Zod schema" error instead of
-    // the clear typo message below.
-    validateQueryRefs(features);
-    validateExtensionSelectorPanels(features);
-    // Must also run after validateQueryRefs — column/field checks below
-    // assume every `query` string already resolves to a registered handler.
-    validateQueryOutputColumns(features);
-    validateProjectionListScreens(features);
-    validateRelatedListSectionQueries(features);
-    validateExtensionPreSaveWiring(features);
-    validateGdprStoragePersistence(features);
-    validateGlobalTenancyEntities(features);
-    validateFeatureBootChecks(features);
-    validateProjectionAllowlist(features);
-    if (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.
-        validateEntityFieldEncryptionAvailable(options?.env, options?.entityFieldCipher);
-    }
-    if (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)`);
-    }
-    validateConfigReads(features, allConfigKeys);
-    warnOnToggleableDependencies(features, featureMap);
-    warnOnMissingSecurityBaseline(features);
-    if (options?.warnOnUniqueAccessRoles === true) {
-        warnOnUniqueAccessRoles(features);
-    }
+    const ctx = buildBootContext(dedupeFeatures(rawFeatures), options);
+    const report = createBootReport();
+    const detailForScreens = runStructurePhase(report, ctx);
+    const flags = runFeaturePhase(report, ctx, detailForScreens);
+    runAppWidePhase(report, ctx);
+    runEnvironmentPhase(report, ctx, flags);
+    report.finish();
+    emitBootWarnings(ctx);
 }

package/dist/engine/boot-validator/pii-retention.js

@@ -1,4 +1,6 @@
+import { holdsFileRefs } from "../../files/file-field-slots.js";
 import { createFallbackLogger } from "../../logging/utils.js";
+import { isUserEntityReference } from "../user-entity-reference.js";
 import { PII_DIRECT_NAME_HINTS, PII_USER_OWNED_NAME_HINTS, PII_USER_REFERENCE_NAME_HINTS, } from "./entity-handler.js";
 const log = createFallbackLogger("kumiko:boot");
 // Framework-managed timestamp fields may be used as retention.reference
@@ -13,12 +15,6 @@ const FRAMEWORK_TIMESTAMP_FIELDS = new Set([
 // The cleanup job performs the actual parsing; the boot validator only checks
 // the format so typos ("30days") become visible before the first cleanup run.
 const KEEP_FOR_PATTERN = /^\d+[hdwmy]$/;
-const FILE_FIELD_TYPES = new Set([
-    "file",
-    "image",
-    "files",
-    "images",
-]);
 // Excludes subjectRef: its `personal: "ref"` union member structurally
 // forbids `anonymize` (packages/types/src/fields.ts).
 function hasAnonymizableSubjectField(annot) {
@@ -139,6 +135,7 @@ export function validatePiiAndRetention(feature) {
 const FIELD_RULES = [
     rejectMultipleSubjectAnnotations,
     rejectTextWithoutPersonalStance,
+    rejectPlaintextUserReference,
     rejectInvalidLookupable,
     rejectSensitiveWithoutCiphertextAtRest,
     validateWriteOnlyField,
@@ -185,6 +182,16 @@ function rejectTextWithoutPersonalStance(input) {
         throw new Error(`${fieldLocation(input)} (type "${field.type}") declares no personal stance. Build it with createTextField / createLongTextField and { personal: "self" | "tenant" | "ref" | { of: "<ownerField>" } | false }; false additionally needs { reason: "..." } stating why the value is not personal data.`);
     }
 }
+function rejectPlaintextUserReference(input) {
+    const { field, flags } = input;
+    // skip: only a plaintext reference to the user entity is a violation
+    if (field.type !== "reference" || !flags.allowPlaintext)
+        return;
+    // skip: references to other entities may stay plaintext
+    if (!isUserEntityReference(field.entity))
+        return;
+    throw new Error(`${fieldLocation(input)} references the user entity "${field.entity}" with { personal: false } — a user id is a pseudonym that falls under Art.17 forget. Use createReferenceField({ entity: "${field.entity}" }) or { personal: "ref" }.`);
+}
 // lookupable: only text fields with a subject annotation are supported. Without
 // a subject, the value remains plaintext, so a blind index would be a
 // second deterministic copy without any benefit.
@@ -268,8 +275,7 @@ function warnOnNonUserOwnerReference(input, ownerName, ownerField) {
     if (ownerField.type !== "reference")
         return;
     const refTarget = ownerField.entity;
-    const targetEntity = refTarget.includes(":") ? refTarget.split(":")[1] : refTarget;
-    if (targetEntity !== "user") {
+    if (!isUserEntityReference(refTarget)) {
         log.warn(`[Feature ${input.featureName}] personal.of "${ownerName}" on entity "${input.entityName}" targets reference "${refTarget}" — typically should be a user reference. If intentional (custom subject-entity like employee/patient), ignore.`);
     }
 }
@@ -278,7 +284,7 @@ function warnOnNonUserOwnerReference(input, ownerName, ownerField) {
 // with { personal: false, reason: "is_business_data" }.
 const UNANNOTATED_NAME_WARNINGS = [
     {
-        applies: (input) => FILE_FIELD_TYPES.has(input.field.type),
+        applies: (input) => holdsFileRefs(input.field),
         message: (input) => `[Feature ${input.featureName}] File field "${input.fieldName}" on entity "${input.entityName}" has no personal annotation. A forget with strategy "delete" then only severs the uploader link and keeps the binary. If the file holds personal data, mark it { personal: "self" } or { personal: { of: "<ownerField>" } }. If it is business data, set { personal: false, reason: "is_business_data" } to silence.`,
     },
     {

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

@@ -167,6 +167,22 @@ function validateRelatedListFacets(prefix, section, schema) {
         return;
     throw new Error(`${prefix}: declares facets but query "${section.query}" has no "filters" parameter in its Zod schema — add filters: z.array(z.object({ field: z.string(), op: z.literal("in"), value: z.unknown() })).optional() (or reuse entityListSchema's shape) to the handler's schema.`);
 }
+function validateRelatedListCount(prefix, section, layoutMode, schema) {
+    // skip: no count badge declared — nothing to reject.
+    if (section.count !== true)
+        return;
+    if (layoutMode !== "tabs") {
+        throw new Error(`${prefix}: count: true only renders in a layout with mode "tabs".`);
+    }
+    if (section.countField !== undefined) {
+        throw new Error(`${prefix}: declares both count and countField — pick one badge source.`);
+    }
+    for (const key of ["totalCount", "limit"]) {
+        if (schemaAccepts(schema, key))
+            continue;
+        throw new Error(`${prefix}: count: true needs query "${section.query}" to accept "${key}" in its Zod schema (the badge asks for limit: 1, totalCount: true).`);
+    }
+}
 // parentFilter lets a relatedList reuse the
 // generic `<entity>:list` query instead of a bespoke child-rows handler —
 // same 422 footgun as facets/filter above, plus its own mutual-exclusivity
@@ -219,7 +235,9 @@ export function validateRelatedListSectionQueries(features) {
             for (const section of screen.layout.sections) {
                 if (section.kind !== "relatedList")
                     continue;
-                validateSectionQuery(`[Feature ${feature.name}] Screen "${screen.id}" (${screen.type}) relatedList section "${section.title}"`, section);
+                const sectionPrefix = `[Feature ${feature.name}] Screen "${screen.id}" (${screen.type}) relatedList section "${section.title}"`;
+                validateSectionQuery(sectionPrefix, section);
+                validateRelatedListCount(sectionPrefix, section, screen.layout.mode, queryHandlers.get(section.query)?.schema);
             }
         }
     }

package/dist/engine/boot-validator/read-gate.d.ts

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