@cosmicdrift/kumiko-framework 0.304.0 → 0.306.0

package/src/db/queries/__tests__/{unsafe-read-retrying.test.ts → unsafe-read-retrying.integration.test.ts}

@@ -1,16 +1,10 @@
-// #2323: event-store.ts's and projection-rebuild.ts's plain SELECT helpers
-// read via asRawClient(db).unsafe() directly, bypassing the #1163
-// closed-connection retry that only covered bun-db/query.ts's own
-// selectMany/countWhere. Routed the non-locking read call sites through
-// unsafeReadRetrying instead — this test mirrors
-// bun-db/__tests__/select-many-retry.test.ts's fake-client pattern to prove
-// the retry now fires. Writes (insertSubsequentEventRow, upsertSnapshot,
-// markProjectionRebuilding, ...) stay unretried per #1358, and the
-// FOR UPDATE / FOR UPDATE SKIP LOCKED reads in event-consumer.ts are always
-// called inside transaction() (verified against their only call sites) — the
-// retry guard there is a no-op, so those are left as asRawClient calls too.
+// event-store.ts's and projection-rebuild.ts's SELECT helpers run through
+// unsafeReadRetrying; this proves the retry fires using a real captured
+// driver error. Writes and the FOR UPDATE reads inside transaction() stay
+// out of scope — unretried by design.
 
-import { describe, expect, test } from "bun:test";
+import { beforeAll, describe, expect, test } from "bun:test";
+import { captureClosedConnectionError } from "../../../testing/closed-connection-error";
 import {
   selectAggregateMaxVersion,
   selectEventsHighWaterMark,
@@ -22,24 +16,28 @@ import {
   selectEventsForProjectionRebuildBatch,
 } from "../projection-rebuild";
 
-function closedConnectionError(): Error {
-  return Object.assign(new Error("The connection was closed."), { name: "AbortError" });
-}
+let closedConnectionError: unknown;
+
+beforeAll(async () => {
+  closedConnectionError = await captureClosedConnectionError();
+});
 
 type RecordedCall = { readonly sql: string; readonly params: readonly unknown[] | undefined };
 
 type FakeClient = {
   unsafe: (sql: string, params?: readonly unknown[]) => Promise<readonly unknown[]>;
   begin: () => never;
+  options: { max: number };
   calls: number;
   recordedCalls: RecordedCall[];
 };
 
-function fakeClient(failures: Error[], row: Record<string, unknown>): FakeClient {
+function fakeClient(failures: unknown[], row: Record<string, unknown>): FakeClient {
   const remaining = [...failures];
   const client: FakeClient = {
     calls: 0,
     recordedCalls: [],
+    options: { max: 1 },
     unsafe: async (sql, params) => {
       client.calls++;
       client.recordedCalls.push({ sql, params });
@@ -54,9 +52,9 @@ function fakeClient(failures: Error[], row: Record<string, unknown>): FakeClient
   return client;
 }
 
-describe("framework db/queries — closed-connection retry (#2323)", () => {
+describe("framework db/queries — closed-connection retry", () => {
   test("selectStreamMaxVersion retries once and returns the version", async () => {
-    const db = fakeClient([closedConnectionError()], { v: 5 });
+    const db = fakeClient([closedConnectionError], { v: 5 });
     const result = await selectStreamMaxVersion(db as never, "agg1", "t1");
     expect(result).toBe(5);
     expect(db.calls).toBe(2);
@@ -65,28 +63,28 @@ describe("framework db/queries — closed-connection retry (#2323)", () => {
   });
 
   test("selectAggregateMaxVersion retries once and returns the version", async () => {
-    const db = fakeClient([closedConnectionError()], { v: 7 });
+    const db = fakeClient([closedConnectionError], { v: 7 });
     const result = await selectAggregateMaxVersion(db as never, "agg1");
     expect(result).toBe(7);
     expect(db.calls).toBe(2);
   });
 
   test("selectEventsHighWaterMark retries once and returns the max id", async () => {
-    const db = fakeClient([closedConnectionError()], { max: 42n });
+    const db = fakeClient([closedConnectionError], { max: 42n });
     const result = await selectEventsHighWaterMark(db as never);
     expect(result).toBe(42n);
     expect(db.calls).toBe(2);
   });
 
   test("selectNextEventIdAfter retries once and returns the next id", async () => {
-    const db = fakeClient([closedConnectionError()], { id: 43n });
+    const db = fakeClient([closedConnectionError], { id: 43n });
     const result = await selectNextEventIdAfter(db as never, 42n);
     expect(result).toBe(43n);
     expect(db.calls).toBe(2);
   });
 
   test("selectEventsForProjectionRebuildBatch retries once and returns rows", async () => {
-    const db = fakeClient([closedConnectionError()], { id: "1", type: "created" });
+    const db = fakeClient([closedConnectionError], { id: "1", type: "created" });
     const rows = await selectEventsForProjectionRebuildBatch(
       db as never,
       ["user"],
@@ -99,17 +97,19 @@ describe("framework db/queries — closed-connection retry (#2323)", () => {
   });
 
   test("countSubscribedEvents retries once and returns the count", async () => {
-    const db = fakeClient([closedConnectionError()], { n: 12n });
+    const db = fakeClient([closedConnectionError], { n: 12n });
     const result = await countSubscribedEvents(db as never, ["user"], ["user:created"]);
     expect(result).toBe(12n);
     expect(db.calls).toBe(2);
   });
 
-  test("gives up after the single retry when the connection stays closed", async () => {
-    const db = fakeClient([closedConnectionError(), closedConnectionError()], { v: 5 });
-    await expect(selectStreamMaxVersion(db as never, "agg1", "t1")).rejects.toThrow(
-      "connection was closed",
+  test("gives up after exhausting pool-bounded retries (max: 1 → 3 total calls)", async () => {
+    const db = fakeClient([closedConnectionError, closedConnectionError, closedConnectionError], {
+      v: 5,
+    });
+    await expect(selectStreamMaxVersion(db as never, "agg1", "t1")).rejects.toBe(
+      closedConnectionError,
     );
-    expect(db.calls).toBe(2);
+    expect(db.calls).toBe(3);
   });
 });

package/src/db/tenant-db.ts

@@ -24,6 +24,7 @@ import {
   type SelectOptions,
   type WhereObject,
 } from "../db/query";
+import type { EntityDefinition } from "../engine/types/fields";
 import { SYSTEM_TENANT_ID, type TenantId } from "../engine/types/identifiers";
 import { AccessDeniedError, InternalError, memberResolutionReadOnlyDenied } from "../errors";
 import { emitDbQuery, type Meter, registerStandardMetrics, type Tracer } from "../observability";
@@ -45,6 +46,21 @@ const declaredUnsafeRawRunners = new WeakMap<
   (reason: string) => DbRunner
 >();
 
+// The CRUD executor writes through tenantDbRunner, not insertOne, so it asks the
+// TenantDb it was handed for its gate. Bound inside createTenantDb so rebound instances
+// (withUnsafeRawGrant, acknowledgeConventionCrossTenant) carry it too.
+const personalDataGates = new WeakMap<TenantDb, PersonalDataGate>();
+
+// The executor passes its entity so the check does not depend on the table-name lookup.
+export function assertPersonalDataWrite(
+  db: TenantDb,
+  tableName: string,
+  keys: readonly string[],
+  entity: EntityDefinition,
+): void {
+  personalDataGates.get(db)?.(tableName, keys, entity);
+}
+
 // Framework-private (not re-exported from db/index.ts): same grant check + audit as unsafeRaw, for engine forwarding.
 export function unsafeRawForDeclaredStep(
   holder: TenantDb | UncheckedSystemDb,
@@ -57,25 +73,49 @@ export function unsafeRawForDeclaredStep(
   if (!runner) {
     throw new InternalError({
       message:
-        "unsafeRawForDeclaredStep received a holder not built by createTenantDb or " +
-        "createUncheckedSystemDb — no declared unsafeRaw runner bound.",
+        "unsafeRawForDeclaredStep received a holder not built by createTenantDb, " +
+        "createUncheckedSystemDb, or createSystemDbView — no declared unsafeRaw runner bound.",
     });
   }
   return runner(reason);
 }
 
-// buildHandlerContext (pipeline/dispatch-shared.ts) always builds "system"
-// mode from the caller's own tenantId, never a foreign one.
-//
-// dbOutsideTransaction is optional so every existing single-arg call site
-// (jobs, tests, delivery-service.ts) keeps compiling — those callers have no
-// outside-tx source to hand in and never needed one. Only
-// buildHandlerContext passes it, which is also the only place `.outsideTransaction`
-// is reachable through `ctx.systemDb`.
-export function createUncheckedSystemDb(
+const systemDbRebinders = new WeakMap<
+  UncheckedSystemDb,
+  (grant: EscapeHatchDeclaration | undefined, deniedCallerLabel: string) => UncheckedSystemDb
+>();
+
+// Rebinds a hook's own escapeHatch onto ctx.systemDb, mirroring withUnsafeRawGrant: always
+// rebuilt from the original db/dbOutsideTransaction/report, never stacked onto a prior rebind.
+// Inputs not built by createUncheckedSystemDb pass through unchanged.
+export function withSystemDbUnsafeRawGrant(
+  systemDb: UncheckedSystemDb,
+  grant: EscapeHatchDeclaration | undefined,
+  deniedCallerLabel: string,
+): UncheckedSystemDb {
+  const rebind = systemDbRebinders.get(systemDb);
+  return rebind ? rebind(grant, deniedCallerLabel) : systemDb;
+}
+
+// Ungated when `gate` is absent (the handler's own ctx.systemDb — systemScope() is
+// itself the grant there). Gated by a hook's own escapeHatch when `gate.kind` is
+// "hook-grant": unsafeRaw then denies without `hasGrant(gate.grant)`, same error shape
+// as ctx.db.unsafeRaw's denial in createTenantDb below. Gated by the source TenantDb's
+// own escapeHatch when `gate.kind` is "source-tenant-db" (createSystemDbView): unsafeRaw
+// defers entirely to db's own declared runner (reason/memberReadOnly/grant check and
+// report) — the view's own `report` is never called for unsafe-raw in that mode, and a
+// source not built by createTenantDb fails closed.
+function buildUncheckedSystemDb(
   db: TenantDb,
-  dbOutsideTransaction?: TenantDb,
-  report: EscapeHatchReporter = fallbackEscapeHatchReporter(db.tenantId),
+  dbOutsideTransaction: TenantDb | undefined,
+  report: EscapeHatchReporter,
+  gate?:
+    | {
+        readonly kind: "hook-grant";
+        readonly grant: EscapeHatchDeclaration | undefined;
+        readonly deniedCallerLabel: string;
+      }
+    | { readonly kind: "source-tenant-db" },
 ): UncheckedSystemDb {
   const allowedTenantIds: readonly TenantId[] = [db.tenantId, SYSTEM_TENANT_ID];
 
@@ -97,9 +137,19 @@ export function createUncheckedSystemDb(
   }
 
   function grantedUnsafeRawRunner(reason: string): DbRunner {
+    if (gate?.kind === "source-tenant-db") {
+      return unsafeRawForDeclaredStep(db, reason);
+    }
     if (reason.trim().length === 0) {
       throw new Error("unsafeRaw requires a non-empty reason");
     }
+    if (gate && !hasGrant(gate.grant)) {
+      throw new AccessDeniedError({
+        message:
+          'ctx.systemDb.unsafeRaw(reason): rejected — declare `escapeHatch: { reason: "..." }` on ' +
+          `${gate.deniedCallerLabel} to allow unsafeRaw.`,
+      });
+    }
     report("unsafe-raw", reason);
     return tenantDbRunner(db);
   }
@@ -162,15 +212,58 @@ export function createUncheckedSystemDb(
     },
   };
   declaredUnsafeRawRunners.set(uncheckedSystemDb, grantedUnsafeRawRunner);
+  if (gate?.kind !== "source-tenant-db") {
+    systemDbRebinders.set(uncheckedSystemDb, (grant, deniedCallerLabel) =>
+      buildUncheckedSystemDb(
+        withUnsafeRawGrant(db, grant),
+        dbOutsideTransaction && withUnsafeRawGrant(dbOutsideTransaction, grant),
+        report,
+        { kind: "hook-grant", grant, deniedCallerLabel },
+      ),
+    );
+  }
   return uncheckedSystemDb;
 }
 
+// Framework-private (not re-exported from db/index.ts): buildHandlerContext
+// (pipeline/dispatch-shared.ts) always builds "system" mode from the caller's
+// own tenantId, never a foreign one.
+//
+// dbOutsideTransaction is optional so every existing single-arg call site
+// (jobs/job-runner.ts, tests) keeps compiling — those callers have no
+// outside-tx source to hand in and never needed one. Only
+// buildHandlerContext passes it, which is also the only place `.outsideTransaction`
+// is reachable through `ctx.systemDb`.
+//
+// Ungated here (the handler's own systemScope() is the grant); a hook's own
+// escapeHatch is layered on afterwards via withSystemDbUnsafeRawGrant. Public
+// callers use createSystemDbView instead, whose unsafeRaw follows the source
+// TenantDb's own escapeHatch gate.
+export function createUncheckedSystemDb(
+  db: TenantDb,
+  dbOutsideTransaction?: TenantDb,
+  report: EscapeHatchReporter = fallbackEscapeHatchReporter(db.tenantId),
+): UncheckedSystemDb {
+  return buildUncheckedSystemDb(db, dbOutsideTransaction, report);
+}
+
+// Public: must never grant more raw access than the source TenantDb — unlike
+// createUncheckedSystemDb (framework-private; r.systemScope()/a job IS the
+// declaration), this view's unsafeRaw defers entirely to db's own escapeHatch gate.
+export function createSystemDbView(
+  db: TenantDb,
+  dbOutsideTransaction?: TenantDb,
+  report: EscapeHatchReporter = fallbackEscapeHatchReporter(db.tenantId),
+): UncheckedSystemDb {
+  return buildUncheckedSystemDb(db, dbOutsideTransaction, report, { kind: "source-tenant-db" });
+}
+
 // @cast-boundary tenant-db-row
 export function castTenantRows<T>(rows: readonly Record<string, unknown>[]): readonly T[] {
   return rows as unknown as readonly T[];
 }
 
-function tableNameOf(table: Table | EntityTableMeta): string {
+export function tableNameOf(table: Table | EntityTableMeta): string {
   const sym = (table as Record<symbol, unknown>)[KUMIKO_NAME_SYMBOL];
   if (typeof sym === "string") return sym;
   return asEntityTableMeta(table)?.tableName ?? "<unknown>";
@@ -205,8 +298,16 @@ export type TenantDbGrants = {
   // Set for a resolved member principal (ctx.queryAsMember): no raw DbRunner leaves
   // this TenantDb, so no handler can COMMIT/RELEASE SAVEPOINT out of the READ ONLY scope.
   readonly memberReadOnly?: boolean;
+  // Set only for an anonymous root without personalData: "public-intake" (write-origin.ts).
+  readonly personalDataGate?: PersonalDataGate;
 };
 
+export type PersonalDataGate = (
+  tableName: string,
+  keys: readonly string[],
+  entity?: EntityDefinition,
+) => void;
+
 const unsafeRawRebinders = new WeakMap<
   TenantDb,
   (grant: EscapeHatchDeclaration | undefined) => TenantDb
@@ -347,6 +448,20 @@ export function createTenantDb(
     return grants?.globalWrites?.reason ?? "";
   }
 
+  function personalDataDenied(
+    table: Table | EntityTableMeta,
+    keys: readonly string[],
+  ): AccessDeniedError | undefined {
+    if (!grants?.personalDataGate) return undefined;
+    try {
+      grants.personalDataGate(tableNameOf(table), keys);
+      return undefined;
+    } catch (e) {
+      if (e instanceof AccessDeniedError) return e;
+      throw e;
+    }
+  }
+
   function foreignTenantOnGlobalWrite(
     table: Table | EntityTableMeta,
     tenantIdValue: unknown,
@@ -379,7 +494,9 @@ export function createTenantDb(
         values: Record<string, unknown>,
       ): Promise<T | undefined> {
         const denied =
-          missingEscapeHatch(table) ?? foreignTenantOnGlobalWrite(table, values["tenantId"]);
+          missingEscapeHatch(table) ??
+          foreignTenantOnGlobalWrite(table, values["tenantId"]) ??
+          personalDataDenied(table, Object.keys(values));
         if (denied) return Promise.reject(denied);
         report("global-write", globalWriteReason());
         return withDbSpan("insert", table, async () => bunInsertOne<T>(db, table, values));
@@ -389,7 +506,9 @@ export function createTenantDb(
         where: WhereObject,
       ): Promise<readonly T[]> {
         const denied =
-          missingEscapeHatch(table) ?? foreignTenantOnGlobalWrite(table, set["tenantId"]);
+          missingEscapeHatch(table) ??
+          foreignTenantOnGlobalWrite(table, set["tenantId"]) ??
+          personalDataDenied(table, Object.keys(set));
         if (denied) return Promise.reject(denied);
         if (!where || Object.keys(where).length === 0) {
           return Promise.reject(
@@ -483,6 +602,8 @@ export function createTenantDb(
         );
         if (denied) return Promise.reject(denied);
       }
+      const personalDenied = personalDataDenied(table, Object.keys(values));
+      if (personalDenied) return Promise.reject(personalDenied);
       const data = insertValues(table, values);
       return withDbSpan("insert", table, async () => bunInsertOne<T>(db, table, data));
     },
@@ -499,6 +620,8 @@ export function createTenantDb(
           ),
         );
       }
+      const personalDenied = personalDataDenied(table, Object.keys(set));
+      if (personalDenied) return Promise.reject(personalDenied);
       const filter = writeWhere(table, where);
       return withDbSpan("update", table, async () => bunUpdateMany<T>(db, table, set, filter));
     },
@@ -525,6 +648,7 @@ export function createTenantDb(
     return createTenantDb(db, tenantId, "system", tracer, meter, signal, grants);
   });
   bindTenantDbRunner(tenantDb, db);
+  if (grants?.personalDataGate) personalDataGates.set(tenantDb, grants.personalDataGate);
   return tenantDb;
 }
 

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

@@ -15,7 +15,12 @@ import { defineFeature } from "../define-feature";
 const udr = () => defineFeature("user-data-rights", () => {});
 const fileProvider = (name: string) =>
   defineFeature(`file-provider-${name}`, (r) => {
-    r.useExtension("fileProvider", name);
+    // build is never invoked here — the boot check only cares that a provider is mounted.
+    r.useExtension("fileProvider", name, {
+      build: async () => {
+        throw new Error("test stub — never invoked");
+      },
+    });
   });
 
 const S3_ENV = ["S3_BUCKET", "S3_REGION", "S3_ACCESS_KEY", "S3_SECRET_KEY"] as const;

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

@@ -104,8 +104,8 @@ describe("S0 Integration — full surface stack", () => {
         access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
 
-      r.useExtension(EXT_USER_DATA, "user", {});
-      r.useExtension(EXT_USER_DATA, "comment", {});
+      r.useExtension(EXT_USER_DATA, "user", { export: async () => null });
+      r.useExtension(EXT_USER_DATA, "comment", { export: async () => null });
 
       r.writeHandler({
         name: "user:rename",

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

@@ -358,7 +358,7 @@ describe("boot-validator", () => {
     const self = defineFeature("tier-stub", (r) => {
       r.extendsRegistrar("tenantTierResolver", { onRegister: () => {} });
       r.entity("dummy", createEntity({ table: "Dummies", fields: {} }));
-      r.useExtension("tenantTierResolver", "dummy");
+      r.useExtension("tenantTierResolver", "dummy", { build: async () => () => new Set() });
     });
     expect(() => validateBoot([self])).not.toThrow();
   });

package/src/engine/__tests__/tier-resolver-extension.test.ts

@@ -15,7 +15,7 @@ function tierResolverFeature(name: string) {
   return defineFeature(name, (r) => {
     r.extendsRegistrar(TENANT_TIER_RESOLVER_EXT, { onRegister: () => {} });
     r.entity("dummy", createEntity({ table: "Dummies", fields: {} }));
-    r.useExtension(TENANT_TIER_RESOLVER_EXT, "dummy");
+    r.useExtension(TENANT_TIER_RESOLVER_EXT, "dummy", { build: async () => () => new Set() });
   });
 }
 

package/src/engine/boot-validator/access-declarations.ts

@@ -1,68 +1,20 @@
+import {
+  accessAllowsAnonymous,
+  declaredPersonalData,
+  personalFieldNames,
+} from "../personal-data-fields";
 import { ANONYMOUS_ROLE } from "../system-user";
 import type {
   AccessRule,
   FeatureDefinition,
-  OwnershipMap,
-  OwnershipRule,
   QueryHandlerDef,
   StreamHandlerDef,
   WriteHandlerDef,
 } from "../types";
-import type { EntityDefinition, ResolvedPiiFlags } from "../types/fields";
 import { collectZodObjectKeys } from "./zod-shape";
 
 type HandlerKind = "write" | "query" | "stream";
 
-// Personal-data annotation check mirrors pii-retention.ts's hasAnonymizableSubjectField,
-// minus tenantOwned: a tenant-scoped field isn't an individual's personal data in the
-// sense the openToAll personal-data check is guarding against.
-function isPersonalDataField(field: unknown): boolean {
-  const annot = field as ResolvedPiiFlags; // @cast-boundary schema-walk — see pii-retention.ts
-  return Boolean(annot.pii || annot.userOwned || annot.recordOwned);
-}
-
-function isCallerIdRuleOn(rule: OwnershipRule, column: string): boolean {
-  if (rule === "all" || rule.kind !== "from") return false;
-  return rule.refKind === "user" && rule.refPath === "id" && rule.column === column;
-}
-
-// The executor checks access.write against every created/updated row; one "all" role
-// or an empty map (= public) lets a caller write rows owned by someone else.
-function writeMapBindsRowsToCaller(
-  writeMap: OwnershipMap | undefined,
-  ownerColumn: string,
-): boolean {
-  const rules = Object.values(writeMap ?? {});
-  return rules.length > 0 && rules.every((rule) => isCallerIdRuleOn(rule, ownerColumn));
-}
-
-const ROW_ID_COLUMN = "id";
-
-// A self/record-owned field's subject is the row itself, so only from("user:id", "id")
-// makes that row the caller — on any other entity "self" names a third party.
-function callerBindingColumn(annot: ResolvedPiiFlags): string | undefined {
-  if (annot.userOwned) return annot.userOwned.ownerField;
-  if (annot.pii || annot.recordOwned) return ROW_ID_COLUMN;
-  return undefined;
-}
-
-function isOwnerBoundField(field: unknown, entity: EntityDefinition): boolean {
-  const column = callerBindingColumn(field as ResolvedPiiFlags); // @cast-boundary schema-walk — see pii-retention.ts
-  return column !== undefined && writeMapBindsRowsToCaller(entity.access?.write, column);
-}
-
-function personalFieldNames(
-  entity: EntityDefinition,
-  honorOwnerBinding: boolean,
-): ReadonlySet<string> {
-  const names = new Set<string>();
-  for (const [fieldName, field] of Object.entries(entity.fields)) {
-    const exempt = honorOwnerBinding && isOwnerBoundField(field, entity);
-    if (isPersonalDataField(field) && !exempt) names.add(fieldName);
-  }
-  return names;
-}
-
 // escapeHatch and r.systemScope() can write around the entity's write map
 // (db.global(), systemDb, SYSTEM identity), so the map no longer vouches for the row.
 function canWriteAroundExecutor(feature: FeatureDefinition, handler: WriteHandlerDef): boolean {
@@ -104,19 +56,6 @@ function hasOpenToAll(access: AccessRule): boolean {
   return "openToAll" in access;
 }
 
-// Read via `unknown`: access can come from untyped sources (pattern JSON, Designer).
-function declaredPersonalData(access: AccessRule): unknown {
-  if (!("openToAll" in access)) return access.personalData;
-  const openToAll: unknown = access.openToAll;
-  if (typeof openToAll !== "object" || openToAll === null) return undefined;
-  return "personalData" in openToAll ? openToAll.personalData : undefined;
-}
-
-function accessAllowsAnonymous(access: AccessRule): boolean {
-  if ("openToAll" in access) return false;
-  return Array.isArray(access.roles) && access.roles.includes(ANONYMOUS_ROLE);
-}
-
 function declaresTenantMembersPersonalData(access: AccessRule): boolean {
   return declaredPersonalData(access) === "tenant-members";
 }

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;
+  }
+}