@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

package/src/engine/__tests__/build-app-schema.test.ts

@@ -47,6 +47,38 @@ describe("buildAppSchema", () => {
     expect(fleet?.entities["vehicle"]).toBeDefined();
   });
 
+  // #1059: r.translations({keys}) must flow into FeatureSchema.translations
+  // BYTE-IDENTICAL — nav/screen labels resolve these keys verbatim via
+  // t(label) client-side, so any re-prefixing (like the registry's internal
+  // mergedTranslations does for features whose keys already carry a colon)
+  // would break the lookup. Mirrors cap-counter's real shape exactly: nav
+  // label references its own already-qualified translation key.
+  test("r.translations landet verbatim in FeatureSchema.translations, ohne Re-Prefixing", () => {
+    const capCounterLikeFeature = defineFeature("cap-counter", (r) => {
+      r.nav({ id: "cap-list", label: "cap-counter:nav.cap-list" });
+      r.translations({
+        keys: {
+          "cap-counter:nav.cap-list": { de: "Limits", en: "Caps" },
+        },
+      });
+    });
+
+    const app = buildAppSchema(createRegistry([capCounterLikeFeature]));
+    const feature = app.features.find((f) => f.featureName === "cap-counter");
+
+    expect(feature?.translations).toEqual({
+      "cap-counter:nav.cap-list": { de: "Limits", en: "Caps" },
+    });
+  });
+
+  test("Feature ohne r.translations lässt das Feld weg (omit-undefined-Pattern)", () => {
+    const f = defineFeature("bare", (r) => {
+      r.nav({ id: "x", label: "X" });
+    });
+    const app = buildAppSchema(createRegistry([f]));
+    expect(app.features[0]?.translations).toBeUndefined();
+  });
+
   test("Workspaces — definition + aufgelöste navMembers landen auf AppSchema-Ebene", () => {
     const ordersFeature = defineFeature("orders", (r) => {
       r.nav({ id: "list", label: "List" });
@@ -111,6 +143,35 @@ describe("buildAppSchema", () => {
     expect(idField?.["type"]).toBe("text"); // type kommt durch
   });
 
+  test("Reference-Field: entity + labelField + multiple überleben die Projection", () => {
+    // Regression: ohne diese Properties im Client-Schema baut der ReferenceInput
+    // die Options-Query als `<feature>:query::list` (leeres refEntity) → 404 →
+    // Dropdown zeigt „Keine Treffer" obwohl die referenzierte Entity Rows hat.
+    const entity = {
+      fields: {
+        name: { type: "text" },
+        parentId: { type: "reference", entity: "component", labelField: "name" },
+        tags: { type: "reference", entity: "tag", labelField: "label", multiple: true },
+      },
+    } as unknown as EntityDefinition;
+
+    const f = defineFeature("ent", (r) => {
+      r.entity("thing", entity);
+    });
+    const app = buildAppSchema(createRegistry([f]));
+    const fields = (
+      app.features[0]?.entities["thing"] as unknown as {
+        fields: Record<string, Record<string, unknown>>;
+      }
+    ).fields;
+
+    expect(fields["parentId"]?.["type"]).toBe("reference");
+    expect(fields["parentId"]?.["entity"]).toBe("component");
+    expect(fields["parentId"]?.["labelField"]).toBe("name");
+    expect(fields["tags"]?.["entity"]).toBe("tag");
+    expect(fields["tags"]?.["multiple"]).toBe(true);
+  });
+
   test("JSON-Safety: literal Defaults bleiben erhalten", () => {
     const entity = {
       fields: {
@@ -155,6 +216,27 @@ describe("buildAppSchema", () => {
     expect(fields["name"]?.["filterable"]).toBeUndefined();
   });
 
+  test("searchable kommt ins Client-Schema (steuert den EntityList-Default, #1194)", () => {
+    const entity = {
+      fields: {
+        title: { type: "text", searchable: true },
+        name: { type: "text" },
+      },
+    } as unknown as EntityDefinition;
+    const f = defineFeature("ent", (r) => {
+      r.entity("thing", entity);
+    });
+    const app = buildAppSchema(createRegistry([f]));
+    const fields = (
+      app.features[0]?.entities["thing"] as unknown as {
+        fields: Record<string, Record<string, unknown>>;
+      }
+    ).fields;
+    expect(fields["title"]?.["searchable"]).toBe(true);
+    // Fields without searchable don't carry the key (no false-litter).
+    expect(fields["name"]?.["searchable"]).toBeUndefined();
+  });
+
   test("AppSchema ist via JSON.stringify roundtrip-sicher", () => {
     // Echter Smoke-Test des Vertrags — wenn jemand in den project-
     // Helper eine Function reinschmuggelt, würde das hier brennen.

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

@@ -90,6 +90,9 @@ describe("buildConfigFeatureSchema — structure", () => {
     expect(sys?.screen).toBeUndefined();
     expect(sys?.parent).toBeUndefined();
     expect(ten?.label).toBe("config.settings.tenant");
+    expect(sys?.icon).toBe("shield");
+    expect(ten?.icon).toBe("building");
+    expect(usr?.icon).toBe("user");
     expect((sys?.order ?? 0) < (ten?.order ?? 0) && (ten?.order ?? 0) < (usr?.order ?? 0)).toBe(
       true,
     );
@@ -256,6 +259,27 @@ describe("buildConfigFeatureSchema — access + workspace", () => {
     expect(out.navs.find((n) => n.id === "audience-tenant")?.access).toEqual({ openToAll: true });
   });
 
+  test("openToAll collapse holds regardless of key declaration order (516/2)", () => {
+    // The test above only ever puts the openToAll key first, so
+    // unionAccessRules's short-circuit (`if ("openToAll" in rule) return`)
+    // never actually has to walk past a role-restricted rule to prove it —
+    // `gated` here comes FIRST so a hypothetical short-circuit-on-first-only
+    // implementation would fail this one even though it passed the other.
+    const mixedWriteReversed = defineFeature("mixedwritereversed", (r) => {
+      r.config({
+        keys: {
+          gated: createTenantConfig("text", { mask: { title: "mwr.gated" } }), // default admin write
+          open: createTenantConfig("text", { write: access.all, mask: { title: "mwr.open" } }),
+        },
+      });
+    });
+    const out = buildConfigFeatureSchema(createRegistry([mixedWriteReversed]));
+    const screen = out.screens.find((s) => s.id === "mixedwritereversed-tenant");
+    if (screen?.type !== "configEdit")
+      throw new Error('expected configEdit screen "mixedwritereversed-tenant"');
+    expect(screen.access).toEqual({ openToAll: true });
+  });
+
   test("returns empty (no workspace) when no key opts into the hub via mask", () => {
     const plain = defineFeature("plain", (r) => {
       r.config({ keys: { secret: createSystemConfig("text", {}) } });
@@ -327,3 +351,104 @@ 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/);
+  });
+
+  test("invalid (non-kebab) group value throws even on a maskless key", () => {
+    // Maskless keys never appear in the hub — group is a no-op for them at
+    // runtime — but the type contract still promises kebab-case is
+    // boot-validated regardless of `mask`. collectMaskedKeys used to check
+    // the mask-gate before the group check, so a maskless key with a bad
+    // group silently passed boot; the check now runs before the mask-gate.
+    const feature = defineFeature("badgroupmaskless", (r) => {
+      r.config({
+        keys: {
+          flag: createTenantConfig("boolean", { group: "Not Kebab!" }),
+        },
+      });
+    });
+    expect(() => buildConfigFeatureSchema(createRegistry([feature]))).toThrow(/kebab-case/);
+  });
+});

package/src/engine/__tests__/build-target.test.ts

@@ -95,11 +95,7 @@ describe("buildTarget — Compile-Time-Safety (verified via @ts-expect-error)",
 
   test("falsche args-shape wird vom Compiler abgelehnt", () => {
     // @ts-expect-error — slug muss string sein, nicht number
-    buildTarget({
-      target: textContentStub,
-      action: "edit",
-      args: { slug: 42 },
-    });
+    buildTarget({ target: textContentStub, action: "edit", args: { slug: 42 } });
     // Runtime: korrekt-typed args liefern valid TargetRef
     const ref = buildTarget({
       target: textContentStub,
@@ -110,12 +106,8 @@ describe("buildTarget — Compile-Time-Safety (verified via @ts-expect-error)",
   });
 
   test("args bei NoArgs-Action wird vom Compiler abgelehnt", () => {
-    buildTarget({
-      target: textContentStub,
-      action: "list",
-      // @ts-expect-error — list hat keine args, args-Feld nicht erlaubt
-      args: { x: 1 },
-    });
+    // @ts-expect-error — list hat keine args, args-Feld nicht erlaubt
+    buildTarget({ target: textContentStub, action: "list", args: { x: 1 } });
     // Runtime: NoArgs-Action ohne args-Feld liefert valid TargetRef
     const ref = buildTarget({ target: textContentStub, action: "list" });
     expect("args" in ref).toBe(false);

package/src/engine/__tests__/codemod-pipeline.test.ts

@@ -1,19 +1,32 @@
 import { afterAll, beforeAll, describe, expect, it, mock } from "bun:test";
-import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
-// Bun.Glob is only used by scanForCandidates / runCodemod, not by
-// analyzeFile or convertFile. Those higher-level functions are tested
-// in the integration suite; unit tests here focus on file-level
-// operations which don't need Glob. A stub class prevents import
-// errors in bun (which runs on Node, not Bun).
+// Bun.Glob is only used by scanForCandidates / runCodemod. Emulate
+// **/*.write.ts via node:fs so scan/convert paths stay testable.
+function collectWriteTsRelPaths(rootDir: string, dir = rootDir, prefix = ""): string[] {
+  const out: string[] = [];
+  for (const name of readdirSync(dir)) {
+    const rel = prefix ? `${prefix}/${name}` : name;
+    const full = join(dir, name);
+    if (statSync(full).isDirectory()) {
+      out.push(...collectWriteTsRelPaths(rootDir, full, rel));
+    } else if (name.endsWith(".write.ts")) {
+      out.push(rel);
+    }
+  }
+  return out;
+}
+
 mock.module("bun", () => {
-  class StubGlob {
-    scanSync(): never {
-      throw new Error("Bun.Glob is not available in unit-test mode");
+  class FsGlob {
+    constructor(private readonly pattern: string) {}
+    scanSync(rootDir: string): string[] {
+      if (this.pattern !== "**/*.write.ts") return [];
+      return collectWriteTsRelPaths(rootDir).sort();
     }
   }
-  return { Glob: StubGlob };
+  return { Glob: FsGlob };
 });
 
 import {
@@ -21,6 +34,8 @@ import {
   analyzeHandlerArrow,
   convertFile,
   generatePerformBlock,
+  runCodemod,
+  scanForCandidates,
 } from "../codemod/index";
 
 const tmpDir = join(__dirname, "__codemod_fixtures__");
@@ -31,6 +46,20 @@ function writeFixture(name: string, content: string): string {
   return p;
 }
 
+function writeFixtureIn(dir: string, name: string, content: string): string {
+  const p = join(dir, name);
+  mkdirSync(join(p, ".."), { recursive: true });
+  writeFileSync(p, content, "utf8");
+  return p;
+}
+
+function freshScanRoot(name: string): string {
+  const dir = join(tmpDir, name);
+  rmSync(dir, { recursive: true, force: true });
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
 beforeAll(() => {
   rmSync(tmpDir, { recursive: true, force: true });
   mkdirSync(tmpDir, { recursive: true });
@@ -103,14 +132,14 @@ export const myHandler = defineWriteHandler({
 `;
 
 const alreadyPipelineContent = `\
-import { access, defineWriteHandler, pipeline } from "@cosmicdrift/kumiko-framework/engine";
+import { access, defineWriteHandler, stepsPipeline } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 
 export const myHandler = defineWriteHandler({
   name: "test:pipeline",
   schema: z.object({}),
   access: { roles: access.authenticated },
-  perform: pipeline(({ event, r }) => [
+  perform: stepsPipeline(({ event, r }) => [
     r.step.return((ctx) => ({ isSuccess: true, data: { ok: true } })),
   ]),
 });
@@ -173,14 +202,14 @@ describe("analyzeFile", () => {
 
 describe("convertFile", () => {
   describe("static return handler", () => {
-    it("converts handler to perform: pipeline(...)", async () => {
+    it("converts handler to perform: stepsPipeline(...)", async () => {
       const p = writeFixture("static-convert.write.ts", staticReturnContent);
       const result = await convertFile(p);
       expect(result.status).toBe("converted");
       const content = readFileSync(p, "utf8");
-      expect(content).toContain("perform: pipeline");
+      expect(content).toContain("perform: stepsPipeline");
       expect(content).toContain("r.step.return");
-      expect(content).toContain("import { access, defineWriteHandler, pipeline }");
+      expect(content).toContain("import { access, defineWriteHandler, stepsPipeline }");
       expect(content).not.toContain("handler:");
     });
 
@@ -198,7 +227,7 @@ export const h = defineWriteHandler({
       const result = await convertFile(p);
       expect(result.status).toBe("converted");
       const converted = readFileSync(p, "utf8");
-      expect(converted).toContain("pipeline<typeof MySchema, unknown>");
+      expect(converted).toContain("stepsPipeline<typeof MySchema, unknown>");
     });
   });
 
@@ -271,12 +300,12 @@ export const h = defineWriteHandler({
       const result = await convertFile(p);
       expect(result.status).toBe("converted");
       const content = readFileSync(p, "utf8");
-      expect(content).toContain("import { access, defineWriteHandler, pipeline }");
+      expect(content).toContain("import { access, defineWriteHandler, stepsPipeline }");
     });
 
     it("does not duplicate pipeline import when already present", async () => {
       const content = `\
-import { access, defineWriteHandler, pipeline } from "@cosmicdrift/kumiko-framework/engine";
+import { access, defineWriteHandler, stepsPipeline } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 
 export const h = defineWriteHandler({
@@ -288,7 +317,9 @@ export const h = defineWriteHandler({
       const result = await convertFile(p);
       expect(result.status).toBe("converted");
       const final = readFileSync(p, "utf8").split("\n");
-      const pipelineImports = final.filter((l) => l.includes("import") && l.includes("pipeline"));
+      const pipelineImports = final.filter(
+        (l) => l.includes("import") && l.includes("stepsPipeline"),
+      );
       // Only one import line should contain "pipeline"
       expect(pipelineImports.length).toBe(1);
     });
@@ -397,6 +428,31 @@ export const h = defineWriteHandler({
       // ts-morph should handle this gracefully (parse error → no call found)
       expect(result.status).toBe("skipped");
     });
+
+    it("returns error when the path is not a readable file", async () => {
+      const dirPath = join(tmpDir, "dir-not-file.write.ts");
+      rmSync(dirPath, { recursive: true, force: true });
+      mkdirSync(dirPath, { recursive: true });
+      const result = await convertFile(dirPath);
+      expect(result.status).toBe("error");
+      expect(result.reason).toBeDefined();
+    });
+
+    it("verbose logs when skipping a non-trivial handler", async () => {
+      const p = writeFixture("verbose-skip-file.write.ts", complexContent);
+      const logs: string[] = [];
+      const origLog = console.log;
+      console.log = (...args: unknown[]) => {
+        logs.push(args.map(String).join(" "));
+      };
+      try {
+        const result = await convertFile(p, undefined, { verbose: true });
+        expect(result.status).toBe("skipped");
+        expect(logs.some((l) => l.includes("non-trivial handler"))).toBe(true);
+      } finally {
+        console.log = origLog;
+      }
+    });
   });
 });
 
@@ -507,20 +563,95 @@ describe("analyzeHandlerArrow", () => {
     expect(result.isGuardedCreate).toBe(true);
     expect(result.isSimpleExecutorCreate).toBe(false);
   });
+
+  it("returns non-convertible defaults for async ( without =>", () => {
+    const result = analyzeHandlerArrow("async (event, ctx) { return { isSuccess: true } }");
+    expect(result.isStaticReturn).toBe(false);
+    expect(result.isSimpleExecutorCreate).toBe(false);
+    expect(result.isSimpleExecutorUpdate).toBe(false);
+    expect(result.hasConditionalLogic).toBe(false);
+    expect(result.isExpressionBodyCreate).toBe(false);
+    expect(result.isGuardedCreate).toBe(false);
+  });
+});
+
+describe("scanForCandidates", () => {
+  it("returns empty list when no *.write.ts files exist", () => {
+    const root = freshScanRoot("scan-empty");
+    expect(scanForCandidates(root)).toEqual([]);
+  });
+
+  it("finds and classifies *.write.ts fixtures under rootDir", () => {
+    const root = freshScanRoot("scan-mixed");
+    writeFixtureIn(root, "freeform.write.ts", staticReturnContent);
+    writeFixtureIn(root, "already-pipeline.write.ts", alreadyPipelineContent);
+    writeFixtureIn(root, "nested/deep.write.ts", queryHandlerContent);
+
+    const results = scanForCandidates(root);
+    expect(results.map((r) => r.filePath).sort()).toEqual(
+      [
+        join(root, "already-pipeline.write.ts"),
+        join(root, "freeform.write.ts"),
+        join(root, "nested/deep.write.ts"),
+      ].sort(),
+    );
+    expect(results.find((r) => r.pattern === "free-form-write")?.convertible).toBe(true);
+    expect(results.find((r) => r.pattern === "pipeline-write")?.convertible).toBe(false);
+    expect(results.find((r) => r.pattern === "query-handler")?.convertible).toBe(false);
+  });
+});
+
+describe("runCodemod", () => {
+  it("returns empty report when scan finds no convertible handlers", async () => {
+    const root = freshScanRoot("run-empty");
+    const report = await runCodemod(root);
+    expect(report).toEqual({ results: [], converted: 0, skipped: 0, errors: 0 });
+  });
+
+  it("converts free-form write handlers discovered by scan", async () => {
+    const root = freshScanRoot("run-convert");
+    const p = writeFixtureIn(root, "to-convert.write.ts", staticReturnContent);
+    const report = await runCodemod(root);
+    expect(report.converted).toBe(1);
+    expect(report.skipped).toBe(0);
+    expect(report.errors).toBe(0);
+    expect(readFileSync(p, "utf8")).toContain("perform: stepsPipeline");
+  });
+
+  it("verbose logs per-file outcomes", async () => {
+    const root = freshScanRoot("run-verbose");
+    writeFixtureIn(root, "verbose-convert.write.ts", staticReturnContent);
+    writeFixtureIn(root, "verbose-skip.write.ts", complexContent);
+
+    const logs: string[] = [];
+    const origLog = console.log;
+    console.log = (...args: unknown[]) => {
+      logs.push(args.map(String).join(" "));
+    };
+    try {
+      const report = await runCodemod(root, { verbose: true });
+      expect(report.converted).toBe(1);
+      expect(report.skipped).toBe(1);
+      expect(logs.some((l) => l.includes("verbose-convert.write.ts"))).toBe(true);
+      expect(logs.some((l) => l.includes("verbose-skip.write.ts"))).toBe(true);
+    } finally {
+      console.log = origLog;
+    }
+  });
 });
 
 describe("generatePerformBlock", () => {
   it("generates pipeline block for static return", () => {
     const analysis = analyzeHandlerArrow("async () => ({ isSuccess: true, data: { ok: true } })");
     const block = generatePerformBlock(analysis, "", "  ");
-    expect(block).toContain("perform: pipeline(");
+    expect(block).toContain("perform: stepsPipeline(");
     expect(block).toContain("r.step.return((ctx) => ({ isSuccess: true, data: { ok: true } })");
   });
 
   it("generates pipeline block with schema type parameter", () => {
     const analysis = analyzeHandlerArrow("async () => ({ isSuccess: true, data: { ok: true } })");
     const block = generatePerformBlock(analysis, "typeof InvoiceSchema", "  ");
-    expect(block).toContain("pipeline<typeof InvoiceSchema, unknown>");
+    expect(block).toContain("stepsPipeline<typeof InvoiceSchema, unknown>");
   });
 
   it("returns null for non-convertible analysis", () => {

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__/define-feature-entity-mapping.test.ts

@@ -29,8 +29,14 @@ describe("defineFeature — bare CRUD verb → entity mapping", () => {
   });
 
   test("feature-name match wins (the fallback is the secondary path)", () => {
+    // Two entities (516/1): with only "note" registered, this would also
+    // pass via the single-entity fallback, proving nothing about the
+    // name-match branch specifically. A second entity ("tag") disables the
+    // fallback (entityKeys.length !== 1), so success here can only come
+    // from entities[name] matching — the branch this test claims to cover.
     const f = defineFeature("note", (r) => {
       r.entity("note", noteEntity);
+      r.entity("tag", tagEntity);
       r.writeHandler(bareCreate);
     });
     expect(f.handlerEntityMappings?.["create"]).toBe("note");

package/src/engine/__tests__/define-roles.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, test } from "bun:test";
+import { defineRoles } from "../define-roles";
+
+describe("defineRoles", () => {
+  test("maps each role name to itself", () => {
+    const roles = defineRoles(["Admin", "SystemAdmin", "Driver"] as const);
+    expect(roles.Admin).toBe("Admin");
+    expect(roles.SystemAdmin).toBe("SystemAdmin");
+    expect(roles.Driver).toBe("Driver");
+  });
+
+  test("returns an object with exactly the given keys", () => {
+    const roles = defineRoles(["A", "B"] as const);
+    expect(Object.keys(roles).sort()).toEqual(["A", "B"]);
+  });
+
+  test("an empty role list returns an empty object", () => {
+    const roles = defineRoles([] as const);
+    expect(roles).toEqual({});
+  });
+});