@cosmicdrift/kumiko-framework 0.249.0 → 0.251.0

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

@@ -121,3 +121,45 @@ export function validateProjectionListScreens(features: readonly FeatureDefiniti
     }
   }
 }
+
+// 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
+// undeclared param would fail every query instead of failing at boot.
+// Reachable on projectionDetail only (screens.ts rejects relatedList
+// elsewhere), but the layout walk stays uniform so lifting that restriction
+// doesn't quietly skip these checks.
+export function validateRelatedListSectionQueries(features: readonly FeatureDefinition[]): void {
+  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;
+      }
+      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.`,
+          );
+        }
+      }
+    }
+  }
+}

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

@@ -25,6 +25,8 @@ import type {
   EditFieldSpec,
   EditLayout,
   FieldCondition,
+  ListColumnSpec,
+  ListFacetSpec,
   RowAction,
   RowActionNavigateBase,
   RowFieldExtractor,
@@ -559,37 +561,12 @@ export function validateScreens(
             `filter.value to be a readonly array.`,
         );
       }
-      // Facets (fw#2224) — unlike filter, a field inventory IS available
-      // here: the declared columns. A facet on a field with no column is
-      // almost always a typo (the user never sees the field anywhere), so
-      // this is hard-checked rather than just documented.
       if (screen.facets !== undefined) {
-        const columnFieldNames = new Set(
-          screen.columns.map((col) => normalizeListColumn(col).field),
+        validateListFacets(
+          `[Feature ${feature.name}] Screen "${screenId}" (projectionList)`,
+          screen.facets,
+          screen.columns,
         );
-        const seenFacetFields = new Set<string>();
-        for (const facet of screen.facets) {
-          if (seenFacetFields.has(facet.field)) {
-            throw new Error(
-              `[Feature ${feature.name}] Screen "${screenId}" (projectionList) declares facet ` +
-                `"${facet.field}" more than once.`,
-            );
-          }
-          seenFacetFields.add(facet.field);
-          if (!columnFieldNames.has(facet.field)) {
-            throw new Error(
-              `[Feature ${feature.name}] Screen "${screenId}" (projectionList) facet references field ` +
-                `"${facet.field}" which is not a declared column. Known columns: ` +
-                `${[...columnFieldNames].sort().join(", ")}`,
-            );
-          }
-          if (facet.type === "select" && facet.options.length === 0) {
-            throw new Error(
-              `[Feature ${feature.name}] Screen "${screenId}" (projectionList) facet "${facet.field}" ` +
-                `(type "select") has an empty options list — declare at least one option.`,
-            );
-          }
-        }
       }
       if (screen.rowActions !== undefined) {
         for (const action of screen.rowActions) {
@@ -863,6 +840,13 @@ export function validateScreens(
               );
             }
           }
+          if (section.facets !== undefined) {
+            validateListFacets(
+              `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) relatedList section "${section.title}"`,
+              section.facets,
+              section.columns,
+            );
+          }
           continue;
         }
         if (isWriteFormEditSection(section)) {
@@ -1805,6 +1789,38 @@ export function validateColumnRendererForm(
   }
 }
 
+// Facets (fw#2224) — unlike filter, a field inventory IS available here: the
+// declared columns. A facet on a field with no column is almost always a
+// typo (the user never sees the field anywhere), so this is hard-checked
+// rather than just documented. Shared by projectionList and relatedList
+// (fw#2740) — `prefix` carries the caller's own screen/section message lead-in.
+function validateListFacets(
+  prefix: string,
+  facets: readonly ListFacetSpec[],
+  columns: readonly ListColumnSpec[],
+): void {
+  const columnFieldNames = new Set(columns.map((col) => normalizeListColumn(col).field));
+  const seenFacetFields = new Set<string>();
+  for (const facet of facets) {
+    if (seenFacetFields.has(facet.field)) {
+      throw new Error(`${prefix} declares facet "${facet.field}" more than once.`);
+    }
+    seenFacetFields.add(facet.field);
+    if (!columnFieldNames.has(facet.field)) {
+      throw new Error(
+        `${prefix} facet references field "${facet.field}" which is not a declared column. ` +
+          `Known columns: ${[...columnFieldNames].sort().join(", ")}`,
+      );
+    }
+    if (facet.type === "select" && facet.options.length === 0) {
+      throw new Error(
+        `${prefix} facet "${facet.field}" (type "select") has an empty options list — ` +
+          `declare at least one option.`,
+      );
+    }
+  }
+}
+
 export function findEntityFeature(
   entityName: string,
   featureMap: ReadonlyMap<string, FeatureDefinition>,

package/src/engine/entity-handlers.ts

@@ -384,6 +384,10 @@ export function defineEntityQueryHandler(
             fields: ctx.registry.getSearchableReferences(entityName),
             resolveEntity: (name) => ctx.registry.getEntity(name),
           },
+          referenceSort: {
+            fields: ctx.registry.getSortableReferences(entityName),
+            resolveEntity: (name) => ctx.registry.getEntity(name),
+          },
         });
         const enrichedRows = hasRefFields
           ? await enrichWithReferences(

package/src/engine/feature-ast/__tests__/canonical-form.test.ts

@@ -56,6 +56,7 @@ defineFeature("todoList", (r) => {
   r.defineEvent({
     name: "taskCompleted",
     schema: z.object({ id: z.string() }),
+    piiFields: "none",
     version: 2,
     migrations: {
       "1": (old) => ({ ...old, done: true }),

package/src/engine/feature-ast/__tests__/parse-happy-path.test.ts

@@ -42,7 +42,7 @@ defineFeature("todoList", (r) => {
     },
   });
 
-  r.defineEvent("taskCompleted", z.object({ id: z.string() }), { version: 1 });
+  r.defineEvent("taskCompleted", z.object({ id: z.string() }), { piiFields: "none", version: 1 });
 
   r.writeHandler(
     "task:create",

package/src/engine/feature-ast/__tests__/parse.test.ts

@@ -2224,7 +2224,7 @@ describe("extractDefineEvent", () => {
   test("captures eventName + version", () => {
     const result = parseInline(`
 defineFeature("f", (r) => {
-  r.defineEvent("incidentOpened", z.object({ id: z.string() }), { version: 2 });
+  r.defineEvent("incidentOpened", z.object({ id: z.string() }), { piiFields: "none", version: 2 });
 });
 `);
 
@@ -2241,6 +2241,7 @@ defineFeature("f", (r) => {
   r.defineEvent({
     name: "incidentOpened",
     schema: z.object({ id: z.string() }),
+    piiFields: "none",
     version: 2,
     migrations: { "1": (payload) => payload },
   });
@@ -2285,6 +2286,17 @@ defineFeature("f", (r) => {
     expect(result.errors[0]?.methodName).toBe("defineEvent");
   });
 
+  test("emits ParseError when object form is missing the piiFields property", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.defineEvent({ name: "incidentOpened", schema: z.object({ id: z.string() }) });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("defineEvent");
+    expect(result.errors[0]?.reason).toContain("piiFields");
+  });
+
   test("emits ParseError when the event name is not a string literal", () => {
     const result = parseInline(`
 defineFeature("f", (r) => {
@@ -2304,6 +2316,17 @@ defineFeature("f", (r) => {
 
     expect(result.errors[0]?.methodName).toBe("defineEvent");
   });
+
+  test("emits ParseError when the positional form is missing the piiFields option", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.defineEvent("incidentOpened", z.object({ id: z.string() }), { version: 2 });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("defineEvent");
+    expect(result.errors[0]?.reason).toContain("piiFields");
+  });
 });
 
 describe("extractDefineEvent — migrations (formerly extractEventMigration)", () => {
@@ -2311,6 +2334,7 @@ describe("extractDefineEvent — migrations (formerly extractEventMigration)", (
     const result = parseInline(`
 defineFeature("f", (r) => {
   r.defineEvent("incidentOpened", z.object({ id: z.string() }), {
+    piiFields: "none",
     version: 2,
     migrations: [
       { fromVersion: 1, toVersion: 2, transform: (payload) => ({ ...payload, severity: "low" }) },
@@ -2333,6 +2357,7 @@ defineFeature("f", (r) => {
   r.defineEvent({
     name: "incidentOpened",
     schema: z.object({ id: z.string() }),
+    piiFields: "none",
     version: 2,
     migrations: {
       "1": (payload) => ({ ...payload, severity: "low" }),
@@ -2353,6 +2378,7 @@ defineFeature("f", (r) => {
     const result = parseInline(`
 defineFeature("f", (r) => {
   r.defineEvent("incidentOpened", z.object({ id: z.string() }), {
+    piiFields: "none",
     migrations: [
       "skip-me",
       { fromVersion: "bad", transform: (payload) => payload },

package/src/engine/feature-ast/__tests__/patch.test.ts

@@ -307,6 +307,7 @@ describe("patch coverage for the remaining pattern-kinds", () => {
     createFeaturePatcher(sf).addDefineEvent({
       name: "itemCreated",
       schemaSource: "z.object({ id: z.string() })",
+      piiFieldsSource: '"none"',
       version: 2,
       migrations: { "1": "(old) => old" },
     });

package/src/engine/feature-ast/__tests__/patcher.test.ts

@@ -178,6 +178,7 @@ describe("FeaturePatcher — typed add helpers for mixed (closure-bearing) patte
     p.addDefineEvent({
       name: "stepCompleted",
       schemaSource: "z.object({ id: z.string() })",
+      piiFieldsSource: '"none"',
       version: 2,
       migrations: { "1": '(old) => ({ id: old.id ?? "" })' },
     });

package/src/engine/feature-ast/__tests__/render-roundtrip.test.ts

@@ -86,6 +86,7 @@ function parse(source: string): {
 //     to match the new context.
 const BODY_LOC_KEYS = new Set([
   "schemaSource",
+  "piiFields",
   "handlerBody",
   "fnBody",
   "transformBody",
@@ -228,7 +229,7 @@ defineFeature("workflow", (r) => {
     console.log("step deleted");
   });
 
-  r.defineEvent("stepCompleted", z.object({ id: z.string() }), { version: 1 });
+  r.defineEvent("stepCompleted", z.object({ id: z.string() }), { piiFields: "none", version: 1 });
 
   r.nav({ id: "steps", label: "Steps", screen: "workflow:screen:step-list" });
 });
@@ -458,8 +459,18 @@ describe("renderPattern — single-pattern shape", () => {
         end: { line: 1, column: 1 },
         raw: "z.object({})",
       },
+      piiFields: {
+        file: "x",
+        start: { line: 1, column: 1 },
+        end: { line: 1, column: 1 },
+        raw: '"none"',
+      },
     });
-    expect(out).toBe("r.defineEvent(DOC_INGESTED_EVENT, z.object({}));");
+    expect(out).toBe(
+      ["r.defineEvent(DOC_INGESTED_EVENT, z.object({}), {", '  piiFields: "none",', "});"].join(
+        "\n",
+      ),
+    );
   });
 });
 
@@ -479,7 +490,7 @@ const DOC_INGESTED_EVENT = "docIngested" as const;
 defineFeature("user-data-rights", (r) => {
   r.extendsRegistrar(EXT_TENANT_DATA, { onRegister: () => {} });
   r.useExtension(EXT_TENANT_DATA, "document", { description: "org-scoped" });
-  r.defineEvent(DOC_INGESTED_EVENT, z.object({ id: z.string() }));
+  r.defineEvent(DOC_INGESTED_EVENT, z.object({ id: z.string() }), { piiFields: "none" });
 });
 `;
 
@@ -625,6 +636,7 @@ import { z } from "zod";
 
 defineFeature("billing", (r) => {
   r.defineEvent("invoicePaid", z.object({ totalCents: z.number() }), {
+    piiFields: "none",
     version: 2,
     migrations: [
       {
@@ -656,6 +668,47 @@ describe("render → parse roundtrip — r.defineEvent({ migrations }) fold", ()
   });
 });
 
+const DEFINE_EVENT_WITH_PII_FIELDS_FEATURE = `
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+defineFeature("mailer", (r) => {
+  r.defineEvent("attempt", z.object({ recipientId: z.string(), recipientAddress: z.string() }), {
+    piiFields: { recipientAddress: { subjectField: "recipientId" } },
+  });
+});
+`;
+
+describe("render → parse roundtrip — r.defineEvent piiFields stance (fw#2558)", () => {
+  test('piiFields: "none" survives parse → render → parse unchanged', () => {
+    const initial = parse(DEFINE_EVENT_WITH_MIGRATIONS_FEATURE);
+    const rendered = renderFeatureFile({
+      featureName: initial.featureName ?? "",
+      patterns: initial.patterns,
+    });
+    expect(rendered).toContain('piiFields: "none",');
+    const reparsed = parse(rendered);
+    expect(reparsed.patterns.map(stripLocations)).toEqual(initial.patterns.map(stripLocations));
+  });
+
+  test("an object-literal piiFields stance survives parse → render → parse unchanged", () => {
+    const initial = parse(DEFINE_EVENT_WITH_PII_FIELDS_FEATURE);
+    const rendered = renderFeatureFile({
+      featureName: initial.featureName ?? "",
+      patterns: initial.patterns,
+    });
+    expect(rendered).toContain('piiFields: { recipientAddress: { subjectField: "recipientId" } }');
+    const reparsed = parse(rendered);
+    expect(reparsed.patterns.map(stripLocations)).toEqual(initial.patterns.map(stripLocations));
+
+    const eventPattern = reparsed.patterns.find((p) => p.kind === "defineEvent");
+    expect(eventPattern?.kind).toBe("defineEvent");
+    if (eventPattern?.kind === "defineEvent") {
+      expect(eventPattern.piiFields.raw).toContain("recipientAddress");
+    }
+  });
+});
+
 // --- Real-compile check ---------------------------------------------------
 //
 // Everything above proves parse(render(patterns)) is structurally faithful.

package/src/engine/feature-ast/extractors/events.ts

@@ -131,6 +131,17 @@ export function extractDefineEvent(
       const v = readDataLiteralNode(versionInit);
       if (typeof v === "number") version = v;
     }
+    const piiFieldsInit = obj
+      .getProperty("piiFields")
+      ?.asKind(SyntaxKind.PropertyAssignment)
+      ?.getInitializer();
+    if (!piiFieldsInit) {
+      return fail(
+        "defineEvent",
+        sourceLocationFromNode(call, sourceFile),
+        'requires an explicit `piiFields` stance (an object literal or "none")',
+      );
+    }
     const migrationsInit = obj
       .getProperty("migrations")
       ?.asKind(SyntaxKind.PropertyAssignment)
@@ -143,6 +154,7 @@ export function extractDefineEvent(
       source: sourceLocationFromNode(call, sourceFile),
       eventName: nameInit.getLiteralValue(),
       schemaSource: sourceLocationFromNode(schemaInit, sourceFile),
+      piiFields: sourceLocationFromNode(piiFieldsInit, sourceFile),
       ...(version !== undefined && { version }),
       ...(migrations !== undefined && { migrations }),
     });
@@ -168,6 +180,17 @@ export function extractDefineEvent(
   let migrations: Readonly<Record<string, SourceLocation>> | undefined;
   const optionsArg = args[2];
   const optionsObj = optionsArg?.asKind(SyntaxKind.ObjectLiteralExpression);
+  const piiFieldsInit = optionsObj
+    ?.getProperty("piiFields")
+    ?.asKind(SyntaxKind.PropertyAssignment)
+    ?.getInitializer();
+  if (!piiFieldsInit) {
+    return fail(
+      "defineEvent",
+      sourceLocationFromNode(call, sourceFile),
+      'requires an explicit `piiFields` stance (an object literal or "none")',
+    );
+  }
   if (optionsObj) {
     const versionInit = optionsObj
       .getProperty("version")
@@ -191,6 +214,7 @@ export function extractDefineEvent(
     eventName: eventNameRef.value,
     ...(eventNameRef.raw !== undefined && { eventNameRaw: eventNameRef.raw }),
     schemaSource: sourceLocationFromNode(schemaArg, sourceFile),
+    piiFields: sourceLocationFromNode(piiFieldsInit, sourceFile),
     ...(version !== undefined && { version }),
     ...(migrations !== undefined && { migrations }),
   });

package/src/engine/feature-ast/patcher.ts

@@ -147,6 +147,10 @@ export type AddHttpRouteArgs = {
 export type AddDefineEventArgs = {
   readonly name: string;
   readonly schemaSource: string;
+  // Raw source of the `piiFields` option value (e.g. `'"none"'` or an object
+  // literal) — mandatory, mirroring r.defineEvent's own required stance
+  // (fw#2558).
+  readonly piiFieldsSource: string;
   readonly version?: number;
   // Keyed by fromVersion (as a string) → the transform source text for the
   // fromVersion -> fromVersion+1 step. Folded in from the former
@@ -496,7 +500,7 @@ export function createFeaturePatcher(sourceFile: SourceFile): FeaturePatcher {
       });
     },
 
-    addDefineEvent({ name, schemaSource, version, migrations }) {
+    addDefineEvent({ name, schemaSource, piiFieldsSource, version, migrations }) {
       const migrationLocs = migrations
         ? Object.fromEntries(
             Object.entries(migrations).map(([fromVersion, source]) => [
@@ -510,6 +514,7 @@ export function createFeaturePatcher(sourceFile: SourceFile): FeaturePatcher {
         source: SYNTHETIC_LOC,
         eventName: name,
         schemaSource: rawLoc(schemaSource),
+        piiFields: rawLoc(piiFieldsSource),
         ...(version !== undefined && { version }),
         ...(migrationLocs !== undefined && { migrations: migrationLocs }),
       });

package/src/engine/feature-ast/patterns.ts

@@ -561,6 +561,12 @@ export type DefineEventPattern = {
   readonly eventNameRaw?: string;
   readonly schemaSource: SourceLocation;
   readonly version?: number;
+  // Raw source of the `piiFields` option value ("none", an object literal,
+  // or a constant reference) — mandatory because `r.defineEvent` itself
+  // requires an explicit PII stance (fw#2558); round-tripping it verbatim
+  // avoids the extractor ever having to invent a stance the author didn't
+  // author.
+  readonly piiFields: SourceLocation;
   // Map fromVersion (as string, e.g. "1") → SourceLocation of the transform
   // closure for the fromVersion → fromVersion+1 step.
   readonly migrations?: Readonly<Record<string, SourceLocation>>;

package/src/engine/feature-ast/render.ts

@@ -596,11 +596,10 @@ function renderMultiStreamProjection(p: MultiStreamProjectionPattern): string {
 function renderDefineEvent(p: DefineEventPattern): string {
   const nameLiteral = p.eventNameRaw ?? JSON.stringify(p.eventName);
   const migrationEntries = p.migrations !== undefined ? Object.entries(p.migrations) : [];
-  const hasOptions = p.version !== undefined || migrationEntries.length > 0;
-  if (!hasOptions) {
-    return `r.defineEvent(${nameLiteral}, ${p.schemaSource.raw});`;
-  }
+  // piiFields is a mandatory option (fw#2558) — the options object is
+  // always rendered, unlike the old version/migrations-only shortcut.
   const lines: string[] = [`r.defineEvent(${nameLiteral}, ${p.schemaSource.raw}, {`];
+  lines.push(`  piiFields: ${p.piiFields.raw},`);
   if (p.version !== undefined) lines.push(`  version: ${p.version},`);
   if (migrationEntries.length > 0) {
     lines.push("  migrations: [");

package/src/engine/feature-config-events-jobs.ts

@@ -14,6 +14,7 @@ import type {
   DeclarativeEventMigration,
   EventDef,
   EventPiiFields,
+  EventPiiStance,
   EventUpcastFn,
   JobDefinition,
   JobHandlerFn,
@@ -217,9 +218,9 @@ export function buildConfigEventsJobsMethods<TName extends string>(
     defineEvent: <const TInner extends string, TPayload>(
       eventName: TInner,
       schema: ZodType<TPayload>,
-      options?: {
+      options: {
         readonly version?: number;
-        readonly piiFields?: EventPiiFields;
+        readonly piiFields: EventPiiStance;
         // Step-wise upcast chain for this event, folded in from the former
         // standalone r.eventMigration() call (#1082 step 8) — an event and
         // its schema evolution are one lifecycle, not two registrar
@@ -232,6 +233,33 @@ export function buildConfigEventsJobsMethods<TName extends string>(
         }[];
       },
     ): EventDef<TPayload, QualifiedEventName<TName, TInner>> => {
+      // Fail-closed PII stance gate (fw#2558) — runs before anything else so
+      // an untyped JS consumer (no compiler to stop it) still can't register
+      // an event without declaring whether its payload carries personal data.
+      const missingStanceError = () =>
+        new Error(
+          `[Feature ${name}] defineEvent("${eventName}") must declare an explicit PII stance. Pass { piiFields: { <payloadField>: { subjectField: "<userIdField>" } } } for payload fields holding personal data, or { piiFields: "none" } when the payload holds none.`,
+        );
+      if (options === undefined || options.piiFields === undefined) {
+        throw missingStanceError();
+      }
+      const piiFields = options.piiFields;
+      // @cast-boundary runtime-guard — an untyped JS caller can hand
+      // anything through `piiFields` (including null), so re-check the
+      // shape before trusting it as EventPiiStance: `typeof null === "object"`
+      // would otherwise pass through to Object.keys(null) below and throw a
+      // raw TypeError instead of this guidance message.
+      if (piiFields !== "none" && (typeof piiFields !== "object" || piiFields === null)) {
+        throw missingStanceError();
+      }
+      if (piiFields !== "none" && Object.keys(piiFields).length === 0) {
+        throw new Error(
+          `[Feature ${name}] defineEvent("${eventName}"): piiFields: {} is not a stance — use piiFields: "none" to declare the payload holds no personal data.`,
+        );
+      }
+      if (piiFields !== "none") {
+        validateEventPiiFields(eventName, schema, piiFields);
+      }
       // Return the fully-qualified event name so callers can pass it
       // straight to ctx.appendEvent without hand-building the
       // "<feature>:event:<name>" shape. Registry keeps events keyed by
@@ -243,16 +271,12 @@ export function buildConfigEventsJobsMethods<TName extends string>(
       // returned `name` carries the literal qualified shape that the
       // augmented `KumikoEventTypeMap` keys against.
       const qualified = qn(toKebab(name), "event", toKebab(eventName));
-      const version = options?.version ?? 1;
+      const version = options.version ?? 1;
       if (!Number.isInteger(version) || version < 1) {
         throw new Error(
           `[Feature ${name}] defineEvent("${eventName}"): version must be a positive integer, got ${String(version)}`,
         );
       }
-      const piiFields = options?.piiFields;
-      if (piiFields) {
-        validateEventPiiFields(eventName, schema, piiFields);
-      }
       // @cast-boundary engine-bridge — runtime-string mirrors the
       // template-literal-type via QualifiedEventName + toKebab. Both
       // sides are tested (CamelToKebab type-tests + scan-events kebab
@@ -261,10 +285,10 @@ export function buildConfigEventsJobsMethods<TName extends string>(
         name: qualified as QualifiedEventName<TName, TInner>,
         schema,
         version,
-        ...(piiFields !== undefined && { piiFields }),
+        piiFields,
       };
       state.events[eventName] = def;
-      for (const m of options?.migrations ?? []) {
+      for (const m of options.migrations ?? []) {
         registerEventMigration(eventName, m.fromVersion, m.toVersion, m.transform);
       }
       return def;

package/src/engine/pattern-library/__tests__/library.test.ts

@@ -333,6 +333,7 @@ function makePlaceholderPattern(kind: FeaturePatternKind): FeaturePattern {
         source: PLACEHOLDER_LOC,
         eventName: "x",
         schemaSource: PLACEHOLDER_BODY_LOC,
+        piiFields: PLACEHOLDER_BODY_LOC,
       };
     case "extendsRegistrar":
       return {

package/src/engine/registry-facade.ts

@@ -1,4 +1,9 @@
-import type { IncomingRelation, RegistryState, SearchableReferenceField } from "./registry-state";
+import type {
+  IncomingRelation,
+  RegistryState,
+  SearchableReferenceField,
+  SortableReferenceField,
+} from "./registry-state";
 import { filterByPhase, filterOwned } from "./registry-state";
 import type {
   AuthClaimsHookDef,
@@ -101,6 +106,10 @@ export function buildRegistryFacade(state: RegistryState): Registry {
       return state.searchableReferencesCache.get(entityName) ?? [];
     },
 
+    getSortableReferences(entityName: string): readonly SortableReferenceField[] {
+      return state.sortableReferencesCache.get(entityName) ?? [];
+    },
+
     getIncomingRelations(entityName: string): readonly IncomingRelation[] {
       return state.incomingRelationsCache.get(entityName) ?? [];
     },

package/src/engine/registry-state.ts

@@ -60,6 +60,12 @@ export type SearchableReferenceField = {
   readonly labelField: string;
 };
 
+// One entry per `ReferenceFieldDef` with `sortable: true` (fw#2741). Same
+// resolved shape as the searchable variant and the same boot guarantee on
+// `labelField` — ORDER BY on the UUID column would look meaningful and be
+// arbitrary.
+export type SortableReferenceField = SearchableReferenceField;
+
 const IMPLICIT_PROJECTION_SUFFIX = "-entity" as const;
 
 // Pro r.entity-Registration eine ImplicitProjection mit auto-generierten
@@ -235,6 +241,7 @@ export type RegistryState = {
   searchableFieldsCache: Map<string, readonly string[]>;
   sortableFieldsCache: Map<string, readonly string[]>;
   searchableReferencesCache: Map<string, readonly SearchableReferenceField[]>;
+  sortableReferencesCache: Map<string, readonly SortableReferenceField[]>;
   incomingRelationsCache: Map<string, IncomingRelation[]>;
   hasRateLimitedHandlerCached: boolean;
 };
@@ -298,6 +305,7 @@ export function createInitialState(): RegistryState {
     searchableFieldsCache: new Map(),
     sortableFieldsCache: new Map(),
     searchableReferencesCache: new Map(),
+    sortableReferencesCache: new Map(),
     incomingRelationsCache: new Map(),
     hasRateLimitedHandlerCached: false,
   };