@cosmicdrift/kumiko-framework 0.257.0 → 0.258.1

package/src/engine/boot-validator/parent-ref.ts

@@ -0,0 +1,96 @@
+import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handlers";
+import type { EntityDefinition, FeatureDefinition, QueryHandlerDef } from "../types";
+
+// --- Parent-ref boot validation (fw#2766) ---
+//
+// Join-row entities (EntityDefinition.parentRef) derive both the write-path
+// deny and the read-path SQL gate from one declaration. This is the boot-time
+// half of the fail-closed guarantee: the read gate itself (db/parent-ref-
+// clause.ts) passes an ungated query through when no ParentVisibilityOption
+// was supplied — throwing there would 500 every custom handler and
+// framework-internal detail() call that doesn't wire it, so the enforcement
+// has to happen loudly here instead, once, at boot.
+
+function findEntity(
+  featureMap: ReadonlyMap<string, FeatureDefinition>,
+  entityName: string,
+): EntityDefinition | undefined {
+  for (const f of featureMap.values()) {
+    const entity = f.entities?.[entityName];
+    if (entity) return entity;
+  }
+  return undefined;
+}
+
+function findQueryHandler(
+  featureMap: ReadonlyMap<string, FeatureDefinition>,
+  handlerName: string,
+): QueryHandlerDef | undefined {
+  for (const f of featureMap.values()) {
+    const handler = f.queryHandlers[handlerName];
+    if (handler) return handler;
+  }
+  return undefined;
+}
+
+export function validateParentRefs(
+  feature: FeatureDefinition,
+  featureMap: ReadonlyMap<string, FeatureDefinition>,
+): void {
+  for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
+    const parentRef = entity.parentRef;
+    if (parentRef === undefined) continue;
+
+    if (entity.fields[parentRef.entityTypeField] === undefined) {
+      throw new Error(
+        `[Kumiko ParentRef] entity "${entityName}".parentRef.entityTypeField references ` +
+          `"${parentRef.entityTypeField}" — which is not a declared field on "${entityName}" ` +
+          `(feature: "${feature.name}"). Fix: point entityTypeField at a real field on the entity.`,
+      );
+    }
+    if (entity.fields[parentRef.entityIdField] === undefined) {
+      throw new Error(
+        `[Kumiko ParentRef] entity "${entityName}".parentRef.entityIdField references ` +
+          `"${parentRef.entityIdField}" — which is not a declared field on "${entityName}" ` +
+          `(feature: "${feature.name}"). Fix: point entityIdField at a real field on the entity.`,
+      );
+    }
+
+    for (const hostName of parentRef.allowedTypes ?? []) {
+      const host = findEntity(featureMap, hostName);
+      if (host === undefined) {
+        throw new Error(
+          `[Kumiko ParentRef] entity "${entityName}".parentRef.allowedTypes names "${hostName}" ` +
+            `— no entity with that name is registered in this feature set (feature: ` +
+            `"${feature.name}"). Fix: remove "${hostName}" from allowedTypes, or register it.`,
+        );
+      }
+      if (host.parentRef !== undefined) {
+        throw new Error(
+          `[Kumiko ParentRef] entity "${entityName}".parentRef.allowedTypes names "${hostName}" ` +
+            `— which itself declares a parentRef (feature: "${feature.name}"). A join-row ` +
+            `entity can't act as a host for another join-row entity (no recursive gating). ` +
+            `Fix: remove "${hostName}" from allowedTypes, or drop its own parentRef.`,
+        );
+      }
+    }
+
+    for (const verb of ["list", "detail"] as const) {
+      const handlerName = `${entityName}:${verb}`;
+      const handler = findQueryHandler(featureMap, handlerName);
+      // skip: no handler registered for this verb — nothing to brand-check
+      if (handler === undefined) continue;
+      if (handler[ENTITY_CONVENTION_QUERY_BRAND] !== true) {
+        throw new Error(
+          `[Kumiko ParentRef] query handler "${handlerName}" does not carry ` +
+            `ENTITY_CONVENTION_QUERY_BRAND, but entity "${entityName}" declares a parentRef ` +
+            `(feature: "${feature.name}"). A hand-written handler bypasses the parent-ref ` +
+            `read-gate unless it explicitly wires parentVisibility. Fix: register "${handlerName}" ` +
+            `via defineEntityListHandler/defineEntityDetailHandler (or defineEntityQueryHandler), ` +
+            `or pass { parentVisibility: { entities: ctx.registry.getAllEntities() } } to ` +
+            `executor.${verb} yourself.`,
+        );
+      }
+    }
+  }
+}

package/src/engine/boot-validator/projection-list-screens.ts

@@ -1,5 +1,11 @@
 import { QnTypes, qualifyEntityName } from "../qualified-name";
-import type { FeatureDefinition, ProjectionListScreenDefinition, QueryHandlerDef } from "../types";
+import { isEditLayoutScreen } from "../screen-helpers";
+import type {
+  EditRelatedListSection,
+  FeatureDefinition,
+  ProjectionListScreenDefinition,
+  QueryHandlerDef,
+} from "../types";
 import { SEARCHABLE_FALSE_WHITELIST } from "./entity-list-screens";
 import { getZodObjectShape } from "./zod-shape";
 
@@ -122,6 +128,32 @@ export function validateProjectionListScreens(features: readonly FeatureDefiniti
   }
 }
 
+function validateRelatedListSearchable(
+  prefix: string,
+  section: EditRelatedListSection,
+  schema: QueryHandlerDef["schema"] | undefined,
+): void {
+  // skip: not searchable, or the schema already accepts search — nothing to reject.
+  if (section.searchable !== true || schemaAccepts(schema, "search")) return;
+  throw new Error(
+    `${prefix}: searchable: true but query "${section.query}" has no "search" parameter in its Zod schema`,
+  );
+}
+
+function validateRelatedListFacets(
+  prefix: string,
+  section: EditRelatedListSection,
+  schema: QueryHandlerDef["schema"] | undefined,
+): void {
+  // skip: no facets declared — nothing to reject.
+  if (section.facets === undefined || section.facets.length === 0) return;
+  // skip: the schema already accepts filters — nothing to reject.
+  if (schemaAccepts(schema, "filters")) 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.`,
+  );
+}
+
 // relatedList sections declare search/facets the same way a projectionList
 // screen does, and hit the same 422 footgun: definePagedQueryHandler doesn't
 // auto-merge params into the handler's own Zod schema (fw#2165/#2224), so an
@@ -133,32 +165,13 @@ export function validateRelatedListSectionQueries(features: readonly FeatureDefi
   const queryHandlers = buildQueryHandlerMap(features);
   for (const feature of features) {
     for (const screen of Object.values(feature.screens)) {
-      if (
-        screen.type !== "projectionDetail" &&
-        screen.type !== "entityEdit" &&
-        screen.type !== "actionForm" &&
-        screen.type !== "configEdit"
-      ) {
-        continue;
-      }
+      if (!isEditLayoutScreen(screen)) continue;
       for (const section of screen.layout.sections) {
         if (section.kind !== "relatedList") continue;
         const prefix = `[Feature ${feature.name}] Screen "${screen.id}" (${screen.type}) relatedList section "${section.title}"`;
         const schema = queryHandlers.get(section.query)?.schema;
-        if (section.searchable === true && !schemaAccepts(schema, "search")) {
-          throw new Error(
-            `${prefix}: searchable: true but query "${section.query}" has no "search" parameter in its Zod schema`,
-          );
-        }
-        if (
-          section.facets !== undefined &&
-          section.facets.length > 0 &&
-          !schemaAccepts(schema, "filters")
-        ) {
-          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.`,
-          );
-        }
+        validateRelatedListSearchable(prefix, section, schema);
+        validateRelatedListFacets(prefix, section, schema);
       }
     }
   }

package/src/engine/boot-validator/query-output-columns.ts

@@ -219,7 +219,8 @@ function checkScreenOutputColumns(
   } else if (
     screen.type === "entityEdit" ||
     screen.type === "actionForm" ||
-    screen.type === "configEdit"
+    screen.type === "configEdit" ||
+    screen.type === "secretMint"
   ) {
     checkEditLayoutOutputColumns(queryHandlers, featureName, screenId, screen.type, screen.layout);
   } else if (screen.type === "dashboard") {

package/src/engine/boot-validator/query-refs.ts

@@ -111,7 +111,8 @@ function checkScreenQueryRefs(
   } else if (
     screen.type === "entityEdit" ||
     screen.type === "actionForm" ||
-    screen.type === "configEdit"
+    screen.type === "configEdit" ||
+    screen.type === "secretMint"
   ) {
     checkEditLayoutQueryRefs(queryHandlers, featureName, screenId, screen.type, screen.layout);
   } else if (screen.type === "dashboard") {