@cosmicdrift/kumiko-framework 0.12.2 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @cosmicdrift/kumiko-framework
 
+## 0.13.0
+
+### Minor Changes
+
+- 7f56b2f: **Framework**: add `JsonbFieldDef` + `createJsonbField()` primitive. Schema-less jsonb-Spalte (default `{}`, NOT NULL) für tenant-defined extension-data, AI-inferred metadata, free-form config-blobs. Vs. `embedded` (typed sub-schema): jsonb akzeptiert beliebige keys. Table-builder + schema-builder + e2e-generator alle aktualisiert.
+
+  **custom-fields-Bundle (B2)**: ergänzt B1 um Custom-Field-VALUES:
+
+  - `customField.set` + `customField.cleared` Event-Types (auf host-aggregate stream)
+  - `set-custom-field` + `clear-custom-field` write-handlers (emit events)
+  - `r.extendsRegistrar("customFields")` für consumer opt-in via `useExtension`
+  - `customFieldsField()` helper für entity-fields-definition
+  - `wireCustomFieldsFor(r, entityName, entityTable)` consumer-side-API registriert:
+    - `r.useExtension("customFields", entity)` opt-in marker
+    - MultiStreamProjection: customField.set/.cleared/fieldDefinition.deleted → UPDATE entityTable.customFields jsonb (jsonb_set / minus-operator)
+    - `r.entityHook("postQuery", entity, ...)` — flatten row.customFields auf API-root (Spec-Promise "indistinguishable von Stammfeldern")
+    - `r.searchPayloadExtension(entity, ...)` — customFields-keys flach ins Meilisearch-Index (F3 wiring)
+
+  **Out-of-B2** (future iterations): cross-scope-conflict (tenant override system fieldKey), cap-counter quota, user-data-rights anonymization, value-validation gegen fieldDefinition.serializedField, system+tenant UNION-read.
+
+  Part of custom-fields-bundle Sprint Phase B2 (Plan-Doc: kumiko-platform/docs/plans/custom-fields-sprint.md).
+
 ## 0.12.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.12.2",
+  "version": "0.13.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>",
@@ -172,7 +172,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.12.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.13.0",
     "@types/uuid": "^11.0.0",
     "bun-types": "^1.3.13",
     "drizzle-kit": "^0.31.10",

package/src/db/table-builder.ts

@@ -132,6 +132,11 @@ function fieldToColumns(
       // "Feld komplett weglassen können") modelliert das über ein
       // wrapper-feld mit boolean-flag oder discriminierte-union.
       return { [name]: jsonb(snakeName).default({}).notNull() };
+    case "jsonb":
+      // Free-form jsonb — keys nicht schema-validated. Default `{}`, NOT NULL
+      // (analog zu embedded). Use-case: custom-fields-Bundle's host-entity-
+      // `customFields`-Spalte (tenant-definierte dynamische keys).
+      return { [name]: jsonb(snakeName).default({}).notNull() };
     case "date": {
       // `type:"date"` aliased auf instant() = TIMESTAMPTZ. Echte
       // PlainDate-Migration (PG `date` Spalte, kein TZ) kommt später.

package/src/engine/factories.ts

@@ -10,6 +10,7 @@ import type {
   FilesFieldDef,
   ImageFieldDef,
   ImagesFieldDef,
+  JsonbFieldDef,
   LocatedTimestampFieldDef,
   LongTextFieldDef,
   MoneyFieldDef,
@@ -159,6 +160,17 @@ export function createEmbeddedField(
   };
 }
 
+// Free-form jsonb-Spalte — siehe `JsonbFieldDef`-Doku. Schema-less, default
+// `{}`, NOT NULL. Hauptnutzer: custom-fields-Bundle (host-entity's
+// `customFields`-Spalte). Andere valid uses: tenant-config-blobs, AI-
+// inferred-metadata, future tags-arrays.
+export function createJsonbField(overrides?: Partial<Omit<JsonbFieldDef, "type">>): JsonbFieldDef {
+  return {
+    type: "jsonb",
+    ...overrides,
+  };
+}
+
 export function createDateField<R extends true | false = false>(
   overrides?: Partial<Omit<DateFieldDef, "type" | "required">> & { required?: R },
 ): DateFieldDef & { required: R } {

package/src/engine/index.ts

@@ -85,6 +85,7 @@ export {
   createFilesField,
   createImageField,
   createImagesField,
+  createJsonbField,
   createLocatedTimestampField,
   createLongTextField,
   createMoneyField,
@@ -252,6 +253,7 @@ export type {
   JobDefinition,
   JobHandlerFn,
   JobTrigger,
+  JsonbFieldDef,
   KumikoEntityTypeMap,
   KumikoEventTypeMap,
   KumikoHandlerPayloadMap,

package/src/engine/schema-builder.ts

@@ -84,6 +84,11 @@ function fieldToZod(field: FieldDefinition, currencies: readonly string[]): z.Zo
       }
       return z.object(shape);
     }
+    case "jsonb": {
+      // Free-form jsonb — keys sind tenant-/runtime-defined. Validation
+      // passthrough: any plain object passt durch.
+      return z.record(z.string(), z.unknown());
+    }
     case "date": {
       return z.string().date();
     }

package/src/engine/types/fields.ts

@@ -302,6 +302,21 @@ export type EmbeddedFieldDef = {
   readonly access?: FieldAccess;
 } & PiiAnnotations;
 
+// Free-form jsonb — keys/shape NOT validated at write-time. Use for:
+//   - Tenant-defined extension data (custom-fields-bundle uses this for
+//     `customFields` on host-entities — keys are dynamic per fieldDefinition)
+//   - Configuration-blobs with shape that evolves outside Stammfeld-schema
+//   - AI-inferred metadata where shape is provider-dependent
+//
+// Vs. embedded: embedded enforces a typed sub-schema; jsonb accepts any
+// JSON-shaped object. Read-side both map to Postgres `jsonb`. Default `{}`
+// + NOT NULL, identisch zu embedded.
+export type JsonbFieldDef = {
+  readonly type: "jsonb";
+  readonly sensitive?: boolean;
+  readonly access?: FieldAccess;
+} & PiiAnnotations;
+
 // Legacy "date" — JS-Date-Object, semantisch unklar (Wall-Clock vs Instant).
 // Für neue Felder bevorzuge:
 //   - `timestamp` für UTC-Instant ("wann ist das passiert")
@@ -429,6 +444,7 @@ export type FieldDefinition =
   | MoneyFieldDef
   | ReferenceFieldDef
   | EmbeddedFieldDef
+  | JsonbFieldDef
   | DateFieldDef
   | TimestampFieldDef
   | TzFieldDef

package/src/engine/types/index.ts

@@ -88,6 +88,7 @@ export type {
   FilesFieldDef,
   ImageFieldDef,
   ImagesFieldDef,
+  JsonbFieldDef,
   LocatedTimestampFieldDef,
   LongTextFieldDef,
   MoneyFieldDef,

package/src/testing/e2e-generator.ts

@@ -450,6 +450,9 @@ function fieldToFixture(name: string, field: FieldDefinition): unknown {
       }
       return sub;
     }
+    case "jsonb":
+      // Free-form jsonb — e2e-generator returns empty-object.
+      return {};
     case "file":
     case "image":
     case "files":