@cosmicdrift/kumiko-framework 0.125.1 → 0.126.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.125.1",
+  "version": "0.126.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>",
@@ -189,7 +189,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.125.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.126.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/auth-middleware.ts

@@ -55,6 +55,10 @@ export type AuthSessionChecker = (
 // and short-circuits the JWT path on a hit.
 export type PatResolver = (rawToken: string) => Promise<SessionUser | null>;
 
+export type TenantLifecycleStatusResolver = (
+  tenantId: TenantId,
+) => Promise<{ readonly status: string } | null>;
+
 export type AuthMiddlewareOptions = {
   // Called after JWT-verify when the token carries a sid. If the checker
   // reports anything other than "live", the request is rejected with 401.
@@ -74,6 +78,10 @@ export type AuthMiddlewareOptions = {
   // a SessionUser with id="anonymous" and roles=["anonymous"], scoped to a
   // tenantId resolved through the chain documented on AnonymousAccessConfig.
   readonly anonymousAccess?: AnonymousAccessConfig;
+  // Consulted after tenantId is resolved (JWT/PAT/anonymous). Returns 410
+  // when the tenant is in teardown (destroyRequested/destroying/destroyed).
+  // cancel-destruction is exempt while status=destroyRequested.
+  readonly resolveTenantLifecycleStatus?: TenantLifecycleStatusResolver;
 };
 
 // Resolves the tenant for an unauthenticated request. Returns null when no
@@ -127,14 +135,15 @@ type MiddlewareRejectCode =
   | "tenant_required"
   | "tenant_not_found"
   | "tenant_mismatch"
-  | "invalid_tenant_format";
+  | "invalid_tenant_format"
+  | "tenant_unavailable";
 
 // @wrapper-known error-helper
 function middlewareReject(
   c: Context,
   opts: {
     code: MiddlewareRejectCode;
-    status: 400 | 401 | 403 | 404;
+    status: 400 | 401 | 403 | 404 | 410;
     message: string;
     i18nKey: string;
     details?: Record<string, unknown>;
@@ -187,7 +196,13 @@ function extractToken(
 }
 
 export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions = {}) {
-  const { sessionChecker, strictMode = false, anonymousAccess, patResolver } = options;
+  const {
+    sessionChecker,
+    strictMode = false,
+    anonymousAccess,
+    patResolver,
+    resolveTenantLifecycleStatus,
+  } = options;
 
   return async (c: Context, next: Next) => {
     const extracted = extractToken(c);
@@ -219,7 +234,7 @@ export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions =
             i18nKey: "auth.errors.missingToken",
           });
         }
-        return await handleAnonymous(c, anonymousAccess, next);
+        return await handleAnonymous(c, anonymousAccess, next, resolveTenantLifecycleStatus);
       }
       return middlewareReject(c, {
         code: "missing_token",
@@ -234,7 +249,7 @@ export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions =
     // Personal Access Token, not a JWT. Short-circuit the JWT path entirely.
     // Cookie transport is never a PAT (the browser holds the JWT).
     if (patResolver && transport === "bearer" && token.startsWith(PAT_TOKEN_PREFIX)) {
-      return await handlePat(c, patResolver, token, next);
+      return await handlePat(c, patResolver, token, next, resolveTenantLifecycleStatus);
     }
 
     let payload: Awaited<ReturnType<JwtHelper["verify"]>>;
@@ -286,6 +301,12 @@ export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions =
       ...(payload.claims ? { claims: payload.claims } : {}),
       ...(payload.jti ? { sid: payload.jti } : {}),
     };
+    const lifecycleReject = await rejectIfTenantTeardown(
+      c,
+      payload.tenantId,
+      resolveTenantLifecycleStatus,
+    );
+    if (lifecycleReject) return lifecycleReject;
     c.set(USER_KEY, user);
     c.set(AUTH_TRANSPORT_KEY, transport);
     await next();
@@ -311,6 +332,7 @@ async function handlePat(
   patResolver: PatResolver,
   token: string,
   next: Next,
+  resolveTenantLifecycleStatus?: TenantLifecycleStatusResolver,
 ): Promise<Response | undefined> {
   const patUser = await patResolver(token);
   if (!patUser) {
@@ -335,6 +357,12 @@ async function handlePat(
   }
   c.set(USER_KEY, patUser);
   c.set(AUTH_TRANSPORT_KEY, "bearer");
+  const lifecycleReject = await rejectIfTenantTeardown(
+    c,
+    patUser.tenantId,
+    resolveTenantLifecycleStatus,
+  );
+  if (lifecycleReject) return lifecycleReject;
   await next();
   // skip: PAT path completed — next() ran; explicit return keeps the
   // Response|undefined union honest (same as handleAnonymous).
@@ -357,6 +385,7 @@ async function handleAnonymous(
   c: Context,
   config: AnonymousAccessConfig,
   next: Next,
+  resolveTenantLifecycleStatus?: TenantLifecycleStatusResolver,
 ): Promise<Response | undefined> {
   // Step 1+2: parse client-supplied tenant. Reject malformed values before
   // they touch any downstream consumer (DB, cache, audit row).
@@ -394,6 +423,12 @@ async function handleAnonymous(
   }
 
   // Step 5: synthesise + continue.
+  const lifecycleReject = await rejectIfTenantTeardown(
+    c,
+    resolved.tenantId,
+    resolveTenantLifecycleStatus,
+  );
+  if (lifecycleReject) return lifecycleReject;
   c.set(USER_KEY, createAnonymousUser(resolved.tenantId));
   await next();
   // skip: anonymous path completed — Hono middleware contract returns void
@@ -479,8 +514,59 @@ async function resolveTenant(
 
 type RejectArgs = {
   code: MiddlewareRejectCode;
-  status: 400 | 401 | 403 | 404;
+  status: 400 | 401 | 403 | 404 | 410;
   message: string;
   i18nKey: string;
   details?: Record<string, unknown>;
 };
+
+const TENANT_LIFECYCLE_BLOCKED = new Set([
+  "destroyRequested",
+  "destroying",
+  "destroyFailed",
+  "destroyed",
+]);
+const TENANT_LIFECYCLE_CANCEL_QN = "tenant-lifecycle:write:cancel-destruction";
+
+async function requestsCancelDestruction(c: Context): Promise<boolean> {
+  if (c.req.method !== "POST") return false;
+  try {
+    const path = c.req.path;
+    const body = (await c.req.raw.clone().json()) as {
+      type?: string;
+      commands?: Array<{ type?: string }>;
+    };
+    if (path === "/api/write") {
+      return body.type === TENANT_LIFECYCLE_CANCEL_QN;
+    }
+    if (path === "/api/batch") {
+      return (
+        Array.isArray(body.commands) &&
+        body.commands.some((command) => command.type === TENANT_LIFECYCLE_CANCEL_QN)
+      );
+    }
+  } catch {
+    return false;
+  }
+  return false;
+}
+
+async function rejectIfTenantTeardown(
+  c: Context,
+  tenantId: TenantId,
+  resolveTenantLifecycleStatus: TenantLifecycleStatusResolver | undefined,
+): Promise<Response | undefined> {
+  if (!resolveTenantLifecycleStatus) return undefined;
+  const lifecycle = await resolveTenantLifecycleStatus(tenantId);
+  if (!lifecycle || !TENANT_LIFECYCLE_BLOCKED.has(lifecycle.status)) return undefined;
+  if (lifecycle.status === "destroyRequested" && (await requestsCancelDestruction(c))) {
+    return undefined;
+  }
+  return middlewareReject(c, {
+    code: "tenant_unavailable",
+    status: 410,
+    message: `tenant "${tenantId}" is unavailable (${lifecycle.status})`,
+    i18nKey: "auth.errors.tenantUnavailable",
+    details: { tenantId, status: lifecycle.status },
+  });
+}

package/src/api/auth-routes.ts

@@ -243,6 +243,8 @@ export type AuthRoutesConfig = {
   // Wired by run-prod-app when the PAT feature is mounted; unwired = no PAT
   // rate limiting.
   patRateLimiter?: LoginRateLimiter;
+  // Tenant-lifecycle 410 gate — wired by tenant-lifecycle / run-prod-app.
+  resolveTenantLifecycleStatus?: import("./auth-middleware").TenantLifecycleStatusResolver;
   // Password-reset flow. When wired, POST /auth/request-password-reset and
   // POST /auth/reset-password are mounted as public routes. The framework
   // dispatches to the feature-level handlers (authoring QNs typically come

package/src/api/index.ts

@@ -7,6 +7,7 @@ export type {
   AuthSessionStatus,
   PatResolver,
   TenantExists,
+  TenantLifecycleStatusResolver,
   TenantResolver,
 } from "./auth-middleware";
 export { authMiddleware, getUser, PAT_TOKEN_PREFIX } from "./auth-middleware";

package/src/api/server.ts

@@ -567,6 +567,9 @@ export function buildServer(options: ServerOptions): KumikoServer {
     ...(options.auth?.sessionChecker ? { sessionChecker: options.auth.sessionChecker } : {}),
     ...(options.auth?.sessionStrictMode ? { strictMode: options.auth.sessionStrictMode } : {}),
     ...(options.auth?.patResolver ? { patResolver: options.auth.patResolver } : {}),
+    ...(options.auth?.resolveTenantLifecycleStatus
+      ? { resolveTenantLifecycleStatus: options.auth.resolveTenantLifecycleStatus }
+      : {}),
     ...(options.anonymousAccess ? { anonymousAccess: options.anonymousAccess } : {}),
   });
   app.use("/api/*", async (c, next) => {

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

@@ -24,6 +24,17 @@ const fileProvider = (name: string) =>
 
 const S3_ENV = ["S3_BUCKET", "S3_REGION", "S3_ACCESS_KEY", "S3_SECRET_KEY"] as const;
 
+// V2/V3 are hard boot gates now — capture the thrown message so a single case
+// can assert several substrings (feature, entity, article).
+function catchMessage(fn: () => void): string {
+  try {
+    fn();
+  } catch (e) {
+    return e instanceof Error ? e.message : String(e);
+  }
+  throw new Error("expected function to throw, but it did not");
+}
+
 describe("validateGdprStoragePersistence (V1)", () => {
   let warnSpy: ReturnType<typeof spyOn>;
   let savedEnv: Array<readonly [string, string | undefined]>;
@@ -84,79 +95,53 @@ describe("validateGdprStoragePersistence (V1)", () => {
 });
 
 describe("validateGdprHookCompleteness (V2)", () => {
-  let warnSpy: ReturnType<typeof spyOn>;
-
-  beforeEach(() => {
-    warnSpy = spyOn(console, "warn").mockImplementation(() => {});
-  });
-
-  afterEach(() => {
-    warnSpy.mockRestore();
-  });
-
   const exportFn = async () => null;
   const deleteFn = async () => {};
 
-  test("export + delete hooks → no warn", () => {
+  test("export + delete hooks → no throw", () => {
     const f = defineFeature("my-feature", (r) => {
       r.useExtension(EXT_USER_DATA, "myEntity", { export: exportFn, delete: deleteFn });
     });
-    validateGdprHookCompleteness([f]);
-    expect(warnSpy).not.toHaveBeenCalled();
+    expect(() => validateGdprHookCompleteness([f])).not.toThrow();
   });
 
-  test("export hook without delete hook → Art.17 warn", () => {
+  test("export hook without delete hook → Art.17 throw", () => {
     const f = defineFeature("my-feature", (r) => {
       r.useExtension(EXT_USER_DATA, "myEntity", { export: exportFn });
     });
-    validateGdprHookCompleteness([f]);
-    expect(warnSpy).toHaveBeenCalledTimes(1);
-    const msg = String(warnSpy.mock.calls[0]?.[0]);
+    const msg = catchMessage(() => validateGdprHookCompleteness([f]));
     expect(msg).toContain("my-feature");
     expect(msg).toContain("myEntity");
     expect(msg).toContain("Art.17");
   });
 
-  test("delete hook only (no export) → no warn", () => {
+  test("delete hook only (no export) → no throw", () => {
     const f = defineFeature("my-feature", (r) => {
       r.useExtension(EXT_USER_DATA, "myEntity", { delete: deleteFn });
     });
-    validateGdprHookCompleteness([f]);
-    expect(warnSpy).not.toHaveBeenCalled();
+    expect(() => validateGdprHookCompleteness([f])).not.toThrow();
   });
 
-  test("no EXT_USER_DATA hooks at all → no warn", () => {
+  test("no EXT_USER_DATA hooks at all → no throw", () => {
     const f = defineFeature("my-feature", (r) => {
       r.useExtension("fileProvider", "s3");
     });
-    validateGdprHookCompleteness([f]);
-    expect(warnSpy).not.toHaveBeenCalled();
+    expect(() => validateGdprHookCompleteness([f])).not.toThrow();
   });
 
-  test("multiple features, one missing delete → one warn per missing hook", () => {
+  test("multiple features, one missing delete → throws naming the offender", () => {
     const good = defineFeature("good", (r) => {
       r.useExtension(EXT_USER_DATA, "entityA", { export: exportFn, delete: deleteFn });
     });
     const bad = defineFeature("bad", (r) => {
       r.useExtension(EXT_USER_DATA, "entityB", { export: exportFn });
     });
-    validateGdprHookCompleteness([good, bad]);
-    expect(warnSpy).toHaveBeenCalledTimes(1);
-    expect(String(warnSpy.mock.calls[0]?.[0])).toContain("entityB");
+    const msg = catchMessage(() => validateGdprHookCompleteness([good, bad]));
+    expect(msg).toContain("entityB");
   });
 });
 
 describe("validateGdprPiiHookCoverage (V3)", () => {
-  let warnSpy: ReturnType<typeof spyOn>;
-
-  beforeEach(() => {
-    warnSpy = spyOn(console, "warn").mockImplementation(() => {});
-  });
-
-  afterEach(() => {
-    warnSpy.mockRestore();
-  });
-
   const exportFn = async () => null;
   const deleteFn = async () => {};
 
@@ -174,30 +159,38 @@ describe("validateGdprPiiHookCoverage (V3)", () => {
       );
     });
 
-  test("user-data-rights not mounted → no warn", () => {
-    validateGdprPiiHookCoverage([piiFeature()]);
-    expect(warnSpy).not.toHaveBeenCalled();
+  test("user-data-rights not mounted → no throw", () => {
+    expect(() => validateGdprPiiHookCoverage([piiFeature()])).not.toThrow();
   });
 
-  test("pii entity without any EXT_USER_DATA hook → warn naming entity and fields", () => {
-    validateGdprPiiHookCoverage([udr(), piiFeature()]);
-    expect(warnSpy).toHaveBeenCalledTimes(1);
-    const msg = String(warnSpy.mock.calls[0]?.[0]);
+  test("pii entity without any EXT_USER_DATA hook → throws naming entity and fields", () => {
+    const msg = catchMessage(() => validateGdprPiiHookCoverage([udr(), piiFeature()]));
     expect(msg).toContain('"contact"');
     expect(msg).toContain("email");
     expect(msg).toContain("note");
     expect(msg).toContain("Art.17");
   });
 
-  test("pii entity with hook registered by another feature → no warn", () => {
+  test("pii entity with hook registered by another feature → no throw", () => {
     const hooks = defineFeature("crm-user-data", (r) => {
       r.useExtension(EXT_USER_DATA, "contact", { export: exportFn, delete: deleteFn });
     });
-    validateGdprPiiHookCoverage([udr(), piiFeature(), hooks]);
-    expect(warnSpy).not.toHaveBeenCalled();
+    expect(() => validateGdprPiiHookCoverage([udr(), piiFeature(), hooks])).not.toThrow();
   });
 
-  test("entity without subject annotations → no warn", () => {
+  test("no-op hook is the intentional escape hatch → no throw", () => {
+    const hooks = defineFeature("crm-user-data", (r) => {
+      // Escape hatch: erasure handled elsewhere (crypto-shredding key-erase),
+      // so the pipeline hook is a deliberate no-op.
+      r.useExtension(EXT_USER_DATA, "contact", {
+        export: async () => null,
+        delete: async () => {},
+      });
+    });
+    expect(() => validateGdprPiiHookCoverage([udr(), piiFeature(), hooks])).not.toThrow();
+  });
+
+  test("entity without subject annotations → no throw", () => {
     const plain = defineFeature("catalog", (r) => {
       r.entity(
         "product",
@@ -206,11 +199,10 @@ describe("validateGdprPiiHookCoverage (V3)", () => {
         }),
       );
     });
-    validateGdprPiiHookCoverage([udr(), plain]);
-    expect(warnSpy).not.toHaveBeenCalled();
+    expect(() => validateGdprPiiHookCoverage([udr(), plain])).not.toThrow();
   });
 
-  test("userOwned field alone counts as user-subject data → warn", () => {
+  test("userOwned field alone counts as user-subject data → throws", () => {
     const f = defineFeature("notes", (r) => {
       r.entity(
         "note",
@@ -222,8 +214,7 @@ describe("validateGdprPiiHookCoverage (V3)", () => {
         }),
       );
     });
-    validateGdprPiiHookCoverage([udr(), f]);
-    expect(warnSpy).toHaveBeenCalledTimes(1);
-    expect(String(warnSpy.mock.calls[0]?.[0])).toContain('"note"');
+    const msg = catchMessage(() => validateGdprPiiHookCoverage([udr(), f]));
+    expect(msg).toContain('"note"');
   });
 });

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

@@ -1,4 +1,4 @@
-import { EXT_USER_DATA } from "../extension-names";
+import { EXT_TENANT_DATA, EXT_USER_DATA } from "../extension-names";
 import type { FeatureDefinition } from "../types";
 import type { PiiAnnotations } from "../types/fields";
 
@@ -60,10 +60,12 @@ export function validateGdprStoragePersistence(features: readonly FeatureDefinit
   }
 }
 
-// V2: export-without-erase guard. A feature that registers an EXT_USER_DATA
+// V2: export-without-erase gate. A feature that registers an EXT_USER_DATA
 // export hook without a matching delete hook exports data under Art.20 but
-// never erases it on forget — an Art.17 violation. Registry-level signal only;
-// runtime no-ops (a delete hook that silently skips) are not detectable here.
+// never erases it on forget — an Art.17 violation. Hard boot failure: no app
+// should ship a GDPR export path with no erase path. Registry-level signal
+// only; runtime no-ops (a delete hook that silently skips) are not detectable
+// here — those are covered by the export/forget integration tests.
 export function validateGdprHookCompleteness(features: readonly FeatureDefinition[]): void {
   for (const feature of features) {
     for (const usage of feature.extensionUsages) {
@@ -71,21 +73,23 @@ export function validateGdprHookCompleteness(features: readonly FeatureDefinitio
       const hasExport = typeof usage.options?.["export"] === "function";
       const hasDelete = typeof usage.options?.["delete"] === "function";
       if (hasExport && !hasDelete) {
-        // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
-        console.warn(
-          `[kumiko:boot] Feature "${feature.name}" exports entity "${usage.entityName}" via EXT_USER_DATA but registers no delete hook — data is included in Art.20 exports but never erased on forget (Art.17 risk). Add a delete hook, or a no-op with a comment explaining why erasure is intentionally skipped.`,
+        throw new Error(
+          `[kumiko:boot] Feature "${feature.name}" exports entity "${usage.entityName}" via EXT_USER_DATA but registers no delete hook — data is included in Art.20 exports but never erased on forget (Art.17 violation). Add a delete hook. If erasure is intentionally handled elsewhere (e.g. crypto-shredding key-erase, parent cascade), register a no-op delete: async () => {} with a comment explaining why.`,
         );
       }
     }
   }
 }
 
-// V3: PII-entity-without-hook guard. V2 checks registered hooks for
+// V3: PII-entity-without-hook gate. V2 checks registered hooks for
 // completeness; V3 catches the entity nobody registered at all — fields
 // annotated as user-subject data (pii / userOwned) yet invisible to the
-// Art.15/20 export and Art.17 forget pipeline. Matching is by entity name
-// across all features (usage.entityName is unqualified); a same-named entity
-// in another feature can mask a gap — accepted for a WARN-level heuristic.
+// Art.15/20 export and Art.17 forget pipeline. Hard boot failure once
+// user-data-rights is mounted: a subject-data entity that skips the pipeline
+// is exactly the "feature built past GDPR" leak this gate exists to stop.
+// Matching is by entity name across all features (usage.entityName is
+// unqualified); a same-named entity in another feature can mask a gap —
+// accepted, as the common case is a distinct entity name.
 export function validateGdprPiiHookCoverage(features: readonly FeatureDefinition[]): void {
   const featureNames = new Set(features.map((f) => f.name));
   if (!featureNames.has("user-data-rights")) {
@@ -110,9 +114,41 @@ export function validateGdprPiiHookCoverage(features: readonly FeatureDefinition
         })
         .map(([name]) => name);
       if (subjectFields.length === 0) continue;
-      // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
-      console.warn(
-        `[kumiko:boot] Entity "${entityName}" (feature "${feature.name}") has user-subject fields (${subjectFields.join(", ")}) but no feature registers an EXT_USER_DATA hook for it — the data never appears in Art.15/20 exports and is never erased on forget (Art.17 gap). Register r.useExtension(EXT_USER_DATA, "${entityName}", { export, delete }) in the owning feature or a defaults feature.`,
+      throw new Error(
+        `[kumiko:boot] Entity "${entityName}" (feature "${feature.name}") has user-subject fields (${subjectFields.join(", ")}) but no feature registers an EXT_USER_DATA hook for it — the data never appears in Art.15/20 exports and is never erased on forget (Art.17 gap). Register r.useExtension(EXT_USER_DATA, "${entityName}", { export, delete }) in the owning feature or a defaults feature. If this entity is intentionally out of the pipeline (e.g. crypto-shredding key-erase covers it), register a no-op hook { export: async () => null, delete: async () => {} } with a comment explaining why.`,
+      );
+    }
+  }
+}
+
+// V4: tenantOwned-entity-without-hook gate. Mirrors validateGdprPiiHookCoverage
+// but for EXT_TENANT_DATA when tenant-lifecycle is mounted.
+export function validateTenantDataHookCoverage(features: readonly FeatureDefinition[]): void {
+  const featureNames = new Set(features.map((f) => f.name));
+  if (!featureNames.has("tenant-lifecycle")) {
+    // skip: this guard only applies to apps that mount tenant-lifecycle
+    return;
+  }
+
+  const hookedEntities = new Set<string>();
+  for (const f of features) {
+    for (const usage of f.extensionUsages) {
+      if (usage.extensionName === EXT_TENANT_DATA) hookedEntities.add(usage.entityName);
+    }
+  }
+
+  for (const feature of features) {
+    for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
+      if (hookedEntities.has(entityName)) continue;
+      const tenantSubjectFields = Object.entries(entity.fields)
+        .filter(([, field]) => {
+          const annot = field as PiiAnnotations;
+          return Boolean(annot.tenantOwned);
+        })
+        .map(([name]) => name);
+      if (tenantSubjectFields.length === 0) continue;
+      throw new Error(
+        `[kumiko:boot] Entity "${entityName}" (feature "${feature.name}") has tenant-subject fields (${tenantSubjectFields.join(", ")}) but no feature registers an EXT_TENANT_DATA destroy hook for it — tenant destroy never erases this data. Register r.useExtension(EXT_TENANT_DATA, "${entityName}", { destroy }) or a documented no-op if crypto-shredding covers it.`,
       );
     }
   }

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

@@ -31,6 +31,7 @@ import {
   validateGdprHookCompleteness,
   validateGdprPiiHookCoverage,
   validateGdprStoragePersistence,
+  validateTenantDataHookCoverage,
 } from "./gdpr-storage";
 import { validateI18nSurfaceKeys } from "./i18n-keys";
 import { validateOwnershipRules } from "./ownership";
@@ -184,6 +185,7 @@ export function validateBoot(features: readonly FeatureDefinition[]): void {
   validateGdprStoragePersistence(features);
   validateGdprHookCompleteness(features);
   validateGdprPiiHookCoverage(features);
+  validateTenantDataHookCoverage(features);
 
   if (hasEncryptedFields) {
     // Availability check, not env-presence: eagerly building the keyring

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

@@ -0,0 +1,19 @@
+// Hook-Signatur-Types für EXT_TENANT_DATA (DSGVO tenant-scoped destroy).
+//
+// Mirror of engine/extensions/user-data.ts at tenant granularity.
+// tenant-lifecycle orchestrates destroy via registry.getExtensionUsages(EXT_TENANT_DATA).
+
+import type { DbRunner } from "../../db/connection";
+import type { Registry, TenantId } from "../types";
+
+export interface TenantDataHookCtx {
+  readonly db: DbRunner;
+  readonly registry: Registry;
+  readonly tenantId: TenantId;
+}
+
+export type TenantDataDestroyHook = (ctx: TenantDataHookCtx) => Promise<void>;
+
+export interface TenantDataExtensionHooks {
+  readonly destroy: TenantDataDestroyHook;
+}

package/src/engine/index.ts

@@ -81,6 +81,11 @@ export {
   EXT_USER_DATA_ORDER,
   FILE_PROVIDER_CONFIG_KEY,
 } from "./extension-names";
+export type {
+  TenantDataDestroyHook,
+  TenantDataExtensionHooks,
+  TenantDataHookCtx,
+} from "./extensions/tenant-data";
 export type {
   TenantUserModel,
   UserDataDeleteHook,