@cosmicdrift/kumiko-framework 0.70.0 → 0.72.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.70.0",
+  "version": "0.72.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -181,7 +181,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.70.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.72.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/__tests__/schema-cli-rebuild.integration.test.ts

@@ -173,4 +173,19 @@ describe("runSchemaCli apply — projection rebuild", () => {
     expect(cap.log.join("\n")).not.toContain("Rebuild");
     expect(await counterFor(group)).toBeUndefined();
   });
+
+  // Marker zeigt auf eine Tabelle die KEINE registrierte Projektion hat →
+  // projections.size === 0 → Early-Return vor dem Rebuild-Schritt (kein Throw,
+  // exit 0). Bisher nur "kein Marker" und "keine Features" getestet.
+  test("with features: marker for a table with no registered projection → no rebuild, exit 0", async () => {
+    await executor.create({ groupId: group, name: "x" }, admin, tdb);
+
+    const appCwd = writeMigration("0004_unknown_table", ["read_nonexistent_table"]);
+    const cap = captureOut();
+    const code = await runSchemaCli(["apply"], appCwd, cap.out, { features: [feature] });
+
+    expect(code).toBe(0);
+    expect(cap.log.join("\n")).not.toContain("Rebuild");
+    expect(await counterFor(group)).toBeUndefined();
+  });
 });

package/src/api/auth-middleware.ts

@@ -24,8 +24,10 @@ export type AuthTransport = "cookie" | "bearer";
 
 // Status of a sid from the server's perspective. The sessions feature owns
 // the DB-backed implementation; middleware just consults whatever function
-// the app wires in.
-export type AuthSessionStatus = "live" | "revoked" | "expired" | "missing";
+// the app wires in. "blocked" = sid is live but the user it belongs to is
+// locked (restricted/deleted) — defense-in-depth so a missed session-revoke
+// can't keep a locked account authenticated.
+export type AuthSessionStatus = "live" | "revoked" | "expired" | "missing" | "blocked";
 
 // Called by the middleware after JWT-verify. Gets the sid AND the expected
 // userId from the JWT's `sub` — the checker MUST confirm the session row

package/src/db/__tests__/assert-exists-in.integration.test.ts

@@ -66,6 +66,16 @@ describe("assertExistsIn — DbConnection + explizite tenantId", () => {
     });
     expect(r).toBeInstanceOf(NotFoundError);
   });
+
+  test("zusätzliches where matcht → null (existiert)", async () => {
+    const r = await assertExistsIn(stack.db, orderTable, {
+      field: "id",
+      value: ID_A,
+      tenantId: tenantA,
+      where: { name: "A-Order" },
+    });
+    expect(r).toBeNull();
+  });
 });
 
 describe("assertExistsIn — TenantDb auto-filter", () => {
@@ -79,6 +89,12 @@ describe("assertExistsIn — TenantDb auto-filter", () => {
     const r = await assertExistsIn(dbA, orderTable, { field: "id", value: ID_B });
     expect(r).toBeInstanceOf(NotFoundError);
   });
+
+  test("fehlende Row via TenantDb → NotFoundError", async () => {
+    const dbA = createTenantDb(stack.db, tenantA, "tenant");
+    const r = await assertExistsIn(dbA, orderTable, { field: "id", value: MISSING });
+    expect(r).toBeInstanceOf(NotFoundError);
+  });
 });
 
 describe("assertExistsIn — Fehler-Benennung + where", () => {

package/src/db/__tests__/eagerload.integration.test.ts

@@ -109,6 +109,23 @@ describe("enrichWithReferences", () => {
     expect(single(row, "author")).toBeUndefined();
   });
 
+  // multiple-ref-Contract: IMMER ein Array (gefiltert), nie undefined — anders
+  // als single (oben). Ein Renderer kann auf .map() vertrauen ohne null-Check.
+  test("multiple-ref filtert cross-tenant raus, behält den Rest als Array", async () => {
+    const row = await enrichA({ id: "p1", tags: [A1, BX] });
+    expect(many(row, "tags")?.map((t) => t["name"])).toEqual(["Ada"]);
+  });
+
+  test("multiple-ref nur cross-tenant → [] (leeres Array, NICHT undefined)", async () => {
+    const row = await enrichA({ id: "p1", tags: [BX] });
+    expect(many(row, "tags")).toEqual([]);
+  });
+
+  test("multiple-ref null → [] (leeres Array, NICHT undefined)", async () => {
+    const row = await enrichA({ id: "p1", tags: null });
+    expect(many(row, "tags")).toEqual([]);
+  });
+
   test("TENANT-ISOLATION: cross-tenant-ref wird NICHT aufgelöst", async () => {
     // bx gehört tenantB; dbA ist auf tenantA gescoped → der Lookup filtert
     // ihn raus, _refs bleibt undefined (Renderer fällt auf die UUID zurück).

package/src/db/__tests__/event-store-executor.integration.test.ts

@@ -104,6 +104,20 @@ describe("event-store-executor", () => {
     const detail = await crud.detail({ id: created.data.id }, adminUser, tdb);
     expect(detail).toBeNull();
   });
+
+  test("list hides soft-deleted rows; includeDeleted returns them (trash query)", async () => {
+    const created = await crud.create({ email: "trash@test.de" }, adminUser, tdb);
+    if (!created.isSuccess) throw new Error("setup failed");
+    await crud.delete({ id: created.data.id }, adminUser, tdb);
+
+    const live = await crud.list({}, adminUser, tdb);
+    expect(live.rows.find((r) => r["id"] === created.data.id)).toBeUndefined();
+
+    const trash = await crud.list({}, adminUser, tdb, { includeDeleted: true });
+    const row = trash.rows.find((r) => r["id"] === created.data.id);
+    expect(row).toBeDefined();
+    expect(row?.["isDeleted"]).toBe(true);
+  });
 });
 
 // Sensitive-field stripping: passwords/tokens/IBANs stay in the entity row

package/src/db/event-store-executor.ts

@@ -218,7 +218,14 @@ export type EventStoreExecutor = {
      *  hier zur Runtime einen aus ctx.searchAdapter durchreichen.
      *  options.searchAdapter (build-time) gewinnt — runtime-Override
      *  ist Fallback für die default-Wrapper. */
-    runtimeOptions?: { readonly searchAdapter?: SearchAdapter },
+    runtimeOptions?: {
+      readonly searchAdapter?: SearchAdapter;
+      // Trash query: skip the implicit `isDeleted = FALSE` filter so soft-
+      // deleted rows are returned too. Tenant + ownership clauses still apply
+      // — includeDeleted only relaxes the soft-delete predicate, never the
+      // visibility ones, so it can ride untrusted query input safely.
+      readonly includeDeleted?: boolean;
+    },
   ) => Promise<CursorResult<Record<string, unknown>>>;
 
   detail: (
@@ -862,7 +869,7 @@ export function createEventStoreExecutor(
         params.push(db.tenantId, SYSTEM_TENANT_ID);
         whereSql.push(`${colSql("tenantId")} IN ($${params.length - 1}, $${params.length})`);
       }
-      if (softDelete && table["isDeleted"]) {
+      if (softDelete && table["isDeleted"] && runtimeOptions?.includeDeleted !== true) {
         whereSql.push(`${colSql("isDeleted")} = FALSE`);
       }
       if (payload.cursor) {

package/src/engine/__tests__/boot-validator.test.ts

@@ -2016,6 +2016,7 @@ describe("boot-validator", () => {
   describe("entityList rowAction row-meta allowlist (#331, #323)", () => {
     function makeFeature(opts: {
       pick?: readonly string[];
+      map?: Record<string, string>;
       visibleField?: string;
       softDelete?: boolean;
     }) {
@@ -2038,6 +2039,7 @@ describe("boot-validator", () => {
               label: "actions.archive",
               handler: "shop:write:archive",
               ...(opts.pick ? { payload: { pick: [...opts.pick] } } : {}),
+              ...(opts.map ? { payload: { map: { ...opts.map } } } : {}),
               ...(opts.visibleField ? { visible: { field: opts.visibleField, eq: true } } : {}),
             },
           ],
@@ -2071,6 +2073,16 @@ describe("boot-validator", () => {
       );
     });
 
+    test("map-Extractor mit Base-Column tenantId → kein Throw", () => {
+      expect(() => validateBoot([makeFeature({ map: { target: "tenantId" } })])).not.toThrow();
+    });
+
+    test("map-Extractor mit unknown Field → Throw", () => {
+      expect(() => validateBoot([makeFeature({ map: { target: "ghost" } })])).toThrow(
+        /payload references unknown field "ghost"/,
+      );
+    });
+
     test("softDelete-Entity: pick isDeleted → kein Throw", () => {
       expect(() =>
         validateBoot([makeFeature({ pick: ["id", "isDeleted"], softDelete: true })]),

package/src/engine/__tests__/engine.test.ts

@@ -241,6 +241,39 @@ describe("defineFeature", () => {
 
     expect(rolesOf(feature.writeHandlers["user:invite"]?.access)).toEqual(["Admin", "SystemAdmin"]);
   });
+
+  test("r.uiHints() flows into the definition", () => {
+    const feature = defineFeature("test", (r) => {
+      r.uiHints({
+        displayLabel: "Test Feature",
+        category: "demo",
+        recommended: true,
+        configurableOptions: [
+          { key: "fancy", label: "Fancy mode", type: "boolean", default: false },
+        ],
+      });
+    });
+    expect(feature.uiHints?.displayLabel).toBe("Test Feature");
+    expect(feature.uiHints?.category).toBe("demo");
+    expect(feature.uiHints?.recommended).toBe(true);
+    expect(feature.uiHints?.configurableOptions).toEqual([
+      { key: "fancy", label: "Fancy mode", type: "boolean", default: false },
+    ]);
+  });
+
+  test("uiHints is absent when r.uiHints() is not called", () => {
+    const feature = defineFeature("test", () => {});
+    expect("uiHints" in feature).toBe(false);
+  });
+
+  test("r.uiHints() throws when called twice", () => {
+    expect(() =>
+      defineFeature("test", (r) => {
+        r.uiHints({ displayLabel: "A" });
+        r.uiHints({ displayLabel: "B" });
+      }),
+    ).toThrow(/r\.uiHints\(\) called twice/);
+  });
 });
 
 // --- Field Factories ---

package/src/engine/__tests__/feature-manifest.test.ts

@@ -84,4 +84,24 @@ describe("buildManifestFromRegistry — deterministic codepoint sort (#330)", ()
     expect(manifest.tier).toBeUndefined();
     expect(manifest.features[0]?.tier).toBeUndefined();
   });
+
+  test("uiHints flow through to the manifest when set", () => {
+    const registry = createRegistry([
+      defineFeature("with-hints", (r) => {
+        r.uiHints({ displayLabel: "With Hints", category: "demo", recommended: true });
+      }),
+      defineFeature("no-hints", () => {}),
+    ]);
+
+    const manifest = buildManifestFromRegistry(registry, { source: "test" });
+    const withHints = manifest.features.find((f) => f.name === "with-hints");
+    const noHints = manifest.features.find((f) => f.name === "no-hints");
+
+    expect(withHints?.uiHints).toEqual({
+      displayLabel: "With Hints",
+      category: "demo",
+      recommended: true,
+    });
+    expect(noHints && "uiHints" in noHints).toBe(false);
+  });
 });

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

@@ -0,0 +1,129 @@
+import { describe, expect, test } from "bun:test";
+import { defineFeature } from "../define-feature";
+import { createRegistry } from "../registry";
+import {
+  DEFAULT_GRACE_DAYS,
+  SOFT_DELETE_CLEANUP_JOB,
+  SOFT_DELETE_GRACE_DAYS_KEY,
+  softDeleteCleanupJob,
+} from "../soft-delete-cleanup";
+import type { AppContext } from "../types/handlers";
+
+function featureWith(softDelete: boolean | undefined) {
+  return defineFeature("probe-sd", (r) => {
+    r.entity("thing", {
+      fields: { label: { type: "text" } },
+      ...(softDelete !== undefined && { softDelete }),
+    });
+  });
+}
+
+describe("registry soft-delete auto-wiring", () => {
+  test("injects cleanup job + grace-days config when an entity opts into softDelete", () => {
+    const registry = createRegistry([featureWith(true)]);
+    expect(registry.getAllJobs().has(SOFT_DELETE_CLEANUP_JOB)).toBe(true);
+    expect(registry.getAllConfigKeys().has(SOFT_DELETE_GRACE_DAYS_KEY)).toBe(true);
+    const job = registry.getJob(SOFT_DELETE_CLEANUP_JOB);
+    expect(job?.trigger).toEqual({ cron: "0 3 * * *" });
+    expect(job?.perTenant).toBe(true);
+    const key = registry.getConfigKey(SOFT_DELETE_GRACE_DAYS_KEY);
+    expect(key?.type).toBe("number");
+    expect(key?.default).toBe(DEFAULT_GRACE_DAYS);
+  });
+
+  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.getAllConfigKeys().has(SOFT_DELETE_GRACE_DAYS_KEY)).toBe(false);
+  });
+});
+
+type DeleteCall = { table: unknown; where: Record<string, unknown> };
+
+function makeCtx(opts: { graceDays?: number; calls: DeleteCall[] }): AppContext {
+  // Shaped to satisfy bun-db's tenantDbDelegate() probe so deleteMany() routes
+  // to this recorder instead of trying to extract real table metadata.
+  const fakeDb = {
+    tenantId: "t1",
+    raw: { unsafe: async () => [] },
+    selectMany: async () => [],
+    fetchOne: async () => undefined,
+    insertOne: async () => undefined,
+    updateMany: async () => [],
+    deleteMany: async (table: unknown, where: Record<string, unknown>) => {
+      opts.calls.push({ table, where });
+    },
+  };
+  const projections = new Map<string, unknown>([
+    // softDelete entity WITH a tenantId column → tenant-scoped delete
+    ["thing~impl", { isImplicit: true, source: "thing", table: { tenantId: {}, isDeleted: {} } }],
+    // softDelete entity WITHOUT a tenantId column → system-global delete
+    ["sys~impl", { isImplicit: true, source: "sysThing", table: { isDeleted: {} } }],
+    // softDelete:false entity → skipped
+    [
+      "audit~impl",
+      { isImplicit: true, source: "auditEntry", table: { tenantId: {}, isDeleted: {} } },
+    ],
+    // explicit (non-implicit) projection → skipped
+    ["custom", { isImplicit: false, source: "thing", table: { isDeleted: {} } }],
+  ]);
+  const registry = {
+    getAllProjections: () => projections,
+    getEntity: (name: string) =>
+      ({
+        thing: { softDelete: true },
+        sysThing: { softDelete: true },
+        auditEntry: { softDelete: false },
+      })[name],
+  };
+  return {
+    db: fakeDb,
+    registry,
+    systemUser: { tenantId: "t1" },
+    ...(opts.graceDays !== undefined && {
+      configResolver: { get: async () => opts.graceDays },
+    }),
+  } as unknown as AppContext;
+}
+
+describe("softDeleteCleanupJob handler", () => {
+  test("hard-deletes only softDelete implicit projections, tenant-scoped where the table has tenantId", async () => {
+    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();
+    }
+  });
+
+  test("cutoff defaults to DEFAULT_GRACE_DAYS when no config resolver", async () => {
+    const calls: DeleteCall[] = [];
+    await softDeleteCleanupJob({}, 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("honours a per-tenant grace-days value from the config resolver", async () => {
+    const calls: DeleteCall[] = [];
+    await softDeleteCleanupJob({}, makeCtx({ calls, graceDays: 7 }));
+    const cutoff = (calls[0]?.where["deletedAt"] as { lt: Temporal.Instant }).lt;
+    const expected = Temporal.Now.instant().subtract({ hours: 7 * 24 });
+    expect(Math.abs(cutoff.epochMilliseconds - expected.epochMilliseconds)).toBeLessThan(10_000);
+  });
+
+  test("throws when the job context is missing db/registry", async () => {
+    await expect(softDeleteCleanupJob({}, {} as AppContext)).rejects.toThrow(
+      /ctx.db \+ ctx.registry/,
+    );
+  });
+});

package/src/engine/define-feature.ts

@@ -63,6 +63,7 @@ import type {
   TreeActionDef,
   TreeActionsHandle,
   TreeChildrenSubscribe,
+  UiHints,
   UnmanagedTableEntry,
   ValidationHookFn,
   WriteHandlerDef,
@@ -157,6 +158,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
   let isSystemScoped = false;
   let toggleableDefault: boolean | undefined;
   let description: string | undefined;
+  let uiHints: UiHints | undefined;
   // Visual-Tree-Slots — at-most-one per feature, only-once-guard im
   // registrar (siehe r.treeActions / r.tree). Undefined wenn das Feature
   // keinen Visual-Tree-Beitrag liefert (Zero-Whitelist-Filter).
@@ -240,6 +242,13 @@ export function defineFeature<const TName extends string, TExports = undefined>(
       toggleableDefault = options.default;
     },
 
+    uiHints(hints: UiHints): void {
+      if (uiHints !== undefined) {
+        throw new Error(`[Feature ${name}] r.uiHints() called twice — UI hints are declared once`);
+      }
+      uiHints = hints;
+    },
+
     entity(
       entityName: string,
       definition: EntityDefinition,
@@ -944,6 +953,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
     requiredProjections,
     requiredSteps,
     ...(toggleableDefault !== undefined && { toggleableDefault }),
+    ...(uiHints !== undefined && { uiHints }),
     entities,
     entityTables,
     relations,

package/src/engine/entity-handlers.ts

@@ -85,6 +85,10 @@ const listSchema = z.object({
   sortDirection: z.enum(["asc", "desc"]).optional(),
   offset: z.number().int().nonnegative().optional(),
   totalCount: z.boolean().optional(),
+  // Trash query: include soft-deleted rows. Honoured only for softDelete
+  // entities; the dispatcher mirrors it onto ctx.includeDeleted. Tenant +
+  // ownership filters still apply.
+  includeDeleted: z.boolean().optional(),
   filter: z
     .object({
       field: z.string(),
@@ -219,6 +223,7 @@ export function defineEntityQueryHandler(
         const listPayload = query.payload as ListPayload; // @cast-boundary engine-payload
         const result = await executor.list(listPayload, query.user, ctx.db, {
           ...(ctx.searchAdapter !== undefined && { searchAdapter: ctx.searchAdapter }),
+          ...(ctx.includeDeleted === true && { includeDeleted: true }),
         });
         if (!hasRefFields) return result;
         const enrichedRows = await enrichWithReferences(

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

@@ -5,6 +5,7 @@ export {
   extractRequires,
   extractSystemScope,
   extractToggleable,
+  extractUiHints,
 } from "./round1";
 export {
   extractEntity,

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

@@ -6,6 +6,7 @@ import type {
   RequiresPattern,
   SystemScopePattern,
   ToggleablePattern,
+  UiHintsPattern,
 } from "../patterns";
 import { sourceLocationFromNode } from "../source-location";
 import {
@@ -84,6 +85,16 @@ export function extractSystemScope(
   });
 }
 
+export function extractUiHints(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<UiHintsPattern> {
+  return ok({
+    kind: "uiHints",
+    source: sourceLocationFromNode(call, sourceFile),
+  });
+}
+
 export function extractDescribe(
   call: CallExpression,
   sourceFile: SourceFile,

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

@@ -58,6 +58,7 @@ import {
   extractTranslations,
   extractTree,
   extractTreeActions,
+  extractUiHints,
   extractUnmanagedTable,
   extractUseExtension,
   extractUsesApi,
@@ -301,6 +302,8 @@ function dispatchExtractor(
       return extractToggleable(call, sourceFile);
     case "describe":
       return extractDescribe(call, sourceFile);
+    case "uiHints":
+      return extractUiHints(call, sourceFile);
     // Round 2 — object-literal-based static patterns
     case "entity":
       return extractEntity(call, sourceFile);

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

@@ -80,6 +80,7 @@ export type PatternId =
   | { readonly kind: "systemScope" }
   | { readonly kind: "toggleable" }
   | { readonly kind: "describe" }
+  | { readonly kind: "uiHints" }
   | { readonly kind: "config" }
   | { readonly kind: "translations" }
   | { readonly kind: "authClaims" }
@@ -272,6 +273,7 @@ export const SINGLETON_KINDS: ReadonlySet<PatternId["kind"]> = new Set([
   "systemScope",
   "toggleable",
   "describe",
+  "uiHints",
   "config",
   "translations",
   "authClaims",
@@ -329,6 +331,7 @@ function callMatchesId(call: CallExpression, id: PatternId): boolean {
     case "systemScope":
     case "toggleable":
     case "describe":
+    case "uiHints":
     case "config":
     case "translations":
     case "authClaims":

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

@@ -203,6 +203,16 @@ export type DescribePattern = {
   readonly text: string;
 };
 
+// `r.uiHints({ displayLabel, category, recommended, configurableOptions })` —
+// picker/scaffolder UI metadata that flows into feature-manifest.json under
+// `feature.uiHints`. Tracked as opaque here (no structured re-parse): the
+// picker reads the manifest, not the AST. The pattern exists so the
+// UnknownPattern dispatcher doesn't trip on a new r.* call.
+export type UiHintsPattern = {
+  readonly kind: "uiHints";
+  readonly source: SourceLocation;
+};
+
 // `r.metric(shortName, options)` — declares a metric under its short name
 // (without the `kumiko_<feature>_` prefix; the framework qualifies it at
 // boot and validates snake_case + type suffix). Runtime usage:
@@ -590,6 +600,7 @@ export type FeaturePattern =
   | SystemScopePattern
   | ToggleablePattern
   | DescribePattern
+  | UiHintsPattern
   | MetricPattern
   | SecretPattern
   | ClaimKeyPattern
@@ -675,6 +686,7 @@ export function getEditability(pattern: FeaturePattern): Editability {
     case "extendsRegistrar":
     case "tree":
     case "envSchema":
+    case "uiHints":
     case "unknown":
       return "opaque";
     default: {

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

@@ -50,6 +50,7 @@ import type {
   TranslationsPattern,
   TreeActionsPattern,
   TreePattern,
+  UiHintsPattern,
   UnknownPattern,
   UseExtensionPattern,
   UsesApiPattern,
@@ -80,6 +81,8 @@ export function renderPattern(pattern: FeaturePattern): string {
       return renderToggleable(pattern);
     case "describe":
       return renderDescribe(pattern);
+    case "uiHints":
+      return renderUiHints(pattern);
     case "entity":
       return renderEntity(pattern);
     case "relation":
@@ -517,6 +520,10 @@ function renderExposesApi(p: ExposesApiPattern): string {
   return `r.exposesApi(${JSON.stringify(p.apiName)});`;
 }
 
+function renderUiHints(p: UiHintsPattern): string {
+  return p.source.raw;
+}
+
 function renderUnknown(p: UnknownPattern): string {
   // Round-trip preservation only: emit the raw call text from the
   // SourceLocation so the rendered file stays semantically identical

package/src/engine/feature-manifest.ts

@@ -8,7 +8,7 @@
 
 import { compareByCodepoint } from "../utils";
 import { qualifyEntityName } from "./qualified-name";
-import type { Registry } from "./types/feature";
+import type { Registry, UiHints } from "./types/feature";
 
 export type ManifestConfigKey = {
   readonly key: string;
@@ -57,6 +57,10 @@ export type ManifestFeature = {
    *  Von `collectWriteHandlerQns` abgeleitet — dient als Source-of-Truth
    *  für den Client-seitigen Typcheck von `dispatcher.write`-Calls. */
   readonly writeHandlers: readonly string[];
+  /** Picker/scaffolder UI metadata declared via r.uiHints(). Optional —
+   *  absent for features that haven't been annotated yet (the picker falls
+   *  back to feature.name + feature.description). */
+  readonly uiHints?: UiHints;
   /** Optionaler Herkunfts-Tag (z.B. "enterprise") — gesetzt via Options. */
   readonly tier?: string;
 };
@@ -148,6 +152,7 @@ export function buildManifestFromRegistry(
       configKeys,
       secrets,
       writeHandlers: writeHandlerQns,
+      ...(feature.uiHints !== undefined && { uiHints: feature.uiHints }),
       ...(options.tier !== undefined && { tier: options.tier }),
     });
   }

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

@@ -31,6 +31,7 @@ const ALL_KINDS: FeaturePatternKind[] = [
   "systemScope",
   "toggleable",
   "describe",
+  "uiHints",
   "entity",
   "relation",
   "nav",
@@ -200,6 +201,8 @@ function makePlaceholderPattern(kind: FeaturePatternKind): FeaturePattern {
       return { kind, source: PLACEHOLDER_LOC, default: false };
     case "describe":
       return { kind, source: PLACEHOLDER_LOC, text: "x" };
+    case "uiHints":
+      return { kind, source: PLACEHOLDER_LOC };
     case "entity":
       return { kind, source: PLACEHOLDER_LOC, entityName: "x", definition: { fields: {} } };
     case "relation":

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

@@ -194,6 +194,16 @@ const describeSchema: PatternFormSchema = {
   ],
 };
 
+const uiHintsSchema: PatternFormSchema = {
+  kind: "uiHints",
+  label: { en: "UI hints", de: "UI-Hinweise" },
+  summary: { en: "Picker/scaffolder metadata. Opaque to the Designer; rendered as raw TS source." },
+  category: "meta",
+  editability: "opaque",
+  singleton: true,
+  fields: [],
+};
+
 const entitySchema: PatternFormSchema = {
   kind: "entity",
   label: { en: "Entity", de: "Entität" },
@@ -1161,6 +1171,7 @@ export const PATTERN_LIBRARY: Readonly<Record<FeaturePatternKind, PatternFormSch
   systemScope: systemScopeSchema,
   toggleable: toggleableSchema,
   describe: describeSchema,
+  uiHints: uiHintsSchema,
   entity: entitySchema,
   relation: relationSchema,
   nav: navSchema,

package/src/engine/registry.ts

@@ -8,6 +8,12 @@ import { asEntityTableMeta } from "../db/query";
 import { buildEntityTable } from "../db/table-builder";
 import { buildMetricName, validateMetricName } from "../observability";
 import { type QnType, qualifyEntityName } from "./qualified-name";
+import {
+  buildSoftDeleteCleanupJob,
+  SOFT_DELETE_CLEANUP_JOB,
+  SOFT_DELETE_GRACE_DAYS_KEY,
+  softDeleteGraceDaysConfig,
+} from "./soft-delete-cleanup";
 import type {
   AuthClaimsHookDef,
   ClaimKeyDefinition,
@@ -1320,6 +1326,20 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
     return false;
   })();
 
+  // Auto-wire the soft-delete cleanup cron + its grace-days config key when ANY
+  // entity opts into softDelete — the framework owns this machinery, no feature
+  // declares it (mirrors the auto restore-handler). Job-runner reads getAllJobs
+  // ungated; config-resolver reads getConfigKey → default. Reserved owner
+  // segment, guarded against a real-feature collision.
+  if ([...entityMap.values()].some((e) => e.softDelete)) {
+    if (!jobMap.has(SOFT_DELETE_CLEANUP_JOB)) {
+      jobMap.set(SOFT_DELETE_CLEANUP_JOB, buildSoftDeleteCleanupJob());
+    }
+    if (!configKeyMap.has(SOFT_DELETE_GRACE_DAYS_KEY)) {
+      configKeyMap.set(SOFT_DELETE_GRACE_DAYS_KEY, softDeleteGraceDaysConfig);
+    }
+  }
+
   return {
     features: featureMap,
 

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

@@ -0,0 +1,84 @@
+// Auto-generated soft-delete maintenance. Hard-deletes entity rows that have
+// been soft-deleted longer than the per-tenant grace period. Injected into the
+// registry (the job + its config key) whenever ANY entity opts into softDelete
+// — see createRegistry. Runtime twin to the auto restore-handler: softDelete:
+// true buys an entity restore + trash (ctx.includeDeleted) + this cleanup, with
+// no feature to wire.
+//
+// Hard-deleting the projection row leaves the event stream intact (source of
+// truth) — a full projection rebuild would replay created+deleted and
+// resurrect the row as isDeleted=true. That's acceptable: cleanup bounds LIVE
+// table growth; irreversible event-log purging is data-retention's job
+// (pruneEvents), a separate, consumer-lag-guarded path.
+
+import { deleteMany, type WhereObject } from "../db/query";
+import { SYSTEM_USER_ID } from "./system-user";
+import type { ConfigKeyDefinition, JobDefinition, JobHandlerFn } from "./types/config";
+
+// qualifyEntityName convention (feature:type:kebab-name) with a reserved
+// "soft-delete" owner — no real feature owns these; the framework synthesizes
+// 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_GRACE_DAYS_KEY = "soft-delete:config:grace-days";
+export const DEFAULT_GRACE_DAYS = 30;
+
+export const softDeleteGraceDaysConfig: ConfigKeyDefinition = {
+  type: "number",
+  default: DEFAULT_GRACE_DAYS,
+  scope: "tenant",
+  access: { read: ["TenantAdmin", "SystemAdmin"], write: ["SystemAdmin"] },
+  bounds: { min: 0 },
+};
+
+export const softDeleteCleanupJob: JobHandlerFn = async (_payload, ctx) => {
+  const { db, registry } = ctx;
+  if (!db || !registry) {
+    throw new Error("soft-delete cleanup: ctx.db + ctx.registry required (JobContext incomplete)");
+  }
+  // perTenant fan-out → one run per active tenant, systemUser scoped to it.
+  // The job's db is the boot DbConnection (NOT tenant-scoped), so every delete
+  // is explicitly tenant-filtered below — otherwise a tenant with a short grace
+  // would purge another tenant's still-within-grace rows.
+  const tenantId = ctx.systemUser?.tenantId ?? ctx._tenantId;
+  if (tenantId === undefined) {
+    // skip: cron fired without a perTenant fan-out tenant — nothing scoped to purge
+    return;
+  }
+
+  const resolved = ctx.configResolver
+    ? await ctx.configResolver.get(
+        SOFT_DELETE_GRACE_DAYS_KEY,
+        softDeleteGraceDaysConfig,
+        tenantId,
+        SYSTEM_USER_ID,
+        db,
+      )
+    : undefined;
+  const graceDays = typeof resolved === "number" && resolved >= 0 ? resolved : DEFAULT_GRACE_DAYS;
+  const cutoff = Temporal.Now.instant().subtract({ hours: graceDays * 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;
+    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;
+    }
+    await deleteMany(db, proj.table, where);
+  }
+};
+
+export function buildSoftDeleteCleanupJob(): JobDefinition {
+  return {
+    name: SOFT_DELETE_CLEANUP_JOB,
+    handler: softDeleteCleanupJob,
+    trigger: { cron: "0 3 * * *" },
+    perTenant: true,
+    concurrency: "skip",
+    runIn: "worker",
+  };
+}

package/src/engine/types/feature.ts

@@ -171,6 +171,51 @@ export type UnmanagedTableDef = UnmanagedTableEntry & {
   readonly featureName: string;
 };
 
+// --- UI-Hints (manifest-only, picker/scaffolder metadata) ---
+
+// Optional, declarative UI metadata declared via `r.uiHints({...})`. Surfaces
+// in feature-manifest.json under `feature.uiHints`. Consumers (the picker in
+// `create-kumiko-app`, the docs feature-reference) treat absent hints as
+// "no special treatment" — bare feature.name + feature.description still work.
+//
+// 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;
+    };
+
+export type UiHints = {
+  // Picker-facing label ("Auth · Email + Password" instead of the bare
+  // feature-name "auth-email-password").
+  readonly displayLabel?: string;
+  // Grouping for the picker. Free-form string; the picker sorts/groups by it.
+  readonly category?: string;
+  // Pre-checked in the picker when the user runs `bun create kumiko-app`.
+  readonly recommended?: boolean;
+  // Sub-options the picker asks about per-feature (e.g. "Password-Reset-Flow
+  // on/off"). The scaffolder maps each key to a generator decision; the
+  // framework doesn't act on them at runtime.
+  readonly configurableOptions?: readonly UiHintOption[];
+};
+
 // --- Feature Definition (output of defineFeature) ---
 
 export type FeatureDefinition = {
@@ -197,6 +242,9 @@ export type FeatureDefinition = {
   // means the feature is always-on (e.g. auth, tenant, user — core infra
   // that would brick the system if switchable).
   readonly toggleableDefault?: boolean;
+  // Declarative UI metadata for picker/scaffolder tooling. Set via r.uiHints().
+  // Pure manifest-side info — the framework runtime doesn't read it.
+  readonly uiHints?: UiHints;
   // entities/hooks/entityHooks are optional: defineFeature always
   // materializes them, but hand-built definitions at system boundaries
   // (test fixtures, partial boots — see registry.test.ts "slot robustness")
@@ -365,6 +413,8 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   // feature; calling on an always-on feature (e.g. auth/tenant/user) is a
   // bug — and one nothing catches at boot, so don't.
   toggleable(options: { default: boolean }): void;
+  // Picker/scaffolder metadata — see UiHints. At most once per feature.
+  uiHints(hints: UiHints): void;
 
   entity(
     name: string,

package/src/engine/types/handlers.ts

@@ -329,6 +329,12 @@ export type HandlerContext<TMap extends object = KumikoEventTypeMap> = SharedCon
   readonly triggeredBy?: { readonly id: string; readonly tenantId: TenantId } | null;
   readonly _userId?: string | undefined;
   readonly _handlerType?: string | undefined;
+  // Trash query opt-in (soft-delete). When true, the auto entity-list handler
+  // asks the executor to include soft-deleted rows; a custom query handler can
+  // read it to branch its own logic. Set by the dispatcher from the query
+  // payload's `includeDeleted` field — visibility (tenant/ownership) filters
+  // still apply, so this never widens what a user may see beyond the live list.
+  readonly includeDeleted?: boolean;
 
   readonly query: (qn: string, payload: unknown) => Promise<unknown>;
   readonly queryAs: (user: SessionUser, qn: string, payload: unknown) => Promise<unknown>;

package/src/engine/types/index.ts

@@ -74,6 +74,8 @@ export type {
   SecretKeyDefinition,
   SecretKeyHandle,
   SecretOptions,
+  UiHintOption,
+  UiHints,
   UnmanagedTableDef,
   UnmanagedTableEntry,
 } from "./feature";

package/src/files/__tests__/storage-tracking.integration.test.ts

@@ -200,3 +200,28 @@ describe("tenant-storage-usage MSP", () => {
     ).toBeGreaterThanOrEqual(0);
   });
 });
+
+// The MSP tests above prove upload *accounting*; nothing asserts the file
+// actually comes back. This pins the full HTTP read path (GET /files/:id →
+// provider readStream → response body) — the user-facing roundtrip.
+describe("file download roundtrip (GET /files/:id)", () => {
+  async function download(user: SessionUser, id: string): Promise<Response> {
+    const token = await stack.jwt.sign(user);
+    return stack.app.request(`/api/files/${id}`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+  }
+
+  test("returns the exact bytes that were uploaded", async () => {
+    const id = await upload(admin, "roundtrip.png", LARGE);
+    const res = await download(admin, id);
+    expect(res.status).toBe(200);
+    expect(new Uint8Array(await res.arrayBuffer())).toEqual(LARGE);
+  });
+
+  test("a deleted file is no longer downloadable", async () => {
+    const id = await upload(admin, "gone.png", SMALL);
+    await deleteFile(admin, id);
+    expect((await download(admin, id)).status).toBe(404);
+  });
+});

package/src/files/feature.ts

@@ -19,6 +19,11 @@ export function createFilesFeature(): FeatureDefinition {
     r.describe(
       "Exposes the `fileRef` entity and `createFilesFeature` from the framework core so that uploaded files \u2014 tracked in the `file_refs` table by `createFileRoutes` \u2014 participate in cross-feature hooks: `user-data-rights-defaults` automatically includes file blobs in GDPR exports and forget flows, and future tenant-lifecycle cleanup will delete all refs on tenant destroy. This feature does not add upload or download routes; those remain in the server bootstrap via the `options.files` parameter.",
     );
+    r.uiHints({
+      displayLabel: "Files \u00b7 Metadata",
+      category: "storage",
+      recommended: false,
+    });
     r.entity("fileRef", fileRefEntity);
   });
 }

package/src/migrations/__tests__/pending-rebuilds.integration.test.ts

@@ -200,6 +200,19 @@ describe("pending-rebuilds queue", () => {
     expect(run).toEqual({ rebuilt: [], failed: [], unmapped: [], unresolvedManaged: [] });
   });
 
+  // Zwei applied-Migrations, die dieselbe Tabelle anfassen, dürfen sie nur
+  // EINMAL queuen (interner Set) — sonst rebuildet ein Run dieselbe Projektion
+  // doppelt.
+  test("two applied migrations touching the same table → deduplicated to one entry", async () => {
+    writeRebuildMarker(markerDir, "0006_a.sql", ["read_pending_counts"]);
+    writeRebuildMarker(markerDir, "0006_b.sql", ["read_pending_counts"]);
+    const queued = await queueRebuildsFromMarkers(testDb.db, {
+      migrationsDir: markerDir,
+      appliedIds: ["0006_a", "0006_b"],
+    });
+    expect(queued).toEqual(["read_pending_counts"]);
+  });
+
   // #361: eine managed-Tabelle (Marker tragen nur managed), die in DIESEM Run
   // geleert wurde, aber keine Projektion auflöst = owning-Feature fehlt in der
   // Komposition → laut (unresolvedManaged), aber non-fatal (gedraint, kein Throw).

package/src/pipeline/dispatcher.ts

@@ -247,6 +247,7 @@ export function createDispatcher(
     user: SessionUser,
     tx?: DbTx,
     afterCommitHooks?: AfterCommitHook[],
+    includeDeleted?: boolean,
   ): HandlerContext {
     const isSystem = registry.isHandlerSystemScoped(type);
     // The outer dispatcher receives a DbConnection from the server/stack;
@@ -573,6 +574,7 @@ export function createDispatcher(
       _userId: user.id,
       _tenantId: user.tenantId,
       _handlerType: type,
+      ...(includeDeleted && { includeDeleted: true }),
       ...bridge,
     } as HandlerContext; // @cast-boundary engine-bridge
   }
@@ -773,7 +775,15 @@ export function createDispatcher(
       throw validationErrorFromZod(parsed.error);
     }
 
-    const handlerContext = buildHandlerContext(type, user, tx);
+    // Trash opt-in rides the validated query payload: only the entity-list
+    // schema (and custom query schemas that opt in) carries `includeDeleted`,
+    // so other handlers never see the flag. Visibility filters still apply
+    // downstream (see HandlerContext.includeDeleted) — safe from raw input.
+    const includeDeleted =
+      typeof parsed.data === "object" &&
+      parsed.data !== null &&
+      (parsed.data as Record<string, unknown>)["includeDeleted"] === true; // @cast-boundary validated-payload
+    const handlerContext = buildHandlerContext(type, user, tx, undefined, includeDeleted);
     let result = await handler.handler({ type, payload: parsed.data, user }, handlerContext);
 
     // postQuery-Hooks: fire BEFORE field-access-filter so hooks see raw data

package/src/utils/__tests__/ids.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, test } from "bun:test";
+import { generateId } from "../ids";
+
+// generateId is the row/stream/correlation ID source. The callers rely on
+// it being a UUIDv7 (time-sortable → dense B-Tree indexes), not a v4 — a
+// swap to v4 would silently kill the lexicographic-time ordering the event
+// store and time-range queries depend on. These tests pin that contract.
+const UUID_RX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+describe("generateId", () => {
+  test("returns a well-formed lowercase UUID", () => {
+    expect(generateId()).toMatch(UUID_RX);
+  });
+
+  test("is UUID version 7 (time-sortable, not v4)", () => {
+    // Version nibble lives in the 13th hex digit (index 14 incl. dashes).
+    expect(generateId()[14]).toBe("7");
+  });
+
+  test("is collision-free across a batch", () => {
+    const ids = Array.from({ length: 10_000 }, generateId);
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+});