@cosmicdrift/kumiko-framework 0.327.0 → 0.328.1

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

@@ -0,0 +1,164 @@
+import type { DerivativeRendererPlugin } from "@cosmicdrift/kumiko-types/derivatives-types";
+import type { OverlayResolverPlugin } from "../derivatives/derivatives-context.js";
+import type { FileProviderPlugin } from "../files/provider-resolver.js";
+import type { PrincipalStatusPlugin, TenantLifecycleStatusPlugin } from "./active-membership.js";
+import type { TenantDataExtensionHooks } from "./extensions/tenant-data.js";
+import type { TenantResourceExtensionHooks } from "./extensions/tenant-resource.js";
+import type { UserDataExtensionOptions } from "./extensions/user-data.js";
+import { TENANT_TIER_RESOLVER_EXT, type TierResolverPlugin } from "./tier-resolver-extension.js";
+/**
+ * `userData` — User-Daten-Rights-Hooks (DSGVO Art. 15 + 17 + 20).
+ *
+ * Erwartete Hook-Methoden:
+ *   - `export(userId, ctx) => Promise<UserDataExport>`
+ *   - `delete(userId, strategy: "delete" | "anonymize", ctx) => Promise<void>`
+ *
+ * Registriert von: `user-data-rights` (Sprint 2).
+ * Genutzt von: jedes Feature mit User-Referenzen (tasks, comments, files, ...).
+ */
+export declare const EXT_USER_DATA: "userData";
+export declare const EXT_USER_DATA_ORDER: {
+    readonly REDACT_BEFORE_OWNER: -100;
+    readonly DEFAULT: 0;
+};
+/**
+ * `tenantData` — Tenant-Destroy-Hooks pro Entity (DSGVO + AVV-Beendigung).
+ *
+ * Erwartete Hook-Methoden:
+ *   - `destroy(tenantId, ctx) => Promise<void>`
+ *
+ * Registriert von: `tenant-lifecycle` (Sprint 5).
+ * Genutzt von: jedes Feature mit tenantId-Field.
+ */
+export declare const EXT_TENANT_DATA: "tenantData";
+/**
+ * `storageProvider` — file-storage-plugin tenant-destroy hook.
+ *
+ * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<void>`.
+ *
+ * Registered by: `files-tenant-data`.
+ * Consumed by: pluggable providers (Local, MinIO, S3, R2).
+ */
+export declare const EXT_STORAGE_PROVIDER: "storageProvider";
+/**
+ * `fileProvider` — File-Storage-Provider-Plugin-Selection (file-foundation).
+ *
+ * Provider-Features (file-provider-s3, -inmemory, -s3-env) registrieren eine
+ * Implementierung via `r.useExtension(EXT_FILE_PROVIDER, "<name>", { build })`;
+ * der per-Tenant Config-Key `provider` waehlt zur Runtime eine aus. Der
+ * Framework-Resolver (`createFileProviderForTenant`) liest das, damit Upload-
+ * Routes, `ctx.files` UND die DSGVO-Jobs denselben Store treffen.
+ *
+ * Framework-seitig besessen, damit kein String-Drift entsteht — file-
+ * foundation MUSS Extension-Point + Config-Key unter genau diesen Namen
+ * registrieren.
+ */
+export declare const EXT_FILE_PROVIDER: "fileProvider";
+export declare const FILE_PROVIDER_CONFIG_KEY: "file-foundation:config:provider";
+export declare const FILE_STORAGE_PROVIDER_ENV: "FILE_STORAGE_PROVIDER";
+export declare const FILE_STORAGE_PROVIDER_BOOT_SENTINEL: "configured";
+/**
+ * `derivativeRenderer` — File-Derivative-Renderer-Plugin-Selection
+ * (file-derivatives).
+ *
+ * Renderer-Features (a future `derivatives-*` feature) register via
+ * `r.useExtension(EXT_DERIVATIVE_RENDERER, "<mimePattern>", { render })`,
+ * where `<mimePattern>` is an exact MIME type (`application/pdf`) or a
+ * type-wildcard (`image/*`). `ctx.derivatives.variant(...)` resolves the
+ * renderer for a FileRef's MIME type at call time — exact match first,
+ * wildcard second.
+ *
+ * No `r.extensionSelector` and no config key: unlike `fileProvider`, the
+ * resolution is deterministic from the MIME type — no tenant ever picks a
+ * different image library for the same content type.
+ */
+export declare const EXT_DERIVATIVE_RENDERER: "derivativeRenderer";
+/**
+ * `derivativePublicPredicate` — per-entityType "is this FileRef's derivative
+ * publicly readable?" gate for the anonymous variant route (file-derivatives).
+ *
+ * Apps register via
+ * `r.useExtension(EXT_DERIVATIVE_PUBLIC_PREDICATE, "<entityType>", { isPublic:
+ * (args, ctx) => boolean | Promise<boolean> })`, where `<entityType>` is the
+ * `entityType` string a FileRef carries from upload (e.g. "vehicle", "event").
+ * No registration for a given entityType is default-deny — the public route
+ * serves nothing for that entityType, not even a 403 (404, so existence isn't
+ * confirmed to an unauthorised caller).
+ *
+ * Registered/consumed by: `file-derivatives`' public variant route (#1951).
+ */
+export declare const EXT_DERIVATIVE_PUBLIC_PREDICATE: "derivativePublicPredicate";
+/**
+ * `derivativeOverlayResolver` — per-entityType "resolve this overlay
+ * dataToken to its real value" contract for `file-derivatives`' overlay
+ * compositing (QR codes on a public variant).
+ *
+ * Apps register via `r.useExtension(EXT_DERIVATIVE_OVERLAY_RESOLVER,
+ * "<entityType>", { resolve: (args) => string | Promise<string> })`. Missing
+ * registration, or a resolve() returning an empty string, both throw —
+ * unlike `derivativePublicPredicate`, there is no default-deny answer here:
+ * an image silently rendered without its QR would look correct while being
+ * wrong.
+ *
+ * Registered/consumed by: `file-derivatives`'s `variant()`
+ * (derivatives-context.ts), before the variant's spec hash is computed.
+ */
+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>`.
+ *
+ * Consumed by: Meilisearch and other search-adapter implementations.
+ */
+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>`.
+ */
+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>`.
+ */
+export declare const EXT_INFRA_RESOURCE: "infraResource";
+/**
+ * `principalStatus` — "is this principal blocked from signing in" contract,
+ * consulted by the active-membership building block; fulfilled by the bundled `user` feature.
+ */
+export declare const EXT_PRINCIPAL_STATUS: "principalStatus";
+/**
+ * `tenantLifecycleStatus` — tenant-teardown status contract, fulfilled by
+ * the bundled `tenant-lifecycle` feature; absent means no tenant is ever "in teardown".
+ */
+export declare const EXT_TENANT_LIFECYCLE_STATUS: "tenantLifecycleStatus";
+export declare const TENANT_MEMBERSHIPS_QUERY: "tenant:query:memberships";
+/**
+ * Union aller standardisierten Extension-Namen der Datenschutz-Surface.
+ * Nicht alle Extensions im System sind in dieser Liste — andere
+ * Features koennen weiterhin eigene Extension-Namen registrieren.
+ */
+export type KumikoExtensionName = typeof EXT_USER_DATA | typeof EXT_TENANT_DATA | typeof EXT_STORAGE_PROVIDER | typeof EXT_SEARCH_ADAPTER | typeof EXT_EXTERNAL_RESOURCE | typeof EXT_INFRA_RESOURCE | typeof EXT_FILE_PROVIDER | typeof EXT_DERIVATIVE_RENDERER | typeof EXT_DERIVATIVE_PUBLIC_PREDICATE | typeof EXT_DERIVATIVE_OVERLAY_RESOLVER | typeof EXT_PRINCIPAL_STATUS | typeof EXT_TENANT_LIFECYCLE_STATUS;
+/** The four `destroyTenant(tenantId, ctx)`-only resource-cleanup extension points. */
+export type TenantResourceExtensionName = typeof EXT_STORAGE_PROVIDER | typeof EXT_SEARCH_ADAPTER | typeof EXT_EXTERNAL_RESOURCE | typeof EXT_INFRA_RESOURCE;
+declare module "@cosmicdrift/kumiko-framework/engine" {
+    interface KumikoExtensionOptionsMap {
+        [EXT_TENANT_DATA]: TenantDataExtensionHooks;
+        [EXT_USER_DATA]: UserDataExtensionOptions;
+        [EXT_FILE_PROVIDER]: FileProviderPlugin;
+        [EXT_DERIVATIVE_RENDERER]: DerivativeRendererPlugin;
+        [EXT_DERIVATIVE_OVERLAY_RESOLVER]: OverlayResolverPlugin;
+        [EXT_PRINCIPAL_STATUS]: PrincipalStatusPlugin;
+        [EXT_TENANT_LIFECYCLE_STATUS]: TenantLifecycleStatusPlugin;
+        [EXT_STORAGE_PROVIDER]: TenantResourceExtensionHooks;
+        [EXT_SEARCH_ADAPTER]: TenantResourceExtensionHooks;
+        [EXT_EXTERNAL_RESOURCE]: TenantResourceExtensionHooks;
+        [EXT_INFRA_RESOURCE]: TenantResourceExtensionHooks;
+        [TENANT_TIER_RESOLVER_EXT]: TierResolverPlugin;
+    }
+}

package/dist/engine/extension-names.js

@@ -0,0 +1,172 @@
+import { TENANT_TIER_RESOLVER_EXT } from "./tier-resolver-extension.js";
+// Standardisierte Extension-Namen fuer Datenschutz-Hook-Achsen.
+//
+// Features registrieren Extensions via:
+//   r.extendsRegistrar(EXT_USER_DATA, { hooks: { ... } });
+//
+// Andere Features haengen sich ein via:
+//   r.useExtension(EXT_USER_DATA, "myEntity", { ...hookImpls });
+//
+// Hintergrund: Magic-Strings driften zwischen Bundled-Features (Beispiel:
+// text-content nutzt "Admin" als Rolle, tenant-handler nutzt "TenantAdmin").
+// Constants sind die einzige Quelle der Wahrheit; String-Literale werden
+// in den Sprint-Touchpoints schrittweise ersetzt. Boot-Validator
+// (validateExtensionUsages) checkt dass jedes useExtension einen
+// passenden extendsRegistrar findet — Tippfehler in Constants →
+// Compile-Time-Fail.
+//
+// Hook-Signaturen + Boot-Validation pro Extension-Achse kommen mit dem
+// jeweiligen registrierenden Sprint:
+//   userData / tenantData         → Sprint 2 (user-data-rights, retention)
+//   storageProvider                → Sprint 4 (storage-encryption)
+//   searchAdapter / external /     → Sprint 5 (tenant-lifecycle)
+//   infraResource
+/**
+ * `userData` — User-Daten-Rights-Hooks (DSGVO Art. 15 + 17 + 20).
+ *
+ * Erwartete Hook-Methoden:
+ *   - `export(userId, ctx) => Promise<UserDataExport>`
+ *   - `delete(userId, strategy: "delete" | "anonymize", ctx) => Promise<void>`
+ *
+ * Registriert von: `user-data-rights` (Sprint 2).
+ * Genutzt von: jedes Feature mit User-Referenzen (tasks, comments, files, ...).
+ */
+export const EXT_USER_DATA = "userData";
+// Order-Bänder für EXT_USER_DATA-Hooks (forget-Pipeline). Der Kontrakt war
+// implizit über zwei Packages verteilt (-100 in custom-fields, 0 in
+// user-data-rights) — ein Host-Hook mit order < REDACT_BEFORE_OWNER liefe
+// VOR den Redaktoren und brächte den Strip-nach-owner-null-Bug zurück
+// (DSGVO-Art.-17-Regression). Regel: Redaktoren < 0 <= owner-mutierende Hooks.
+export const EXT_USER_DATA_ORDER = {
+    REDACT_BEFORE_OWNER: -100,
+    DEFAULT: 0,
+};
+/**
+ * `tenantData` — Tenant-Destroy-Hooks pro Entity (DSGVO + AVV-Beendigung).
+ *
+ * Erwartete Hook-Methoden:
+ *   - `destroy(tenantId, ctx) => Promise<void>`
+ *
+ * Registriert von: `tenant-lifecycle` (Sprint 5).
+ * Genutzt von: jedes Feature mit tenantId-Field.
+ */
+export const EXT_TENANT_DATA = "tenantData";
+/**
+ * `storageProvider` — file-storage-plugin tenant-destroy hook.
+ *
+ * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<void>`.
+ *
+ * Registered by: `files-tenant-data`.
+ * Consumed by: pluggable providers (Local, MinIO, S3, R2).
+ */
+export const EXT_STORAGE_PROVIDER = "storageProvider";
+/**
+ * `fileProvider` — File-Storage-Provider-Plugin-Selection (file-foundation).
+ *
+ * Provider-Features (file-provider-s3, -inmemory, -s3-env) registrieren eine
+ * Implementierung via `r.useExtension(EXT_FILE_PROVIDER, "<name>", { build })`;
+ * der per-Tenant Config-Key `provider` waehlt zur Runtime eine aus. Der
+ * Framework-Resolver (`createFileProviderForTenant`) liest das, damit Upload-
+ * Routes, `ctx.files` UND die DSGVO-Jobs denselben Store treffen.
+ *
+ * Framework-seitig besessen, damit kein String-Drift entsteht — file-
+ * foundation MUSS Extension-Point + Config-Key unter genau diesen Namen
+ * registrieren.
+ */
+export const EXT_FILE_PROVIDER = "fileProvider";
+// Qualifizierter Config-Key, den das file-foundation-Feature registriert
+// (Format `<feature>:config:<key>`). Akzeptierte Kopplung: der Framework-
+// Resolver liegt UNTER dem Feature und liest den Key per String. Umbenennen
+// des file-foundation-Features MUSS diese Konstante mitziehen.
+export const FILE_PROVIDER_CONFIG_KEY = "file-foundation:config:provider";
+// Two roles: boot gate (validateBoot requires its presence once file/image
+// fields are in use) AND the ENV source of the config key above, bridged via
+// keyDef.env. Tenant rows keep overriding the bridged value.
+export const FILE_STORAGE_PROVIDER_ENV = "FILE_STORAGE_PROVIDER";
+// Presence placeholder runDevApp writes when an explicitly wired provider
+// (options.files) already satisfies the boot gate. It names no plugin, so
+// provider resolution treats it like an unset key.
+export const FILE_STORAGE_PROVIDER_BOOT_SENTINEL = "configured";
+/**
+ * `derivativeRenderer` — File-Derivative-Renderer-Plugin-Selection
+ * (file-derivatives).
+ *
+ * Renderer-Features (a future `derivatives-*` feature) register via
+ * `r.useExtension(EXT_DERIVATIVE_RENDERER, "<mimePattern>", { render })`,
+ * where `<mimePattern>` is an exact MIME type (`application/pdf`) or a
+ * type-wildcard (`image/*`). `ctx.derivatives.variant(...)` resolves the
+ * renderer for a FileRef's MIME type at call time — exact match first,
+ * wildcard second.
+ *
+ * No `r.extensionSelector` and no config key: unlike `fileProvider`, the
+ * resolution is deterministic from the MIME type — no tenant ever picks a
+ * different image library for the same content type.
+ */
+export const EXT_DERIVATIVE_RENDERER = "derivativeRenderer";
+/**
+ * `derivativePublicPredicate` — per-entityType "is this FileRef's derivative
+ * publicly readable?" gate for the anonymous variant route (file-derivatives).
+ *
+ * Apps register via
+ * `r.useExtension(EXT_DERIVATIVE_PUBLIC_PREDICATE, "<entityType>", { isPublic:
+ * (args, ctx) => boolean | Promise<boolean> })`, where `<entityType>` is the
+ * `entityType` string a FileRef carries from upload (e.g. "vehicle", "event").
+ * No registration for a given entityType is default-deny — the public route
+ * serves nothing for that entityType, not even a 403 (404, so existence isn't
+ * confirmed to an unauthorised caller).
+ *
+ * Registered/consumed by: `file-derivatives`' public variant route (#1951).
+ */
+export const EXT_DERIVATIVE_PUBLIC_PREDICATE = "derivativePublicPredicate";
+/**
+ * `derivativeOverlayResolver` — per-entityType "resolve this overlay
+ * dataToken to its real value" contract for `file-derivatives`' overlay
+ * compositing (QR codes on a public variant).
+ *
+ * Apps register via `r.useExtension(EXT_DERIVATIVE_OVERLAY_RESOLVER,
+ * "<entityType>", { resolve: (args) => string | Promise<string> })`. Missing
+ * registration, or a resolve() returning an empty string, both throw —
+ * unlike `derivativePublicPredicate`, there is no default-deny answer here:
+ * an image silently rendered without its QR would look correct while being
+ * wrong.
+ *
+ * Registered/consumed by: `file-derivatives`'s `variant()`
+ * (derivatives-context.ts), before the variant's spec hash is computed.
+ */
+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>`.
+ *
+ * Consumed by: Meilisearch and other search-adapter implementations.
+ */
+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>`.
+ */
+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>`.
+ */
+export const EXT_INFRA_RESOURCE = "infraResource";
+/**
+ * `principalStatus` — "is this principal blocked from signing in" contract,
+ * consulted by the active-membership building block; fulfilled by the bundled `user` feature.
+ */
+export const EXT_PRINCIPAL_STATUS = "principalStatus";
+/**
+ * `tenantLifecycleStatus` — tenant-teardown status contract, fulfilled by
+ * the bundled `tenant-lifecycle` feature; absent means no tenant is ever "in teardown".
+ */
+export const EXT_TENANT_LIFECYCLE_STATUS = "tenantLifecycleStatus";
+// Default membership-list query handler name. Accepted coupling, same
+// pattern as FILE_PROVIDER_CONFIG_KEY — the `tenant` feature registers a handler under this literal.
+export const TENANT_MEMBERSHIPS_QUERY = "tenant:query:memberships";

package/dist/engine/extension-selector-plugins.d.ts

@@ -0,0 +1,5 @@
+import type { Registry } from "./types/feature.js";
+export declare const SELECTED_EXTENSIONS_QUERY = "config:query:config-value:selected-extensions";
+export declare const EXTENSION_SELECTOR_HINT_KEY = "config.settings.extensionSelectorHint";
+export declare function selectablePluginIds(registry: Pick<Registry, "getExtensionUsages">, extensionName: string): string[];
+export declare function extensionSelectorTargets(registry: Pick<Registry, "getAllExtensionSelectors">): ReadonlyMap<string, string>;

package/dist/engine/extension-selector-plugins.js

@@ -0,0 +1,14 @@
+// Pinned QN of config's selected-extensions query — framework cannot import
+// bundled-features, so a pin test bundled-side keeps it equal to the handler.
+export const SELECTED_EXTENSIONS_QUERY = "config:query:config-value:selected-extensions";
+export const EXTENSION_SELECTOR_HINT_KEY = "config.settings.extensionSelectorHint";
+export function selectablePluginIds(registry, extensionName) {
+    return [...new Set(registry.getExtensionUsages(extensionName).map((u) => u.entityName))].sort();
+}
+export function extensionSelectorTargets(registry) {
+    const extensionByKey = new Map();
+    for (const [extensionName, selectorKey] of registry.getAllExtensionSelectors()) {
+        extensionByKey.set(selectorKey, extensionName);
+    }
+    return extensionByKey;
+}

package/dist/engine/extensions/escape-hatch-usage.d.ts

@@ -0,0 +1,2 @@
+import type { RegistrarExtensionRegistration } from "../types/config.js";
+export declare function extensionUsageEscapeHatchReason(usage: Pick<RegistrarExtensionRegistration, "options">): string | undefined;

package/dist/engine/extensions/escape-hatch-usage.js

@@ -0,0 +1,12 @@
+// fw#2914 — reads the { escapeHatch: { reason } } convention off a
+// `r.useExtension(...)` registration's untyped options bag. Registration-time
+// validation (feature-ui-extensions.ts's useExtension) already rejects an
+// empty reason, but options stays `Record<string, unknown>`, so orchestrators
+// re-narrow at read time instead of trusting the shape.
+export function extensionUsageEscapeHatchReason(usage) {
+    const escapeHatch = usage.options?.["escapeHatch"];
+    if (typeof escapeHatch !== "object" || escapeHatch === null)
+        return undefined;
+    const reason = escapeHatch.reason;
+    return typeof reason === "string" && reason.trim().length > 0 ? reason : undefined;
+}

package/dist/engine/extensions/storage-provider.d.ts

@@ -0,0 +1,4 @@
+import type { TenantResourceDestroyHook, TenantResourceExtensionHooks, TenantResourceHookCtx } from "./tenant-resource.js";
+export type StorageProviderHookCtx = TenantResourceHookCtx;
+export type StorageProviderDestroyTenantHook = TenantResourceDestroyHook;
+export type StorageProviderExtensionHooks = TenantResourceExtensionHooks;

package/dist/engine/extensions/storage-provider.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,15 @@
+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";
+export interface TenantDataHookCtx {
+    readonly db: TenantDb;
+    readonly registry: Registry;
+    readonly tenantId: TenantId;
+    readonly fileProviderResolver?: FileProviderResolver;
+    readonly log?: (message: string) => void;
+}
+export type TenantDataDestroyHook = (ctx: TenantDataHookCtx) => Promise<void>;
+export interface TenantDataExtensionHooks {
+    readonly destroy: TenantDataDestroyHook;
+}
+export declare function isTenantDataExtensionHooks(o: unknown): o is TenantDataExtensionHooks;

package/dist/engine/extensions/tenant-data.js

@@ -0,0 +1,7 @@
+// 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).
+export function isTenantDataExtensionHooks(o) {
+    return typeof o === "object" && o !== null && "destroy" in o && typeof o.destroy === "function";
+}

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

@@ -0,0 +1,14 @@
+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 interface TenantResourceHookCtx {
+    readonly tenantId: TenantId;
+    readonly db: DbRunner;
+    readonly fileProviderResolver?: FileProviderResolver;
+    readonly log?: (message: string) => void;
+}
+export type TenantResourceDestroyHook = (tenantId: TenantId, ctx: TenantResourceHookCtx) => Promise<void>;
+export interface TenantResourceExtensionHooks {
+    readonly destroyTenant: TenantResourceDestroyHook;
+}
+export declare function isTenantResourceExtensionHooks(o: unknown): o is TenantResourceExtensionHooks;

package/dist/engine/extensions/tenant-resource.js

@@ -0,0 +1,6 @@
+export function isTenantResourceExtensionHooks(o) {
+    return (typeof o === "object" &&
+        o !== null &&
+        "destroyTenant" in o &&
+        typeof o.destroyTenant === "function");
+}

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

@@ -0,0 +1,152 @@
+import type { TenantDb } from "../../db/tenant-db.js";
+import type { Registry, TenantId } from "../types/index.js";
+type UserId = string;
+/**
+ * Strategie für den Forget-Pfad pro Entity:
+ *   - "delete":    Row physisch entfernen (Profil, Eigene Notizen, Sessions).
+ *   - "anonymize": User-Reference auf null + Display-Felder auf
+ *                  "[Geloescht]" — typisch für geteilte Daten (Tasks,
+ *                  Comments) damit andere User die History nicht verlieren.
+ *
+ * Cleanup-Job (Sprint 2 data-retention) entscheidet pro Entity über
+ * Retention-Policy, welche Strategie greift. blockDelete-Entries lösen
+ * IMMER `anonymize` aus damit Aufbewahrungs-Pflicht respektiert wird.
+ */
+export type UserDataDeleteStrategy = "delete" | "anonymize";
+/**
+ * Effective tenant-occupancy model for THIS tenant during a forget run, set by
+ * the forget orchestrator. `"single-user"` means the tenant has exactly one
+ * member (the user being forgotten) — so a tenant-scoped contributor MAY erase
+ * the tenant's data as that user's personal data. `"multi-user"` (the safe
+ * default) means tenant-scoped rows are shared and must NOT be erased per-user.
+ *
+ * The orchestrator derives this from the app-level `tenantModel` config AND a
+ * runtime sole-member check, so a stray invite that makes the config's
+ * `"single-user"` claim false at runtime never causes a co-member's data to be
+ * deleted. Absent → treat as `"multi-user"`.
+ */
+export type TenantUserModel = "single-user" | "multi-user";
+/**
+ * fw#2914 — `db` is a tenant-filtered `TenantDb`, bound to `tenantId`
+ * (or the per-user sub-tx in the forget path). Unfiltered access needs
+ * `escapeHatch: { reason }` on the `r.useExtension(...)` registration,
+ * then `ctx.db.unsafeRaw(reason)`.
+ */
+/**
+ * Minimal storage surface a file-aware forget hook needs to erase binaries.
+ * Structural on purpose — the engine stays free of a dependency on the files
+ * package; `FileStorageProvider` is assignable here. The forget/export
+ * orchestrator resolves the concrete provider per tenant from the mounted
+ * file-foundation and injects it via `UserDataHookCtx.buildStorageProvider`.
+ */
+export interface UserDataStorageProvider {
+    delete(storageKey: string): Promise<void>;
+    list(prefix: string): Promise<readonly string[]>;
+}
+export interface UserDataHookCtx {
+    readonly db: TenantDb;
+    /**
+     * The app registry. A forget hook that must erase CHILD read-model rows past
+     * the entity's own row — m:n join projections, per-parent detail projections —
+     * uses it to run those custom projections for the executor's
+     * `<entity>.forgotten` event: `runProjectionsForEvent(result.data.event,
+     * ctx.registry, ctx.db)`. `executor.forget` purges only its OWN projection,
+     * and the dispatcher's post-command projection pass does not fire in the forget
+     * pipeline (a job, not a dispatched command), so the hook must trigger the
+     * cascade itself. Live-erase + rebuild `<parent>.forgotten`-apply converge.
+     */
+    readonly registry: Registry;
+    readonly tenantId: TenantId;
+    readonly userId: UserId;
+    /**
+     * Per-tenant storage-provider resolver, injected by the forget orchestrator
+     * from the mounted file-foundation — so a hook deletes binaries from the
+     * SAME store the upload/export path uses (delete-target == upload-target by
+     * construction). Undefined when no file provider is resolvable; file-aware
+     * hooks then skip binary cleanup (row-only delete) and warn. Resolution
+     * failures (provider not configured) should be caught by the hook so a
+     * misconfigured store never permanently blocks the user's erasure.
+     */
+    readonly buildStorageProvider?: (tenantId: TenantId) => Promise<UserDataStorageProvider | undefined>;
+    /**
+     * Effective tenant-occupancy model for this tenant — see {@link TenantUserModel}.
+     * A tenant-scoped contributor reads this to decide whether per-user erasure may
+     * touch tenant-scoped rows. Absent → treat as `"multi-user"` (no erasure).
+     */
+    readonly tenantModel?: TenantUserModel;
+    /**
+     * Original user email captured before the forget transaction anonymizes it.
+     * Set on delete hooks during `runForgetCleanup` so matchers (e.g. email
+     * subscriptions) work in every tenant pass. Absent on export hooks.
+     */
+    readonly userEmailBeforeDelete?: string | null;
+}
+/**
+ * Pro Feature/Entity-Snippet das im Export-Bundle landet. Sprint 2
+ * orchestriert die JSON-Serialisierung; Hooks geben Plain-Records.
+ */
+export interface UserDataExportSnippet {
+    readonly entity: string;
+    readonly rows: ReadonlyArray<Record<string, unknown>>;
+    /**
+     * Optional: signed-URLs für File-Refs. user-data-rights packt sie
+     * separat ins ZIP unter `files/`. Andere Hooks lassen das leer.
+     */
+    readonly fileRefs?: ReadonlyArray<{
+        readonly fileRefId: string;
+        readonly storageKey: string;
+        readonly fileName: string;
+    }>;
+}
+/**
+ * Export-Hook: Sammelt alle Daten einer Entity die zu einem User
+ * gehören. Wird im Daten-Export-Job pro registrierter Entity einmal
+ * aufgerufen. Idempotent — kann mehrfach aufgerufen werden ohne
+ * Side-Effects.
+ *
+ * Sprint 2 user-data-rights ruft das via Iteration über alle
+ * `r.useExtension(EXT_USER_DATA, ...)`-Registrierungen.
+ */
+export type UserDataExportHook = (ctx: UserDataHookCtx) => Promise<UserDataExportSnippet | null>;
+/**
+ * Forget-Hook: Löscht oder anonymisiert die Entity-Rows die zu einem
+ * User gehören. Strategy kommt vom Cleanup-Job (kann per Entity
+ * unterschiedlich sein wegen Retention-Policy).
+ *
+ * Idempotent — wenn der Job zweimal läuft (Crash-Recovery), darf der
+ * Hook nicht crashen.
+ *
+ * Return additive to `void`: a hook can return `{status:"ok"}` or
+ * `{status:"incomplete", reason}` to signal a partial success to the
+ * cleanup runner (e.g. an external provider call failed) without
+ * throwing/rolling back the sub-transaction. Existing `void` returners
+ * stay valid unchanged — including ones explicitly typed
+ * `Promise<void>` (an explicitly-annotated hook, unlike a contextually-
+ * typed arrow literal, needs `void` in the union itself: `void` is not
+ * assignable to `undefined`).
+ */
+export type UserDataDeleteHookResult = void | {
+    readonly status: "ok";
+} | {
+    readonly status: "incomplete";
+    readonly reason: string;
+};
+export type UserDataDeleteHook = (ctx: UserDataHookCtx, strategy: UserDataDeleteStrategy) => Promise<UserDataDeleteHookResult>;
+/**
+ * Full hook table for EXT_USER_DATA. Export-only is a legitimate partial
+ * contract, so registrations are typed by `UserDataExtensionOptions`.
+ */
+export interface UserDataExtensionHooks {
+    readonly export: UserDataExportHook;
+    readonly delete: UserDataDeleteHook;
+}
+export type UserDataExtensionOptions = ({
+    readonly export: UserDataExportHook;
+    readonly delete?: UserDataDeleteHook;
+} | {
+    readonly export?: UserDataExportHook;
+    readonly delete: UserDataDeleteHook;
+}) & {
+    readonly order?: number;
+};
+export {};

package/dist/engine/extensions/user-data.js

@@ -0,0 +1,12 @@
+// Hook signature types for the EXT_USER_DATA extension (GDPR Art. 15+17+20).
+//
+// The boot validator does not check useExtension(EXT_USER_DATA, "X", { export: ... })
+// hook shapes against an expected signature — these types are the canonical
+// schema view; app authors get compile-time hints only, no runtime validation.
+//
+// The runner pipelines that consume these hooks are built and live: see
+// packages/bundled-features/src/user-data-rights/run-user-export.ts,
+// run-forget-cleanup.ts, run-export-jobs.ts.
+//
+// See docs/plans/datenschutz/user-data-rights.md.
+export {};