@cosmicdrift/kumiko-framework 0.150.0 → 0.151.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.150.0",
+  "version": "0.151.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>",
@@ -193,7 +193,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.150.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.151.1",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/bun-db/index.ts

@@ -23,6 +23,7 @@ export {
   incrementCounter,
   insertMany,
   insertOne,
+  runInSavepoint,
   selectMany,
   transaction,
   type UpsertOnConflictOptions,

package/src/db/index.ts

@@ -107,6 +107,7 @@ export {
   fetchOne,
   insertMany,
   insertOne,
+  runInSavepoint,
   selectMany,
   transaction,
   updateMany,

package/src/db/query-api.ts

@@ -17,6 +17,7 @@ export {
   fetchOne,
   insertMany,
   insertOne,
+  runInSavepoint,
   selectMany,
   transaction,
   updateMany,

package/src/engine/__tests__/build-config-feature-schema.test.ts

@@ -351,3 +351,88 @@ describe("buildConfigFeatureSchema — access + workspace", () => {
     expect([...roles].sort()).toEqual(["Admin", "SystemAdmin", "TenantAdmin"]);
   });
 });
+
+describe("buildConfigFeatureSchema — cross-feature group", () => {
+  test("two features sharing a group bucket under one screen/nav per scope, not two", () => {
+    const timeTracking = defineFeature("time-tracking", (r) => {
+      r.config({
+        keys: {
+          enabled: createTenantConfig("boolean", {
+            group: "bmc-settings",
+            mask: { title: "bmc.time-tracking-enabled" },
+          }),
+        },
+      });
+    });
+    const autoProtocol = defineFeature("auto-protocol", (r) => {
+      r.config({
+        keys: {
+          enabled: createTenantConfig("boolean", {
+            group: "bmc-settings",
+            mask: { title: "bmc.auto-protocol-enabled" },
+          }),
+        },
+      });
+    });
+
+    const out = buildConfigFeatureSchema(createRegistry([timeTracking, autoProtocol]));
+    expect(out.screens.filter((s) => s.id === "bmc-settings-tenant")).toHaveLength(1);
+    expect(out.navs.filter((n) => n.id === "bmc-settings-tenant")).toHaveLength(1);
+
+    const screen = out.screens.find((s) => s.id === "bmc-settings-tenant");
+    if (screen?.type !== "configEdit") throw new Error("expected configEdit screen");
+    // Neither feature owns the group name, so field ids are prefixed by the
+    // owning feature to stay unique — the whole point of the collision guard.
+    expect(screen.configKeys).toEqual({
+      "time-tracking-enabled": "time-tracking:config:enabled",
+      "auto-protocol-enabled": "auto-protocol:config:enabled",
+    });
+  });
+
+  test("same group + colliding owner-prefixed field id throws instead of silently overwriting", () => {
+    // "a-b" owner + shortKey "x" and "a" owner + shortKey "b-x" both produce
+    // the prefixed field id "a-b-x" — the exact clobbering hazard the
+    // owner-prefix scheme must catch, not just avoid in the common case.
+    const ab = defineFeature("a-b", (r) => {
+      r.config({
+        keys: { x: createTenantConfig("boolean", { group: "shared", mask: { title: "ab.x" } }) },
+      });
+    });
+    const a = defineFeature("a", (r) => {
+      r.config({
+        keys: {
+          bX: createTenantConfig("boolean", { group: "shared", mask: { title: "a.b-x" } }),
+        },
+      });
+    });
+    expect(() => buildConfigFeatureSchema(createRegistry([ab, a]))).toThrow(
+      /both resolve to field id "a-b-x"/,
+    );
+  });
+
+  test("group unset → behavior unchanged (buckets under the owning feature, plain shortKey)", () => {
+    const feature = defineFeature("ungrouped", (r) => {
+      r.config({
+        keys: { flag: createTenantConfig("boolean", { mask: { title: "u.flag" } }) },
+      });
+    });
+    const out = buildConfigFeatureSchema(createRegistry([feature]));
+    const screen = out.screens.find((s) => s.id === "ungrouped-tenant");
+    if (screen?.type !== "configEdit") throw new Error("expected configEdit screen");
+    expect(screen.configKeys).toEqual({ flag: "ungrouped:config:flag" });
+  });
+
+  test("invalid (non-kebab) group value throws at schema-build time", () => {
+    const feature = defineFeature("badgroup", (r) => {
+      r.config({
+        keys: {
+          flag: createTenantConfig("boolean", {
+            group: "Not Kebab!",
+            mask: { title: "bg.flag" },
+          }),
+        },
+      });
+    });
+    expect(() => buildConfigFeatureSchema(createRegistry([feature]))).toThrow(/kebab-case/);
+  });
+});

package/src/engine/__tests__/config-helpers.test.ts

@@ -257,6 +257,22 @@ describe("config helpers — allowPerRequest opt-in", () => {
   });
 });
 
+describe("config helpers — group (Settings-Hub namespace override)", () => {
+  test("group is carried when set", () => {
+    const key = createTenantConfig("boolean", { group: "tenant-settings" });
+    expect(key.group).toBe("tenant-settings");
+  });
+
+  test("no group → field absent (defaults to the owning feature)", () => {
+    expect(createTenantConfig("boolean").group).toBeUndefined();
+  });
+
+  test("group is available on every scope factory", () => {
+    expect(createSystemConfig("text", { group: "shared" }).group).toBe("shared");
+    expect(createUserConfig("text", { group: "shared" }).group).toBe("shared");
+  });
+});
+
 describe("config helpers — computed (plan-based / derived values)", () => {
   test("computed function attaches to the definition and returns the typed value", async () => {
     const key = createTenantConfig("number", {

package/src/engine/__tests__/engine.test.ts

@@ -1208,6 +1208,47 @@ describe("r.config()", () => {
   });
 });
 
+// --- r.configKey() ---
+
+describe("r.configKey()", () => {
+  test("returns a bare handle with the same qualified name r.config({keys}) would produce", () => {
+    let viaConfigKey!: { readonly name: string; readonly type: "boolean" };
+    let viaConfig!: { readonly defaultVat: { readonly name: string; readonly type: "number" } };
+    defineFeature("invoicing", (r) => {
+      viaConfigKey = r.configKey("enabled", createTenantConfig("boolean", { default: false }));
+    });
+    defineFeature("invoicing2", (r) => {
+      viaConfig = r.config({ keys: { defaultVat: createTenantConfig("number", { default: 19 }) } });
+    });
+
+    expect(viaConfigKey.name).toBe("invoicing:config:enabled");
+    expect(viaConfigKey.type).toBe("boolean");
+    // Structural check: configKey()'s handle is exactly what config({keys:{one}})
+    // would have produced for that single key — same shape, same qualification scheme.
+    expect(viaConfig.defaultVat.name).toBe("invoicing2:config:default-vat");
+  });
+
+  test("registers the key on the feature exactly like r.config would", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.configKey("maxItems", createTenantConfig("number", { default: 10 }));
+    });
+    expect(feature.configKeys["maxItems"]).toBeDefined();
+    expect(feature.configKeys["maxItems"]?.type).toBe("number");
+    expect(feature.configKeys["maxItems"]?.scope).toBe("tenant");
+
+    const registry = createRegistry([feature]);
+    expect(registry.getConfigKey("shop:config:max-items")).toBeDefined();
+  });
+
+  test("camelCase feature + key are kebab-cased in the handle name", () => {
+    let handle!: { readonly name: string };
+    defineFeature("billingCore", (r) => {
+      handle = r.configKey("monthlyTotalCents", createSystemConfig("number", { default: 0 }));
+    });
+    expect(handle.name).toBe("billing-core:config:monthly-total-cents");
+  });
+});
+
 // --- Relations ---
 
 describe("r.relation()", () => {

package/src/engine/build-config-feature-schema.ts

@@ -23,6 +23,7 @@ import {
   createSelectField,
   createTextField,
 } from "./factories";
+import { isKebabSegment } from "./qualified-name";
 import type { ConfigKeyDefinition } from "./types/config";
 import type { Registry } from "./types/feature";
 import type { FieldDefinition } from "./types/fields";
@@ -90,7 +91,14 @@ const MACHINE_WRITE_ROLE = "system" as const;
 
 type MaskedKey = {
   readonly qn: string;
+  // Effective group this key is bucketed under for the Settings-Hub —
+  // `def.group` if set, else `ownerFeature`. This is what screen/nav
+  // generation groups by.
   readonly feature: string;
+  // The feature that actually declared this key (always derived from `qn`).
+  // Needed to disambiguate field ids when `feature !== ownerFeature` (a
+  // cross-feature `group`) and for collision error messages.
+  readonly ownerFeature: string;
   readonly shortKey: string;
   readonly def: ConfigKeyDefinition;
 };
@@ -197,15 +205,30 @@ function buildScreen(
   const configKeys: Record<string, string> = {};
   const fields: Record<string, FieldDefinition> = {};
   const fieldLabels: Record<string, string> = {};
+  // Field id collapses to the plain shortKey when the key stays in its own
+  // feature's group (100% of today's apps — byte-identical output). Only a
+  // cross-feature `group` (feature !== ownerFeature) needs the owner prefix,
+  // to keep two features sharing a group from clobbering the same shortKey.
+  const fieldId = (k: MaskedKey): string =>
+    k.feature === k.ownerFeature ? k.shortKey : `${k.ownerFeature}-${k.shortKey}`;
+  const seenFieldIds = new Map<string, string>();
   for (const k of keys) {
-    configKeys[k.shortKey] = k.qn;
-    fields[k.shortKey] = deriveField(k.def);
+    const id = fieldId(k);
+    const prevQn = seenFieldIds.get(id);
+    if (prevQn !== undefined) {
+      throw new Error(
+        `[Settings-Hub] group "${feature}" scope "${scope}": config keys "${prevQn}" and "${k.qn}" both resolve to field id "${id}" — rename one key or its group.`,
+      );
+    }
+    seenFieldIds.set(id, k.qn);
+    configKeys[id] = k.qn;
+    fields[id] = deriveField(k.def);
     // mask is the visibility gate, so collectMaskedKeys guarantees it here.
-    if (k.def.mask) fieldLabels[k.shortKey] = k.def.mask.title;
+    if (k.def.mask) fieldLabels[id] = k.def.mask.title;
   }
   const section: EditFieldsSection = {
     title: `${feature}.settings`,
-    fields: keys.map((k) => k.shortKey),
+    fields: keys.map(fieldId),
   };
   return {
     id: shortId,
@@ -242,9 +265,16 @@ function collectMaskedKeys(registry: Registry): MaskedKey[] {
     if (def.mask === undefined || def.computed !== undefined) continue;
     const sep = qn.indexOf(":config:");
     if (sep === -1) continue;
+    const ownerFeature = qn.slice(0, sep);
+    if (def.group !== undefined && !isKebabSegment(def.group)) {
+      throw new Error(
+        `[Feature ${ownerFeature}] config key "${qn.slice(sep + ":config:".length)}" has invalid group "${def.group}" — must be kebab-case.`,
+      );
+    }
     out.push({
       qn,
-      feature: qn.slice(0, sep),
+      feature: def.group ?? ownerFeature,
+      ownerFeature,
       shortKey: qn.slice(sep + ":config:".length),
       def,
     });

package/src/engine/config-helpers.ts

@@ -95,6 +95,7 @@ type ConfigKeyOptions<T extends ConfigKeyType> = {
   inheritedToTenant?: boolean;
   backing?: ConfigBacking;
   mask?: ConfigMask;
+  group?: string;
 };
 
 // --- Scope Defaults ---
@@ -132,6 +133,7 @@ function createConfigKey<T extends ConfigKeyType>(
     ...(opts.inheritedToTenant === false ? { inheritedToTenant: false } : {}),
     ...(opts.backing === "secrets" ? { backing: "secrets" } : {}),
     ...(opts.mask ? { mask: opts.mask } : {}),
+    ...(opts.group ? { group: opts.group } : {}),
   };
 }
 

package/src/engine/feature-config-events-jobs.ts

@@ -32,41 +32,57 @@ export function buildConfigEventsJobsMethods<TName extends string>(
   state: FeatureBuilderState,
   name: TName,
 ) {
-  return {
-    config<TKeys extends Readonly<Record<string, ConfigKeyDefinition<ConfigKeyType>>>>(definition: {
-      readonly keys: TKeys;
-      readonly seeds?: Readonly<Record<string, ConfigSeedDef>>;
-    }): { readonly [K in keyof TKeys]: ConfigKeyHandle<TKeys[K]["type"]> } {
-      // Qualify eagerly (same as defineEvent) so the handle name matches what
-      // the registry stores — lazy qualification would break compile-time
-      // autocomplete and hand-built test registries.
-      const handles: Record<string, ConfigKeyHandle<ConfigKeyType>> = {};
-      for (const [key, keyDef] of Object.entries(definition.keys)) {
-        state.configKeys[key] = keyDef;
-        handles[key] = {
-          name: qn(toKebab(name), "config", toKebab(key)),
-          type: keyDef.type,
-        };
-      }
-      // Parse seeds: resolve qualified key names and validate scope
-      if (definition.seeds) {
-        for (const [shortKey, seedDef] of Object.entries(definition.seeds)) {
-          const keyDef = definition.keys[shortKey];
-          if (!keyDef) continue; // skip — boot-validator reports unknown keys
-          const qualifiedKey = qn(toKebab(name), "config", toKebab(shortKey));
-          const scope = seedDef.scope ?? keyDef.scope;
-          state.configSeeds.push({
-            key: qualifiedKey,
-            value: seedDef.value,
-            scope,
-            tenantId: seedDef.tenantId,
-            userId: seedDef.userId,
-          });
-        }
+  // Hoisted out of the returned object literal (not just a method) so
+  // `configKey()` below can call it directly — object-literal methods
+  // aren't in scope for their siblings without a `this`-bind.
+  function config<
+    TKeys extends Readonly<Record<string, ConfigKeyDefinition<ConfigKeyType>>>,
+  >(definition: {
+    readonly keys: TKeys;
+    readonly seeds?: Readonly<Record<string, ConfigSeedDef>>;
+  }): { readonly [K in keyof TKeys]: ConfigKeyHandle<TKeys[K]["type"]> } {
+    // Qualify eagerly (same as defineEvent) so the handle name matches what
+    // the registry stores — lazy qualification would break compile-time
+    // autocomplete and hand-built test registries.
+    const handles: Record<string, ConfigKeyHandle<ConfigKeyType>> = {};
+    for (const [key, keyDef] of Object.entries(definition.keys)) {
+      state.configKeys[key] = keyDef;
+      handles[key] = {
+        name: qn(toKebab(name), "config", toKebab(key)),
+        type: keyDef.type,
+      };
+    }
+    // Parse seeds: resolve qualified key names and validate scope
+    if (definition.seeds) {
+      for (const [shortKey, seedDef] of Object.entries(definition.seeds)) {
+        const keyDef = definition.keys[shortKey];
+        if (!keyDef) continue; // skip — boot-validator reports unknown keys
+        const qualifiedKey = qn(toKebab(name), "config", toKebab(shortKey));
+        const scope = seedDef.scope ?? keyDef.scope;
+        state.configSeeds.push({
+          key: qualifiedKey,
+          value: seedDef.value,
+          scope,
+          tenantId: seedDef.tenantId,
+          userId: seedDef.userId,
+        });
       }
-      return handles as {
-        readonly [K in keyof TKeys]: ConfigKeyHandle<TKeys[K]["type"]>;
-      }; // @cast-boundary engine-bridge — Mapped-Type-Inference at config()-callsite
+    }
+    return handles as {
+      readonly [K in keyof TKeys]: ConfigKeyHandle<TKeys[K]["type"]>;
+    }; // @cast-boundary engine-bridge — Mapped-Type-Inference at config()-callsite
+  }
+
+  return {
+    config,
+    // Shorthand for a single key — same handle shape `r.config({keys:{name:def}})`
+    // would produce for that key, just without the wrapping record. No seeds
+    // param: callers needing seeds use `r.config` directly.
+    configKey<T extends ConfigKeyType>(
+      keyName: string,
+      def: ConfigKeyDefinition<T>,
+    ): ConfigKeyHandle<T> {
+      return config({ keys: { [keyName]: def } })[keyName] as ConfigKeyHandle<T>; // @cast-boundary engine-bridge — mapped-type narrows to the single key
     },
     job(
       jobName: string,

package/src/engine/types/config.ts

@@ -136,6 +136,14 @@ export type ConfigKeyDefinition<T extends ConfigKeyType = ConfigKeyType> = {
   // manuelles r.screen/r.nav). Fehlt `mask`, gilt der Key als internes
   // Plumbing (ENV-provisioniert/computed) und erscheint NICHT im Hub.
   readonly mask?: ConfigMask;
+  // Überschreibt, unter welchem Settings-Hub-Namespace/Screen dieser Key
+  // gruppiert wird (Default: das deklarierende Feature). Erlaubt einem
+  // Feature, seine Keys unter einem fremden oder geteilten Namespace zu
+  // bündeln (z.B. viele flache Migrations-Flags unter "tenant-settings"),
+  // ohne dass das Ziel-Feature sie kennt. Rührt NICHT an qualifiziertem
+  // Namen, Storage, Seeds oder App-Overrides — nur reine UI-Gruppierung.
+  // Muss kebab-case sein (Boot-Validierung).
+  readonly group?: string;
 };
 
 // Label-Träger für den Settings-Hub. `title` ist ein i18n-Key (kein Literal —

package/src/engine/types/feature.ts

@@ -508,6 +508,14 @@ export type FeatureRegistrar<TFeature extends string = string> = {
     readonly seeds?: Readonly<Record<string, ConfigSeedDef>>;
   }): { readonly [K in keyof TKeys]: ConfigKeyHandle<TKeys[K]["type"]> };
 
+  // Shorthand for a single key — same handle shape `config({keys:{name:def}})`
+  // would produce for that key, no wrapping record. No seeds param: callers
+  // needing seeds use `config` directly.
+  configKey<T extends ConfigKeyType>(
+    keyName: string,
+    def: ConfigKeyDefinition<T>,
+  ): ConfigKeyHandle<T>;
+
   job(name: string, options: Omit<JobDefinition, "name" | "handler">, handler: JobHandlerFn): void;
 
   notification(