@cosmicdrift/kumiko-framework 0.352.0 → 0.354.0

package/dist/engine/changeset-changes.js

@@ -1,7 +1,7 @@
 import { validateChangelog } from "./feature-changelog.js";
 const BLOCK_RE = /<!--\s*kumiko-changes\s*\n([\s\S]*?)\n\s*-->/g;
 const TYPE_VALUES = new Set(["breaking", "improvement", "fix"]);
-const KEY_RE = /^(feature|type|title|detail|migration|codemod):(?:\s(.*))?$/;
+const KEY_RE = /^(feature|type|title|detail|migration|codemod|manualAfterCodemod):(?:\s(.*))?$/;
 function requiredField(fields, field, source) {
     const value = fields.get(field)?.trim();
     if (!value)
@@ -70,6 +70,53 @@ function assertBlockNotClosedEarly(markdown, match, source) {
         throw new Error(`${source}: kumiko-changes block closed early by a line starting with "-->"; field values must not contain such a line`);
     }
 }
+function resolveTitleAndDetail(fields, prose, source) {
+    const explicitTitle = fields.get("title")?.trim();
+    const title = explicitTitle || prose[0];
+    if (!title)
+        throw new Error(`${source}: kumiko-changes title is required`);
+    // The first prose line is the title's source only when no title was given or
+    // the explicit one restates it; otherwise it is genuine detail.
+    const firstLineIsTitle = !explicitTitle || sameTitle(explicitTitle, prose[0]);
+    const detail = fields.get("detail")?.trim() ||
+        prose
+            .slice(firstLineIsTitle ? 1 : 0)
+            .join("\n")
+            .trim();
+    return { title, detail };
+}
+function parseManualAfterCodemod(fields, source) {
+    const raw = fields.get("manualAfterCodemod")?.trim();
+    if (raw !== undefined && raw !== "true" && raw !== "false") {
+        throw new Error(`${source}: kumiko-changes manualAfterCodemod must be true or false`);
+    }
+    return raw === "true";
+}
+function buildChange(fields, prose, source) {
+    const feature = requiredField(fields, "feature", source);
+    const rawType = requiredField(fields, "type", source);
+    if (!TYPE_VALUES.has(rawType)) {
+        throw new Error(`${source}: kumiko-changes type must be breaking, improvement, or fix`);
+    }
+    const { title, detail } = resolveTitleAndDetail(fields, prose, source);
+    const migration = fields.get("migration")?.trim();
+    const codemod = fields.get("codemod")?.trim();
+    const manualAfterCodemod = parseManualAfterCodemod(fields, source);
+    const change = {
+        feature,
+        type: rawType,
+        title,
+        ...(detail ? { detail } : {}),
+        ...(migration ? { migration } : {}),
+        ...(codemod ? { codemod } : {}),
+        ...(manualAfterCodemod ? { manualAfterCodemod: true } : {}),
+        source,
+    };
+    const validation = validateChangelog({ version: "0.0.0", ...change });
+    if (validation.length > 0)
+        throw new Error(`${source}: ${validation.join("; ")}`);
+    return change;
+}
 /** Parse structured upgrade metadata embedded in a Changeset body. */
 export function parseChangesetChanges(markdown, source) {
     const changes = [];
@@ -85,38 +132,7 @@ export function parseChangesetChanges(markdown, source) {
         assertBlockNotClosedEarly(markdown, match, source);
         if (!block)
             throw new Error(`${source}: empty kumiko-changes block`);
-        const fields = parseBlock(block, source);
-        const feature = requiredField(fields, "feature", source);
-        const rawType = requiredField(fields, "type", source);
-        if (!TYPE_VALUES.has(rawType)) {
-            throw new Error(`${source}: kumiko-changes type must be breaking, improvement, or fix`);
-        }
-        const explicitTitle = fields.get("title")?.trim();
-        const title = explicitTitle || prose[0];
-        if (!title)
-            throw new Error(`${source}: kumiko-changes title is required`);
-        // The first prose line is the title's source only when no title was given or
-        // the explicit one restates it; otherwise it is genuine detail.
-        const firstLineIsTitle = !explicitTitle || sameTitle(explicitTitle, prose[0]);
-        const detail = fields.get("detail")?.trim() ||
-            prose
-                .slice(firstLineIsTitle ? 1 : 0)
-                .join("\n")
-                .trim();
-        const migration = fields.get("migration")?.trim();
-        const codemod = fields.get("codemod")?.trim();
-        const change = {
-            feature,
-            type: rawType,
-            title,
-            ...(detail ? { detail } : {}),
-            ...(migration ? { migration } : {}),
-            ...(codemod ? { codemod } : {}),
-            source,
-        };
-        const validation = validateChangelog({ version: "0.0.0", ...change });
-        if (validation.length > 0)
-            throw new Error(`${source}: ${validation.join("; ")}`);
+        const change = buildChange(parseBlock(block, source), prose, source);
         changes.push(change);
         match = BLOCK_RE.exec(markdown);
     }

package/dist/engine/dedupe-features.js

@@ -6,15 +6,31 @@ function dedupeOptionsShallowEqual(a, b) {
     }
     return true;
 }
+function sameKeys(a, b) {
+    const aKeys = Object.keys(a ?? {});
+    const bKeys = new Set(Object.keys(b ?? {}));
+    return aKeys.length === bKeys.size && aKeys.every((key) => bKeys.has(key));
+}
+// dedupeOptions is a declaration, not proof: two same-named features that both
+// carry `{}` but register different surface must still clash, not silently drop one.
+function sameRegisteredSurface(a, b) {
+    return (sameKeys(a.entities, b.entities) &&
+        sameKeys(a.writeHandlers, b.writeHandlers) &&
+        sameKeys(a.queryHandlers, b.queryHandlers) &&
+        sameKeys(a.streamHandlers, b.streamHandlers));
+}
 function isInterchangeable(existing, next) {
     if (existing === next)
         return true;
     if (existing.dedupeOptions !== undefined && next.dedupeOptions !== undefined) {
-        return dedupeOptionsShallowEqual(existing.dedupeOptions, next.dedupeOptions);
+        return (dedupeOptionsShallowEqual(existing.dedupeOptions, next.dedupeOptions) &&
+            sameRegisteredSurface(existing, next));
     }
     return false;
 }
 // First occurrence wins: runtimes late-bind closure state (sessions' autoRevoke) on the kept instance.
+// An app holding its own handle to a later, dropped instance would bind state the registry never
+// runs — resolve the kept instance from the composed list (`features.find(name)`), not a local handle.
 export function dedupeFeatures(features) {
     const byName = new Map();
     const result = [];

package/dist/engine/define-feature.js

@@ -22,7 +22,18 @@ import { unwrapArrayForm } from "./object-form.js";
 function resolveFeatureNamesArgs(args) {
     return unwrapArrayForm(args, "features");
 }
+// dedupe-features compares options with Object.is per key, so a nested object
+// would make two structurally identical mounts look different and fail the boot
+// with an unobvious "mounted twice with different options".
+function assertDedupeOptionsComparable(featureName, options) {
+    for (const [key, value] of Object.entries(options ?? {})) {
+        if (typeof value === "object" && value !== null) {
+            throw new Error(`[Feature ${featureName}] dedupeOptions.${key} must be a primitive or a stable function reference; dedupeOptions are compared shallowly, so a nested object never matches a second mount`);
+        }
+    }
+}
 export function defineFeature(name, setup, settings) {
+    assertDedupeOptionsComparable(name, settings?.dedupeOptions);
     const state = createInitialFeatureBuilderState();
     const registrar = {
         systemScope() {

package/dist/engine/entity-handlers.d.ts

@@ -4,8 +4,6 @@ import { type EntityTable } from "../db/table-builder.js";
 import type { EntityCrudRegistrar, EntityHandlerOptions, EntityQueryHandlerOptions, EntityWriteHandlerOptions, RegisterEntityCrudOptions } from "./types/entity-handlers.js";
 import type { AccessRule, EntityDefinition, EscapeHatchDeclaration, QueryHandlerDef, WriteHandlerDef } from "./types/index.js";
 export type { EntityCrudHandlerDefaults, EntityCrudRegistrar, EntityCrudVerb, EntityHandlerOptions, EntityQueryHandlerOptions, EntityWriteHandlerOptions, RegisterEntityCrudOptions, } from "./types/entity-handlers.js";
-export declare function isDeprecatedCrossTenantHandler(handler: object): boolean;
-export declare const DEPRECATED_CROSS_TENANT_SIGNAL = "deprecation:entity-handler-cross-tenant";
 export declare const MAX_LIST_LIMIT = 200;
 export declare const entityListSchema: z.ZodObject<{
     cursor: z.ZodOptional<z.ZodString>;
@@ -60,7 +58,9 @@ export declare function createEntityExecutor(entityName: string, entity: EntityD
 };
 export declare function defineProjectionQueryHandler(name: string, projectionQualifiedName: string, options: {
     access: AccessRule;
-    unsafeAllTenants?: boolean;
+    unsafeAllTenants?: boolean | {
+        readonly reason: string;
+    };
     escapeHatch?: EscapeHatchDeclaration;
 }): QueryHandlerDef;
 /** Register standard entity CRUD handlers in one call. Access stays explicit — no openToAll default. */

package/dist/engine/entity-handlers.js

@@ -3,13 +3,15 @@ import * as z from "zod";
 import { collectReferenceFields, enrichRowWithReferences, enrichWithReferences, } from "../db/eagerload.js";
 import { createEventStoreExecutor } from "../db/event-store-executor.js";
 import { buildEntityTable } from "../db/table-builder.js";
-import { acknowledgeConventionCrossTenant } from "../db/tenant-db.js";
+import { acknowledgeConventionCrossTenant, reportConventionCrossTenantUse, } from "../db/tenant-db.js";
 import { isSystemIdentity } from "../pipeline/system-identity-switch.js";
 import { assertUnreachable } from "../utils/index.js";
 import { PAGED_QUERY_HANDLER_BRAND } from "./define-handler.js";
+import { codemodPlaceholderReasonProblem } from "./escape-hatch-reason.js";
 import { dropEmptyWriteOnlyValues } from "./field-access.js";
 import { instructionFieldNames } from "./instruction-fields.js";
 import { buildInsertSchema, buildUpdateSchema } from "./schema-builder.js";
+import { parseTenantId } from "./types/identifiers.js";
 // Convention-based handler factories for event-sourced aggregates.
 //
 // You register one handler per call (no auto-generation of a whole CRUD set),
@@ -46,26 +48,27 @@ import { buildInsertSchema, buildUpdateSchema } from "./schema-builder.js";
 const WRITE_VERBS = ["create", "update", "delete", "restore"];
 const QUERY_VERBS = ["list", "detail"];
 const idSchema = z.object({ id: z.uuid() });
-// Keyed by handler function: the registrar rebuilds the def object but keeps the function reference.
-const deprecatedCrossTenantHandlers = new WeakSet();
-export function isDeprecatedCrossTenantHandler(handler) {
-    return deprecatedCrossTenantHandlers.has(handler);
+const SYSTEM_ADMIN_ROLE = "SystemAdmin";
+// A write handler with escapeHatch reads/writes rows of every tenant, so only an operator
+// role may reach it — otherwise any tenant-level role holder could mutate foreign tenants.
+function isSystemAdminOnly(access) {
+    return ("roles" in access &&
+        access.roles.length > 0 &&
+        access.roles.every((role) => role === SYSTEM_ADMIN_ROLE));
 }
-export const DEPRECATED_CROSS_TENANT_SIGNAL = "deprecation:entity-handler-cross-tenant";
-function resolveCrossTenantReason(name, options) {
-    if (options.escapeHatch !== undefined && options.crossTenant === true) {
-        throw new Error(`"${name}": declare either escapeHatch or the deprecated crossTenant, not both.`);
+function resolveCrossTenantReason(name, options, kind) {
+    if (options.escapeHatch === undefined)
+        return undefined;
+    if (options.escapeHatch.reason.trim().length === 0) {
+        throw new Error(`"${name}": escapeHatch requires a non-empty reason.`);
     }
-    if (options.escapeHatch !== undefined) {
-        if (options.escapeHatch.reason.trim().length === 0) {
-            throw new Error(`"${name}": escapeHatch requires a non-empty reason.`);
-        }
-        return options.escapeHatch.reason;
-    }
-    if (options.crossTenant === true) {
-        return `deprecated crossTenant: true on entity convention handler ${name}`;
+    const placeholderProblem = codemodPlaceholderReasonProblem(options.escapeHatch.reason);
+    if (placeholderProblem !== undefined)
+        throw new Error(`"${name}": ${placeholderProblem}`);
+    if (kind === "write" && !isSystemAdminOnly(options.access)) {
+        throw new Error(`"${name}": a write handler with escapeHatch reaches across every tenant, so its access must be SystemAdmin-only ({ roles: ["${SYSTEM_ADMIN_ROLE}"] }); got ${JSON.stringify(options.access)}.`);
     }
-    return undefined;
+    return options.escapeHatch.reason;
 }
 // Upper bound on entity-list `limit`: unbounded/fractional values ran
 // straight into the raw `LIMIT ${limit}` SQL string (event-store-executor-
@@ -194,29 +197,43 @@ export function defineEntityWriteHandler(name, entity, options) {
     // behavior-preserving: ctx.db was already an unfiltered "system"-mode
     // TenantDb for these handlers before the ctx.db cutover.
     //
-    // crossTenantReason (escapeHatch or the deprecated crossTenant) mirrors the
+    // crossTenantReason (escapeHatch) mirrors the
     // query-handler branch below: this ONE write handler reads/writes across
     // every tenant without making the whole feature r.systemScope().
-    const crossTenantReason = resolveCrossTenantReason(name, options);
+    const crossTenantReason = resolveCrossTenantReason(name, options, "write");
+    // create always writes into the acting user's own tenant, so its FK,
+    // unique and preSave lookups must stay tenant-filtered even when the
+    // handler declares cross-tenant access for the row-addressing verbs.
     const dbFor = (ctx) => {
         if (ctx.systemDb) {
             return ctx.systemDb.acknowledgeCrossTenant(`entity convention handler for r.systemScope() feature (${name})`);
         }
-        return crossTenantReason !== undefined
-            ? acknowledgeConventionCrossTenant(ctx.db, crossTenantReason)
+        return crossTenantReason !== undefined && verb !== "create"
+            ? acknowledgeConventionCrossTenant(ctx.db, crossTenantReason, {
+                deferReport: reportsPerTouchedRow(ctx),
+            })
             : ctx.db;
     };
+    // actingUserFor reads the row it is about to touch anyway, so for these calls it reports the
+    // cross-tenant use per row (with that row as target) instead of dbFor reporting once up front.
+    const reportsPerTouchedRow = (ctx) => ctx.systemDb === undefined && crossTenantReason !== undefined && !entity.systemStream;
     // The event stream is keyed by the acting user's tenantId (streamTenantFor in
     // event-store-executor-context.ts), not by the db handed to the executor — an
     // unfiltered "system"-mode db alone reads the foreign row but appends to an
     // empty stream in the operator's own tenant, surfacing as a bogus
     // version_conflict. Rewriting the acting tenant also keeps PII envelope keys
     // derived from the row's tenant rather than the operator's.
-    const actingUserFor = async (user, id, db) => {
+    const actingUserFor = async (user, id, db, ctx) => {
         if (crossTenantReason === undefined || entity.systemStream)
             return user;
         const row = await db.fetchOne(table, { id });
         const rowTenantId = row?.["tenantId"];
+        if (reportsPerTouchedRow(ctx)) {
+            const targetTenantId = parseTenantId(rowTenantId);
+            reportConventionCrossTenantUse(db, targetTenantId !== null && typeof id === "string"
+                ? { id, tenantId: targetTenantId }
+                : undefined);
+        }
         if (typeof rowTenantId !== "string" || rowTenantId === user.tenantId)
             return user;
         return { ...user, tenantId: rowTenantId };
@@ -255,7 +272,7 @@ export function defineEntityWriteHandler(name, entity, options) {
                     ...submitted,
                     changes: dropEmptyWriteOnlyValues(entity, submitted.changes),
                 };
-                const user = await actingUserFor(event.user, payload.id, db);
+                const user = await actingUserFor(event.user, payload.id, db, ctx);
                 // skipUnchanged (#464): API-driven updates diff against the stored
                 // row so a resubmitted-but-identical field doesn't force a fresh
                 // pii/encrypted ciphertext. Direct executor.update() callers (e.g.
@@ -274,7 +291,7 @@ export function defineEntityWriteHandler(name, entity, options) {
             handler = async (event, ctx) => {
                 const db = dbFor(ctx);
                 const payload = event.payload; // @cast-boundary engine-payload
-                const user = await actingUserFor(event.user, payload.id, db);
+                const user = await actingUserFor(event.user, payload.id, db, ctx);
                 return executor.delete(payload, user, db);
             };
             break;
@@ -283,15 +300,13 @@ export function defineEntityWriteHandler(name, entity, options) {
             handler = async (event, ctx) => {
                 const db = dbFor(ctx);
                 const payload = event.payload; // @cast-boundary engine-payload
-                const user = await actingUserFor(event.user, payload.id, db);
+                const user = await actingUserFor(event.user, payload.id, db, ctx);
                 return executor.restore(payload, user, db);
             };
             break;
         default:
             assertUnreachable(verb, "write verb");
     }
-    if (options.crossTenant === true)
-        deprecatedCrossTenantHandlers.add(handler);
     // escapeHatch stays off the def: WriteHandlerDef.escapeHatch also grants unsafeRaw, global writes, identity switches.
     return {
         name,
@@ -335,13 +350,13 @@ export function defineEntityQueryHandler(name, entity, options) {
     // useReferenceLookup stays as a fallback (for apps that write custom
     // handlers by hand without this wrapper).
     const hasRefFields = collectReferenceFields(entity).length > 0;
-    const crossTenantReason = resolveCrossTenantReason(name, options);
+    const crossTenantReason = resolveCrossTenantReason(name, options, "query");
     // Preference order:
     //  1. ctx.systemDb — the feature declared r.systemScope() (whole-feature
     //     cutover, dispatch-shared.ts), so ctx.db is fail-closed. This is
     //     behavior-preserving: ctx.db was already an unfiltered "system"-mode
     //     TenantDb for these handlers before that cutover.
-    //  2. crossTenantReason (escapeHatch or the deprecated crossTenant) — this
+    //  2. crossTenantReason (escapeHatch) — 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
@@ -386,8 +401,12 @@ export function defineEntityQueryHandler(name, entity, options) {
                     },
                     parentVisibility: { entities: ctx.registry.getAllEntities() },
                 });
+                const eagerLoadViewer = {
+                    user: query.user,
+                    parentVisibility: { entities: ctx.registry.getAllEntities() },
+                };
                 const enrichedRows = hasRefFields
-                    ? await enrichWithReferences(result.rows, entity, (name) => ctx.registry.getEntity(name), db)
+                    ? await enrichWithReferences(result.rows, entity, (name) => ctx.registry.getEntity(name), db, eagerLoadViewer)
                     : result.rows;
                 return { ...result, rows: augmentDerivedFields(enrichedRows, entity) };
             };
@@ -401,14 +420,15 @@ export function defineEntityQueryHandler(name, entity, options) {
                 }); // @cast-boundary engine-payload
                 if (row === null || !hasRefFields)
                     return row;
-                return enrichRowWithReferences(row, entity, (name) => ctx.registry.getEntity(name), db);
+                return enrichRowWithReferences(row, entity, (name) => ctx.registry.getEntity(name), db, {
+                    user: query.user,
+                    parentVisibility: { entities: ctx.registry.getAllEntities() },
+                });
             };
             break;
         default:
             assertUnreachable(verb, "query verb");
     }
-    if (options.crossTenant === true)
-        deprecatedCrossTenantHandlers.add(handler);
     // escapeHatch stays off the def: QueryHandlerDef.escapeHatch also grants unsafeRaw and identity switches.
     return {
         name,
@@ -497,6 +517,10 @@ export function createEntityExecutor(entityName, entity) {
 // For anything more involved (filters, joins, custom shaping), write the
 // query-handler explicitly with ctx.queryProjection or a raw select.
 export function defineProjectionQueryHandler(name, projectionQualifiedName, options) {
+    const escapeHatch = options.escapeHatch ??
+        (typeof options.unsafeAllTenants === "object"
+            ? { reason: options.unsafeAllTenants.reason }
+            : undefined);
     return {
         name,
         schema: z.object({}),
@@ -506,7 +530,7 @@ export function defineProjectionQueryHandler(name, projectionQualifiedName, opti
         // pagination envelopes or added metadata.
         handler: async (_query, ctx) => ctx.queryProjection(projectionQualifiedName, options.unsafeAllTenants ? { unsafeAllTenants: true } : undefined), // @wrapper-known semantic-alias
         access: options.access,
-        ...(options.escapeHatch && { escapeHatch: options.escapeHatch }),
+        ...(escapeHatch && { escapeHatch }),
     };
 }
 function defaultCrudVerbs(entity) {
@@ -539,18 +563,24 @@ export function registerEntityCrud(r, entityName, entity, options) {
     };
     const resolveWriteOpts = (verb) => {
         const excludeFields = verb === "create" || verb === "update" ? options?.excludeFields?.[verb] : undefined;
+        const verbAgent = options?.agents?.[verb];
         return {
             ...writeOpts,
             access: requireAccess(verb, options?.verbAccess?.[verb] ?? writeOpts?.access),
             description: options?.descriptions?.[verb] ?? writeOpts?.description,
+            ...(verbAgent !== undefined && { agent: verbAgent }),
             ...(excludeFields !== undefined && { excludeFields }),
         };
     };
-    const resolveReadOpts = (verb) => ({
-        ...readOpts,
-        access: requireAccess(verb, options?.verbAccess?.[verb] ?? readOpts?.access),
-        description: options?.descriptions?.[verb] ?? readOpts?.description,
-    });
+    const resolveReadOpts = (verb) => {
+        const verbAgent = options?.agents?.[verb];
+        return {
+            ...readOpts,
+            access: requireAccess(verb, options?.verbAccess?.[verb] ?? readOpts?.access),
+            description: options?.descriptions?.[verb] ?? readOpts?.description,
+            ...(verbAgent !== undefined && { agent: verbAgent }),
+        };
+    };
     if (verbs.create) {
         r.writeHandler(defineEntityCreateHandler(entityName, entity, resolveWriteOpts("create")));
     }

package/dist/engine/escape-hatch-reason.d.ts

@@ -0,0 +1,2 @@
+export declare const CODEMOD_PLACEHOLDER_REASON_MARKER = "state the operator use case here";
+export declare function codemodPlaceholderReasonProblem(reason: string): string | undefined;

package/dist/engine/escape-hatch-reason.js

@@ -0,0 +1,8 @@
+// Shared by the migrate-cross-tenant codemod (which writes it) and the escapeHatch reason
+// validation (which rejects it), so an unedited codemod reason can never reach a running app.
+export const CODEMOD_PLACEHOLDER_REASON_MARKER = "state the operator use case here";
+export function codemodPlaceholderReasonProblem(reason) {
+    if (!reason.includes(CODEMOD_PLACEHOLDER_REASON_MARKER))
+        return undefined;
+    return `the reason still contains the migrate-cross-tenant codemod placeholder ("${CODEMOD_PLACEHOLDER_REASON_MARKER}") — replace the codemod placeholder with the real operator use case`;
+}

package/dist/engine/extension-names.d.ts

@@ -23,19 +23,18 @@ export declare const EXT_USER_DATA_ORDER: {
     readonly DEFAULT: 0;
 };
 /**
- * `tenantData` — Tenant-Destroy-Hooks pro Entity (DSGVO + AVV-Beendigung).
+ * `tenantData` — per-entity tenant-destroy hooks (GDPR + end of data processing agreement).
  *
- * Erwartete Hook-Methoden:
- *   - `destroy(tenantId, ctx) => Promise<void>`
+ * Expected hook method: `destroy(ctx) => Promise<TenantDestroyHookResult | void>`.
  *
- * Registriert von: `tenant-lifecycle` (Sprint 5).
- * Genutzt von: jedes Feature mit tenantId-Field.
+ * Registered by: `tenant-lifecycle`.
+ * Consumed by: every feature with a tenantId field.
  */
 export declare const EXT_TENANT_DATA: "tenantData";
 /**
  * `storageProvider` — file-storage-plugin tenant-destroy hook.
  *
- * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<void>`.
+ * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<TenantDestroyHookResult | void>`.
  *
  * Registered by: `files-tenant-data`.
  * Consumed by: pluggable providers (Local, MinIO, S3, R2).
@@ -113,7 +112,7 @@ export declare const EXT_DERIVATIVE_OVERLAY_RESOLVER: "derivativeOverlayResolver
  * `searchAdapter` — search-index tenant-destroy hook (Meilisearch index
  * cleanup on tenant-destroy).
  *
- * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<void>`.
+ * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<TenantDestroyHookResult | void>`.
  *
  * Consumed by: Meilisearch and other search-adapter implementations.
  */
@@ -122,14 +121,14 @@ export declare const EXT_SEARCH_ADAPTER: "searchAdapter";
  * `externalResource` — external-service tenant-destroy hook (webhook
  * subscriptions, Brevo recipient lists, provider customer accounts).
  *
- * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<void>`.
+ * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<TenantDestroyHookResult | void>`.
  */
 export declare const EXT_EXTERNAL_RESOURCE: "externalResource";
 /**
  * `infraResource` — Pulumi-managed per-tenant resource tenant-destroy hook
  * (custom domain, cert-manager issuer, dedicated pod/volume).
  *
- * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<void>`.
+ * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<TenantDestroyHookResult | void>`.
  */
 export declare const EXT_INFRA_RESOURCE: "infraResource";
 /**

package/dist/engine/extension-names.js

@@ -42,19 +42,18 @@ export const EXT_USER_DATA_ORDER = {
     DEFAULT: 0,
 };
 /**
- * `tenantData` — Tenant-Destroy-Hooks pro Entity (DSGVO + AVV-Beendigung).
+ * `tenantData` — per-entity tenant-destroy hooks (GDPR + end of data processing agreement).
  *
- * Erwartete Hook-Methoden:
- *   - `destroy(tenantId, ctx) => Promise<void>`
+ * Expected hook method: `destroy(ctx) => Promise<TenantDestroyHookResult | void>`.
  *
- * Registriert von: `tenant-lifecycle` (Sprint 5).
- * Genutzt von: jedes Feature mit tenantId-Field.
+ * Registered by: `tenant-lifecycle`.
+ * Consumed by: every feature with a tenantId field.
  */
 export const EXT_TENANT_DATA = "tenantData";
 /**
  * `storageProvider` — file-storage-plugin tenant-destroy hook.
  *
- * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<void>`.
+ * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<TenantDestroyHookResult | void>`.
  *
  * Registered by: `files-tenant-data`.
  * Consumed by: pluggable providers (Local, MinIO, S3, R2).
@@ -142,7 +141,7 @@ export const EXT_DERIVATIVE_OVERLAY_RESOLVER = "derivativeOverlayResolver";
  * `searchAdapter` — search-index tenant-destroy hook (Meilisearch index
  * cleanup on tenant-destroy).
  *
- * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<void>`.
+ * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<TenantDestroyHookResult | void>`.
  *
  * Consumed by: Meilisearch and other search-adapter implementations.
  */
@@ -151,14 +150,14 @@ export const EXT_SEARCH_ADAPTER = "searchAdapter";
  * `externalResource` — external-service tenant-destroy hook (webhook
  * subscriptions, Brevo recipient lists, provider customer accounts).
  *
- * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<void>`.
+ * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<TenantDestroyHookResult | void>`.
  */
 export const EXT_EXTERNAL_RESOURCE = "externalResource";
 /**
  * `infraResource` — Pulumi-managed per-tenant resource tenant-destroy hook
  * (custom domain, cert-manager issuer, dedicated pod/volume).
  *
- * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<void>`.
+ * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<TenantDestroyHookResult | void>`.
  */
 export const EXT_INFRA_RESOURCE = "infraResource";
 /**

package/dist/engine/extensions/tenant-data.d.ts

@@ -1,14 +1,16 @@
 import type { FileProviderResolver } from "@cosmicdrift/kumiko-types/file-provider-resolver-types";
 import type { TenantDb } from "../../db/tenant-db.js";
 import type { Registry, TenantId } from "../types/index.js";
+import type { TenantDestroyHookResult } from "./tenant-resource.js";
 export interface TenantDataHookCtx {
     readonly db: TenantDb;
     readonly registry: Registry;
     readonly tenantId: TenantId;
+    readonly deadlineAt?: number;
     readonly fileProviderResolver?: FileProviderResolver;
     readonly log?: (message: string) => void;
 }
-export type TenantDataDestroyHook = (ctx: TenantDataHookCtx) => Promise<void>;
+export type TenantDataDestroyHook = (ctx: TenantDataHookCtx) => Promise<TenantDestroyHookResult | void>;
 export interface TenantDataExtensionHooks {
     readonly destroy: TenantDataDestroyHook;
 }

package/dist/engine/extensions/tenant-resource.d.ts

@@ -1,13 +1,21 @@
 import type { FileProviderResolver } from "@cosmicdrift/kumiko-types/file-provider-resolver-types";
 import type { DbRunner } from "../../db/connection.js";
 import type { TenantId } from "../types/index.js";
+export type TenantDestroyHookResult = {
+    readonly done: true;
+    readonly processed?: number;
+} | {
+    readonly done: false;
+    readonly processed: number;
+};
 export interface TenantResourceHookCtx {
     readonly tenantId: TenantId;
+    readonly deadlineAt?: number;
     readonly db: DbRunner;
     readonly fileProviderResolver?: FileProviderResolver;
     readonly log?: (message: string) => void;
 }
-export type TenantResourceDestroyHook = (tenantId: TenantId, ctx: TenantResourceHookCtx) => Promise<void>;
+export type TenantResourceDestroyHook = (tenantId: TenantId, ctx: TenantResourceHookCtx) => Promise<TenantDestroyHookResult | void>;
 export interface TenantResourceExtensionHooks {
     readonly destroyTenant: TenantResourceDestroyHook;
 }

package/dist/engine/factories.d.ts

@@ -35,7 +35,7 @@ export declare function createBooleanField<R extends true | false = false>(overr
 };
 export declare function createSelectField<const TOptions extends readonly string[], R extends true | false = false>(opts: {
     options: TOptions;
-} & Partial<Omit<SelectFieldDef<TOptions>, "type" | "options" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & {
+} & Partial<Omit<SelectFieldDef<NoInfer<TOptions>>, "type" | "options" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & {
     required?: R;
 }): SelectFieldDef<TOptions> & {
     required: R;

package/dist/engine/feature-builder-state.d.ts

@@ -1,8 +1,7 @@
 import type { WebSocketRouteDefinition } from "@cosmicdrift/kumiko-types/websocket-route";
 import type * as z from "zod";
-import type { ZodType } from "zod";
 import type { HttpRouteDefinition } from "./types/http-route.js";
-import type { AuthClaimsFn, BootCheckFn, ClaimKeyDefinition, ConfigKeyDefinition, ConfigSeedDef, EntityDefinition, EntityProjectionExtension, EventMigrationDef, ExtensionSelectorDef, FeatureMetricDef, JobDefinition, LifecycleHookFn, MultiStreamProjectionDefinition, NotificationDefinition, OwnedFn, PhasedHook, PostDeleteHookFn, PostQueryHookFn, PostSaveHookFn, PreDeleteHookFn, ProjectionDefinition, QueryHandlerDef, ReferenceDataDef, RegistrarExtensionDef, RegistrarExtensionRegistration, RelationDefinition, SearchPayloadContributorFn, SecretKeyDefinition, SecretNamespaceDefinition, StoreTableEntry, StreamHandlerDef, TranslationKeys, TreeActionDef, UiHints, ValidationHookFn, WriteHandlerDef } from "./types/index.js";
+import type { AuthClaimsFn, BootCheckFn, ClaimKeyDefinition, ConfigKeyDefinition, ConfigSeedDef, EntityDefinition, EntityProjectionExtension, EventDef, EventMigrationDef, ExtensionSelectorDef, FeatureMetricDef, JobDefinition, LifecycleHookFn, MultiStreamProjectionDefinition, NotificationDefinition, OwnedFn, PhasedHook, PostDeleteHookFn, PostQueryHookFn, PostSaveHookFn, PreDeleteHookFn, ProjectionDefinition, QueryHandlerDef, ReferenceDataDef, RegistrarExtensionDef, RegistrarExtensionRegistration, RelationDefinition, SearchPayloadContributorFn, SecretKeyDefinition, SecretNamespaceDefinition, StoreTableEntry, StreamHandlerDef, TranslationKeys, TreeActionDef, UiHints, ValidationHookFn, WriteHandlerDef } from "./types/index.js";
 import type { ContentCollectionDefinition, NavDefinition } from "./types/nav.js";
 import type { ScreenDefinition } from "./types/screen.js";
 import type { WorkspaceDefinition } from "./types/workspace.js";
@@ -23,11 +22,7 @@ export type FeatureBuilderState = {
     configKeys: Record<string, ConfigKeyDefinition>;
     configSeeds: ConfigSeedDef[];
     jobs: Record<string, JobDefinition>;
-    events: Record<string, {
-        name: string;
-        schema: ZodType;
-        version: number;
-    }>;
+    events: Record<string, EventDef>;
     eventMigrations: Record<string, EventMigrationDef[]>;
     configReads: string[];
     entityPostSave: Record<string, PhasedHook<PostSaveHookFn>[]>;

package/dist/engine/feature-changelog.d.ts

@@ -8,6 +8,8 @@ export type ChangelogEntry = {
     readonly migration?: string;
     /** Path (relative to packages/framework/src/, under scripts/codemod/) run by `kumiko upgrade --apply`. */
     readonly codemod?: string;
+    /** The codemod only covers part of the migration: the entry is also recorded as pending manual work after it ran. */
+    readonly manualAfterCodemod?: boolean;
 };
 export type FeatureChangelog = {
     readonly feature: string;

package/dist/engine/feature-changelog.js

@@ -33,6 +33,9 @@ function isChangelogEntry(value) {
         return false;
     if (typeof obj["title"] !== "string")
         return false;
+    if (obj["manualAfterCodemod"] !== undefined && typeof obj["manualAfterCodemod"] !== "boolean") {
+        return false;
+    }
     return true;
 }
 export function validateChangelog(entry) {
@@ -43,6 +46,9 @@ export function validateChangelog(entry) {
     if (entry.type === "breaking" && entry.migration?.trim() === "") {
         errors.push(`breaking change "${entry.title}" has empty migration field`);
     }
+    if (entry.manualAfterCodemod && !entry.codemod) {
+        errors.push(`change "${entry.title}" sets manualAfterCodemod without a codemod field`);
+    }
     return errors;
 }
 export function compareVersions(a, b) {