@cosmicdrift/kumiko-framework 0.256.0 → 0.258.0

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

@@ -15,9 +15,10 @@ import {
   normalizeEditField,
   normalizeListColumn,
 } from "../screen-helpers";
-import type { EntityDefinition, FeatureDefinition } from "../types";
+import type { EntityDefinition, FeatureDefinition, FieldDefinition } from "../types";
 import { metricField } from "../types";
 import type {
+  ActionFormScreenDefinition,
   DashboardCustomPanel,
   DashboardFilterDefinition,
   DashboardPanelDefinition,
@@ -32,6 +33,7 @@ import type {
   RowActionNavigateBase,
   RowFieldExtractor,
   ScreenDefinition,
+  SecretMintScreenDefinition,
   ToolbarAction,
 } from "../types/screen";
 
@@ -157,7 +159,9 @@ function validateRowActionNavigateParams(
     (action.entityId !== undefined ||
       (screenEntity !== undefined && target.screen.entity === screenEntity));
   if (
-    (target.screen.type !== "actionForm" && target.screen.type !== "entityEdit") ||
+    (target.screen.type !== "actionForm" &&
+      target.screen.type !== "secretMint" &&
+      target.screen.type !== "entityEdit") ||
     isEntityEditUpdate
   ) {
     const reason = isEntityEditUpdate
@@ -171,9 +175,10 @@ function validateRowActionNavigateParams(
       action.screen !== undefined ? `"${action.screen}"` : `entity "${action.entity}"`;
     throw new Error(
       `[Feature ${featureName}] Screen "${screenId}" (${screenType}) rowAction "${action.id}" ` +
-        `sets params on navigate-target ${targetDescriptor} which ${reason} — only actionForm ` +
-        `and entityEdit-create targets read URL search params as initial values. Remove the ` +
-        `params extractor or retarget to an actionForm / cross-entity entityEdit-create screen.`,
+        `sets params on navigate-target ${targetDescriptor} which ${reason} — only actionForm, ` +
+        `secretMint and entityEdit-create targets read URL search params as initial values. Remove ` +
+        `the params extractor or retarget to an actionForm / secretMint / cross-entity ` +
+        `entityEdit-create screen.`,
     );
   }
 }
@@ -184,7 +189,7 @@ function validateRowActionNavigateParams(
 function validateWizardLayout(
   featureName: string,
   screenId: string,
-  screenType: "entityEdit" | "actionForm" | "configEdit",
+  screenType: "entityEdit" | "actionForm" | "configEdit" | "secretMint",
   layout: EditLayout,
   featureMap: ReadonlyMap<string, FeatureDefinition>,
 ): void {
@@ -395,6 +400,8 @@ function validateDrawerTargetAction(
         `Known screens in this feature: ${[...Object.keys(screens)].sort().join(", ") || "(none)"}.`,
     );
   }
+  // secretMint is intentionally excluded — a one-time secret reveal belongs on
+  // its own page, not layered in a Drawer above a list.
   if (target.type !== "actionForm") {
     throw new Error(
       `[Feature ${featureName}] Screen "${screenId}" (${screenKind}) ${actionLabel} "${action.id}" ` +
@@ -496,6 +503,277 @@ function resolveRowActionNavigateTarget(
   return screensByShortId.get(action.screen)?.[0];
 }
 
+// Shared by the mint step's own handler (screen.handler) and its optional
+// confirm step (confirm.handler) — both are a bare write-handler QN with the
+// same registration requirement.
+function validateWriteHandlerRegistered(
+  featureName: string,
+  screenId: string,
+  context: string,
+  handler: unknown,
+  allWriteHandlerQns: ReadonlySet<string>,
+): void {
+  if (!handler || typeof handler !== "string") {
+    throw new Error(
+      `[Feature ${featureName}] Screen "${screenId}" (${context}) has empty or non-string handler.`,
+    );
+  }
+  if (!allWriteHandlerQns.has(handler)) {
+    throw new Error(
+      `[Feature ${featureName}] Screen "${screenId}" (${context}) handler "${handler}" ` +
+        `is not a registered write-handler. Check the QN spelling (expected ` +
+        `"<feature>:write:<short>") and that the handler is declared via r.writeHandler(...).`,
+    );
+  }
+}
+
+// Every field entry must carry a `type` discriminator. An author typo
+// (`title: { required: true }` without a type) would otherwise let
+// RenderField silently fall through to the default renderer and submit an
+// empty string — failing at boot is clearer. `type as unknown` because
+// FieldDefinition, as a union, only allows known type strings; here we're
+// checking author code that may have circumvented the type check.
+//
+// Parametrized over (fields, layout) instead of a whole screen so a
+// secretMint's own `confirm` step — a second, independent inline form on the
+// same screen — can reuse the same checks as its `fields`/`layout` pair.
+// `allowEmpty` is only ever true for a secretMint's own mint step (an
+// input-less mint, fw#2838): the secret is server-generated and the mint
+// step is just its submit button — actionForm and the confirm step always
+// require at least one field.
+function validateFormFieldsMap(
+  featureName: string,
+  screenId: string,
+  context: string,
+  fields: Readonly<Record<string, FieldDefinition>>,
+  allowEmpty: boolean,
+): Set<string> {
+  const fieldNames = new Set(Object.keys(fields));
+  if (fieldNames.size === 0 && !allowEmpty) {
+    throw new Error(
+      `[Feature ${featureName}] Screen "${screenId}" (${context}) has empty fields map — ` +
+        `declare at least one field.`,
+    );
+  }
+  for (const [fname, fdef] of Object.entries(fields)) {
+    // @cast-boundary schema-walk — feature-config inspection (Author may circumvent type-check)
+    const ftype = (fdef as { type?: unknown }).type;
+    if (typeof ftype !== "string" || ftype.length === 0) {
+      throw new Error(
+        `[Feature ${featureName}] Screen "${screenId}" (${context}) field "${fname}" has no ` +
+          `\`type\` set. Each field must declare a type (e.g. "text", "number", "select").`,
+      );
+    }
+  }
+  return fieldNames;
+}
+
+// `allowEmptySections` mirrors `validateFormFieldsMap`'s `allowEmpty` — the
+// caller only ever passes true together with an actually-empty fields map
+// (an input-less secretMint declares BOTH `fields: {}` and
+// `layout.sections: []`; fields declared with no layout to show them stays
+// an error).
+function validateFormLayoutSections(
+  featureName: string,
+  screenId: string,
+  context: string,
+  layout: EditLayout,
+  fieldNames: ReadonlySet<string>,
+  allowEmptySections: boolean,
+): void {
+  if (layout.sections.length === 0) {
+    // skip: an input-less secretMint declares fields: {} and sections: [] together — no sections to validate.
+    if (allowEmptySections) return;
+    throw new Error(
+      `[Feature ${featureName}] Screen "${screenId}" (${context}) has an empty sections list — ` +
+        `declare at least one section.`,
+    );
+  }
+  for (const section of layout.sections) {
+    if (isExtensionEditSection(section)) {
+      if (section.component?.react === undefined && section.component?.native === undefined) {
+        throw new Error(
+          `[Feature ${featureName}] Screen "${screenId}" (${context}) extension section ` +
+            `"${section.title}" has no component — declare a react/native component marker.`,
+        );
+      }
+      continue;
+    }
+    if (section.kind === "relatedList") {
+      throw new Error(
+        `[Feature ${featureName}] Screen "${screenId}" (${context}) relatedList section ` +
+          `"${section.title}" is not supported — relatedList is a projectionDetail-only ` +
+          `primitive (fw#2166).`,
+      );
+    }
+    if (isWriteFormEditSection(section)) {
+      throw new Error(
+        `[Feature ${featureName}] Screen "${screenId}" (${context}) writeForm section ` +
+          `"${section.title}" is not supported — writeForm is a projectionDetail-only primitive.`,
+      );
+    }
+    if (section.fields.length === 0) {
+      throw new Error(
+        `[Feature ${featureName}] Screen "${screenId}" (${context}) has a section "${section.title}" ` +
+          `with zero fields — drop the section or add fields to it.`,
+      );
+    }
+    for (const fieldSpec of section.fields) {
+      const normalized = normalizeEditField(fieldSpec);
+      if (!fieldNames.has(normalized.field)) {
+        throw new Error(
+          `[Feature ${featureName}] Screen "${screenId}" (${context}) layout references unknown field ` +
+            `"${normalized.field}". Known fields: ${[...fieldNames].sort().join(", ")}`,
+        );
+      }
+    }
+  }
+}
+
+function validateInlineFormNavTargets(
+  feature: FeatureDefinition,
+  screenId: string,
+  screen: ActionFormScreenDefinition | SecretMintScreenDefinition,
+  kind: "actionForm" | "secretMint",
+  allScreenQns: ReadonlySet<string>,
+): void {
+  if (screen.redirect !== undefined) {
+    // redirect is either a short screen id (same-feature, e.g. "item-list")
+    // or a fully-qualified cross-feature QN (`<feature>:screen:<id>`) — the
+    // renderer strips the latter to the short id (lastSegment) when
+    // navigating, which the nav-router resolves app-wide (#1946). The object
+    // form (fw#2670, actionForm only) carries the same target under `screen`
+    // plus the payload field `idFrom`.
+    const redirectTarget =
+      typeof screen.redirect === "string" ? screen.redirect : screen.redirect.screen;
+    if (
+      typeof screen.redirect !== "string" &&
+      (typeof screen.redirect.idFrom !== "string" || screen.redirect.idFrom.trim() === "")
+    ) {
+      throw new Error(
+        `[Feature ${feature.name}] Screen "${screenId}" (${kind}) redirect.idFrom is empty or not a string — ` +
+          `name the success-payload field carrying the navigation id, or use the plain string ` +
+          `redirect form to navigate with the handler's own "id".`,
+      );
+    }
+    validateScreenNavTarget(
+      feature.name,
+      screenId,
+      kind,
+      "redirect",
+      redirectTarget,
+      allScreenQns,
+      feature.screens,
+    );
+  }
+  if (typeof screen.cancelTarget === "string") {
+    // Same rule as redirect — `false` (no Cancel button) needs no validation.
+    validateScreenNavTarget(
+      feature.name,
+      screenId,
+      kind,
+      "cancelTarget",
+      screen.cancelTarget,
+      allScreenQns,
+      feature.screens,
+    );
+  }
+}
+
+// actionForm/secretMint have no entity link, only a write-handler QN +
+// inline fields: checks handler registration, field types, layout refs, and nav targets.
+function validateInlineFormScreen(
+  feature: FeatureDefinition,
+  screenId: string,
+  screen: ActionFormScreenDefinition | SecretMintScreenDefinition,
+  kind: "actionForm" | "secretMint",
+  allWriteHandlerQns: ReadonlySet<string>,
+  allScreenQns: ReadonlySet<string>,
+  featureMap: ReadonlyMap<string, FeatureDefinition>,
+): void {
+  validateWriteHandlerRegistered(feature.name, screenId, kind, screen.handler, allWriteHandlerQns);
+  // Only a secretMint's own mint step may skip fields/sections entirely
+  // (input-less mint, fw#2838) — actionForm always needs at least one field.
+  const allowEmptyMintForm = kind === "secretMint";
+  const fieldNames = validateFormFieldsMap(
+    feature.name,
+    screenId,
+    kind,
+    screen.fields,
+    allowEmptyMintForm,
+  );
+  validateFormLayoutSections(
+    feature.name,
+    screenId,
+    kind,
+    screen.layout,
+    fieldNames,
+    allowEmptyMintForm && fieldNames.size === 0,
+  );
+  validateWizardLayout(feature.name, screenId, kind, screen.layout, featureMap);
+  validateInlineFormNavTargets(feature, screenId, screen, kind, allScreenQns);
+}
+
+// SecretMintConfirmStep (fw#2838): an optional proof-of-receipt form rendered
+// on the reveal card in place of the bare acknowledge button (TOTP enrollment:
+// scan the code, then enter one). Unlike the mint step, confirm always needs
+// at least one field — a step whose only job is proving receipt with no input
+// would be meaningless — and its layout is a single plain form, never a
+// wizard/tabs flow and never a persisted draft: a one-time reveal-confirm is
+// not a multi-step flow, and persisting a draft of it would re-open the leak
+// fw#2548 closed (a lingering copy of the just-revealed secret in storage).
+function validateSecretMintConfirm(
+  feature: FeatureDefinition,
+  screenId: string,
+  screen: SecretMintScreenDefinition,
+  allWriteHandlerQns: ReadonlySet<string>,
+): void {
+  const confirm = screen.confirm;
+  // skip: the screen declares no confirm step — nothing to validate.
+  if (confirm === undefined) return;
+  const context = "secretMint confirm";
+  validateWriteHandlerRegistered(
+    feature.name,
+    screenId,
+    context,
+    confirm.handler,
+    allWriteHandlerQns,
+  );
+  const fieldNames = validateFormFieldsMap(feature.name, screenId, context, confirm.fields, false);
+  validateFormLayoutSections(feature.name, screenId, context, confirm.layout, fieldNames, false);
+  if (confirm.layout.mode !== undefined && confirm.layout.mode !== "single") {
+    throw new Error(
+      `[Feature ${feature.name}] Screen "${screenId}" (${context}) sets layout.mode: ` +
+        `"${confirm.layout.mode}" — a one-time reveal confirm step must stay a single-step form. ` +
+        `Remove mode or set it to "single".`,
+    );
+  }
+  if (confirm.layout.draft === true) {
+    throw new Error(
+      `[Feature ${feature.name}] Screen "${screenId}" (${context}) sets layout.draft: true — ` +
+        `persisting a draft of the reveal-confirm step would leak the one-time secret into storage, ` +
+        `the exact leak fw#2548 closed. Remove draft: true.`,
+    );
+  }
+  // skip: no carry list declared — no carried fields to cross-check against confirm.fields.
+  if (confirm.carry === undefined) return;
+  for (const carryField of confirm.carry) {
+    if (typeof carryField !== "string" || carryField.trim() === "") {
+      throw new Error(
+        `[Feature ${feature.name}] Screen "${screenId}" (${context}) has an empty or non-string ` +
+          `entry in "carry".`,
+      );
+    }
+    if (fieldNames.has(carryField)) {
+      throw new Error(
+        `[Feature ${feature.name}] Screen "${screenId}" (${context}) carry field "${carryField}" ` +
+          `also names a confirm.fields entry — a carried mint-payload value would silently ` +
+          `overwrite the user-entered field of the same name. Rename one of them.`,
+      );
+    }
+  }
+}
+
 export function validateScreens(
   feature: FeatureDefinition,
   featureMap: ReadonlyMap<string, FeatureDefinition>,
@@ -1052,144 +1330,57 @@ export function validateScreens(
     }
 
     if (screen.type === "actionForm") {
-      // Tier 2.7d: Action-Form-Screens haben keinen entity-Link, nur
-      // einen Write-Handler-QN + Inline-Fields. Sechs Author-Code-
-      // Checks am Boot:
-      //   1) handler ist non-empty String.
-      //   2) handler ist als Write-Handler registriert (cross-feature-
-      //      Lookup gegen die collected QN-Map). Tippfehler/umbenannte
-      //      Handler fallen sonst erst beim ersten Klick als 404 auf.
-      //   3) fields-Map ist non-empty.
-      //   4) Jeder Field-Eintrag hat einen `type`-Discriminator
-      //      (Tippfehler in Schema → Renderer crasht stumm sonst).
-      //   5) layout.sections + jedes referenced field existiert in
-      //      fields.
-      //   6) redirect (wenn gesetzt) verweist auf einen registrierten
-      //      Screen-QN (Cross-Feature ok).
-      if (!screen.handler || typeof screen.handler !== "string") {
-        throw new Error(
-          `[Feature ${feature.name}] Screen "${screenId}" (actionForm) has empty or non-string handler.`,
-        );
-      }
-      if (!allWriteHandlerQns.has(screen.handler)) {
-        throw new Error(
-          `[Feature ${feature.name}] Screen "${screenId}" (actionForm) handler "${screen.handler}" ` +
-            `is not a registered write-handler. Check the QN spelling (expected ` +
-            `"<feature>:write:<short>") and that the handler is declared via r.writeHandler(...).`,
-        );
-      }
-      const fieldNames = new Set(Object.keys(screen.fields));
-      if (fieldNames.size === 0) {
+      validateInlineFormScreen(
+        feature,
+        screenId,
+        screen,
+        "actionForm",
+        allWriteHandlerQns,
+        allScreenQns,
+        featureMap,
+      );
+      continue;
+    }
+
+    if (screen.type === "secretMint") {
+      validateInlineFormScreen(
+        feature,
+        screenId,
+        screen,
+        "secretMint",
+        allWriteHandlerQns,
+        allScreenQns,
+        featureMap,
+      );
+      if (screen.reveal.fields.length === 0) {
         throw new Error(
-          `[Feature ${feature.name}] Screen "${screenId}" (actionForm) has empty fields map — ` +
-            `declare at least one field.`,
+          `[Feature ${feature.name}] Screen "${screenId}" (secretMint) has an empty reveal.fields ` +
+            `list — declare at least one field to reveal.`,
         );
       }
-      // Jeder Field-Eintrag muss einen `type`-Discriminator haben.
-      // Author-Tippfehler (`title: { required: true }` ohne type) →
-      // RenderField fällt zur Laufzeit auf den Default-Renderer und
-      // schickt einen leeren String — silent broken. Boot-Fail ist
-      // klarer. `type as unknown` weil FieldDefinition als Union nur
-      // bekannte Strings erlaubt; wir prüfen Author-Code, der ggf.
-      // den Type-Check umgangen hat.
-      for (const [fname, fdef] of Object.entries(screen.fields)) {
-        // @cast-boundary schema-walk — feature-config inspection (Author may circumvent type-check)
-        const ftype = (fdef as { type?: unknown }).type;
-        if (typeof ftype !== "string" || ftype.length === 0) {
+      const revealFieldNames = new Set<string>();
+      for (const revealField of screen.reveal.fields) {
+        if (typeof revealField.field !== "string" || revealField.field.trim() === "") {
           throw new Error(
-            `[Feature ${feature.name}] Screen "${screenId}" (actionForm) field "${fname}" has no ` +
-              `\`type\` set. Each field must declare a type (e.g. "text", "number", "select").`,
+            `[Feature ${feature.name}] Screen "${screenId}" (secretMint) has a reveal.fields entry ` +
+              `with an empty or non-string "field".`,
           );
         }
-      }
-      if (screen.layout.sections.length === 0) {
-        throw new Error(
-          `[Feature ${feature.name}] Screen "${screenId}" (actionForm) has an empty sections list — ` +
-            `declare at least one section.`,
-        );
-      }
-      for (const section of screen.layout.sections) {
-        if (isExtensionEditSection(section)) {
-          if (section.component?.react === undefined && section.component?.native === undefined) {
-            throw new Error(
-              `[Feature ${feature.name}] Screen "${screenId}" (actionForm) extension section ` +
-                `"${section.title}" has no component — declare a react/native component marker.`,
-            );
-          }
-          continue;
-        }
-        if (section.kind === "relatedList") {
+        if (revealFieldNames.has(revealField.field)) {
           throw new Error(
-            `[Feature ${feature.name}] Screen "${screenId}" (actionForm) relatedList section ` +
-              `"${section.title}" is not supported — relatedList is a projectionDetail-only ` +
-              `primitive (fw#2166).`,
+            `[Feature ${feature.name}] Screen "${screenId}" (secretMint) reveal.fields has a ` +
+              `duplicate field "${revealField.field}" — each revealed field must be unique.`,
           );
         }
-        if (isWriteFormEditSection(section)) {
+        revealFieldNames.add(revealField.field);
+        if (typeof revealField.label !== "string" || revealField.label.trim() === "") {
           throw new Error(
-            `[Feature ${feature.name}] Screen "${screenId}" (actionForm) writeForm section ` +
-              `"${section.title}" is not supported — writeForm is a projectionDetail-only primitive.`,
+            `[Feature ${feature.name}] Screen "${screenId}" (secretMint) reveal.fields entry ` +
+              `"${revealField.field}" has an empty or non-string "label".`,
           );
         }
-        if (section.fields.length === 0) {
-          throw new Error(
-            `[Feature ${feature.name}] Screen "${screenId}" (actionForm) has a section "${section.title}" ` +
-              `with zero fields — drop the section or add fields to it.`,
-          );
-        }
-        for (const fieldSpec of section.fields) {
-          const normalized = normalizeEditField(fieldSpec);
-          if (!fieldNames.has(normalized.field)) {
-            throw new Error(
-              `[Feature ${feature.name}] Screen "${screenId}" (actionForm) layout references unknown field ` +
-                `"${normalized.field}". Known fields: ${[...fieldNames].sort().join(", ")}`,
-            );
-          }
-        }
-      }
-      validateWizardLayout(feature.name, screenId, "actionForm", screen.layout, featureMap);
-      if (screen.redirect !== undefined) {
-        // redirect is either a short screen id (same-feature, e.g.
-        // "item-list") or a fully-qualified cross-feature QN
-        // (`<feature>:screen:<id>`) — the renderer strips the latter to the
-        // short id (lastSegment) when navigating, which the nav-router
-        // resolves app-wide (#1946). The object form (fw#2670) carries the
-        // same target under `screen` plus the payload field `idFrom`.
-        const redirectTarget =
-          typeof screen.redirect === "string" ? screen.redirect : screen.redirect.screen;
-        if (
-          typeof screen.redirect !== "string" &&
-          (typeof screen.redirect.idFrom !== "string" || screen.redirect.idFrom.trim() === "")
-        ) {
-          throw new Error(
-            `[Feature ${feature.name}] Screen "${screenId}" (actionForm) redirect.idFrom is empty or not a string — ` +
-              `name the success-payload field carrying the navigation id, or use the plain string ` +
-              `redirect form to navigate with the handler's own "id".`,
-          );
-        }
-        validateScreenNavTarget(
-          feature.name,
-          screenId,
-          "actionForm",
-          "redirect",
-          redirectTarget,
-          allScreenQns,
-          feature.screens,
-        );
-      }
-      if (typeof screen.cancelTarget === "string") {
-        // Gleiche Regel wie redirect — `false` (kein Cancel-Button)
-        // braucht keine Validierung.
-        validateScreenNavTarget(
-          feature.name,
-          screenId,
-          "actionForm",
-          "cancelTarget",
-          screen.cancelTarget,
-          allScreenQns,
-          feature.screens,
-        );
       }
+      validateSecretMintConfirm(feature, screenId, screen, allWriteHandlerQns);
       continue;
     }
 

package/src/engine/define-handler.ts

@@ -1,4 +1,5 @@
 import type { CursorResult } from "@cosmicdrift/kumiko-types/cursor-types";
+import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handlers";
 import type { ZodType, z } from "zod";
 import type { ContainsSecret } from "../secrets/types";
 import { runPipeline } from "./run-pipeline";
@@ -147,6 +148,11 @@ export function isPagedQueryHandler(def: object): boolean {
   return (def as Record<string, unknown>)[PAGED_QUERY_HANDLER_BRAND] === true;
 }
 
+export function isEntityConventionQueryHandler(def: object): boolean {
+  // @cast-boundary brand-probe — same shape as isPagedQueryHandler above.
+  return (def as Record<string, unknown>)[ENTITY_CONVENTION_QUERY_BRAND] === true;
+}
+
 export type PagedQueryHandlerDefinition<
   TName extends string = string,
   TSchema extends ZodType = ZodType,

package/src/engine/entity-handlers.ts

@@ -1,3 +1,4 @@
+import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handlers";
 import { type ZodType, z } from "zod";
 import type { DbRow } from "../db/connection";
 import {
@@ -388,6 +389,7 @@ export function defineEntityQueryHandler(
             fields: ctx.registry.getSortableReferences(entityName),
             resolveEntity: (name) => ctx.registry.getEntity(name),
           },
+          parentVisibility: { entities: ctx.registry.getAllEntities() },
         });
         const enrichedRows = hasRefFields
           ? await enrichWithReferences(
@@ -404,7 +406,9 @@ export function defineEntityQueryHandler(
       schema = idSchema;
       handler = async (query, ctx) => {
         const db = dbFor(ctx);
-        const row = await executor.detail(query.payload as IdPayload, query.user, db); // @cast-boundary engine-payload
+        const row = await executor.detail(query.payload as IdPayload, query.user, db, {
+          parentVisibility: { entities: ctx.registry.getAllEntities() },
+        }); // @cast-boundary engine-payload
         if (row === null || !hasRefFields) return row;
         return enrichRowWithReferences(row, entity, (name) => ctx.registry.getEntity(name), db);
       };
@@ -426,6 +430,7 @@ export function defineEntityQueryHandler(
     // definePagedQueryHandler on top. The "detail" verb returns a single
     // row/null, never this shape.
     ...(verb === "list" && { [PAGED_QUERY_HANDLER_BRAND]: true }),
+    [ENTITY_CONVENTION_QUERY_BRAND]: true,
   };
 }
 

package/src/engine/factories.ts

@@ -456,6 +456,8 @@ export function createEntity<F>(def: {
   readonly indexes?: readonly EntityIndexDef[];
   readonly idType?: "serial" | "uuid";
   readonly access?: EntityDefinition["access"];
+  /** Join-row carrier reference — see EntityDefinition.parentRef. */
+  readonly parentRef?: EntityDefinition["parentRef"];
   readonly retention?: RetentionDef;
   readonly derivedFields?: EntityDefinition["derivedFields"];
 }): F extends FieldsMap ? EntityDefinition<F> : never {

package/src/engine/feature-entity-handlers.ts

@@ -1,6 +1,8 @@
+import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handlers";
 import type { ZodType, z } from "zod";
 import { toTableName } from "../db/table-builder";
 import {
+  isEntityConventionQueryHandler,
   isPagedQueryHandler,
   PAGED_QUERY_HANDLER_BRAND,
   type QueryHandlerDefinition,
@@ -184,6 +186,9 @@ export function buildEntityHandlerMethods<TName extends string>(
           // Carry the definePagedQueryHandler brand through — this rebuild
           // drops any field not explicitly listed.
           ...(isPagedQueryHandler(def) && { [PAGED_QUERY_HANDLER_BRAND]: true }),
+          ...(isEntityConventionQueryHandler(def) && {
+            [ENTITY_CONVENTION_QUERY_BRAND]: true as const,
+          }),
         };
         tryMapEntity(state, name, def.name);
         return { name: def.name };

package/src/engine/index.ts

@@ -221,6 +221,7 @@ export {
 export type { OwnershipClause, OwnershipMap, OwnershipRef, OwnershipRule } from "./ownership";
 export {
   buildOwnershipClause,
+  combineClauses,
   from,
   normalizeAccessEntry,
   userCanCreateFieldRow,
@@ -411,6 +412,7 @@ export type {
   NotifyPriority,
   NumberFieldDef,
   OnDeleteStrategy,
+  ParentRefDef,
   PersonalAnnotations,
   PersonalAnnotationsLongText,
   PersonalAnnotationsNoFind,
@@ -447,6 +449,10 @@ export type {
   ScreenNavSugar,
   ScreenSlots,
   SecretKeyHandle,
+  SecretMintConfirmStep,
+  SecretMintScreenDefinition,
+  SecretReveal,
+  SecretRevealField,
   SecretsEditScreenDefinition,
   SecretsEditSection,
   SelectFieldDef,

package/src/engine/ownership.ts

@@ -336,6 +336,21 @@ export function buildOwnershipClause(
   return { kind: "sql", sqlText: `(${sqlText})`, params };
 }
 
+// AND-combine two independently built read clauses. Both are built at
+// paramStart=1; `b`'s placeholders are shifted past `a`'s params so the
+// concatenated fragment binds positionally.
+export function combineClauses(a: OwnershipClause, b: OwnershipClause): OwnershipClause {
+  if (a.kind === "empty" || b.kind === "empty") return { kind: "empty" };
+  if (a.kind === "pass") return b;
+  if (b.kind === "pass") return a;
+  const shifted = shiftParams({ sqlText: b.sqlText, params: b.params }, a.params.length);
+  return {
+    kind: "sql",
+    sqlText: `(${a.sqlText} AND ${shifted.sqlText})`,
+    params: [...a.params, ...shifted.params],
+  };
+}
+
 type RuleFragmentResult =
   | { readonly kind: "empty" }
   | { readonly kind: "sql"; readonly sqlText: string; readonly params: readonly unknown[] };

package/src/engine/pattern-library/mixed-schemas.ts

@@ -26,6 +26,7 @@ export const screenSchema: PatternFormSchema = {
         { value: "entityList", label: { en: "Entity list" } },
         { value: "entityEdit", label: { en: "Entity edit" } },
         { value: "actionForm", label: { en: "Action form" } },
+        { value: "secretMint", label: { en: "Secret mint" } },
         { value: "custom", label: { en: "Custom" } },
       ],
       required: true,