@cosmicdrift/kumiko-framework 0.10.0 → 0.11.1

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @cosmicdrift/kumiko-framework
 
+## 0.11.1
+
+## 0.11.0
+
+### Minor Changes
+
+- 9347212: Add `r.searchPayloadExtension(entity, fn)` API. Contributor functions add flat fields to an entity's search-index document during `buildSearchDocument` indexing.
+
+  Use-cases:
+
+  - `custom-fields-bundle` (upcoming): merge customFields-jsonb-keys flat into search-doc so tenant-defined fields are searchable
+  - Tags-bundle: project tags-array into searchable form
+  - Computed-fields: denormalize related-counts (e.g., `messageCount` on conversation)
+
+  Contributor receives `{entityName, entityId, state}`, returns extras to merge. Async-allowed but discouraged (indexing-path hot loop).
+
+  Boot-validation: typo'd entity-names fail-fast at registry-build (sibling to entity-hooks boot-validation).
+
+  **Behavior-change**: entities without any stammfeld `searchable: true` now get a search-doc indexed when at least one extension registers contributors for them. Before this PR, such entities were skipped entirely. This enables custom-fields-only-indexing (the customFields-bundle use-case) but slightly increases Meilisearch-Index-Membership.
+
+  Ownership-tracking: contributors are stored as `OwnedFn` and filtered by `effectiveFeatures` in the getter — feature-toggle-disabled bundles' contributors don't fire (consistent with postQuery-Hooks).
+
+  Part of custom-fields-bundle Sprint Phase F3.
+
+### Patch Changes
+
+- 30ea981: `validateEntityIndexes` allows UNIQUE constraints on single-column `tenantId`.
+
+  Previously any single-column index on `tenantId` was rejected as redundant — `buildDrizzleTable` auto-creates an index on tenantId for query-performance. But that auto-index is **not** a UNIQUE constraint; entities that need a 1:1 relation to the tenant (e.g. `tenant-compliance-profile`) declared `{ unique: true, columns: ["tenantId"] }` explicitly and the validator rejected them, breaking boot.
+
+  Now: `{ unique: true, columns: ["tenantId"] }` passes (semantic UNIQUE constraint, not a duplicate performance-hint). The original block stays in place for `{ unique: false, columns: ["tenantId"] }` (still redundant).
+
+  Surfaced when studio.kumiko.so booted in production-bundle and the bundled-features `compliance-profiles` entity hit the validator.
+
 ## 0.10.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "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.10.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.11.1",
     "@types/uuid": "^11.0.0",
     "bun-types": "^1.3.13",
     "drizzle-kit": "^0.31.10",

package/src/engine/__tests__/search-payload-extension.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, test } from "vitest";
+import { createEntity, createRegistry, defineFeature } from "../index";
+import type { SearchPayloadContributorFn } from "../types";
+
+// F3 — Search-Payload-Extension registers per-entity contributors that
+// enrich the search-index doc during `buildSearchDocument`. Tests pin:
+//   1. r.searchPayloadExtension(entity, fn) lands keyed by entity-name
+//   2. Multiple contributors per entity stack (additive merge)
+//   3. Registry getter returns ordered list
+//   4. Empty for unknown entity
+//   5. Contributor-Function-Signature passes correct args + returns extras
+//   6. Boot-validation rejects typo'd entity-names (sibling-guard to
+//      entity-hooks boot-validation — Memory feedback_entity_hook_boot_validation)
+
+const noop: SearchPayloadContributorFn = () => ({});
+
+describe("searchPayloadExtension registration", () => {
+  test("r.searchPayloadExtension(entity, fn) lands in feature.searchPayloadExtensions", () => {
+    const feature = defineFeature("test", (r) => {
+      const thing = r.entity("thing", createEntity({ table: "things", fields: {} }));
+      r.searchPayloadExtension(thing, noop);
+    });
+
+    const entry = feature.searchPayloadExtensions["thing"];
+    expect(entry).toHaveLength(1);
+  });
+
+  test("multiple contributors on same entity stack additively", () => {
+    const c1: SearchPayloadContributorFn = () => ({ a: 1 });
+    const c2: SearchPayloadContributorFn = () => ({ b: 2 });
+
+    const feature = defineFeature("test", (r) => {
+      const thing = r.entity("thing", createEntity({ table: "things", fields: {} }));
+      r.searchPayloadExtension(thing, c1);
+      r.searchPayloadExtension(thing, c2);
+    });
+
+    expect(feature.searchPayloadExtensions["thing"]).toHaveLength(2);
+  });
+});
+
+describe("Registry getter", () => {
+  test("getSearchPayloadExtensions returns contributors", () => {
+    const fn: SearchPayloadContributorFn = ({ state }) => ({ extra: state["id"] });
+
+    const feature = defineFeature("test", (r) => {
+      const thing = r.entity("thing", createEntity({ table: "things", fields: {} }));
+      r.searchPayloadExtension(thing, fn);
+    });
+
+    const registry = createRegistry([feature]);
+    const extensions = registry.getSearchPayloadExtensions("thing");
+    expect(extensions).toHaveLength(1);
+    expect(extensions[0]).toBe(fn);
+  });
+
+  test("getSearchPayloadExtensions empty for unknown entity", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("thing", createEntity({ table: "things", fields: {} }));
+    });
+
+    const registry = createRegistry([feature]);
+    expect(registry.getSearchPayloadExtensions("unknown")).toEqual([]);
+  });
+});
+
+describe("Contributor-Function-Signature", () => {
+  test("contributor receives entityName + entityId + state, returns extras to merge", async () => {
+    const contributor: SearchPayloadContributorFn = ({ entityName, entityId, state }) => ({
+      // Sanity-Check: contributor sees the exact args passed
+      _entityName: entityName,
+      _entityId: entityId,
+      // Project state.tags into a flat searchable field
+      flatTags: Array.isArray(state["tags"]) ? (state["tags"] as string[]).join(",") : "",
+    });
+
+    const feature = defineFeature("test", (r) => {
+      const thing = r.entity("thing", createEntity({ table: "things", fields: {} }));
+      r.searchPayloadExtension(thing, contributor);
+    });
+
+    const registry = createRegistry([feature]);
+    const extensions = registry.getSearchPayloadExtensions("thing");
+    const result = await extensions[0]?.({
+      entityName: "thing",
+      entityId: "t1",
+      state: { id: "t1", tags: ["a", "b"] },
+    });
+    expect(result).toEqual({ _entityName: "thing", _entityId: "t1", flatTags: "a,b" });
+  });
+});
+
+describe("effectiveFeatures filtering", () => {
+  test("getSearchPayloadExtensions filters contributors of feature-toggle-disabled bundles", () => {
+    const fnA: SearchPayloadContributorFn = () => ({ a: 1 });
+    const fnB: SearchPayloadContributorFn = () => ({ b: 2 });
+
+    const featureA = defineFeature("bundleA", (r) => {
+      r.entity("thing", createEntity({ table: "things", fields: {} }));
+      r.searchPayloadExtension("thing", fnA);
+    });
+    const featureB = defineFeature("bundleB", (r) => {
+      r.searchPayloadExtension("thing", fnB);
+    });
+
+    const registry = createRegistry([featureA, featureB]);
+
+    // both effective → both fire
+    expect(registry.getSearchPayloadExtensions("thing")).toHaveLength(2);
+
+    // only bundleA effective → only fnA returned (bundleB filtered out)
+    const onlyA = registry.getSearchPayloadExtensions("thing", new Set(["bundleA"]));
+    expect(onlyA).toHaveLength(1);
+    expect(onlyA[0]).toBe(fnA);
+  });
+});
+
+describe("Boot-Validation", () => {
+  test("rejects searchPayloadExtension on unknown entity-name (sibling to entity-hooks)", () => {
+    expect(() =>
+      defineFeature("test", (r) => {
+        r.entity("thing", createEntity({ table: "things", fields: {} }));
+        // Typo: "propery" doesn't exist
+        r.searchPayloadExtension("propery", noop);
+      }),
+    ).not.toThrow(); // defineFeature itself doesn't validate — registry does
+
+    expect(() => {
+      const feature = defineFeature("test", (r) => {
+        r.entity("thing", createEntity({ table: "things", fields: {} }));
+        r.searchPayloadExtension("propery", noop);
+      });
+      createRegistry([feature]);
+    }).toThrow(/searchPayloadExtension.*"propery".*no entity/);
+  });
+});

package/src/engine/boot-validator/entity-handler.ts

@@ -224,7 +224,11 @@ export function validateEntityIndexes(feature: FeatureDefinition): void {
           );
         }
       }
-      if (def.columns.length === 1 && def.columns[0] === "tenantId") {
+      // UNIQUE-constraint auf tenantId ist semantisch (1:1 tenant→entity)
+      // und NICHT redundant — buildDrizzleTable's auto-Index ist nur ein
+      // Performance-Hint, kein constraint. Nur die rein-tenantId-Single-
+      // column-non-unique-Form blockieren.
+      if (def.columns.length === 1 && def.columns[0] === "tenantId" && !def.unique) {
         throw new Error(
           `${where}: single-column index on "tenantId" is redundant — ` +
             `buildDrizzleTable always creates one automatically. Remove this entry.`,

package/src/engine/define-feature.ts

@@ -53,6 +53,7 @@ import type {
   RegistrarExtensionDef,
   RegistrarExtensionRegistration,
   RelationDefinition,
+  SearchPayloadContributorFn,
   SecretKeyDefinition,
   SecretKeyHandle,
   SecretOptions,
@@ -123,6 +124,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
   const entityPreDelete: Record<string, PhasedHook<PreDeleteHookFn>[]> = {};
   const entityPostDelete: Record<string, PhasedHook<PostDeleteHookFn>[]> = {};
   const entityPostQuery: Record<string, OwnedFn<PostQueryHookFn>[]> = {};
+  const searchPayloadExtensions: Record<string, OwnedFn<SearchPayloadContributorFn>[]> = {};
   const notifications: Record<string, NotificationDefinition> = {};
   const registrarExtensions: Record<string, RegistrarExtensionDef> = {};
   const extensionUsages: RegistrarExtensionRegistration[] = [];
@@ -372,6 +374,12 @@ export function defineFeature<const TName extends string, TExports = undefined>(
       }
     },
 
+    searchPayloadExtension(entityRef: NameOrRef, fn: SearchPayloadContributorFn): void {
+      const entityName = resolveName(entityRef);
+      if (!searchPayloadExtensions[entityName]) searchPayloadExtensions[entityName] = [];
+      searchPayloadExtensions[entityName].push({ fn, featureName: name });
+    },
+
     config<TKeys extends Readonly<Record<string, ConfigKeyDefinition<ConfigKeyType>>>>(definition: {
       readonly keys: TKeys;
       readonly seeds?: Readonly<Record<string, ConfigSeedDef>>;
@@ -873,6 +881,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
       postDelete: entityPostDelete,
       postQuery: entityPostQuery,
     },
+    searchPayloadExtensions,
     configKeys,
     configSeeds,
     jobs,

package/src/engine/registry.ts

@@ -35,6 +35,7 @@ import type {
   Registry,
   RelationDefinition,
   ScreenDefinition,
+  SearchPayloadContributorFn,
   SecretKeyDefinition,
   TranslationKeys,
   TreeActionDef,
@@ -120,6 +121,7 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
   const entityPreDeleteHooks = new Map<string, PhasedHook<PreDeleteHookFn>[]>();
   const entityPostDeleteHooks = new Map<string, PhasedHook<PostDeleteHookFn>[]>();
   const entityPostQueryHooks = new Map<string, OwnedFn<PostQueryHookFn>[]>();
+  const searchPayloadExtensions = new Map<string, OwnedFn<SearchPayloadContributorFn>[]>();
   const configKeyMap = new Map<string, ConfigKeyDefinition>();
   const jobMap = new Map<string, JobDefinition>();
   const notificationMap = new Map<string, NotificationDefinition>();
@@ -421,6 +423,13 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
     mergeHookList(entityPostDeleteHooks, feature.entityHooks.postDelete);
     mergeHookList(entityPostQueryHooks, feature.entityHooks.postQuery);
 
+    // F3 search-payload-extensions: per-entity contributors merged additively
+    for (const [entityName, contributors] of Object.entries(feature.searchPayloadExtensions)) {
+      const existing = searchPayloadExtensions.get(entityName) ?? [];
+      for (const c of contributors) existing.push(c);
+      searchPayloadExtensions.set(entityName, existing);
+    }
+
     // Registrar extensions: collect definitions and usages
     for (const [extName, extDef] of Object.entries(feature.registrarExtensions)) {
       if (extensionMap.has(extName)) {
@@ -1103,6 +1112,7 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
     { map: entityPreDeleteHooks, phase: "preDelete (entityHook)" },
     { map: entityPostDeleteHooks, phase: "postDelete (entityHook)" },
     { map: entityPostQueryHooks, phase: "postQuery (entityHook)" },
+    { map: searchPayloadExtensions, phase: "searchPayloadExtension" },
   ] as const;
   for (const { map, phase } of entityHookMaps) {
     for (const entityName of map.keys()) {
@@ -1269,6 +1279,17 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
       return filterOwned(entityPostQueryHooks.get(entityName), effectiveFeatures);
     },
 
+    // F3 — Search-Payload-Extension contributors for an entity. Used by
+    // `buildSearchDocument` in system-hooks.ts to enrich the indexed payload.
+    // `effectiveFeatures` filters out contributors owned by feature-toggle-
+    // disabled features (parallel to getEntityPostQueryHooks etc.).
+    getSearchPayloadExtensions(
+      entityName: string,
+      effectiveFeatures?: ReadonlySet<string>,
+    ): readonly SearchPayloadContributorFn[] {
+      return filterOwned(searchPayloadExtensions.get(entityName), effectiveFeatures);
+    },
+
     getAllTranslations(): TranslationKeys {
       return mergedTranslations;
     },

package/src/engine/types/feature.ts

@@ -43,12 +43,14 @@ import type {
   EntityHookMap,
   HookMap,
   HookPhase,
+  OwnedFn,
   PostDeleteHookFn,
   PostQueryHookFn,
   PostSaveHookFn,
   PreDeleteHookFn,
   PreQueryHookFn,
   PreSaveHookFn,
+  SearchPayloadContributorFn,
   ValidationHookFn,
 } from "./hooks";
 import type { HttpRouteDefinition } from "./http-route";
@@ -171,6 +173,12 @@ export type FeatureDefinition = {
   readonly translations: TranslationKeys;
   readonly hooks: HookMap;
   readonly entityHooks: EntityHookMap;
+  // F3 search-payload-extension — per-entity contributors that add flat fields
+  // to the search-index payload during indexing. Keyed by entityName. Wrapped
+  // in OwnedFn for feature-toggle filtering (consistent with postQuery-Hooks).
+  readonly searchPayloadExtensions: Readonly<
+    Record<string, readonly OwnedFn<SearchPayloadContributorFn>[]>
+  >;
   readonly configKeys: Readonly<Record<string, ConfigKeyDefinition>>;
   readonly configSeeds: readonly ConfigSeedDef[];
   readonly jobs: Readonly<Record<string, JobDefinition>>;
@@ -369,6 +377,13 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   // access-filter).
   entityHook(type: "postQuery", entity: NameOrRef, fn: PostQueryHookFn): void;
 
+  // F3 — Search-Payload-Extension: contributor function adds flat fields to
+  // an entity's search-index document. Fires synchronously during
+  // buildSearchDocument indexing. Use-case: custom-fields-bundle merging
+  // customFields-jsonb-keys flat into search-doc; tags-bundle projecting
+  // tags-array as searchable. See `SearchPayloadContributorFn`.
+  searchPayloadExtension(entity: NameOrRef, fn: SearchPayloadContributorFn): void;
+
   // Returns a handle map keyed exactly like the input. Pass any handle to
   // `ctx.config(handle)` to get the value type narrowed by the key's `type`.
   // Optional `seeds` declare boot-time system-rows that are written via the
@@ -679,6 +694,14 @@ export type Registry = {
     entityName: string,
     effectiveFeatures?: ReadonlySet<string>,
   ): readonly PostQueryHookFn[];
+  // F3 — contributors for an entity's search-doc-payload, fired during
+  // buildSearchDocument indexing. See `SearchPayloadContributorFn`.
+  // `effectiveFeatures` filters out contributors owned by feature-toggle-
+  // disabled features (parallel to other getters' filtering semantic).
+  getSearchPayloadExtensions(
+    entityName: string,
+    effectiveFeatures?: ReadonlySet<string>,
+  ): readonly SearchPayloadContributorFn[];
   getHandlerEntity(qualifiedHandler: string): string | undefined;
   isHandlerSystemScoped(qualifiedHandler: string): boolean;
   getHandlerFeature(qualifiedHandler: string): string | undefined;

package/src/engine/types/hooks.ts

@@ -156,3 +156,22 @@ export type EntityHookMap = {
   readonly postDelete: Readonly<Record<string, readonly PhasedHook<PostDeleteHookFn>[]>>;
   readonly postQuery: Readonly<Record<string, readonly OwnedFn<PostQueryHookFn>[]>>;
 };
+
+// Search-Payload-Extension (F3) — contributor function that adds flat
+// fields to an entity's search-document. Fires synchronously during
+// buildSearchDocument (in `system-hooks.ts`), receives current entity
+// state, returns extra fields to merge into the search-index payload.
+//
+// Use-cases: custom-fields-bundle (merge customFields-jsonb-keys flat
+// into index), tags-bundle (project tags-array as searchable), computed-
+// fields (denormalize related-counts).
+//
+// IMPORTANT: contributor must be deterministic per (entityName, entityId,
+// state). Async-allowed for future-proofing but discouraged — the
+// indexing path runs once per entity-write, sync extension is
+// near-zero-cost.
+export type SearchPayloadContributorFn = (args: {
+  readonly entityName: string;
+  readonly entityId: EntityId;
+  readonly state: Record<string, unknown>;
+}) => Record<string, unknown> | Promise<Record<string, unknown>>;

package/src/engine/types/index.ts

@@ -165,6 +165,7 @@ export type {
   PreQueryHookFn,
   PreSaveHookFn,
   SaveContext,
+  SearchPayloadContributorFn,
   ValidationError,
   ValidationHookFn,
 } from "./hooks";

package/src/pipeline/system-hooks.ts

@@ -62,7 +62,7 @@ export function createSearchEventConsumer(
       }
 
       const state = reconstructStateForSearch(event.payload, verb);
-      const doc = buildSearchDocument(entityName, event.aggregateId, state, registry);
+      const doc = await buildSearchDocument(entityName, event.aggregateId, state, registry);
       if (!doc) {
         // skip: entity isn't searchable (no searchable fields declared)
         return;
@@ -98,17 +98,22 @@ function reconstructStateForSearch(
 // Build a SearchDocument from raw field-state. Parallel to the old
 // buildSearchDocument that took a SaveContext — same selector logic, just
 // a different input shape.
-function buildSearchDocument(
+async function buildSearchDocument(
   entityName: string,
   entityId: EntityId,
   state: Record<string, unknown>,
   registry: Registry,
-): SearchDocument | null {
+): Promise<SearchDocument | null> {
   const entity = registry.getEntity(entityName);
   if (!entity) return null;
 
   const searchableFields = registry.getSearchableFields(entityName);
-  if (searchableFields.length === 0) return null;
+  const extensions = registry.getSearchPayloadExtensions(entityName);
+  // Skip-Guard: kein indexable payload UND keine Extensions → kein doc.
+  // Extensions können auch ohne searchable-Stammfields den index befüllen
+  // (z.B. customFields-only-indexierung), daher muss die check beide
+  // berücksichtigen.
+  if (searchableFields.length === 0 && extensions.length === 0) return null;
 
   const embeddedFields = new Set<string>();
   for (const [fname, fdef] of Object.entries(entity.fields)) {
@@ -135,6 +140,17 @@ function buildSearchDocument(
     }
   }
 
+  // F3 — Search-Payload-Extensions: contributors merge flat fields into the
+  // search-doc (customFields-bundle / tags / computed-counts / etc.).
+  // Sequential await — extensions are expected sync or sub-millisecond async;
+  // sequential keeps the path simple and deterministic. If parallel ever
+  // matters, switch to Promise.all but bind contributor-output-precedence
+  // (last-wins vs. merge-conflict) explicitly.
+  for (const contribute of extensions) {
+    const contributed = await contribute({ entityName, entityId, state });
+    Object.assign(fields, contributed);
+  }
+
   return {
     entityType: entityName,
     entityId,