@cosmicdrift/kumiko-framework 0.2.1 → 0.2.3

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

@@ -0,0 +1,106 @@
+// Hook-Signatur-Types für die EXT_USER_DATA-Extension (DSGVO Art. 15+17+20).
+//
+// Sprint 1.9 Z1: Bisher gibt der Boot-Validator JEDES Hook-Shape durch
+// — useExtension(EXT_USER_DATA, "X", { export: ... }) wird nicht gegen
+// eine erwartete Signatur geprüft. Diese Types sind die canonical
+// Schema-Sicht; Sprint 2 user-data-rights wird sie via
+// `r.extendsRegistrar(EXT_USER_DATA, { hooks: ... })`-Doku exposen.
+//
+// Boot-Time-Schape-Check (Runtime) ist orthogonal und kommt in Sprint
+// 2 wenn die exportRunner-/forgetRunner-Pipelines stehen — bis dahin
+// sind diese Types Compile-Time-Hints für App-Authors, keine Runtime-
+// Validation.
+//
+// Siehe docs/plans/datenschutz/user-data-rights.md.
+
+import type { DbRunner } from "../../db/connection";
+import type { TenantId } from "../types";
+
+// SessionUser.id ist plattformweit `string` (kein Brand-Type). Wenn
+// jemals ein UserId-Brand eingefuehrt wird, ersetzt man hier den
+// inline-Type — andere Codebase-Stellen nutzen denselben Pfad.
+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";
+
+/**
+ * Context-Snapshot der dem Hook übergeben wird. Sprint 2 erweitert
+ * das ggf. um cancel-/timeout-Marker; aktuell minimaler Schnitt.
+ *
+ * `db` ist `DbRunner` (DbConnection | DbTx) damit der Cleanup-Runner
+ * (S2.U5b) den Hook in einer Per-User-Sub-Tx callen kann. Hooks die
+ * raw-DB-Operationen machen funktionieren auf beiden Shapes via
+ * Drizzle's polymorphem select/insert/update/delete-Chain.
+ */
+export interface UserDataHookCtx {
+  readonly db: DbRunner;
+  readonly tenantId: TenantId;
+  readonly userId: UserId;
+}
+
+/**
+ * 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.
+ */
+export type UserDataDeleteHook = (
+  ctx: UserDataHookCtx,
+  strategy: UserDataDeleteStrategy,
+) => Promise<void>;
+
+/**
+ * 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.
+ */
+export interface UserDataExtensionHooks {
+  readonly export: UserDataExportHook;
+  readonly delete: UserDataDeleteHook;
+}

package/src/engine/factories.ts

@@ -1,8 +1,10 @@
 import type {
+  BigIntFieldDef,
   BooleanFieldDef,
   DateFieldDef,
   EmbeddedFieldDef,
   EntityDefinition,
+  EntityIndexDef,
   FieldsMap,
   FileFieldDef,
   FilesFieldDef,
@@ -13,6 +15,7 @@ import type {
   MoneyFieldDef,
   MultiSelectFieldDef,
   NumberFieldDef,
+  RetentionDef,
   SelectFieldDef,
   TextFieldDef,
   TimestampFieldDef,
@@ -126,6 +129,16 @@ export function createNumberField<R extends true | false = false>(
   } as NumberFieldDef & { required: R };
 }
 
+export function createBigIntField<R extends true | false = false>(
+  overrides?: Partial<Omit<BigIntFieldDef, "type" | "required">> & { required?: R },
+): BigIntFieldDef & { required: R } {
+  return {
+    type: "bigInt",
+    required: false,
+    ...overrides,
+  } as BigIntFieldDef & { required: R };
+}
+
 export function createMoneyField<R extends true | false = false>(
   overrides?: Partial<Omit<MoneyFieldDef, "type" | "required">> & { required?: R },
 ): MoneyFieldDef & { required: R } {
@@ -309,13 +322,10 @@ export function createEntity<F>(def: {
   readonly searchWeight?: number;
   readonly defaultCurrency?: string;
   readonly transitions?: Readonly<Record<string, Readonly<Record<string, readonly string[]>>>>;
-  readonly indexes?: readonly {
-    readonly columns: readonly [string, ...string[]];
-    readonly unique?: boolean;
-    readonly name?: string;
-  }[];
+  readonly indexes?: readonly EntityIndexDef[];
   readonly idType?: "serial" | "uuid";
   readonly access?: EntityDefinition["access"];
+  readonly retention?: RetentionDef;
 }): F extends FieldsMap ? EntityDefinition<F> : never {
   return {
     softDelete: false,

package/src/engine/feature-ast/extractors.ts

@@ -50,6 +50,7 @@ import type {
   EntityHookPattern,
   EntityPattern,
   EventMigrationPattern,
+  ExposesApiPattern,
   ExtendsRegistrarPattern,
   HookPattern,
   HttpRoutePattern,
@@ -72,6 +73,7 @@ import type {
   ToggleablePattern,
   TranslationsPattern,
   UseExtensionPattern,
+  UsesApiPattern,
   WorkspacePattern,
   WriteHandlerPattern,
 } from "./patterns";
@@ -2560,3 +2562,41 @@ export function extractExtendsRegistrar(
     defBody: sourceLocationFromNode(defArg, sourceFile),
   });
 }
+
+export function extractUsesApi(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<UsesApiPattern> {
+  const arg = call.getArguments()[0]?.asKind(SyntaxKind.StringLiteral);
+  if (!arg) {
+    return fail(
+      "usesApi",
+      sourceLocationFromNode(call, sourceFile),
+      'expected a single string-literal API name (e.g. "sessions.revokeAllForUser")',
+    );
+  }
+  return ok({
+    kind: "usesApi",
+    source: sourceLocationFromNode(call, sourceFile),
+    apiName: arg.getLiteralValue(),
+  });
+}
+
+export function extractExposesApi(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<ExposesApiPattern> {
+  const arg = call.getArguments()[0]?.asKind(SyntaxKind.StringLiteral);
+  if (!arg) {
+    return fail(
+      "exposesApi",
+      sourceLocationFromNode(call, sourceFile),
+      'expected a single string-literal API name (e.g. "sessions.revokeAllForUser")',
+    );
+  }
+  return ok({
+    kind: "exposesApi",
+    source: sourceLocationFromNode(call, sourceFile),
+    apiName: arg.getLiteralValue(),
+  });
+}

package/src/engine/feature-ast/parse.ts

@@ -33,6 +33,7 @@ import {
   extractEntity,
   extractEntityHook,
   extractEventMigration,
+  extractExposesApi,
   extractExtendsRegistrar,
   extractHook,
   extractHttpRoute,
@@ -54,6 +55,7 @@ import {
   extractToggleable,
   extractTranslations,
   extractUseExtension,
+  extractUsesApi,
   extractWorkspace,
   extractWriteHandler,
 } from "./extractors";
@@ -346,6 +348,10 @@ function dispatchExtractor(
     // Round 5 — opaque patterns
     case "extendsRegistrar":
       return extractExtendsRegistrar(call, sourceFile);
+    case "usesApi":
+      return extractUsesApi(call, sourceFile);
+    case "exposesApi":
+      return extractExposesApi(call, sourceFile);
     // Unknown method — UnknownPattern signal so Designer/AI surface it
     // as "custom call" without losing the source location.
     default:

package/src/engine/feature-ast/patterns.ts

@@ -318,6 +318,24 @@ export type ExtendsRegistrarPattern = {
   readonly defBody: SourceLocation;
 };
 
+// r.usesApi("a.b") — declarative cross-feature handler-ID dependency.
+// Boot-validation throws if no other feature exposes the handler. Single
+// string argument; pattern is purely declarative.
+export type UsesApiPattern = {
+  readonly kind: "usesApi";
+  readonly source: SourceLocation;
+  readonly apiName: string;
+};
+
+// r.exposesApi("a.b") — declarative announcement that this feature
+// provides a handler matching the cross-feature contract `a.b`. Single
+// string argument; pattern is purely declarative.
+export type ExposesApiPattern = {
+  readonly kind: "exposesApi";
+  readonly source: SourceLocation;
+  readonly apiName: string;
+};
+
 // =============================================================================
 // Catch-all — r.* calls the visitor doesn't recognise. Designer renders
 // "unknown call (cannot edit)", AI patcher leaves them unchanged. When
@@ -354,6 +372,8 @@ export type FeaturePattern =
   | ReferenceDataPattern
   | ReadsConfigPattern
   | UseExtensionPattern
+  | UsesApiPattern
+  | ExposesApiPattern
   // Mixed
   | ScreenPattern
   | WriteHandlerPattern
@@ -406,6 +426,8 @@ export function getEditability(pattern: FeaturePattern): Editability {
     case "referenceData":
     case "readsConfig":
     case "useExtension":
+    case "usesApi":
+    case "exposesApi":
       return "static";
     case "screen":
     case "writeHandler":

package/src/engine/feature-ast/render.ts

@@ -24,6 +24,7 @@ import type {
   EntityHookPattern,
   EntityPattern,
   EventMigrationPattern,
+  ExposesApiPattern,
   ExtendsRegistrarPattern,
   FeaturePattern,
   HookPattern,
@@ -47,6 +48,7 @@ import type {
   TranslationsPattern,
   UnknownPattern,
   UseExtensionPattern,
+  UsesApiPattern,
   WorkspacePattern,
   WriteHandlerPattern,
 } from "./patterns";
@@ -122,6 +124,10 @@ export function renderPattern(pattern: FeaturePattern): string {
       return renderEventMigration(pattern);
     case "extendsRegistrar":
       return renderExtendsRegistrar(pattern);
+    case "usesApi":
+      return renderUsesApi(pattern);
+    case "exposesApi":
+      return renderExposesApi(pattern);
     case "unknown":
       return renderUnknown(pattern);
     default: {
@@ -473,6 +479,14 @@ function renderExtendsRegistrar(p: ExtendsRegistrarPattern): string {
   return `r.extendsRegistrar(${JSON.stringify(p.extensionName)}, ${p.defBody.raw});`;
 }
 
+function renderUsesApi(p: UsesApiPattern): string {
+  return `r.usesApi(${JSON.stringify(p.apiName)});`;
+}
+
+function renderExposesApi(p: ExposesApiPattern): string {
+  return `r.exposesApi(${JSON.stringify(p.apiName)});`;
+}
+
 function renderUnknown(p: UnknownPattern): string {
   // Round-trip preservation only: emit the raw call text from the
   // SourceLocation so the rendered file stays semantically identical

package/src/engine/index.ts

@@ -41,7 +41,25 @@ export {
 } from "./entity-handlers";
 export type { EmitCtx } from "./event-helpers";
 export { emitEvent, typedPayload } from "./event-helpers";
+export type { KumikoExtensionName } from "./extension-names";
 export {
+  EXT_EXTERNAL_RESOURCE,
+  EXT_INFRA_RESOURCE,
+  EXT_SEARCH_ADAPTER,
+  EXT_STORAGE_PROVIDER,
+  EXT_TENANT_DATA,
+  EXT_USER_DATA,
+} from "./extension-names";
+export type {
+  UserDataDeleteHook,
+  UserDataDeleteStrategy,
+  UserDataExportHook,
+  UserDataExportSnippet,
+  UserDataExtensionHooks,
+  UserDataHookCtx,
+} from "./extensions/user-data";
+export {
+  createBigIntField,
   createBooleanField,
   createDateField,
   createEmbeddedField,
@@ -144,6 +162,7 @@ export type {
   AuthClaimsFn,
   AuthClaimsHookDef,
   BelongsToRelation,
+  BigIntFieldDef,
   BooleanFieldDef,
   CamelToKebab,
   ClaimKeyDefinition,
@@ -220,6 +239,7 @@ export type {
   NotifyPriority,
   NumberFieldDef,
   OnDeleteStrategy,
+  PiiAnnotations,
   PlatformComponent,
   PostDeleteHookFn,
   PostSaveHookFn,
@@ -234,6 +254,7 @@ export type {
   QueryHandlerFn,
   Registry,
   RelationDefinition,
+  RetentionDef,
   RowAction,
   SaveContext,
   ScreenDefinition,

package/src/engine/pattern-library/__tests__/library.test.ts

@@ -55,6 +55,8 @@ const ALL_KINDS: readonly FeaturePatternKind[] = [
   "defineEvent",
   "eventMigration",
   "extendsRegistrar",
+  "usesApi",
+  "exposesApi",
   "unknown",
 ];
 
@@ -340,6 +342,9 @@ function makePlaceholderPattern(kind: FeaturePatternKind): FeaturePattern {
       };
     case "unknown":
       return { kind, source: PLACEHOLDER_LOC, methodName: "x" };
+    case "usesApi":
+    case "exposesApi":
+      return { kind, source: PLACEHOLDER_LOC, apiName: "demo.api" };
     default: {
       const _exhaustive: never = kind;
       return _exhaustive;

package/src/engine/pattern-library/library.ts

@@ -1020,6 +1020,40 @@ const extendsRegistrarSchema: PatternFormSchema = {
   ],
 };
 
+const usesApiSchema: PatternFormSchema = {
+  kind: "usesApi",
+  label: { en: "Uses API", de: "Nutzt API" },
+  summary: {
+    en: "Cross-feature handler-ID dependency. Boot fails if no other feature exposes it.",
+  },
+  category: "advanced",
+  editability: "static",
+  fields: [
+    {
+      path: "apiName",
+      label: { en: "API name", de: "API-Name" },
+      input: "text",
+      required: true,
+    },
+  ],
+};
+
+const exposesApiSchema: PatternFormSchema = {
+  kind: "exposesApi",
+  label: { en: "Exposes API", de: "Stellt API bereit" },
+  summary: { en: "Declares this feature provides a handler matching the cross-feature contract." },
+  category: "advanced",
+  editability: "static",
+  fields: [
+    {
+      path: "apiName",
+      label: { en: "API name", de: "API-Name" },
+      input: "text",
+      required: true,
+    },
+  ],
+};
+
 const unknownSchema: PatternFormSchema = {
   kind: "unknown",
   label: { en: "Unknown call", de: "Unbekannter Call" },
@@ -1077,6 +1111,8 @@ export const PATTERN_LIBRARY: Readonly<Record<FeaturePatternKind, PatternFormSch
   defineEvent: defineEventSchema,
   eventMigration: eventMigrationSchema,
   extendsRegistrar: extendsRegistrarSchema,
+  usesApi: usesApiSchema,
+  exposesApi: exposesApiSchema,
   unknown: unknownSchema,
 };
 

package/src/engine/schema-builder.ts

@@ -60,6 +60,14 @@ function fieldToZod(field: FieldDefinition, currencies: readonly string[]): z.Zo
       const schema = z.number();
       return field.default !== undefined ? schema.default(field.default) : schema;
     }
+    case "bigInt": {
+      // JS-`number`-Round-trip via mode:"number"; sicher bis 2^53.
+      // safe-integer-Cap ist explizit damit ein Caller, der einen
+      // Float reinwirft (z.B. parseFloat-Bug), beim Insert sofort
+      // failed statt silent-Truncation zu kassieren.
+      const schema = z.number().int().safe();
+      return field.default !== undefined ? schema.default(field.default) : schema;
+    }
     case "money": {
       const [first, ...rest] = currencies;
       if (!first) throw new Error("No currencies configured");

package/src/engine/types/feature.ts

@@ -164,6 +164,21 @@ export type FeatureDefinition = {
   readonly jobs: Readonly<Record<string, JobDefinition>>;
   readonly registrarExtensions: Readonly<Record<string, RegistrarExtensionDef>>;
   readonly extensionUsages: readonly RegistrarExtensionRegistration[];
+  /**
+   * Cross-feature API names this feature exposes via `r.exposesApi(name)`.
+   * Pure Marker-Deklaration — die echte Implementation wird als
+   * Query-/Write-Handler unter dem QN-Pattern registriert (z.B.
+   * `compliance-profiles:query:effective-profile`). Boot-Validator prüft
+   * dass jedes `r.usesApi(name)` einen passenden Exposer hier findet —
+   * Tippfehler oder Drop-Refactorings werden zu Boot-Fail statt Runtime-Crash.
+   */
+  readonly exposedApis: ReadonlySet<string>;
+  /**
+   * Cross-feature API names this feature calls. Pflicht-Boot-Check:
+   * jeder Eintrag muss in `exposedApis` irgendeines Features auftauchen
+   * UND das Provider-Feature muss in requires/optionalRequires sein.
+   */
+  readonly usedApis: ReadonlySet<string>;
   readonly referenceData: readonly ReferenceDataDef[];
   readonly notifications: Readonly<Record<string, NotificationDefinition>>;
   readonly events: Readonly<Record<string, EventDef>>;
@@ -360,6 +375,42 @@ export type FeatureRegistrar<TFeature extends string = string> = {
 
   useExtension(extensionName: string, entity: NameOrRef, options?: Record<string, unknown>): void;
 
+  /**
+   * Marker-Deklaration: dieses Feature stellt eine Cross-Feature-API
+   * unter dem genannten Namen bereit. Die eigentliche Implementation
+   * wird separat als Query- oder Write-Handler unter dem QN-Pattern
+   * registriert; `r.exposesApi` ist reine Boot-Check-Surface.
+   *
+   * Boot-Validator prüft, dass jedes `r.usesApi(name)` einen passenden
+   * Exposer findet, dass das Exposer-Feature in requires/optionalRequires
+   * gelisted ist und dass kein API-Name doppelt exposed wird.
+   *
+   * ```ts
+   * defineFeature("compliance-profiles", (r) => {
+   *   r.exposesApi("compliance.forTenant");
+   *   r.queryHandler({
+   *     name: "compliance:query:for-tenant",
+   *     // ... echte Implementation
+   *   });
+   * });
+   * ```
+   */
+  exposesApi(apiName: string): void;
+
+  /**
+   * Declares that this feature calls a cross-feature API. Boot-Validator
+   * checkt dass irgendein anderes Feature `r.exposesApi(apiName)` macht
+   * und dass dieses Feature `r.requires/optionalRequires` darauf hat.
+   *
+   * ```ts
+   * defineFeature("user-data-rights", (r) => {
+   *   r.requires("compliance-profiles");
+   *   r.usesApi("compliance.forTenant");
+   * });
+   * ```
+   */
+  usesApi(apiName: string): void;
+
   // Declare a metric. Short name (without kumiko_<feature>_ prefix) — Framework
   // qualifies it on boot. Validation (snake_case + typ-suffix) runs at boot.
   // Usage at runtime: ctx.metrics.inc("created_total", { status: "new" }).