@cosmicdrift/kumiko-framework 0.105.2 → 0.109.0

package/src/engine/__tests__/extend-entity-projection.test.ts

@@ -0,0 +1,123 @@
+// r.extendEntityProjection — registrar/registry contracts (#759). The
+// runtime rebuild-replay behaviour is proven in
+// custom-fields/__tests__/custom-fields.integration.test.ts.
+
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { defineFeature } from "../define-feature";
+import { createEntity, createTextField } from "../factories";
+import { createRegistry } from "../registry";
+
+function exampleEntity(name = "unit") {
+  return createEntity({
+    table: name,
+    fields: { name: createTextField() },
+  });
+}
+
+const noopApply = async (): Promise<void> => {};
+
+describe("r.extendEntityProjection — registration", () => {
+  test("merges apply keys + extraSources into the implicit projection", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("unit", exampleEntity());
+      const setEvent = r.defineEvent("custom-field-set", z.object({ fieldKey: z.string() }));
+      r.extendEntityProjection("unit", {
+        sources: ["field-definition"],
+        apply: { [setEvent.name]: noopApply },
+      });
+    });
+    const registry = createRegistry([feature]);
+    const projection = registry.getAllProjections().get("test:projection:unit-entity");
+    expect(projection).toBeDefined();
+    expect(projection?.apply["test:event:custom-field-set"]).toBe(noopApply);
+    expect(projection?.apply["unit.created"]).toBeDefined();
+    expect(projection?.extraSources).toEqual(["field-definition"]);
+    expect(projection?.source).toBe("unit");
+  });
+
+  test("extension source equal to the entity name is not duplicated into extraSources", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("unit", exampleEntity());
+      const setEvent = r.defineEvent("custom-field-set", z.object({ fieldKey: z.string() }));
+      r.extendEntityProjection("unit", {
+        sources: ["unit"],
+        apply: { [setEvent.name]: noopApply },
+      });
+    });
+    const registry = createRegistry([feature]);
+    const projection = registry.getAllProjections().get("test:projection:unit-entity");
+    expect(projection?.extraSources).toBeUndefined();
+  });
+
+  test("auto-verb of a registered extraSources entity is a valid apply-key", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("unit", exampleEntity());
+      r.entity("field-definition", exampleEntity("field_definitions"));
+      r.extendEntityProjection("unit", {
+        sources: ["field-definition"],
+        apply: { "field-definition.deleted": noopApply },
+      });
+    });
+    const registry = createRegistry([feature]);
+    const projection = registry.getAllProjections().get("test:projection:unit-entity");
+    expect(projection?.apply["field-definition.deleted"]).toBe(noopApply);
+  });
+
+  test("registration order is free: extension before r.entity in the same feature", () => {
+    const feature = defineFeature("test", (r) => {
+      const setEvent = r.defineEvent("custom-field-set", z.object({ fieldKey: z.string() }));
+      r.extendEntityProjection("unit", { apply: { [setEvent.name]: noopApply } });
+      r.entity("unit", exampleEntity());
+    });
+    const registry = createRegistry([feature]);
+    const projection = registry.getAllProjections().get("test:projection:unit-entity");
+    expect(projection?.apply["test:event:custom-field-set"]).toBe(noopApply);
+  });
+
+  test("empty apply throws at registration time", () => {
+    expect(() =>
+      defineFeature("test", (r) => {
+        r.entity("unit", exampleEntity());
+        r.extendEntityProjection("unit", { apply: {} });
+      }),
+    ).toThrow(/no apply handlers/);
+  });
+});
+
+describe("r.extendEntityProjection — registry-build validation", () => {
+  test("unknown entity fails at registry build", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("unit", exampleEntity());
+      const setEvent = r.defineEvent("custom-field-set", z.object({ fieldKey: z.string() }));
+      r.extendEntityProjection("typo-entity", { apply: { [setEvent.name]: noopApply } });
+    });
+    expect(() => createRegistry([feature])).toThrow(/no r\.entity/);
+  });
+
+  test("apply-key collision with a lifecycle apply fails at registry build", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("unit", exampleEntity());
+      r.extendEntityProjection("unit", { apply: { "unit.created": noopApply } });
+    });
+    expect(() => createRegistry([feature])).toThrow(/collides/);
+  });
+
+  test("apply-key collision between two extensions fails at registry build", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("unit", exampleEntity());
+      const setEvent = r.defineEvent("custom-field-set", z.object({ fieldKey: z.string() }));
+      r.extendEntityProjection("unit", { apply: { [setEvent.name]: noopApply } });
+      r.extendEntityProjection("unit", { apply: { [setEvent.name]: noopApply } });
+    });
+    expect(() => createRegistry([feature])).toThrow(/collides/);
+  });
+
+  test("unknown apply-key (neither auto-verb nor domain event) fails at registry build", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("unit", exampleEntity());
+      r.extendEntityProjection("unit", { apply: { "customField.set": noopApply } });
+    });
+    expect(() => createRegistry([feature])).toThrow(/no such event/);
+  });
+});

package/src/engine/__tests__/projection-helpers.test.ts

@@ -50,7 +50,7 @@ describe("setFields", () => {
   test("returns an apply fn that UPDATEs the passed fields WHERE id = aggregateId", async () => {
     const apply = setFields(fakeTable, { status: "sent" });
     const { fakeTx, unsafe } = makeFakeTx();
-    await apply(makeFakeEvent(), fakeTx);
+    await apply(makeFakeEvent(), fakeTx, fakeTable);
     expect(unsafe).toHaveBeenCalledTimes(1);
     const [sqlText, params] = unsafe.mock.calls[0]!;
     expect(sqlText).toMatch(/UPDATE "fake_table" SET "status" = \$1.*WHERE "id" = \$2/);
@@ -62,7 +62,7 @@ describe("setFields", () => {
       status: (event.payload as { newStatus: string }).newStatus,
     }));
     const { fakeTx, unsafe } = makeFakeTx();
-    await apply(makeFakeEvent({ payload: { newStatus: "cancelled" } }), fakeTx);
+    await apply(makeFakeEvent({ payload: { newStatus: "cancelled" } }), fakeTx, fakeTable);
     expect(unsafe).toHaveBeenCalledTimes(1);
     const [, params] = unsafe.mock.calls[0]!;
     expect(params).toEqual(["cancelled", "agg-42"]);

package/src/engine/__tests__/soft-delete-cleanup.test.ts

@@ -4,8 +4,10 @@ import { createRegistry } from "../registry";
 import {
   DEFAULT_GRACE_DAYS,
   SOFT_DELETE_CLEANUP_JOB,
+  SOFT_DELETE_CLEANUP_SYSTEM_JOB,
   SOFT_DELETE_GRACE_DAYS_KEY,
   softDeleteCleanupJob,
+  softDeleteCleanupSystemJob,
 } from "../soft-delete-cleanup";
 import type { AppContext } from "../types/handlers";
 
@@ -31,9 +33,17 @@ describe("registry soft-delete auto-wiring", () => {
     expect(key?.default).toBe(DEFAULT_GRACE_DAYS);
   });
 
+  test("also injects the system-scope cleanup job (not perTenant)", () => {
+    const registry = createRegistry([featureWith(true)]);
+    expect(registry.getAllJobs().has(SOFT_DELETE_CLEANUP_SYSTEM_JOB)).toBe(true);
+    const job = registry.getJob(SOFT_DELETE_CLEANUP_SYSTEM_JOB);
+    expect(job?.perTenant).toBeUndefined();
+  });
+
   test("does NOT inject when no entity uses softDelete", () => {
     const registry = createRegistry([featureWith(false)]);
     expect(registry.getAllJobs().has(SOFT_DELETE_CLEANUP_JOB)).toBe(false);
+    expect(registry.getAllJobs().has(SOFT_DELETE_CLEANUP_SYSTEM_JOB)).toBe(false);
     expect(registry.getAllConfigKeys().has(SOFT_DELETE_GRACE_DAYS_KEY)).toBe(false);
   });
 });
@@ -87,22 +97,21 @@ function makeCtx(opts: { graceDays?: number; calls: DeleteCall[] }): AppContext
 }
 
 describe("softDeleteCleanupJob handler", () => {
-  test("hard-deletes only softDelete implicit projections, tenant-scoped where the table has tenantId", async () => {
+  test("hard-deletes only tenant-scoped softDelete implicit projections; system-global entities are skipped", async () => {
+    // Regression (565/1): sysThing (no tenantId column) must NOT be touched
+    // here — this handler is perTenant-fanned-out, so sweeping a system-
+    // global entity with THIS tenant's grace value would purge it using
+    // whichever tenant has the shortest grace period, for every tenant.
+    // softDeleteCleanupSystemJob (below) owns sysThing instead.
     const calls: DeleteCall[] = [];
     await softDeleteCleanupJob({}, makeCtx({ calls }));
 
-    // thing + sysThing deleted; auditEntry (softDelete:false) + custom (explicit) skipped
-    expect(calls).toHaveLength(2);
-
-    const tenantScoped = calls.filter((c) => c.where["tenantId"] === "t1");
-    const systemScoped = calls.filter((c) => c.where["tenantId"] === undefined);
-    expect(tenantScoped).toHaveLength(1);
-    expect(systemScoped).toHaveLength(1);
-
-    for (const c of calls) {
-      expect(c.where["isDeleted"]).toBe(true);
-      expect(c.where["deletedAt"]).toBeDefined();
-    }
+    // thing deleted; sysThing (no tenantId), auditEntry (softDelete:false)
+    // and custom (explicit) all skipped.
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.where["tenantId"]).toBe("t1");
+    expect(calls[0]?.where["isDeleted"]).toBe(true);
+    expect(calls[0]?.where["deletedAt"]).toBeDefined();
   });
 
   test("cutoff defaults to DEFAULT_GRACE_DAYS when no config resolver", async () => {
@@ -127,3 +136,30 @@ describe("softDeleteCleanupJob handler", () => {
     );
   });
 });
+
+describe("softDeleteCleanupSystemJob handler", () => {
+  test("hard-deletes only system-global (no tenantId) softDelete implicit projections", async () => {
+    const calls: DeleteCall[] = [];
+    await softDeleteCleanupSystemJob({}, makeCtx({ calls }));
+
+    // sysThing deleted; thing (has tenantId), auditEntry (softDelete:false)
+    // and custom (explicit) all skipped.
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.where["tenantId"]).toBeUndefined();
+    expect(calls[0]?.where["isDeleted"]).toBe(true);
+  });
+
+  test("cutoff is DEFAULT_GRACE_DAYS — no per-tenant config to read", async () => {
+    const calls: DeleteCall[] = [];
+    await softDeleteCleanupSystemJob({}, makeCtx({ calls }));
+    const cutoff = (calls[0]?.where["deletedAt"] as { lt: Temporal.Instant }).lt;
+    const expected = Temporal.Now.instant().subtract({ hours: DEFAULT_GRACE_DAYS * 24 });
+    expect(Math.abs(cutoff.epochMilliseconds - expected.epochMilliseconds)).toBeLessThan(10_000);
+  });
+
+  test("throws when the job context is missing db/registry", async () => {
+    await expect(softDeleteCleanupSystemJob({}, {} as AppContext)).rejects.toThrow(
+      /ctx.db \+ ctx.registry/,
+    );
+  });
+});

package/src/engine/boot-validator/entity-handler.ts

@@ -270,6 +270,20 @@ export function validateEntityIndexes(feature: FeatureDefinition): void {
             `buildEntityTable always creates one automatically. Remove this entry.`,
         );
       }
+      // AES-GCM's random-IV ciphertext is never equal to itself across two
+      // writes of the same plaintext, so a unique index on an encrypted
+      // column can never detect a real duplicate.
+      if (def.unique) {
+        for (const col of def.columns) {
+          const field = entity.fields[col];
+          if (field && (field.type === "text" || field.type === "longText") && field.encrypted) {
+            throw new Error(
+              `${where}: column "${col}" is encrypted — a unique index on it can never detect ` +
+                `duplicates (non-deterministic ciphertext). Remove \`unique\` or \`encrypted\`.`,
+            );
+          }
+        }
+      }
     }
   }
 }
@@ -298,6 +312,15 @@ export function validateEncryptedFields(feature: FeatureDefinition): boolean {
             `Field "${fieldName}" on entity "${entityName}" cannot be both encrypted and sortable`,
           );
         }
+        // AES-GCM draws a fresh random IV per call, so the ciphertext is
+        // non-deterministic — an equality filter on it never matches, even
+        // against the identical plaintext.
+        if (field.filterable) {
+          throw new Error(
+            `Field "${fieldName}" on entity "${entityName}" cannot be both encrypted and filterable ` +
+              `— non-deterministic ciphertext never matches an equality filter.`,
+          );
+        }
       }
     }
   }
@@ -507,3 +530,25 @@ export function validateExtendSchemaCollisions(feature: FeatureDefinition): void
     }
   }
 }
+
+// --- derivedFields / fields collision detection ---
+//
+// augmentDerivedFields (entity-handlers.ts) does `{...row}` then
+// `out[fieldName] = def.derive(row, ctx)` — a derivedFields key that matches a
+// stored field name silently overwrites the real, persisted value with the
+// derived one on every read, without a boot or runtime error. Reject it here,
+// analogous to the extendSchema collision check above.
+export function validateDerivedFieldCollisions(feature: FeatureDefinition): void {
+  for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
+    if (!entity.derivedFields) continue;
+    const fieldNames = new Set(Object.keys(entity.fields));
+    for (const derivedName of Object.keys(entity.derivedFields)) {
+      if (fieldNames.has(derivedName)) {
+        throw new Error(
+          `Entity "${entityName}": derivedFields key "${derivedName}" conflicts with a stored ` +
+            `field of the same name — the derived value would silently overwrite the real one on every read.`,
+        );
+      }
+    }
+  }
+}

package/src/engine/boot-validator/gdpr-storage.ts

@@ -1,3 +1,4 @@
+import { EXT_USER_DATA } from "../extension-names";
 import type { FeatureDefinition } from "../types";
 
 // Providers whose bytes do not survive a process restart. Only "inmemory"
@@ -65,7 +66,7 @@ export function validateGdprStoragePersistence(features: readonly FeatureDefinit
 export function validateGdprHookCompleteness(features: readonly FeatureDefinition[]): void {
   for (const feature of features) {
     for (const usage of feature.extensionUsages) {
-      if (usage.extensionName !== "userData") continue;
+      if (usage.extensionName !== EXT_USER_DATA) continue;
       const hasExport = typeof usage.options?.["export"] === "function";
       const hasDelete = typeof usage.options?.["delete"] === "function";
       if (hasExport && !hasDelete) {

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

@@ -12,6 +12,7 @@ import {
   warnOnToggleableDependencies,
 } from "./config-deps";
 import {
+  validateDerivedFieldCollisions,
   validateEmbeddedFields,
   validateEncryptedFields,
   validateEntityIndexes,
@@ -33,11 +34,13 @@ import {
   collectKnownRoles,
   collectNavQns,
   collectScreenQns,
+  collectScreensByShortId,
   collectWorkspaceQns,
   collectWriteHandlerQns,
   validateDefaultWorkspaceUniqueness,
   validateNavCycles,
   validateNavs,
+  validateScreenShortIdCollisions,
   validateScreens,
   validateWorkspaces,
 } from "./screens-nav";
@@ -110,6 +113,8 @@ export function validateBoot(features: readonly FeatureDefinition[]): void {
   const allNavQns = collectNavQns(features);
   const allWorkspaceQns = collectWorkspaceQns(features);
   const allWriteHandlerQns = collectWriteHandlerQns(features);
+  const screensByShortId = collectScreensByShortId(features);
+  validateScreenShortIdCollisions(screensByShortId);
 
   // Cross-feature API exposure-map — jedes Feature deklariert Marker via
   // r.exposesApi(name). Per-feature validateApiExposureMatching walkt
@@ -144,6 +149,7 @@ export function validateBoot(features: readonly FeatureDefinition[]): void {
     validateTransitions(feature);
     validateExtensionUsages(feature, extensionProviders);
     validateExtendSchemaCollisions(feature);
+    validateDerivedFieldCollisions(feature);
     validateHandlerAccess(feature);
     validateLocatedTimestamps(feature);
     validateEntityIndexes(feature);
@@ -154,7 +160,14 @@ export function validateBoot(features: readonly FeatureDefinition[]): void {
     validateConfigKeyBacking(feature);
     validateOwnershipRules(feature, allClaimKeys, knownRoles);
     validateMultiStreamProjections(feature);
-    validateScreens(feature, featureMap, allWriteHandlerQns, allScreenQns, allConfigKeyQns);
+    validateScreens(
+      feature,
+      featureMap,
+      allWriteHandlerQns,
+      allScreenQns,
+      allConfigKeyQns,
+      screensByShortId,
+    );
     validateNavs(feature, allScreenQns, allNavQns, allWorkspaceQns);
     validateWorkspaces(feature, allNavQns);
   }

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

@@ -3,7 +3,13 @@ import { SETTINGS_HUB_AUDIENCE_NAV_QNS } from "../build-config-feature-schema";
 import { qualifyEntityName } from "../qualified-name";
 import { getAllowedFilterOps, isFieldFilterable } from "../screen-filter-ops";
 import type { FeatureDefinition, NavDefinition, WorkspaceDefinition } from "../types";
-import type { FieldCondition, RowAction, RowFieldExtractor, ToolbarAction } from "../types/screen";
+import type {
+  FieldCondition,
+  RowAction,
+  RowFieldExtractor,
+  ScreenDefinition,
+  ToolbarAction,
+} from "../types/screen";
 import { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "../types/screen";
 
 // --- Screen validation ---
@@ -81,12 +87,41 @@ function validateActionFieldRefs(
   }
 }
 
+// Two features registering the same short screen-id is a silent routing
+// footgun: create-app.tsx's runtime router resolves a bare navigate-target
+// id by scanning features[] and taking the first match — the collision
+// never surfaces as an error, the second feature's screen is just
+// unreachable by that id (and always the same one that loses, in whatever
+// order the app composed its features).
+export function validateScreenShortIdCollisions(
+  screensByShortId: ReadonlyMap<
+    string,
+    ReadonlyArray<{ readonly featureName: string; readonly screen: ScreenDefinition }>
+  >,
+): void {
+  for (const [shortId, entries] of screensByShortId) {
+    const featureNames = new Set(entries.map((e) => e.featureName));
+    if (featureNames.size > 1) {
+      throw new Error(
+        `Screen short-id "${shortId}" is registered by ${featureNames.size} features ` +
+          `(${[...featureNames].join(", ")}) — the runtime router resolves a bare navigate-target ` +
+          `id by taking the first match, so all but one of these screens would be unreachable by ` +
+          `that id. Give each screen a distinct id.`,
+      );
+    }
+  }
+}
+
 export function validateScreens(
   feature: FeatureDefinition,
   featureMap: ReadonlyMap<string, FeatureDefinition>,
   allWriteHandlerQns: ReadonlySet<string>,
   allScreenQns: ReadonlySet<string>,
   allConfigKeyQns: ReadonlySet<string>,
+  screensByShortId: ReadonlyMap<
+    string,
+    ReadonlyArray<{ readonly featureName: string; readonly screen: ScreenDefinition }>
+  >,
 ): void {
   // navigate-Targets (rowAction/toolbarAction) dürfen cross-feature zeigen —
   // der Runtime-Router (create-app) löst eine bare screenId app-weit über ALLE
@@ -338,11 +373,16 @@ export function validateScreens(
       }
       for (const col of screen.columns) {
         const normalized = normalizeListColumn(col);
-        // A labeled column whose field is not an entity field is a *virtual*
-        // presentational column (drawn by a columnRenderer component from the
-        // row, e.g. tag chips) — its `field` is just a column key. Only an
-        // unlabeled unknown field is an author typo worth failing the boot.
-        if (!columnFieldNames.has(normalized.field) && normalized.label === undefined) {
+        // A virtual presentational column (drawn by a columnRenderer component
+        // from the row, e.g. tag chips) needs BOTH a label AND a renderer —
+        // renderer is what actually makes it "virtual" (label alone still
+        // needs list.ts's virtual-branch to have something to draw; without
+        // a renderer the column would render nothing). A column with neither
+        // matching a real field NOR a renderer is a typo worth failing the boot.
+        if (
+          !columnFieldNames.has(normalized.field) &&
+          !(normalized.label !== undefined && normalized.renderer !== undefined)
+        ) {
           throw new Error(
             buildUnknownFieldMessage(
               feature.name,
@@ -446,6 +486,26 @@ export function validateScreens(
                   `navigate-target "${action.screen}" does not resolve to a registered screen in any feature.`,
               );
             }
+            // The renderer's default-entityId fallback (row["id"]) only fires
+            // for a same-feature entityEdit target — it can't safely guess
+            // the id for a screen owned by a different feature. Cross-feature
+            // + entityEdit therefore MUST set an explicit entityId, or the
+            // edit screen silently opens with no entity context at runtime.
+            const target = screensByShortId.get(action.screen)?.[0];
+            if (
+              target !== undefined &&
+              target.featureName !== feature.name &&
+              target.screen.type === "entityEdit" &&
+              action.entityId === undefined
+            ) {
+              throw new Error(
+                `[Feature ${feature.name}] Screen "${screenId}" (entityList) rowAction "${action.id}" ` +
+                  `navigates cross-feature to entityEdit screen "${action.screen}" (feature ` +
+                  `"${target.featureName}") without an explicit entityId field — the renderer's ` +
+                  `same-feature row["id"] fallback does not apply across features. Set entityId to ` +
+                  `the row field that names the target entity's id.`,
+              );
+            }
           } else {
             if (!allWriteHandlerQns.has(action.handler)) {
               throw new Error(
@@ -648,6 +708,30 @@ export function screenShortIdsFrom(allScreenQns: ReadonlySet<string>): Set<strin
   return set;
 }
 
+// Short screen-id → every {featureName, screen} that registers it. The
+// runtime router (create-app.tsx) resolves a bare navigate-target short-id by
+// scanning ALL features and taking the first match — so two features
+// registering the same short-id is a silent routing footgun (whichever
+// feature comes first in the app's features[] array always wins, the other
+// is unreachable by that id) and a prerequisite for the entityId-check below
+// (which target screen it resolves to must be unambiguous).
+export function collectScreensByShortId(
+  features: readonly FeatureDefinition[],
+): Map<string, ReadonlyArray<{ readonly featureName: string; readonly screen: ScreenDefinition }>> {
+  const map = new Map<
+    string,
+    Array<{ readonly featureName: string; readonly screen: ScreenDefinition }>
+  >();
+  for (const f of features) {
+    for (const [screenId, screen] of Object.entries(f.screens)) {
+      const entries = map.get(screenId) ?? [];
+      entries.push({ featureName: f.name, screen });
+      map.set(screenId, entries);
+    }
+  }
+  return map;
+}
+
 // Sammelt alle qualifizierten Write-Handler-QNs (`<feature>:write:<short>`).
 // Wird vom actionForm-Screen-Validator genutzt um zu prüfen ob der
 // im Schema deklarierte handler tatsächlich registriert ist —

package/src/engine/build-app-schema.ts

@@ -32,7 +32,7 @@ import {
   SETTINGS_HUB_FEATURE,
 } from "./build-config-feature-schema";
 import type { Registry } from "./types/feature";
-import type { DerivedFieldDef, FieldDefinition } from "./types/fields";
+import type { ClientDerivedFieldDef, DerivedFieldDef, FieldDefinition } from "./types/fields";
 
 export type BuildAppSchemaOptions = {
   /** Dev-server authoring hints (Settings-Hub placement). Default off — only
@@ -290,7 +290,7 @@ function projectEntity(entity: EntityDefinition): EntityDefinition {
   // `entity.derivedFields[field].valueType` auf — fehlt der Eintrag, wirft es
   // "references unknown field". Der executor hat den Wert server-seitig schon
   // an die Row gehängt; der Client braucht nur den valueType für den Renderer.
-  const derivedOut: Record<string, DerivedFieldDef> = {};
+  const derivedOut: Record<string, ClientDerivedFieldDef> = {};
   for (const [name, derivedDef] of Object.entries(entity.derivedFields ?? {})) {
     derivedOut[name] = projectDerivedField(derivedDef);
   }
@@ -300,16 +300,24 @@ function projectEntity(entity: EntityDefinition): EntityDefinition {
   // Kein Cast nötig: alle weggelassenen Felder sind `?`-optional.
   return {
     fields: fieldsOut,
-    ...(Object.keys(derivedOut).length > 0 && { derivedFields: derivedOut }),
+    // @cast-boundary schema-walk: EntityDefinition.derivedFields is typed for
+    // the SERVER (derive required); this is the one place a client schema
+    // narrows it to ClientDerivedFieldDef (valueType only) — the cast lives
+    // at the actual server/client type boundary instead of inside
+    // projectDerivedField, which now honestly returns the narrower type.
+    ...(Object.keys(derivedOut).length > 0 && {
+      derivedFields: derivedOut as unknown as Record<string, DerivedFieldDef>,
+    }),
     ...(typeof entity.table === "string" && { table: entity.table }),
   };
 }
 
 // Nur valueType durch — die derive-fn ist Server-only und NICHT JSON-safe
-// (würde sonst die Output-Walk-Guard triggern). Der Cast bridged die
-// fn-lose Projektion auf DerivedFieldDef (Client liest nur valueType).
-function projectDerivedField(derivedDef: DerivedFieldDef): DerivedFieldDef {
-  return { valueType: derivedDef.valueType } as DerivedFieldDef; // @cast-boundary schema-walk
+// (würde sonst die Output-Walk-Guard triggern). Gibt ehrlich
+// ClientDerivedFieldDef zurück statt eine DerivedFieldDef vorzutäuschen,
+// die keine derive-fn hat.
+function projectDerivedField(derivedDef: DerivedFieldDef): ClientDerivedFieldDef {
+  return { valueType: derivedDef.valueType };
 }
 
 // Whitelist pro Field. `default` darf nur durch wenn Literal (string/

package/src/engine/define-feature.ts

@@ -15,6 +15,7 @@ import type {
   ConfigKeyType,
   ConfigSeedDef,
   EntityDefinition,
+  EntityProjectionExtension,
   EntityRef,
   EventDef,
   EventMigrationDef,
@@ -141,6 +142,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
   const secretKeys: Record<string, SecretKeyDefinition> = {};
   const projections: Record<string, ProjectionDefinition> = {};
   const multiStreamProjections: Record<string, MultiStreamProjectionDefinition> = {};
+  const entityProjectionExtensions: Record<string, EntityProjectionExtension[]> = {};
   const rawTables: Record<string, RawTableEntry> = {};
   const unmanagedTables: Record<string, UnmanagedTableEntry> = {};
   const authClaimsHooks: AuthClaimsFn[] = [];
@@ -727,6 +729,20 @@ export function defineFeature<const TName extends string, TExports = undefined>(
       multiStreamProjections[definition.name] = definition;
     },
 
+    extendEntityProjection(entityName: string, extension: EntityProjectionExtension): void {
+      if (Object.keys(extension.apply).length === 0) {
+        throw new Error(
+          `[Feature ${name}] extendEntityProjection("${entityName}") has no apply handlers. ` +
+            `Declare at least one event type, otherwise the rebuild replay has nothing to do.`,
+        );
+      }
+      // Entity existence + apply-key collisions are validated at registry
+      // build — r.entity may legally be called after this in the same feature.
+      const list = entityProjectionExtensions[entityName] ?? [];
+      list.push(extension);
+      entityProjectionExtensions[entityName] = list;
+    },
+
     authClaims(fn: AuthClaimsFn): void {
       authClaimsHooks.push(fn);
     },
@@ -997,6 +1013,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
     metrics,
     secretKeys,
     projections,
+    entityProjectionExtensions,
     multiStreamProjections,
     authClaimsHooks,
     claimKeys,

package/src/engine/define-handler.ts

@@ -90,7 +90,20 @@ export function defineWriteHandler<
   // responses get `[]`, so existing call-sites are unaffected. Checking it in a
   // parameter post-inference (not as a `TData extends …` constraint, which TS
   // rejects as circular, TS2313) is what makes inference survive.
-  ..._noSecretInResponse: ContainsSecret<TData> extends true
+  //
+  // Membership form `true extends ContainsSecret<TData>` (556/1), not
+  // `ContainsSecret<TData> extends true`: when TData is a union like
+  // `{ok:true} | {s:Secret<string>}`, the naked-type-parameter conditional in
+  // ContainsSecret DISTRIBUTES over the union, so the result is
+  // `false | true` = `boolean`, not the literal `true` — `ContainsSecret<
+  // TData> extends true` is then false (boolean isn't assignable to the
+  // literal true) and the old check silently fell through to `[]` even with
+  // a real leak in one branch. Putting the naked `true` on the LEFT instead
+  // keeps the check fail-closed for the union case (`true extends boolean`
+  // is true) without eagerly normalizing ContainsSecret<TData> against a
+  // literal — which is what blew up TS's instantiation depth on generic
+  // call-sites (createTokenRequestHandler's still-unresolved TSuccessKind).
+  ..._noSecretInResponse: true extends ContainsSecret<TData>
     ? [
         secretLeak: "A handler response must not contain a Secret<> — call .reveal() and return the plaintext, or drop the field.",
       ]
@@ -174,7 +187,8 @@ export function defineQueryHandler<
   def: QueryHandlerDefinition<TName, TSchema, TResult, TMap>,
   // R6: phantom rest-param — see defineWriteHandler. Forbids a Secret<> in the
   // inferred query response `TResult` at compile time; `[]` for clean responses.
-  ..._noSecretInResponse: ContainsSecret<TResult> extends true
+  // Membership form (556/1) — see defineWriteHandler's comment for why.
+  ..._noSecretInResponse: true extends ContainsSecret<TResult>
     ? [
         secretLeak: "A handler response must not contain a Secret<> — call .reveal() and return the plaintext, or drop the field.",
       ]