@cosmicdrift/kumiko-framework 0.249.0 → 0.250.0

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,
   };

package/src/engine/registry-validate.ts

@@ -1,6 +1,10 @@
 import { configureEventPiiCatalog } from "../crypto/event-pii";
 import { resolveName } from "./handler-helpers";
-import type { RegistryState, SearchableReferenceField } from "./registry-state";
+import type {
+  RegistryState,
+  SearchableReferenceField,
+  SortableReferenceField,
+} from "./registry-state";
 import { buildImplicitProjection, hasFieldAccessRules, qualify } from "./registry-state";
 import {
   buildSoftDeleteCleanupJob,
@@ -192,12 +196,43 @@ function buildSearchableReferenceField(
   };
 }
 
-// Precompute: searchable/sortable fields, searchable reference fields.
+// fw#2741: ORDER BY runs against the referenced row's label column, so the
+// same explicit-labelField requirement as searchable applies — ordering by the
+// "id" default would be a UUID order that looks deliberate to the user.
+function buildSortableReferenceField(
+  entityName: string,
+  fieldName: string,
+  field: ReferenceFieldDef,
+): SortableReferenceField {
+  if (field.labelField === undefined || field.labelField === "id") {
+    throw new Error(
+      `[Entity ${entityName}] field "${fieldName}": sortable reference fields require an ` +
+        `explicit, non-"id" labelField. Ordering by "id" is a UUID order — arbitrary to the ` +
+        `user while looking deliberate. Set labelField to a human-readable field on the ` +
+        `referenced entity.`,
+    );
+  }
+  if (field.multiple === true) {
+    throw new Error(
+      `[Entity ${entityName}] field "${fieldName}": sortable is not supported on multiple ` +
+        `(array) reference fields — there is no single label to order by; remove "multiple" ` +
+        `or "sortable".`,
+    );
+  }
+  return {
+    fieldName,
+    targetEntityName: parseReferenceTargetEntityName(field.entity),
+    labelField: field.labelField,
+  };
+}
+
+// Precompute: searchable/sortable fields, searchable + sortable reference fields.
 export function buildSearchableSortableCaches(state: RegistryState): void {
   for (const [name, entity] of state.entityMap) {
     const searchable: string[] = [];
     const sortable: string[] = [];
     const searchableReferences: SearchableReferenceField[] = [];
+    const sortableReferences: SortableReferenceField[] = [];
     for (const [fieldName, field] of Object.entries(entity.fields)) {
       if (field.type === "text" && field.searchable === true) searchable.push(fieldName);
       if (field.type === "text" && field.sortable === true) sortable.push(fieldName);
@@ -209,10 +244,14 @@ export function buildSearchableSortableCaches(state: RegistryState): void {
       if (field.type === "reference" && field.searchable === true) {
         searchableReferences.push(buildSearchableReferenceField(name, fieldName, field));
       }
+      if (field.type === "reference" && field.sortable === true) {
+        sortableReferences.push(buildSortableReferenceField(name, fieldName, field));
+      }
     }
     state.searchableFieldsCache.set(name, searchable);
     state.sortableFieldsCache.set(name, sortable);
     state.searchableReferencesCache.set(name, searchableReferences);
+    state.sortableReferencesCache.set(name, sortableReferences);
   }
 }
 
@@ -664,9 +703,21 @@ export function publishEventPiiCatalog(state: RegistryState): void {
   // into kumiko_events — encrypts catalogued payload fields regardless of
   // which path produced the event (ctx.appendEvent, MSP-apply, low-level
   // append in delivery/jobs loggers).
+  //
+  // Defense-in-depth (fw#2558): defineEvent is the only producer of
+  // EventDef.piiFields and already fails closed without a stance, but this
+  // boot gate re-checks every registered event — a future producer that
+  // forgets to run through defineEvent would otherwise leave a hole where
+  // append() silently ships plaintext instead of refusing to boot.
   const eventPiiCatalog = new Map<string, EventPiiFields>();
   for (const [qualified, def] of state.eventMap) {
-    if (def.piiFields) eventPiiCatalog.set(qualified, def.piiFields);
+    if (def.piiFields === undefined) {
+      throw new Error(
+        `Registered event "${qualified}" has no PII stance. Every r.defineEvent(...) call must pass { piiFields: { ... } } or { piiFields: "none" }.`,
+      );
+    }
+    if (def.piiFields === "none") continue;
+    eventPiiCatalog.set(qualified, def.piiFields);
   }
   configureEventPiiCatalog(eventPiiCatalog);
 }

package/src/engine/types/index.ts

@@ -158,6 +158,7 @@ export type {
   EventDef,
   EventMigrationDef,
   EventPiiFields,
+  EventPiiStance,
   EventUpcastCtx,
   EventUpcastFn,
   FetchForWritingArgs,

package/src/entrypoint/__tests__/entrypoint-attach-dispatcher.integration.test.ts

@@ -25,7 +25,10 @@ const writeProbeResults: Array<{ isSuccess: boolean }> = [];
 const writeProbeFailures: string[] = [];
 
 const writeProbeFeature = defineFeature("writeProbe", (r) => {
-  const noted = r.defineEvent("noted", z.object({ note: z.string() }), { version: 1 });
+  const noted = r.defineEvent("noted", z.object({ note: z.string() }), {
+    piiFields: "none",
+    version: 1,
+  });
   r.writeHandler(
     "note",
     z.object({ note: z.string() }),

package/src/entrypoint/__tests__/split-deploy.integration.test.ts

@@ -23,7 +23,10 @@ import { createTestRedis, type TestRedis, TestUsers } from "../../stack";
 import { createAllInOneEntrypoint, createApiEntrypoint, createWorkerEntrypoint } from "../index";
 
 const splitFeature = defineFeature("split", (r) => {
-  const tick = r.defineEvent("tick", z.object({ note: z.string() }), { version: 1 });
+  const tick = r.defineEvent("tick", z.object({ note: z.string() }), {
+    piiFields: "none",
+    version: 1,
+  });
   r.multiStreamProjection({
     name: "spy",
     apply: {
@@ -38,7 +41,10 @@ const splitFeature = defineFeature("split", (r) => {
 const consumedNotes: string[] = [];
 
 const workerWriteFeature = defineFeature("workerWrite", (r) => {
-  const noted = r.defineEvent("noted", z.object({ note: z.string() }), { version: 1 });
+  const noted = r.defineEvent("noted", z.object({ note: z.string() }), {
+    piiFields: "none",
+    version: 1,
+  });
   r.writeHandler(
     "note",
     z.object({ note: z.string() }),
@@ -76,6 +82,7 @@ const jobSawFilesRef: string[] = [];
 
 const fileJobFeature = defineFeature("fileJob", (r) => {
   const requested = r.defineEvent("bytes-requested", z.object({ storageKey: z.string() }), {
+    piiFields: "none",
     version: 1,
   });
   // Stands in for file-foundation, which this package cannot import.
@@ -310,7 +317,7 @@ describe("entrypoint factories", () => {
 // process's lane are skipped during buildServer()".
 
 const laneFeature = defineFeature("lane", (r) => {
-  const ping = r.defineEvent("ping", z.object({}), { version: 1 });
+  const ping = r.defineEvent("ping", z.object({}), { piiFields: "none", version: 1 });
   // Three MSPs: one pinned to api, one to worker (explicit), one to both.
   // A fourth would be a default-undefined-runIn MSP which resolves to
   // "worker" — covered implicitly by the worker test below.

package/src/event-store/__tests__/upcaster.integration.test.ts

@@ -57,6 +57,7 @@ const orderFeature = defineFeature("upcastshop", (r) => {
     "priced",
     z.object({ totalCents: z.number().int(), currency: z.string() }),
     {
+      piiFields: "none",
       version: 3,
       migrations: [
         // v1 → v2: renamed totalEuros → total (kept as string for this step)
@@ -321,6 +322,7 @@ describe("upcaster: async (Marten AsyncOnlyEventUpcaster — DB-Lookups)", () =>
         "placed",
         z.object({ customerId: z.string(), segment: z.string() }),
         {
+          piiFields: "none",
           version: 2,
           migrations: [
             {
@@ -407,6 +409,7 @@ describe("upcaster: boot-time validation", () => {
       r.entity("hole-order", orderEntity);
       // Only 1→2 registered — the 2→3 gap must be rejected.
       r.defineEvent("bad", z.object({ v3: z.string() }), {
+        piiFields: "none",
         version: 3,
         migrations: [{ fromVersion: 1, toVersion: 2, transform: (p) => p }],
       });
@@ -424,6 +427,7 @@ describe("upcaster: boot-time validation", () => {
     const future = defineFeature("future", (r) => {
       r.entity("future-order", orderEntity);
       r.defineEvent("early", z.object({ x: z.number() }), {
+        piiFields: "none",
         version: 1,
         migrations: [{ fromVersion: 1, toVersion: 2, transform: (p) => p }],
       });
@@ -435,6 +439,7 @@ describe("upcaster: boot-time validation", () => {
     const gaps = defineFeature("gaps", (r) => {
       r.entity("gap-order", orderEntity);
       r.defineEvent("jumpy", z.object({ v: z.number() }), {
+        piiFields: "none",
         version: 4,
         migrations: [
           { fromVersion: 1, toVersion: 2, transform: (p) => p },
@@ -452,6 +457,7 @@ describe("upcaster: registrar input validation", () => {
       defineFeature("bigstep", (r) => {
         r.entity("bigstep-order", orderEntity);
         r.defineEvent("biz", z.object({ x: z.number() }), {
+          piiFields: "none",
           version: 3,
           migrations: [{ fromVersion: 1, toVersion: 3, transform: (p) => p }],
         });
@@ -464,6 +470,7 @@ describe("upcaster: registrar input validation", () => {
       defineFeature("dupestep", (r) => {
         r.entity("dup-order", orderEntity);
         r.defineEvent("dup", z.object({ x: z.number() }), {
+          piiFields: "none",
           version: 2,
           migrations: [
             { fromVersion: 1, toVersion: 2, transform: (p) => p },
@@ -478,7 +485,7 @@ describe("upcaster: registrar input validation", () => {
     expect(() =>
       defineFeature("badver", (r) => {
         r.entity("badver-order", orderEntity);
-        r.defineEvent("neg", z.object({ x: z.number() }), { version: 0 });
+        r.defineEvent("neg", z.object({ x: z.number() }), { piiFields: "none", version: 0 });
       }),
     ).toThrow(/positive integer/);
   });