@cosmicdrift/kumiko-framework 0.328.0 → 0.329.0

package/dist/engine/boot-validator/access-roles.js

@@ -0,0 +1,76 @@
+import { normalizeAccessEntry } from "../ownership.js";
+const BUILTIN_ROLES = new Set(["all", "system"]);
+function addRole(roleHandlers, role, identifier) {
+    let handlers = roleHandlers.get(role);
+    if (!handlers) {
+        handlers = new Set();
+        roleHandlers.set(role, handlers);
+    }
+    handlers.add(identifier);
+}
+function addHandlerRoles(roleHandlers, f) {
+    const handlerGroups = [
+        { type: "write", defs: f.writeHandlers },
+        { type: "query", defs: f.queryHandlers },
+        { type: "stream", defs: f.streamHandlers },
+    ];
+    for (const { type, defs } of handlerGroups) {
+        for (const [handlerName, def] of Object.entries(defs)) {
+            if (!def.access || !("roles" in def.access))
+                continue;
+            const identifier = `${f.name}:${type}:${handlerName}`;
+            for (const role of def.access.roles) {
+                addRole(roleHandlers, role, identifier);
+            }
+        }
+    }
+}
+function addConfigKeyRoles(roleHandlers, f) {
+    for (const [key, keyDef] of Object.entries(f.configKeys ?? {})) {
+        const identifier = `${f.name}:config:${key}`;
+        for (const role of [...keyDef.access.read, ...keyDef.access.write]) {
+            addRole(roleHandlers, role, identifier);
+        }
+    }
+}
+function addEntityFieldRoles(roleHandlers, f) {
+    for (const [entityName, entity] of Object.entries(f.entities ?? {})) {
+        for (const [fieldName, field] of Object.entries(entity.fields)) {
+            const identifier = `${f.name}:entity:${entityName}.${fieldName}`;
+            const readRoles = Object.keys(normalizeAccessEntry(field.access?.read) ?? {});
+            const writeRoles = Object.keys(normalizeAccessEntry(field.access?.write) ?? {});
+            for (const role of [...readRoles, ...writeRoles]) {
+                addRole(roleHandlers, role, identifier);
+            }
+        }
+    }
+}
+// A single "exactly one handler" heuristic over-counts by construction:
+// legitimate fine-grained roles (a role scoped to one admin endpoint on
+// purpose) are the normal case, not a typo — and until every access
+// surface is scanned, a role can look unique here while it's really used
+// elsewhere (configKeys / entity+field access), a false positive in the
+// other direction. Both is why this stays opt-in (#1711) rather than a
+// default-on prod warning.
+export function warnOnUniqueAccessRoles(features) {
+    // role → set of distinct identifiers using it, across every access
+    // surface — write/query/stream handlers, config-key access, and
+    // entity/field-level access rules.
+    const roleHandlers = new Map();
+    for (const f of features) {
+        addHandlerRoles(roleHandlers, f);
+        addConfigKeyRoles(roleHandlers, f);
+        addEntityFieldRoles(roleHandlers, f);
+    }
+    for (const [role, handlers] of roleHandlers) {
+        if (BUILTIN_ROLES.has(role))
+            continue;
+        if (handlers.size !== 1)
+            continue;
+        const [identifier] = handlers;
+        // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+        console.warn(`[kumiko:boot] Access role "${role}" is only used by one handler (${identifier}). ` +
+            `This is often a typo — the role is unknown to every other handler in the boot scan. ` +
+            `If this is intentional, ignore this warning.`);
+    }
+}

package/dist/engine/boot-validator/action-wiring.d.ts

@@ -0,0 +1,3 @@
+import type { FeatureDefinition } from "../types/index.js";
+export declare function validateActionWiring(feature: FeatureDefinition): void;
+export declare function validateFieldWiring(feature: FeatureDefinition): void;

package/dist/engine/boot-validator/action-wiring.js

@@ -0,0 +1,104 @@
+import { isEditLayoutScreen, isFieldsEditSection, normalizeEditField, normalizeListColumn, sectionFieldSpecs, } from "../screen-helpers.js";
+const FUNCTION_DROPPED_HINT = "functions are dropped by JSON.stringify when the screen config reaches the client " +
+    "bundle — the action/field silently no-ops at runtime instead of failing loudly.";
+function throwIfFunction(value, message) {
+    if (typeof value === "function") {
+        throw new Error(message);
+    }
+}
+// rowActions/toolbarActions carry row-context extractors (payload/params),
+// static visibility conditions and navigate entityId — all declarative-DSL-
+// only fields (RowFieldExtractor's `{ pick }`/`{ map }`, FieldCondition's
+// `{ field, eq }`/`{ field, ne }`/`{ field, in }`/`{ field, notIn }`, plain
+// strings). A function literal here does not type-check against these
+// structural DSL types — it only reaches here via a leaked `any`/`as any`,
+// which this runtime check backstops.
+const ACTION_FUNCTION_FIELDS = ["payload", "params", "entityId", "visible"];
+function validateActionNoFunctions(featureName, screenId, actionKind, action) {
+    const record = action;
+    for (const field of ACTION_FUNCTION_FIELDS) {
+        throwIfFunction(record[field], `[Feature ${featureName}] Screen "${screenId}" ${actionKind} "${action.id}" ${field} ` +
+            `is a function — ${FUNCTION_DROPPED_HINT} Use the declarative DSL ({ pick }, { map }, ` +
+            `"fieldName", { field, eq }/{ field, in }) instead.`);
+    }
+}
+export function validateActionWiring(feature) {
+    for (const screen of Object.values(feature.screens)) {
+        if (screen.type === "projectionDetail") {
+            for (const action of screen.actions ?? []) {
+                validateActionNoFunctions(feature.name, screen.id, "action", action);
+            }
+            continue;
+        }
+        if (screen.type !== "entityList" && screen.type !== "projectionList")
+            continue;
+        for (const action of screen.rowActions ?? []) {
+            validateActionNoFunctions(feature.name, screen.id, "rowAction", action);
+        }
+        for (const action of screen.toolbarActions ?? []) {
+            validateActionNoFunctions(feature.name, screen.id, "toolbarAction", action);
+        }
+    }
+}
+// EditFieldSpec's visible/readOnly/required are the same FieldCondition DSL
+// as rowActions — same footgun, different screen type (entityEdit layouts).
+const EDIT_FIELD_FUNCTION_FIELDS = ["visible", "readOnly", "required"];
+function validateEditFieldNoFunctions(featureName, screenId, screenType, fieldSpec) {
+    const normalized = normalizeEditField(fieldSpec);
+    const record = normalized;
+    for (const key of EDIT_FIELD_FUNCTION_FIELDS) {
+        throwIfFunction(record[key], `[Feature ${featureName}] Screen "${screenId}" (${screenType}) field "${normalized.field}" ` +
+            `${key} is a function — ${FUNCTION_DROPPED_HINT} Use a FieldCondition ` +
+            `(boolean or { field, eq }/{ field, ne }/{ field, in }/{ field, notIn }) instead.`);
+    }
+    throwIfFunction(normalized.renderer, `[Feature ${featureName}] Screen "${screenId}" (${screenType}) field "${normalized.field}" ` +
+        `renderer is a function — ${FUNCTION_DROPPED_HINT} Use a FormatSpec ({ format: "..." }) instead.`);
+}
+function validateColumnsNoFunctions(featureName, screenId, screenType, columns) {
+    for (const col of columns) {
+        const normalized = normalizeListColumn(col);
+        throwIfFunction(normalized.renderer, `[Feature ${featureName}] Screen "${screenId}" (${screenType}) column ` +
+            `"${normalized.field}" renderer is a function — ${FUNCTION_DROPPED_HINT} ` +
+            `Use a FormatSpec ({ format: "..." }) instead.`);
+    }
+}
+function validateEditLayoutNoFunctions(featureName, screenId, screenType, layout) {
+    for (const section of layout.sections) {
+        // relatedList carries `columns` instead of `fields` — route it through
+        // the same column check entityList/projectionList top-level columns use.
+        if (section.kind === "relatedList") {
+            validateColumnsNoFunctions(featureName, screenId, screenType, section.columns);
+            continue;
+        }
+        if (!isFieldsEditSection(section))
+            continue;
+        for (const fieldSpec of sectionFieldSpecs(section)) {
+            validateEditFieldNoFunctions(featureName, screenId, screenType, fieldSpec);
+        }
+    }
+}
+// Screen types that carry an EditLayout (entityEdit's layout shape, reused
+// verbatim by actionForm/configEdit/projectionDetail) vs. ones that carry
+// ListColumnSpec[] (entityList/projectionList, plus dashboard "list" panels)
+// both funnel through the same two checks below — a function literal in
+// either shape is dropped by JSON.stringify regardless of which screen type
+// hosts it.
+export function validateFieldWiring(feature) {
+    for (const screen of Object.values(feature.screens)) {
+        if (screen.type === "entityList" || screen.type === "projectionList") {
+            validateColumnsNoFunctions(feature.name, screen.id, screen.type, screen.columns);
+            continue;
+        }
+        if (isEditLayoutScreen(screen)) {
+            validateEditLayoutNoFunctions(feature.name, screen.id, screen.type, screen.layout);
+            continue;
+        }
+        if (screen.type === "dashboard") {
+            for (const panel of screen.panels) {
+                if (panel.kind !== "list")
+                    continue;
+                validateColumnsNoFunctions(feature.name, `${screen.id}:${panel.id}`, "dashboard-list", panel.columns);
+            }
+        }
+    }
+}

package/dist/engine/boot-validator/api-ext.d.ts

@@ -0,0 +1,3 @@
+import type { FeatureDefinition } from "../types/index.js";
+export declare function validateApiExposureMatching(feature: FeatureDefinition, allExposedApis: ReadonlyMap<string, string>, featureMap: ReadonlyMap<string, FeatureDefinition>): void;
+export declare function validateExtensionUsages(feature: FeatureDefinition, extensionProviders: ReadonlyMap<string, string>): void;

package/dist/engine/boot-validator/api-ext.js

@@ -0,0 +1,54 @@
+// --- Cross-feature API exposure / usage matching ---
+//
+// `r.exposesApi(name, impl)` registers a callable; `r.usesApi(name)`
+// declares a caller. Boot-Validator prüft drei Invarianten:
+//   1. Jeder usesApi(name) findet einen exposesApi(name) in irgendeinem
+//      Feature.
+//   2. Das exposing-Feature ist in requires/optionalRequires des callers
+//      gelisted (sonst klappt die Cross-Feature-Aufruf-Reihenfolge nicht).
+//   3. Self-exposure ist erlaubt (Feature ruft eigene API), wird aber
+//      mit Warning markiert weil es typisch ein Refactor-Restbestand ist.
+//
+// Globale Eindeutigkeit der apiNames (kein Dublicate über Features)
+// wird in validateBoot() vor dem Per-Feature-Walk geprüft.
+export function validateApiExposureMatching(feature, allExposedApis, featureMap) {
+    for (const apiName of feature.usedApis) {
+        const providerFeature = allExposedApis.get(apiName);
+        if (!providerFeature) {
+            const known = [...allExposedApis.keys()].sort().join(", ") || "(none)";
+            throw new Error(`[Feature ${feature.name}] r.usesApi("${apiName}") but no feature exposes that API. Known exposed APIs: ${known}`);
+        }
+        if (providerFeature === feature.name) {
+            // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+            console.warn(`[kumiko:boot] [Feature ${feature.name}] r.usesApi("${apiName}") on its own r.exposesApi — typically a refactor leftover. Call the impl directly instead.`);
+            continue;
+        }
+        const allDeps = [...feature.requires, ...feature.optionalRequires];
+        if (!allDeps.includes(providerFeature)) {
+            throw new Error(`[Feature ${feature.name}] r.usesApi("${apiName}") is exposed by "${providerFeature}" but feature is not in requires/optionalRequires. Add r.requires("${providerFeature}").`);
+        }
+        // Sanity: provider feature actually exists in this app's feature set.
+        // Should always be true if allExposedApis was built from `features`,
+        // aber defensiv für unklare Constructor-Pfade.
+        if (!featureMap.has(providerFeature)) {
+            throw new Error(`[Feature ${feature.name}] internal: r.usesApi("${apiName}") points to provider "${providerFeature}" which is not in feature map`);
+        }
+    }
+}
+// --- Extension usage validation ---
+export function validateExtensionUsages(feature, extensionProviders) {
+    for (const usage of feature.extensionUsages) {
+        const providerFeature = extensionProviders.get(usage.extensionName);
+        if (!providerFeature) {
+            throw new Error(`Feature "${feature.name}" uses extension "${usage.extensionName}" on entity "${usage.entityName}" but no feature defines that extension`);
+        }
+        // self-extension is legitimate: requires(self) would be circular.
+        if (providerFeature === feature.name) {
+            continue;
+        }
+        const allDeps = [...feature.requires, ...feature.optionalRequires];
+        if (!allDeps.includes(providerFeature)) {
+            throw new Error(`Feature "${feature.name}" uses extension "${usage.extensionName}" but missing requires("${providerFeature}")`);
+        }
+    }
+}

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

@@ -0,0 +1,2 @@
+import type { FeatureDefinition } from "../types/index.js";
+export declare function validateFeatureBootChecks(features: readonly FeatureDefinition[]): void;

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

@@ -0,0 +1,20 @@
+// r.bootCheck(fn) lets a feature declare its own mount-invariant instead of
+// relying on framework-internal knowledge (the gdpr-storage.ts guards are
+// the framework-owned version of this same idea). Each registered fn gets
+// the full mounted-feature set and throws to fail the boot; we wrap the
+// message with the owning feature's name so the error text points back at
+// the feature that declared the check.
+export function validateFeatureBootChecks(features) {
+    const ctx = { features };
+    for (const feature of features) {
+        for (const check of feature.bootChecks) {
+            try {
+                check(ctx);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                throw new Error(`[Feature ${feature.name}] r.bootCheck failed: ${message}`);
+            }
+        }
+    }
+}

package/dist/engine/boot-validator/config-deps.d.ts

@@ -0,0 +1,10 @@
+import type { FeatureDefinition } from "../types/index.js";
+export declare function warnOnToggleableDependencies(features: readonly FeatureDefinition[], featureMap: ReadonlyMap<string, FeatureDefinition>): void;
+export declare function validateConfigKeyBounds(feature: FeatureDefinition): void;
+export declare function validateConfigKeyComputed(feature: FeatureDefinition): void;
+export declare function validateConfigKeyRequired(feature: FeatureDefinition): void;
+export declare function validateConfigKeyAllowPerRequest(feature: FeatureDefinition): void;
+export declare function validateConfigKeyBacking(feature: FeatureDefinition): void;
+export declare function validateConfigKeyPiiEncrypted(feature: FeatureDefinition): void;
+export declare function validateConfigReads(features: readonly FeatureDefinition[], allConfigKeys: ReadonlySet<string>): void;
+export declare function validateCircularDeps(featureName: string, featureMap: ReadonlyMap<string, FeatureDefinition>): void;

package/dist/engine/boot-validator/config-deps.js

@@ -0,0 +1,180 @@
+import { isEncryptedAtRest } from "../config-helpers.js";
+// --- Toggleable-dependency warnings ---
+//
+// When feature A declares r.requires("B") and B is toggleable with
+// default=false, A is effectively disabled out-of-the-box until someone
+// flips B on globally. That's usually an oversight — the dev either meant
+// optionalRequires, or forgot to ship B with default=true. We warn (not
+// fail) because the combination is legal: an app might intentionally
+// require an opt-in feature to make it explicit that B must be activated.
+export function warnOnToggleableDependencies(features, featureMap) {
+    for (const f of features) {
+        for (const dep of f.requires) {
+            const depFeature = featureMap.get(dep);
+            if (!depFeature)
+                continue; // requires-target-missing is handled elsewhere
+            if (depFeature.toggleableDefault === false) {
+                // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+                console.warn(`[kumiko:boot] Feature "${f.name}" requires "${dep}", which is toggleable(default=false). ` +
+                    `"${f.name}" will be effectively disabled until "${dep}" is enabled globally via the feature-toggles feature. ` +
+                    `If this is intentional, ignore this warning; otherwise consider r.optionalRequires() or default=true.`);
+            }
+        }
+    }
+}
+// --- Config key bounds consistency ---
+export function validateConfigKeyBounds(feature) {
+    for (const [keyName, keyDef] of Object.entries(feature.configKeys)) {
+        const bounds = keyDef.bounds;
+        // skip: no bounds declared, nothing to validate
+        if (!bounds)
+            continue;
+        // Bounds on non-number keys are nonsensical — the call-site type-guard
+        // already rejects this, but catch it at boot as defence in depth (e.g.
+        // a hand-rolled key definition that bypasses createTenantConfig).
+        if (keyDef.type !== "number") {
+            throw new Error(`[Feature ${feature.name}] Config key "${keyName}" has bounds but type is "${keyDef.type}" — bounds are only valid for type="number"`);
+        }
+        const { min, max } = bounds;
+        if (min !== undefined && max !== undefined && min > max) {
+            throw new Error(`[Feature ${feature.name}] Config key "${keyName}" has bounds.min (${min}) > bounds.max (${max})`);
+        }
+        if (keyDef.default !== undefined) {
+            const defaultNum = keyDef.default; // @cast-boundary engine-payload
+            if (min !== undefined && defaultNum < min) {
+                throw new Error(`[Feature ${feature.name}] Config key "${keyName}" default (${defaultNum}) is below bounds.min (${min})`);
+            }
+            if (max !== undefined && defaultNum > max) {
+                throw new Error(`[Feature ${feature.name}] Config key "${keyName}" default (${defaultNum}) is above bounds.max (${max})`);
+            }
+        }
+    }
+}
+// --- Config key computed + encrypted exclusivity ---
+export function validateConfigKeyComputed(feature) {
+    for (const [keyName, keyDef] of Object.entries(feature.configKeys)) {
+        if (!keyDef.computed)
+            continue;
+        // computed + encrypted mix two paradigms that shouldn't meet: computed
+        // returns a plain value, encrypted expects cipher-text in the row. The
+        // cascade doesn't know which one to prefer on write. Rejecting at boot
+        // is cheaper than surprising behaviour at runtime.
+        if (isEncryptedAtRest(keyDef)) {
+            throw new Error(`[Feature ${feature.name}] Config key "${keyName}" has both encrypted/backing="secrets" and a computed resolver — these are mutually exclusive paradigms`);
+        }
+    }
+}
+// --- Config key required/default compatibility ---
+export function validateConfigKeyRequired(feature) {
+    for (const [keyName, keyDef] of Object.entries(feature.configKeys ?? {})) {
+        if (keyDef.required !== true)
+            continue;
+        // required heißt "Tenant MUSS konfigurieren" — ein non-empty default
+        // oder ein computed-Resolver macht den Key nie unset, readiness könnte
+        // die Lücke nie melden: der required-Flag wäre eine stille Lüge.
+        if (keyDef.computed !== undefined) {
+            throw new Error(`[Feature ${feature.name}] Config key "${keyName}" has required=true AND a computed resolver — a computed key can never be missing; drop one of the two`);
+        }
+        const d = keyDef.default;
+        const nonEmptyDefault = d !== undefined && !(typeof d === "string" && d.trim().length === 0);
+        if (nonEmptyDefault) {
+            throw new Error(`[Feature ${feature.name}] Config key "${keyName}" has required=true AND a non-empty default (${JSON.stringify(d)}) — the key can never be unset, readiness would never flag it; use default "" or drop required`);
+        }
+    }
+}
+// --- Config key allowPerRequest compatibility ---
+export function validateConfigKeyAllowPerRequest(feature) {
+    for (const [keyName, keyDef] of Object.entries(feature.configKeys)) {
+        if (!keyDef.allowPerRequest)
+            continue;
+        // text is hard-locked against per-request — the helper refuses
+        // anyway, but declaring allowPerRequest on a text key is a
+        // misconfiguration that should fail loudly at boot.
+        if (keyDef.type === "text") {
+            throw new Error(`[Feature ${feature.name}] Config key "${keyName}" has allowPerRequest=true but type="text" — text keys are permanently ineligible for per-request overrides (XSS/injection risk)`);
+        }
+        // encrypted + per-request would expose a cipher-text interpretation
+        // to query-strings. The secret-value shouldn't be transported this
+        // way — reject as a paradigm-mismatch.
+        if (isEncryptedAtRest(keyDef)) {
+            throw new Error(`[Feature ${feature.name}] Config key "${keyName}" has allowPerRequest=true but encrypted/backing="secrets" — secret values may not be set via query-params`);
+        }
+    }
+}
+// --- Config key storage backing × scope matrix ---
+export function validateConfigKeyBacking(feature) {
+    for (const [keyName, keyDef] of Object.entries(feature.configKeys)) {
+        if (keyDef.backing !== "secrets")
+            continue;
+        // secrets storage is flat per (tenant, key) with no system→tenant cascade,
+        // so a tenant- or user-scoped secret could never inherit a system default.
+        // Permanent rule: secrets-backed keys must be system-scoped.
+        if (keyDef.scope !== "system") {
+            throw new Error(`[Feature ${feature.name}] Config key "${keyName}" has backing="secrets" but scope="${keyDef.scope}" — secrets storage is flat per (tenant,key) and does not cascade; backing="secrets" requires scope="system"`);
+        }
+        // system-scoped backing="secrets" is wired end-to-end: reads dispatch
+        // through the resolver's secretsReader, writes through config:write:set/
+        // :reset into the secrets store (SYSTEM_TENANT_ID), masked in the query
+        // handlers. The runtime contract is that the app provides
+        // `extraContext.secrets` (+ a MasterKeyProvider) — a backing="secrets"
+        // read/write without it throws loud at request time, not silently.
+    }
+}
+// --- Config key piiEncrypted compatibility (kumiko-platform#231/#459) ---
+export function validateConfigKeyPiiEncrypted(feature) {
+    for (const [keyName, keyDef] of Object.entries(feature.configKeys)) {
+        if (!keyDef.piiEncrypted)
+            continue;
+        if (keyDef.type !== "text") {
+            throw new Error(`[Feature ${feature.name}] Config key "${keyName}" has piiEncrypted=true but type="${keyDef.type}" — piiEncrypted only applies to text keys`);
+        }
+        // system scope has no subject (no tenant, no user) for the subject-KMS
+        // to encrypt under.
+        if (keyDef.scope === "system") {
+            throw new Error(`[Feature ${feature.name}] Config key "${keyName}" has piiEncrypted=true but scope="system" — system-scope has no subject (tenant/user) for the subject-KMS to encrypt under`);
+        }
+        // Mutually exclusive with the shared-cipher path: a config value is
+        // either subject-keyed (piiEncrypted) or master-key-keyed (encrypted/
+        // backing="secrets"), never both — unlike entity fields, which allow
+        // both markers together (double-wrap, e.g. auth-mfa.totpSecret) because
+        // entity rows decrypt through a fixed executor pipeline that peels both
+        // layers. Config values have no such pipeline; picking one keeps the
+        // resolver simple.
+        if (isEncryptedAtRest(keyDef)) {
+            throw new Error(`[Feature ${feature.name}] Config key "${keyName}" has both piiEncrypted=true and encrypted/backing="secrets" — pick one: piiEncrypted (subject-KMS, user-visible) or encrypted (shared cipher, server-only values)`);
+        }
+    }
+}
+// --- Config key cross-feature reference validation ---
+export function validateConfigReads(features, allConfigKeys) {
+    for (const feature of features) {
+        for (const key of feature.configReads) {
+            if (!allConfigKeys.has(key)) {
+                throw new Error(`Feature "${feature.name}" reads config "${key}" but no feature defines that key`);
+            }
+        }
+    }
+}
+// --- Circular dependency detection ---
+export function validateCircularDeps(featureName, featureMap) {
+    const visited = new Set();
+    const stack = new Set();
+    function visit(name, path) {
+        if (stack.has(name)) {
+            throw new Error(`Circular dependency: ${[...path, name].join(" → ")}`);
+        }
+        // skip: node already visited in DFS traversal
+        if (visited.has(name))
+            return;
+        visited.add(name);
+        stack.add(name);
+        const feature = featureMap.get(name);
+        if (feature) {
+            for (const dep of feature.requires) {
+                visit(dep, [...path, name]);
+            }
+        }
+        stack.delete(name);
+    }
+    visit(featureName, []);
+}

package/dist/engine/boot-validator/custom-screen-write-qns.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Boot-time scan of app `src/**` for `dispatcher.write("…")` string literals.
+ * Fails fast before the first Custom-Screen click would 404.
+ *
+ * Only covers string literals — Handler-constant refs are caught by the CI
+ * guard (ts-morph) and compile-time TypedDispatcher.
+ */
+export declare function validateAppCustomScreenWriteQns(appRoot: string, knownQns: ReadonlySet<string>): void;

package/dist/engine/boot-validator/custom-screen-write-qns.js

@@ -0,0 +1,75 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { extractDispatcherWriteQnsFromSource, validateDispatcherWriteQn, } from "../write-handler-qn-extract.js";
+const SKIP_SEGMENTS = new Set(["node_modules", ".kumiko", "dist", "dist-server", "__tests__"]);
+function collectAppSourceFiles(dir, out) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        // skip: directory unreadable (permissions / race) — treat as empty
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.startsWith("."))
+            continue;
+        if (SKIP_SEGMENTS.has(entry))
+            continue;
+        const full = join(dir, entry);
+        let stat;
+        try {
+            stat = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isDirectory()) {
+            collectAppSourceFiles(full, out);
+        }
+        else if (stat.isFile() &&
+            (entry.endsWith(".ts") || entry.endsWith(".tsx")) &&
+            !entry.endsWith(".d.ts") &&
+            !entry.endsWith(".test.ts") &&
+            !entry.endsWith(".test.tsx") &&
+            !entry.endsWith(".integration.ts") &&
+            !entry.endsWith(".integration.tsx")) {
+            out.push(full);
+        }
+    }
+}
+/**
+ * Boot-time scan of app `src/**` for `dispatcher.write("…")` string literals.
+ * Fails fast before the first Custom-Screen click would 404.
+ *
+ * Only covers string literals — Handler-constant refs are caught by the CI
+ * guard (ts-morph) and compile-time TypedDispatcher.
+ */
+export function validateAppCustomScreenWriteQns(appRoot, knownQns) {
+    const srcDir = join(appRoot, "src");
+    // skip: apps without a src/ tree (server-only packages) — nothing to scan
+    if (!existsSync(srcDir))
+        return;
+    const files = [];
+    collectAppSourceFiles(srcDir, files);
+    const violations = [];
+    for (const filePath of files) {
+        const source = readFileSync(filePath, "utf-8");
+        for (const qn of extractDispatcherWriteQnsFromSource(source)) {
+            const result = validateDispatcherWriteQn(qn, knownQns);
+            if (!result.ok) {
+                violations.push({
+                    file: relative(appRoot, filePath),
+                    qn,
+                    reason: result.reason,
+                });
+            }
+        }
+    }
+    // skip: no invalid QNs found — boot continues
+    if (violations.length === 0)
+        return;
+    const lines = violations.map((v) => `  - ${v.file}: "${v.qn}" — ${v.reason}`);
+    throw new Error(`[kumiko:boot] ${violations.length} invalid dispatcher.write QN(s) in app source:\n${lines.join("\n")}\n` +
+        `  Check spelling against registered write handlers (expected "<feature>:write:<handler>").`);
+}

package/dist/engine/boot-validator/detail-screens.d.ts

@@ -0,0 +1,6 @@
+import type { FeatureDefinition } from "../types/index.js";
+import type { ScreenDefinition } from "../types/screen.js";
+export declare function collectDetailForScreens(features: readonly FeatureDefinition[], featureMap: ReadonlyMap<string, FeatureDefinition>): Map<string, {
+    readonly featureName: string;
+    readonly screen: ScreenDefinition;
+}>;

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

@@ -0,0 +1,31 @@
+import { qualifyEntityName } from "../qualified-name.js";
+import { findEntityFeature } from "./screens.js";
+// Entity name → the one screen that declares detailFor: "<entity>". Built
+// once, up front (before the per-feature validateScreens loop) so both this
+// module's own uniqueness check AND rowAction entity-targets (fw#2228,
+// screens.ts) resolve against the same map instead of re-walking every
+// feature's screens twice.
+export function collectDetailForScreens(features, featureMap) {
+    const screenQnByEntity = new Map();
+    const result = new Map();
+    for (const feature of features) {
+        for (const [screenId, screen] of Object.entries(feature.screens)) {
+            const detailFor = screen.detailFor;
+            if (detailFor === undefined)
+                continue;
+            const qualified = qualifyEntityName(feature.name, "screen", screenId);
+            const existingQn = screenQnByEntity.get(detailFor);
+            if (existingQn !== undefined) {
+                throw new Error(`[detailFor] Screens "${existingQn}" and "${qualified}" both declare ` +
+                    `detailFor: "${detailFor}" — only one screen may be the detail view for an entity.`);
+            }
+            screenQnByEntity.set(detailFor, qualified);
+            if (findEntityFeature(detailFor, featureMap) === undefined) {
+                throw new Error(`[detailFor] Screen "${qualified}" declares detailFor: "${detailFor}", ` +
+                    `but no feature registers an entity with that name.`);
+            }
+            result.set(detailFor, { featureName: feature.name, screen });
+        }
+    }
+    return result;
+}

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

@@ -0,0 +1,23 @@
+import type { FeatureDefinition, QueryHandlerDef } from "../types/index.js";
+export declare const FILE_FIELD_TYPES: Set<string>;
+export declare const PII_DIRECT_NAME_HINTS: ReadonlySet<string>;
+export declare const PII_USER_OWNED_NAME_HINTS: ReadonlySet<string>;
+export declare const PII_USER_REFERENCE_NAME_HINTS: ReadonlySet<string>;
+/** Extensions with preSave must target an entity that has mapped write handlers. */
+export declare function validateExtensionPreSaveWiring(features: readonly FeatureDefinition[]): void;
+export declare function validateHandlerAccess(feature: FeatureDefinition): void;
+export declare function validateRateLimitDisabledReason(featureName: string, kind: "write" | "query" | "stream", handlerName: string, rateLimit: FeatureDefinition["writeHandlers"][string]["rateLimit"]): void;
+export declare function validateNoAllRoleInHandlerAccess(featureName: string, kind: "write" | "query" | "stream", handlerName: string, access: NonNullable<FeatureDefinition["writeHandlers"][string]["access"]>): void;
+export declare function validateAnonymousRateLimit(featureName: string, kind: "write" | "query" | "stream", handlerName: string, access: NonNullable<FeatureDefinition["writeHandlers"][string]["access"]>, rateLimit: FeatureDefinition["writeHandlers"][string]["rateLimit"]): void;
+export declare function validateMultiStreamProjections(feature: FeatureDefinition): void;
+export declare function validateLocatedTimestamps(feature: FeatureDefinition): void;
+export declare function validateEntityIndexes(feature: FeatureDefinition): void;
+export declare function validateEncryptedFields(feature: FeatureDefinition): boolean;
+export declare function validateFileFields(feature: FeatureDefinition): boolean;
+export declare function validateReferenceFields(feature: FeatureDefinition, featureMap: ReadonlyMap<string, FeatureDefinition>, queryHandlers: ReadonlyMap<string, QueryHandlerDef>): void;
+export declare function validateEmbeddedFields(feature: FeatureDefinition, featureMap: ReadonlyMap<string, FeatureDefinition>, queryHandlers: ReadonlyMap<string, QueryHandlerDef>): void;
+export declare function validateMultiSelectFields(feature: FeatureDefinition): void;
+export declare function validateImageVariants(feature: FeatureDefinition): void;
+export declare function validateTransitions(feature: FeatureDefinition): void;
+export declare function validateExtendSchemaCollisions(feature: FeatureDefinition): void;
+export declare function validateDerivedFieldCollisions(feature: FeatureDefinition): void;