@cosmicdrift/kumiko-framework 0.305.0 → 0.306.0

package/src/engine/extension-names.ts

@@ -1,3 +1,12 @@
+import type { DerivativeRendererPlugin } from "@cosmicdrift/kumiko-types/derivatives-types";
+import type { OverlayResolverPlugin } from "../derivatives/derivatives-context";
+import type { FileProviderPlugin } from "../files/provider-resolver";
+import type { PrincipalStatusPlugin, TenantLifecycleStatusPlugin } from "./active-membership";
+import type { TenantDataExtensionHooks } from "./extensions/tenant-data";
+import type { TenantResourceExtensionHooks } from "./extensions/tenant-resource";
+import type { UserDataExtensionOptions } from "./extensions/user-data";
+import { TENANT_TIER_RESOLVER_EXT, type TierResolverPlugin } from "./tier-resolver-extension";
+
 // Standardisierte Extension-Namen fuer Datenschutz-Hook-Achsen.
 //
 // Features registrieren Extensions via:
@@ -55,14 +64,12 @@ export const EXT_USER_DATA_ORDER = {
 export const EXT_TENANT_DATA = "tenantData" as const;
 
 /**
- * `storageProvider` — File-Storage-Plugin-Hooks (Crypto-Shredding fuer Files).
+ * `storageProvider` — file-storage-plugin tenant-destroy hook.
  *
- * Erwartete Hook-Methoden:
- *   - `destroyTenant(tenantId, ctx) => Promise<void>`
- *   - `destroySubject(subject, ctx) => Promise<{ deleted: number }>`
+ * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<void>`.
  *
- * Registriert von: `storage-encryption` (Sprint 4).
- * Genutzt von: pluggable Provider (Local, MinIO, S3, R2).
+ * Registered by: `files-tenant-data`.
+ * Consumed by: pluggable providers (Local, MinIO, S3, R2).
  */
 export const EXT_STORAGE_PROVIDER = "storageProvider" as const;
 
@@ -148,37 +155,28 @@ export const EXT_DERIVATIVE_PUBLIC_PREDICATE = "derivativePublicPredicate" as co
 export const EXT_DERIVATIVE_OVERLAY_RESOLVER = "derivativeOverlayResolver" as const;
 
 /**
- * `searchAdapter` — Search-Adapter-Forget-Hooks (Meilisearch-Index-Cleanup
- * bei User-Forget oder Tenant-Destroy).
+ * `searchAdapter` — search-index tenant-destroy hook (Meilisearch index
+ * cleanup on tenant-destroy).
  *
- * Erwartete Hook-Methoden:
- *   - `destroyTenant(tenantId, ctx) => Promise<void>`
- *   - `eraseSubject(subject, ctx) => Promise<void>`
+ * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<void>`.
  *
- * Registriert von: `tenant-lifecycle` (Sprint 5).
- * Genutzt von: Meilisearch- und andere Search-Adapter-Implementierungen.
+ * Consumed by: Meilisearch and other search-adapter implementations.
  */
 export const EXT_SEARCH_ADAPTER = "searchAdapter" as const;
 
 /**
- * `externalResource` — External-Service-Tenant-Cleanup
- * (Webhook-Subscriptions, Brevo-Empfaenger-Listen, Stripe-Customer-Account).
+ * `externalResource` — external-service tenant-destroy hook (webhook
+ * subscriptions, Brevo recipient lists, provider customer accounts).
  *
- * Erwartete Hook-Methoden:
- *   - `destroyTenant(tenantId, ctx) => Promise<void>`
- *
- * Registriert von: `tenant-lifecycle` (Sprint 5).
+ * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<void>`.
  */
 export const EXT_EXTERNAL_RESOURCE = "externalResource" as const;
 
 /**
- * `infraResource` — Pulumi-managed Resources pro Tenant
- * (Custom-Domain, Cert-Manager-Issuer, dedicated Pod/Volume).
+ * `infraResource` — Pulumi-managed per-tenant resource tenant-destroy hook
+ * (custom domain, cert-manager issuer, dedicated pod/volume).
  *
- * Erwartete Hook-Methoden:
- *   - `destroyTenant(tenantId, ctx) => Promise<void>`
- *
- * Registriert von: `tenant-lifecycle` (Sprint 5).
+ * Expected hook method: `destroyTenant(tenantId, ctx) => Promise<void>`.
  */
 export const EXT_INFRA_RESOURCE = "infraResource" as const;
 
@@ -206,7 +204,39 @@ export const TENANT_MEMBERSHIPS_QUERY = "tenant:query:memberships" as const;
 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;
+
+// r.useExtension options-shape for framework-owned extension points; app/bundled-features-owned
+// points augment co-located with their owner, since the framework never imports upward.
+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/src/engine/extensions/storage-provider.ts

@@ -1,43 +1,16 @@
-// Hook signature types for EXT_STORAGE_PROVIDER (tenant-destroy binary cleanup).
-//
-// Mirror of tenant-data.ts, but the destroyTenant hook takes (tenantId, ctx)
-// rather than just (ctx) — runExtensionDestroyHooks (tenant-lifecycle/stages.ts)
-// passes tenantId as its own positional arg for every EXT_*_RESOURCE-style
-// extension point, not just this one. ctx here guarantees tenantId, db, plus
-// the optional fileProviderResolver/log; the richer stage-runner ctx
-// (tenant-lifecycle's DestructionStageCtx) is a structural superset, so a hook
-// typed against this minimal ctx is safely assignable wherever that richer ctx
-// is passed.
-//
-// `db` is a raw DbRunner, NOT a tenant-scoped TenantDb — unlike
-// TenantDataHookCtx.db (EXT_TENANT_DATA), runExtensionDestroyHooks hands every
-// EXT_*_RESOURCE-style hook (this one included) the stage runner's own
-// DestructionStageCtx.db straight through, with no tenant filter and no
-// escapeHatch/unsafeRaw gate — there is nothing to declare, because nothing
-// ever wraps it. That's deliberate for this stage family: wiping a whole
-// search index, an S3 prefix, or infra resources is inherently a cross-tenant,
-// bulk operation, not a row-scoped one. A hook that needs a plain read across
-// tenants (kumiko-framework#3035: does a foreign tenant's file_refs row still
+// EXT_STORAGE_PROVIDER (tenant-destroy binary cleanup) is one of the four
+// EXT_*_RESOURCE-style extension points — see tenant-resource.ts for the
+// shared hook-signature contract. Kept as aliases so the existing public
+// exports/imports stay valid; a hook that needs a plain cross-tenant read
+// (kumiko-framework#3035: does a foreign tenant's file_refs row still
 // reference a key under THIS tenant's storage prefix) uses `db` directly via
-// executeRawQueryRead — there is no `ctx.systemDb` here (that belongs to
-// HandlerContext / r.systemScope() write-handler dispatch, a different code
-// path this stage runner never goes through).
-import type { FileProviderResolver } from "@cosmicdrift/kumiko-types/file-provider-resolver-types";
-import type { DbRunner } from "../../db/connection";
-import type { TenantId } from "../types";
+// executeRawQueryRead — there is no `ctx.systemDb` here.
+import type {
+  TenantResourceDestroyHook,
+  TenantResourceExtensionHooks,
+  TenantResourceHookCtx,
+} from "./tenant-resource";
 
-export interface StorageProviderHookCtx {
-  readonly tenantId: TenantId;
-  readonly db: DbRunner;
-  readonly fileProviderResolver?: FileProviderResolver;
-  readonly log?: (message: string) => void;
-}
-
-export type StorageProviderDestroyTenantHook = (
-  tenantId: TenantId,
-  ctx: StorageProviderHookCtx,
-) => Promise<void>;
-
-export interface StorageProviderExtensionHooks {
-  readonly destroyTenant: StorageProviderDestroyTenantHook;
-}
+export type StorageProviderHookCtx = TenantResourceHookCtx;
+export type StorageProviderDestroyTenantHook = TenantResourceDestroyHook;
+export type StorageProviderExtensionHooks = TenantResourceExtensionHooks;

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

@@ -28,3 +28,7 @@ export type TenantDataDestroyHook = (ctx: TenantDataHookCtx) => Promise<void>;
 export interface TenantDataExtensionHooks {
   readonly destroy: TenantDataDestroyHook;
 }
+
+export function isTenantDataExtensionHooks(o: unknown): o is TenantDataExtensionHooks {
+  return typeof o === "object" && o !== null && "destroy" in o && typeof o.destroy === "function";
+}

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

@@ -0,0 +1,40 @@
+// Hook signature types shared by the four EXT_*_RESOURCE-style extension
+// points (storageProvider, searchAdapter, externalResource, infraResource).
+// runExtensionDestroyHooks (tenant-lifecycle/stages.ts) passes tenantId as
+// its own positional arg for all of them, not just storageProvider — the
+// stage runner's DestructionStageCtx is a structural superset of the ctx
+// below, so a hook typed against it is safely assignable wherever the
+// richer ctx is passed.
+//
+// `db` is a raw DbRunner, not a tenant-scoped TenantDb: wiping a whole
+// search index, an S3 prefix, or infra resources is inherently a
+// cross-tenant, bulk operation, not a row-scoped one — there is no
+// escapeHatch/unsafeRaw gate here because nothing ever wraps `db`.
+import type { FileProviderResolver } from "@cosmicdrift/kumiko-types/file-provider-resolver-types";
+import type { DbRunner } from "../../db/connection";
+import type { TenantId } from "../types";
+
+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 function isTenantResourceExtensionHooks(o: unknown): o is TenantResourceExtensionHooks {
+  return (
+    typeof o === "object" &&
+    o !== null &&
+    "destroyTenant" in o &&
+    typeof o.destroyTenant === "function"
+  );
+}

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

@@ -166,15 +166,16 @@ export type UserDataDeleteHook = (
 ) => Promise<UserDataDeleteHookResult>;
 
 /**
- * Komplette Hook-Tafel für EXT_USER_DATA. Sprint 2 user-data-rights
- * deklariert das via `r.extendsRegistrar(EXT_USER_DATA, { hooks: ... })`,
- * konsumierende Features liefern beide Hooks via
- * `r.useExtension(EXT_USER_DATA, "<entity>", { export, delete })`.
- *
- * Kein Hook ist optional — beide MÜSSEN registriert sein. Boot-Check
- * (Sprint 2) prüft das.
+ * 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;
 }
+
+// At least one hook is required: an empty bag would silently register neither export nor forget.
+export type UserDataExtensionOptions = (
+  | { readonly export: UserDataExportHook; readonly delete?: UserDataDeleteHook }
+  | { readonly export?: UserDataExportHook; readonly delete: UserDataDeleteHook }
+) & { readonly order?: number };