@cosmicdrift/kumiko-framework 0.105.1 → 0.108.0

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.",
       ]

package/src/engine/entity-handlers.ts

@@ -1,19 +1,20 @@
 import { type ZodType, z } from "zod";
 import type { DbRow } from "../db/connection";
-import type { TableColumns } from "../db/dialect";
 import {
   collectReferenceFields,
   enrichRowWithReferences,
   enrichWithReferences,
 } from "../db/eagerload";
 import { createEventStoreExecutor, type EventStoreExecutor } from "../db/event-store-executor";
-import { buildEntityTable } from "../db/table-builder";
+import { buildEntityTable, type EntityTable } from "../db/table-builder";
+import { createTenantDb, type TenantDb } from "../db/tenant-db";
 import { assertUnreachable } from "../utils";
 import { buildInsertSchema, buildUpdateSchema } from "./schema-builder";
 import type {
   AccessRule,
   DeriveContext,
   EntityDefinition,
+  HandlerContext,
   QueryHandlerDef,
   WriteHandlerDef,
 } from "./types";
@@ -222,7 +223,7 @@ function augmentDerivedFields(
 export function defineEntityQueryHandler(
   name: string,
   entity: EntityDefinition,
-  options?: { access?: AccessRule },
+  options?: { access?: AccessRule; crossTenant?: boolean },
 ): QueryHandlerDef {
   const { entityName, verb } = parseHandlerName(name, QUERY_VERBS);
 
@@ -240,6 +241,17 @@ export function defineEntityQueryHandler(
   // Wrapper zu nutzen).
   const hasRefFields = collectReferenceFields(entity).length > 0;
 
+  // crossTenant: this ONE handler reads across every tenant (e.g. a
+  // SystemAdmin-only operator inspector) without making the whole feature
+  // r.systemScope() — that would drop tenant isolation from every OTHER
+  // handler the feature registers too. The executor's list()/detail() only
+  // add a tenant filter when db.mode === "tenant" (see event-store-executor
+  // .ts), so handing them a "system"-mode TenantDb built from the same raw
+  // connection is enough to skip it — access-control (who may call this
+  // handler at all) is unaffected, still gated by `options.access`.
+  const dbFor = (ctx: HandlerContext): TenantDb =>
+    options?.crossTenant ? createTenantDb(ctx.db.raw, ctx.db.tenantId, "system") : ctx.db;
+
   switch (verb) {
     case "list":
       schema = listSchema;
@@ -250,7 +262,8 @@ export function defineEntityQueryHandler(
         // Definition-Time gebaut, kennt den Adapter also nicht —
         // Runtime-Override holt das.
         const listPayload = query.payload as ListPayload; // @cast-boundary engine-payload
-        const result = await executor.list(listPayload, query.user, ctx.db, {
+        const db = dbFor(ctx);
+        const result = await executor.list(listPayload, query.user, db, {
           ...(ctx.searchAdapter !== undefined && { searchAdapter: ctx.searchAdapter }),
           ...(ctx.includeDeleted === true && { includeDeleted: true }),
         });
@@ -259,7 +272,7 @@ export function defineEntityQueryHandler(
               result.rows,
               entity,
               (name) => ctx.registry.getEntity(name),
-              ctx.db,
+              db,
             )
           : result.rows;
         return { ...result, rows: augmentDerivedFields(enrichedRows, entity) };
@@ -268,9 +281,10 @@ export function defineEntityQueryHandler(
     case "detail":
       schema = idSchema;
       handler = async (query, ctx) => {
-        const row = await executor.detail(query.payload as IdPayload, query.user, ctx.db); // @cast-boundary engine-payload
+        const db = dbFor(ctx);
+        const row = await executor.detail(query.payload as IdPayload, query.user, db); // @cast-boundary engine-payload
         if (row === null || !hasRefFields) return row;
-        return enrichRowWithReferences(row, entity, (name) => ctx.registry.getEntity(name), ctx.db);
+        return enrichRowWithReferences(row, entity, (name) => ctx.registry.getEntity(name), db);
       };
       break;
     default:
@@ -306,6 +320,14 @@ export function defineEntityQueryHandler(
 // — feasible but not yet wired; the runtime guard catches misuse.
 
 type EntityHandlerOptions = { readonly access?: AccessRule };
+type EntityQueryHandlerOptions = EntityHandlerOptions & {
+  /** Reads across every tenant instead of the caller's own — for a
+   *  SystemAdmin-only operator inspector over an otherwise tenant-scoped
+   *  entity. Scope this to the ONE handler that needs it rather than making
+   *  the whole feature r.systemScope(), which would drop tenant isolation
+   *  from every other handler the feature registers too. */
+  readonly crossTenant?: boolean;
+};
 
 // @wrapper-known semantic-alias
 export function defineEntityCreateHandler(
@@ -347,7 +369,7 @@ export function defineEntityRestoreHandler(
 export function defineEntityListHandler(
   entityName: string,
   entity: EntityDefinition,
-  options?: EntityHandlerOptions,
+  options?: EntityQueryHandlerOptions,
 ): QueryHandlerDef {
   return defineEntityQueryHandler(`${entityName}:list`, entity, options);
 }
@@ -356,14 +378,11 @@ export function defineEntityListHandler(
 export function defineEntityDetailHandler(
   entityName: string,
   entity: EntityDefinition,
-  options?: EntityHandlerOptions,
+  options?: EntityQueryHandlerOptions,
 ): QueryHandlerDef {
   return defineEntityQueryHandler(`${entityName}:detail`, entity, options);
 }
 
-// biome-ignore lint/suspicious/noExplicitAny: Drizzle dynamic table — erased on purpose, same as db/event-store-executor.ts does.
-type AnyTable = TableColumns<any>;
-
 // Bundle the two calls every custom write-handler opens with: build the
 // Drizzle table from the entity, then wire an event-store executor onto it.
 // The pair is identical in every sample that hand-writes handlers, so the
@@ -377,7 +396,7 @@ type AnyTable = TableColumns<any>;
 export function createEntityExecutor(
   entityName: string,
   entity: EntityDefinition,
-): { readonly table: AnyTable; readonly executor: EventStoreExecutor } {
+): { readonly table: EntityTable; readonly executor: EventStoreExecutor } {
   const table = buildEntityTable(entityName, entity);
   const executor = createEventStoreExecutor(table, entity, { entityName });
   return { table, executor };

package/src/engine/extensions/user-data.ts

@@ -90,6 +90,12 @@ export interface UserDataHookCtx {
    * touch tenant-scoped rows. Absent → treat as `"multi-user"` (no erasure).
    */
   readonly tenantModel?: TenantUserModel;
+  /**
+   * Original user email captured before the forget transaction anonymizes it.
+   * Set on delete hooks during `runForgetCleanup` so matchers (e.g. email
+   * subscriptions) work in every tenant pass. Absent on export hooks.
+   */
+  readonly userEmailBeforeDelete?: string | null;
 }
 
 /**

package/src/engine/index.ts

@@ -170,8 +170,12 @@ export {
   checkWriteFieldRoles,
   filterReadFields,
 } from "./field-access";
+// findForbiddenMembershipRole/isForbiddenMembershipRole/
+// stripForbiddenMembershipRoles are Public API for host apps that build
+// their own membership handlers. FORBIDDEN_MEMBERSHIP_ROLES itself stays
+// internal (637/3) — exporting the raw Set would make its representation a
+// semver promise; the predicate functions are the intended surface.
 export {
-  FORBIDDEN_MEMBERSHIP_ROLES,
   findForbiddenMembershipRole,
   isForbiddenMembershipRole,
   stripForbiddenMembershipRoles,
@@ -214,6 +218,7 @@ export {
 export {
   type EffectiveFeaturesResolver,
   findTierResolverUsage,
+  isTierResolverPlugin,
   TENANT_TIER_RESOLVER_EXT,
   type TierResolverPlugin,
   type TrialGate,

package/src/engine/projection-helpers.ts

@@ -11,16 +11,19 @@ import type { MultiStreamApplyFn, ProjectionTable, SingleStreamApplyFn } from ".
 // Der Helper ist ein purer Type-Vehikel — zur Laufzeit identitäts-fn:
 //
 //   apply: {
-//     "user.created": defineApply<UserCreatedPayload>(async (event, tx) => {
-//       // event.payload ist UserCreatedPayload, nicht Record<string, unknown>
-//       await tx.insert(usersTable).values({ id: event.aggregateId, ...event.payload });
+//     "user.created": defineApply<UserCreatedPayload>(async (event, tx, table) => {
+//       // event.payload ist UserCreatedPayload, nicht Record<string, unknown>.
+//       // Write through the passed `table` (ES-blessed inside apply), not a
+//       // closed-over branded constant.
+//       await insertOne(tx, table, { id: event.aggregateId, ...event.payload });
 //     }),
 //   }
 //
 // Default-Generic = Record<string, unknown> behält rückwärtskompatibles
-// Verhalten für Apply-Handler die ohne Type-Argument geschrieben sind.
+// Verhalten für Apply-Handler die ohne Type-Argument geschrieben sind. Der
+// `table`-Param ist optional zu nutzen — 2-arg-Applies bleiben gültig.
 export function defineApply<TPayload = Record<string, unknown>>(
-  fn: (event: StoredEvent<TPayload>, tx: DbRunner) => Promise<void>,
+  fn: (event: StoredEvent<TPayload>, tx: DbRunner, table: ProjectionTable) => Promise<void>,
 ): SingleStreamApplyFn {
   // @cast-boundary engine-bridge — typed user-fn → erased internal storage
   return fn as SingleStreamApplyFn;

package/src/engine/registry.ts

@@ -10,7 +10,9 @@ import { buildMetricName, validateMetricName } from "../observability";
 import { type QnType, qualifyEntityName } from "./qualified-name";
 import {
   buildSoftDeleteCleanupJob,
+  buildSoftDeleteCleanupSystemJob,
   SOFT_DELETE_CLEANUP_JOB,
+  SOFT_DELETE_CLEANUP_SYSTEM_JOB,
   SOFT_DELETE_GRACE_DAYS_KEY,
   softDeleteGraceDaysConfig,
 } from "./soft-delete-cleanup";
@@ -20,6 +22,7 @@ import type {
   ConfigKeyDefinition,
   ConfigSeedDef,
   EntityDefinition,
+  EntityProjectionExtension,
   EntityRelations,
   EventDef,
   EventUpcastFn,
@@ -79,6 +82,7 @@ function buildImplicitProjection(
   entity: EntityDefinition,
   qualify: typeof qualifyEntityName,
   backingTable?: unknown,
+  extensions: readonly EntityProjectionExtension[] = [],
 ): ProjectionDefinition {
   const name = qualify(featureName, "projection", `${entityName}${IMPLICIT_PROJECTION_SUFFIX}`);
   // Backing table (r.entity(name, def, { table })) is the one physical table
@@ -102,6 +106,9 @@ function buildImplicitProjection(
     [`${entityName}.created`]: handler,
     [`${entityName}.updated`]: handler,
     [`${entityName}.deleted`]: handler,
+    // forget/purge (Art. 17): hard-deletes the row even for softDelete entities.
+    // Registered for every entity so the erasure replays on rebuild.
+    [`${entityName}.forgotten`]: handler,
   };
   // Restore-Verb existiert nur für softDelete-Entities. Hard-Delete-
   // Entities sollten keine restored-Events produzieren — würden sie es
@@ -110,9 +117,28 @@ function buildImplicitProjection(
   if (entity.softDelete) {
     apply[`${entityName}.restored`] = handler;
   }
+  // r.extendEntityProjection: merge extension applies into the rebuild
+  // replay. Collisions with lifecycle applies (or another extension) are
+  // authoring bugs — fail at boot, not by silently overwriting a handler.
+  const extraSources: string[] = [];
+  for (const ext of extensions) {
+    for (const [eventType, fn] of Object.entries(ext.apply)) {
+      if (apply[eventType]) {
+        throw new Error(
+          `Implicit projection "${name}": extendEntityProjection apply-key "${eventType}" ` +
+            `collides with an existing handler (entity lifecycle apply or another extension).`,
+        );
+      }
+      apply[eventType] = fn;
+    }
+    for (const s of ext.sources ?? []) {
+      if (s !== entityName && !extraSources.includes(s)) extraSources.push(s);
+    }
+  }
   return {
     name,
     source: entityName,
+    ...(extraSources.length > 0 && { extraSources }),
     table: drizzleTable,
     apply,
     isImplicit: true,
@@ -926,6 +952,18 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
   // vermeidet Kollisionen wenn jemand z.B. eine Cross-Aggregate-Projection
   // mit Entity-Name registriert.
   for (const feature of features) {
+    // extendEntityProjection targets must exist as r.entity in the SAME
+    // feature — a typo'd entity name would otherwise vanish silently and the
+    // extension's events would still be wiped on rebuild.
+    for (const extEntity of Object.keys(feature.entityProjectionExtensions ?? {})) {
+      if (!feature.entities?.[extEntity]) {
+        throw new Error(
+          `[Feature ${feature.name}] extendEntityProjection("${extEntity}"): no r.entity ` +
+            `with that name in this feature. Declare the entity first — the extension ` +
+            `merges into its implicit projection.`,
+        );
+      }
+    }
     for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
       const def = buildImplicitProjection(
         feature.name,
@@ -933,6 +971,7 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
         entity,
         qualify,
         feature.entityTables?.[entityName],
+        feature.entityProjectionExtensions?.[entityName] ?? [],
       );
       if (projectionMap.has(def.name)) {
         throw new Error(
@@ -1112,10 +1151,13 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
   // CRUD types per source entity PLUS every domain event registered via
   // r.defineEvent — an apply-handler for a domain event is how a projection
   // reacts to ctx.appendEvent writes on the same aggregate stream.
-  const AUTO_EVENT_VERBS = ["created", "updated", "deleted", "restored"] as const;
+  const AUTO_EVENT_VERBS = ["created", "updated", "deleted", "restored", "forgotten"] as const;
   const allDomainEventNames = new Set(eventMap.keys());
   for (const [projName, projDef] of projectionMap) {
     const sources = Array.isArray(projDef.source) ? projDef.source : [projDef.source];
+    // extraSources (r.extendEntityProjection) sit in the rebuild filter, so
+    // their auto-verbs are legitimately observable apply-keys too.
+    const rebuildSources = [...sources, ...(projDef.extraSources ?? [])];
     const validEventTypes = new Set<string>();
     // Two source-modes are legal:
     //
@@ -1133,7 +1175,7 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
     //      or `jobRun` (BullMQ-callback-driven lifecycle, no executor).
     //      A "Shape-Anchor"-entity is no longer needed for this case.
     const isEventsOnlySource = !sources.every((src) => entityMap.has(src));
-    for (const src of sources) {
+    for (const src of rebuildSources) {
       if (entityMap.has(src)) {
         for (const verb of AUTO_EVENT_VERBS) validEventTypes.add(`${src}.${verb}`);
       }
@@ -1335,6 +1377,9 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
     if (!jobMap.has(SOFT_DELETE_CLEANUP_JOB)) {
       jobMap.set(SOFT_DELETE_CLEANUP_JOB, buildSoftDeleteCleanupJob());
     }
+    if (!jobMap.has(SOFT_DELETE_CLEANUP_SYSTEM_JOB)) {
+      jobMap.set(SOFT_DELETE_CLEANUP_SYSTEM_JOB, buildSoftDeleteCleanupSystemJob());
+    }
     if (!configKeyMap.has(SOFT_DELETE_GRACE_DAYS_KEY)) {
       configKeyMap.set(SOFT_DELETE_GRACE_DAYS_KEY, softDeleteGraceDaysConfig);
     }

package/src/engine/schema-builder.ts

@@ -94,7 +94,9 @@ export function fieldToZod(field: FieldDefinition, currencies: readonly string[]
       return field.default !== undefined ? schema.default([...field.default]) : schema;
     }
     case "number": {
-      const schema = z.number();
+      let schema = z.number();
+      if (field.integer) schema = schema.int();
+      if (field.min !== undefined) schema = schema.min(field.min);
       return field.default !== undefined ? schema.default(field.default) : schema;
     }
     case "decimal": {

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

@@ -20,6 +20,7 @@ import type { ConfigKeyDefinition, JobDefinition, JobHandlerFn } from "./types/c
 // them. The job-runner keys cron scheduling off the name, the config-resolver
 // off the key.
 export const SOFT_DELETE_CLEANUP_JOB = "soft-delete:job:cleanup";
+export const SOFT_DELETE_CLEANUP_SYSTEM_JOB = "soft-delete:job:cleanup-system";
 export const SOFT_DELETE_GRACE_DAYS_KEY = "soft-delete:config:grace-days";
 export const DEFAULT_GRACE_DAYS = 30;
 
@@ -62,16 +63,42 @@ export const softDeleteCleanupJob: JobHandlerFn = async (_payload, ctx) => {
     if (proj.isImplicit !== true || typeof proj.source !== "string" || !proj.table) continue;
     const entity = registry.getEntity(proj.source);
     if (!entity?.softDelete) continue;
-    const where: WhereObject = { isDeleted: true, deletedAt: { lt: cutoff } };
     // @cast-boundary column-presence probe — identical access the executor's
     // list() does on table["tenantId"] to decide tenant-scoping.
-    if ((proj.table as Record<string, unknown>)["tenantId"] !== undefined) {
-      where["tenantId"] = tenantId;
-    }
+    const hasTenantColumn = (proj.table as Record<string, unknown>)["tenantId"] !== undefined;
+    // System-global entities (no tenantId column, e.g. `user`) are NOT swept
+    // here: this handler runs once PER TENANT, so a tenant-scoped grace value
+    // would purge every OTHER tenant's still-within-grace rows too (effective
+    // grace = min() across all tenants). softDeleteCleanupSystemJob handles
+    // these separately, once, with a fixed grace period.
+    if (!hasTenantColumn) continue;
+    const where: WhereObject = { isDeleted: true, deletedAt: { lt: cutoff }, tenantId };
     await deleteMany(db, proj.table, where);
   }
 };
 
+// System-global soft-deleted entities (no tenantId column) can't take a
+// per-tenant grace period — there's no "this tenant's view" of a row that
+// isn't scoped to any tenant. Runs once (not perTenant) with a fixed grace
+// period; a future system-scope config key could make this configurable
+// without reintroducing the per-tenant-fanout bug.
+export const softDeleteCleanupSystemJob: JobHandlerFn = async (_payload, ctx) => {
+  const { db, registry } = ctx;
+  if (!db || !registry) {
+    throw new Error(
+      "soft-delete system cleanup: ctx.db + ctx.registry required (JobContext incomplete)",
+    );
+  }
+  const cutoff = Temporal.Now.instant().subtract({ hours: DEFAULT_GRACE_DAYS * 24 });
+  for (const proj of registry.getAllProjections().values()) {
+    if (proj.isImplicit !== true || typeof proj.source !== "string" || !proj.table) continue;
+    const entity = registry.getEntity(proj.source);
+    if (!entity?.softDelete) continue;
+    if ((proj.table as Record<string, unknown>)["tenantId"] !== undefined) continue;
+    await deleteMany(db, proj.table, { isDeleted: true, deletedAt: { lt: cutoff } });
+  }
+};
+
 export function buildSoftDeleteCleanupJob(): JobDefinition {
   return {
     name: SOFT_DELETE_CLEANUP_JOB,
@@ -82,3 +109,13 @@ export function buildSoftDeleteCleanupJob(): JobDefinition {
     runIn: "worker",
   };
 }
+
+export function buildSoftDeleteCleanupSystemJob(): JobDefinition {
+  return {
+    name: SOFT_DELETE_CLEANUP_SYSTEM_JOB,
+    handler: softDeleteCleanupSystemJob,
+    trigger: { cron: "15 3 * * *" },
+    concurrency: "skip",
+    runIn: "worker",
+  };
+}

package/src/engine/steps/unsafe-projection-delete.ts

@@ -16,6 +16,7 @@
 // must commit in the same TX as the aggregate-mutation that triggered
 // it (stronger consistency than an async projection). Reviewer judges.
 
+import type { EntityTableMeta } from "../../db/entity-table-meta";
 import { deleteMany, type WhereObject } from "../../db/query";
 import { defineStep } from "../define-step";
 import type { PipelineCtx, StepInstance, StepResolver } from "../types/step";
@@ -36,7 +37,10 @@ defineStep<UnsafeProjectionDeleteArgs, void>({
   defaultFailureStrategy: "throw",
   run: async (args, ctx: PipelineCtx) => {
     const where = resolveRequired(args.where, ctx);
-    await deleteMany(ctx.db.raw, args.table, where);
+    // The `unsafe*`-step IS the sanctioned direct projection write — it exists
+    // to bypass the executor deliberately (boot-validated allowlist + reviewer
+    // gate). The brand-strip cast makes that explicit at the one blessed seam.
+    await deleteMany(ctx.db.raw, args.table as EntityTableMeta, where);
   },
 });
 

package/src/engine/tier-resolver-extension.ts

@@ -81,6 +81,17 @@ export type TierResolverPlugin = {
  * Geteilter helper für runDevApp + runProdApp damit der Pickup-Pfad
  * bit-identisch ist (drift-resistent).
  */
+/** Narrows a registration's untyped `options` bag to the tier-resolver
+ *  plugin shape — the only thing every implementation must provide is the
+ *  `build` factory. */
+export function isTierResolverPlugin(v: unknown): v is TierResolverPlugin {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    typeof (v as Record<string, unknown>)["build"] === "function"
+  );
+}
+
 export function findTierResolverUsage(
   features: readonly FeatureDefinition[],
 ): RegistrarExtensionRegistration | undefined {

package/src/engine/types/feature.ts

@@ -62,7 +62,11 @@ import type {
 } from "./hooks";
 import type { HttpRouteDefinition } from "./http-route";
 import type { NavDefinition } from "./nav";
-import type { MultiStreamProjectionDefinition, ProjectionDefinition } from "./projection";
+import type {
+  EntityProjectionExtension,
+  MultiStreamProjectionDefinition,
+  ProjectionDefinition,
+} from "./projection";
 import type { EntityRelations, RelationDefinition } from "./relations";
 import type { ScreenDefinition } from "./screen";
 import type { TreeActionDef, TreeActionsHandle, TreeChildrenSubscribe } from "./tree-node";
@@ -181,26 +185,15 @@ export type UnmanagedTableDef = UnmanagedTableEntry & {
 // Keep this list lean. Anything that already has a home on the feature
 // (configKeys.scope/default/encrypted, secretKeys, requires, etc.) lives there.
 // Only add fields here that are genuinely UI-only.
-export type UiHintOption =
-  | {
-      readonly key: string;
-      readonly label: string;
-      readonly type: "boolean";
-      readonly default: boolean;
-    }
-  | {
-      readonly key: string;
-      readonly label: string;
-      readonly type: "select";
-      readonly options: readonly string[];
-      readonly default: string;
-    }
-  | {
-      readonly key: string;
-      readonly label: string;
-      readonly type: "text";
-      readonly default?: string;
-    };
+// "select"/"text" variants dropped (569/1) — no bundled feature uses anything
+// but "boolean" yet and the picker doesn't render them either; re-add once a
+// real feature needs them.
+export type UiHintOption = {
+  readonly key: string;
+  readonly label: string;
+  readonly type: "boolean";
+  readonly default: boolean;
+};
 
 export type UiHints = {
   // Picker-facing label ("Auth · Email + Password" instead of the bare
@@ -310,6 +303,12 @@ export type FeatureDefinition = {
   // Projections declared via r.projection(). Keyed by projection name; executor
   // looks them up by source-entity at write-time.
   readonly projections: Readonly<Record<string, ProjectionDefinition>>;
+  // Implicit-projection extensions declared via r.extendEntityProjection().
+  // Keyed by entity name; merged into that entity's implicit projection at
+  // registry build so rebuildProjection replays the extension's events.
+  readonly entityProjectionExtensions?: Readonly<
+    Record<string, readonly EntityProjectionExtension[]>
+  >;
   // Multi-stream projections — cross-aggregate async read-models. Keyed by
   // short name; the dispatcher wraps each into an EventConsumer with its
   // own cursor.
@@ -624,6 +623,15 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   // per-consumer ordering and dead-letter behaviour.
   multiStreamProjection(definition: MultiStreamProjectionDefinition): void;
 
+  // Merge extra apply handlers (+ extra event sources) into an entity's
+  // implicit projection so rebuildProjection replays event types a bundled
+  // extension materializes into the HOST entity's table (custom-fields
+  // pattern). Rebuild-only: the inline runner skips implicit projections —
+  // live delivery stays with the extension's own MSP. The entity must be
+  // declared via r.entity in the SAME feature; unknown entities and
+  // apply-key collisions fail at registry build.
+  extendEntityProjection(entityName: string, extension: EntityProjectionExtension): void;
+
   // Register a function that contributes claims into SessionUser.claims at
   // login time. Multiple features (and multiple calls within one feature)
   // are allowed; returns are merged. Keys are auto-prefixed with the feature