@cosmicdrift/kumiko-framework 0.105.2 → 0.109.0

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/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

package/src/engine/types/fields.ts

@@ -199,6 +199,11 @@ export type NumberFieldDef = {
   readonly sensitive?: boolean;
   readonly default?: number;
   readonly access?: FieldAccess;
+  // Write-boundary constraints (Zod-level, no migration/storage impact — the
+  // Postgres column stays a plain numeric). Opt-in, so existing entities are
+  // unaffected.
+  readonly min?: number;
+  readonly integer?: boolean;
 } & PiiAnnotations;
 
 /**
@@ -557,6 +562,13 @@ export type DerivedFieldDef = {
 
 export type DerivedFieldsMap = Readonly<Record<string, DerivedFieldDef>>;
 
+/** Client-facing projection of DerivedFieldDef — `derive` is server-only and
+ *  not JSON-safe (would trip the output-walk guard), so the browser schema
+ *  only ever carries `valueType`. A real `Pick`, not a same-shape cast: TS
+ *  itself proves `derive` isn't there instead of a `{ valueType } as
+ *  DerivedFieldDef` cast lying about a field that's actually missing. */
+export type ClientDerivedFieldDef = Pick<DerivedFieldDef, "valueType">;
+
 // --- Entity ---
 
 // --- State Transitions ---

package/src/engine/types/handlers.ts

@@ -40,6 +40,19 @@ export type SessionUser = {
   // When present, middleware can validate that the sid is still alive before
   // accepting the request (session revocation).
   readonly sid?: string;
+  // Set ONLY when the request authenticated via a Personal Access Token
+  // (bearer, PAT_TOKEN_PREFIX). Absent for cookie/JWT logins, which stay
+  // unrestricted. `allowedQns` are the QN globs the token's granted scopes
+  // expand to; the API boundary (routes.ts) rejects any dispatch type not
+  // matched by one of them (fail-closed). `scopes` are the granted scope
+  // names, kept for audit/display only.
+  readonly pat?: {
+    // The token row id — the per-token key for PAT rate limiting. Not the
+    // secret; safe to carry on the principal.
+    readonly tokenId: string;
+    readonly scopes: readonly string[];
+    readonly allowedQns: readonly string[];
+  };
 };
 
 // --- Claim Keys (r.claimKey declarations) ---

package/src/engine/types/index.ts

@@ -83,6 +83,7 @@ export type {
   AnyFileFieldDef,
   BigIntFieldDef,
   BooleanFieldDef,
+  ClientDerivedFieldDef,
   DateFieldDef,
   DecimalFieldDef,
   DefaultCurrency,
@@ -195,6 +196,7 @@ export type { EntityId, TenantId } from "./identifiers";
 export { isSystemTenant, parseTenantId, SYSTEM_TENANT_ID } from "./identifiers";
 export type { NavDefinition } from "./nav";
 export type {
+  EntityProjectionExtension,
   MspErrorMode,
   MspErrorPolicy,
   MultiStreamApplyFn,

package/src/engine/types/projection.ts

@@ -14,17 +14,23 @@ import type { RunIn } from "./config";
 export type ProjectionTable = TableColumns<any>;
 
 // Single-stream projection apply: runs inline in the write-TX of the event
-// it projects. Gets the event + TX-scoped DbRunner — that's it. Inline
-// projections must not spawn further events (no ctx) because they run
-// inside the command's transaction and the framework guarantees a single
-// commit boundary per command.
+// it projects. Gets the event, the TX-scoped DbRunner, and the projection's
+// own `table` (already erased to ProjectionTable). Write through THAT table —
+// it is the only ES-blessed write into a managed projection outside the
+// executor, and it is reachable only here (an arbitrary handler has no such
+// arg), so the write-brand cannot be bypassed by closing over the branded
+// table constant. Inline projections must not spawn further events (no ctx)
+// because they run inside the command's transaction and the framework
+// guarantees a single commit boundary per command.
 //
 // Generic über payload-shape. Default = Record<string, unknown> behält
 // rückwärtskompatibles Verhalten; Konkrete Apply-Handler annotieren
-// `SingleStreamApplyFn<MyPayload>` für typed event.payload-Access.
+// `SingleStreamApplyFn<MyPayload>` für typed event.payload-Access. Der
+// `table`-Param ist additiv — 2-arg-Applies (event, tx) bleiben gültig.
 export type SingleStreamApplyFn<TPayload = Record<string, unknown>> = (
   event: StoredEvent<TPayload>,
   tx: DbRunner,
+  table: ProjectionTable,
 ) => Promise<void>;
 
 // Multi-stream projection apply: runs asynchronously via the event-dispatcher
@@ -45,6 +51,11 @@ export type ProjectionDefinition = {
   // index projections so the executor doesn't scan all projections on every
   // write.
   readonly source: string | readonly string[];
+  // Additional aggregate-types whose events the rebuild replay must include
+  // beyond `source`. Fed by r.extendEntityProjection — an extension can react
+  // to events on foreign streams (e.g. "field-definition") while `source`
+  // keeps meaning "the owning entity" for consumers like soft-delete-cleanup.
+  readonly extraSources?: readonly string[];
   // Drizzle-table the projection materializes into. User owns the schema —
   // framework just guarantees the TX and event delivery.
   readonly table: ProjectionTable;
@@ -61,6 +72,23 @@ export type ProjectionDefinition = {
   readonly isImplicit?: boolean;
 };
 
+// Extension merged into an entity's implicit projection at registry build.
+// Lets a bundled feature that writes into the HOST entity's table via events
+// (custom-fields pattern) hook those event types into the entity's rebuild
+// replay — without it, a rebuild resets everything the extension wrote.
+// Live delivery stays with the extension's own MSP: implicit projections are
+// skipped by the inline runner, so the apply here runs ONLY during rebuild.
+export type EntityProjectionExtension = {
+  // Aggregate-types beyond the entity's own stream whose events the rebuild
+  // must scan (e.g. "field-definition"). Omit when all extension events are
+  // appended on the host entity's stream.
+  readonly sources?: readonly string[];
+  // Keyed by fully-qualified event type. Must not collide with the entity's
+  // built-in lifecycle applies (<entity>.created/updated/...) or another
+  // extension — collisions fail at boot.
+  readonly apply: Readonly<Record<string, SingleStreamApplyFn>>;
+};
+
 // Per-lifecycle error policy for a MultiStreamProjection. Mirrors Marten's
 // Projections.Errors / Projections.RebuildErrors split — a projection can
 // be lenient during steady-state delivery but strict during rebuild (or

package/src/event-store/index.ts

@@ -24,6 +24,14 @@ export {
   streamAllEventsByType,
 } from "./event-store";
 export { createEventsTable, eventsTable } from "./events-schema";
+export {
+  createRebuildDeadLetterTable,
+  listRebuildDeadLetters,
+  type RebuildDeadLetterRow,
+  rebuildDeadLetterTable,
+  recordRebuildDeadLetters,
+  type SkippedApply,
+} from "./rebuild-dead-letter";
 export { toStoredEvent } from "./row-to-stored-event";
 export {
   createSnapshotsTable,