@cosmicdrift/kumiko-framework 0.1.0

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

@@ -0,0 +1,154 @@
+// Tests für buildAppSchema. Drei Invarianten pinnen:
+//   1. Multi-Feature: jedes Feature kommt mit eigenem featureName +
+//      seinen Entities/Screens/Navs in der features-Liste an.
+//   2. Workspaces werden mit aufgelösten navMembers (cross-feature
+//      gemerged) auf AppSchema-Ebene gehoben.
+//   3. JSON-Safety: function defaults und Zod-validators werden im
+//      projection-Schritt rausgefiltert — sonst landet Server-Runtime
+//      im Browser-Bundle.
+
+import { describe, expect, test } from "vitest";
+import { buildAppSchema } from "../build-app-schema";
+import { defineFeature } from "../define-feature";
+import { createRegistry } from "../registry";
+import type { EntityDefinition } from "../types/fields";
+
+describe("buildAppSchema", () => {
+  test("Multi-Feature: jedes Feature wird mit eigenem featureName projiziert", () => {
+    const orderEntity = {
+      table: "orders",
+      fields: { label: { type: "text" } },
+    } as unknown as EntityDefinition;
+    const fleetEntity = {
+      table: "vehicles",
+      fields: { plate: { type: "text" } },
+    } as unknown as EntityDefinition;
+
+    const orderFeature = defineFeature("orders", (r) => {
+      r.entity("order", orderEntity);
+      r.screen({ id: "list", type: "entityList", entity: "order", columns: ["label"] });
+      r.nav({ id: "list", label: "Order List" });
+    });
+    const fleetFeature = defineFeature("fleet", (r) => {
+      r.entity("vehicle", fleetEntity);
+      r.screen({ id: "list", type: "entityList", entity: "vehicle", columns: ["plate"] });
+      r.nav({ id: "list", label: "Fleet List" });
+    });
+
+    const registry = createRegistry([orderFeature, fleetFeature]);
+    const app = buildAppSchema(registry);
+
+    expect(app.features.map((f) => f.featureName).sort()).toEqual(["fleet", "orders"]);
+    const orders = app.features.find((f) => f.featureName === "orders");
+    const fleet = app.features.find((f) => f.featureName === "fleet");
+    expect(orders?.screens).toHaveLength(1);
+    expect(orders?.navs).toHaveLength(1);
+    expect(orders?.entities["order"]).toBeDefined();
+    expect(fleet?.entities["vehicle"]).toBeDefined();
+  });
+
+  test("Workspaces — definition + aufgelöste navMembers landen auf AppSchema-Ebene", () => {
+    const ordersFeature = defineFeature("orders", (r) => {
+      r.nav({ id: "list", label: "List" });
+    });
+    const fleetFeature = defineFeature("fleet", (r) => {
+      r.nav({ id: "vehicles", label: "Vehicles" });
+    });
+    const adminFeature = defineFeature("app", (r) => {
+      r.workspace({
+        id: "admin",
+        label: "Admin",
+        access: { openToAll: true },
+        nav: ["orders:nav:list", "fleet:nav:vehicles"],
+        default: true,
+      });
+    });
+
+    const registry = createRegistry([ordersFeature, fleetFeature, adminFeature]);
+    const app = buildAppSchema(registry);
+
+    expect(app.workspaces).toHaveLength(1);
+    const admin = app.workspaces?.[0];
+    // Short id — Renderer matcht gegen URL-Segment ("/admin/...") und
+    // erwartet die kurze Form. Registry intern qualifiziert, buildAppSchema
+    // projeziert zurück auf short.
+    expect(admin?.definition.id).toBe("admin");
+    // Cross-feature merge: beide Members sind drin, der Workspace-Owner
+    // (`app`) sieht die anderen Features ohne dass er sie importiert.
+    expect(admin?.navMembers).toEqual(["orders:nav:list", "fleet:nav:vehicles"]);
+  });
+
+  test("Apps ohne Workspaces lassen das Feld weg (omit-undefined-Pattern)", () => {
+    const f = defineFeature("only", (r) => {
+      r.nav({ id: "x", label: "X" });
+    });
+    const app = buildAppSchema(createRegistry([f]));
+    expect(app.workspaces).toBeUndefined();
+  });
+
+  test("JSON-Safety: Function-Defaults werden in der Projection rausgefiltert", () => {
+    // Field mit function-default — typisch z.B. () => generateId(). Auf
+    // dem Server legitimer Code, im Browser-Bundle aber unbrauchbar weil
+    // die Function auf Server-Internals zugreifen würde. Projection muss
+    // den default-Slot weglassen, nicht die Function durchlassen.
+    const entity = {
+      fields: {
+        id: { type: "text", default: () => "would-be-runtime-id" },
+        title: { type: "text" },
+      },
+    } as unknown as EntityDefinition;
+
+    const f = defineFeature("ent", (r) => {
+      r.entity("thing", entity);
+    });
+    const app = buildAppSchema(createRegistry([f]));
+    const projectedEntity = app.features[0]?.entities["thing"] as unknown as {
+      fields: Record<string, Record<string, unknown>>;
+    };
+    const idField = projectedEntity.fields["id"];
+    expect(idField).toBeDefined();
+    expect(idField?.["default"]).toBeUndefined(); // Function abgewiesen
+    expect(idField?.["type"]).toBe("text"); // type kommt durch
+  });
+
+  test("JSON-Safety: literal Defaults bleiben erhalten", () => {
+    const entity = {
+      fields: {
+        active: { type: "boolean", default: false },
+        count: { type: "number", default: 0 },
+        label: { type: "text", default: "" },
+      },
+    } 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["active"]?.["default"]).toBe(false);
+    expect(fields["count"]?.["default"]).toBe(0);
+    expect(fields["label"]?.["default"]).toBe("");
+  });
+
+  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.
+    const entity = {
+      fields: { id: { type: "text", default: () => "x" } },
+    } as unknown as EntityDefinition;
+    const f = defineFeature("ent", (r) => {
+      r.entity("thing", entity);
+      r.nav({ id: "n", label: "N" });
+      r.workspace({ id: "ws", label: "Ws", access: { openToAll: true } });
+    });
+    const app = buildAppSchema(createRegistry([f]));
+    const json = JSON.stringify(app);
+    const parsed = JSON.parse(json);
+    // Feature-namen identisch nach Roundtrip
+    expect(parsed.features[0].featureName).toBe("ent");
+  });
+});

package/src/engine/__tests__/claim-keys.test.ts

@@ -0,0 +1,274 @@
+import { describe, expect, test } from "vitest";
+import { createRegistry, defineFeature, readClaim } from "../index";
+import type { ClaimKeyHandle, SessionUser } from "../types";
+
+// --- r.claimKey() registration ---
+
+describe("r.claimKey() — registration", () => {
+  test("feature without claimKey has an empty claimKeys record", () => {
+    const feature = defineFeature("plain", () => {});
+    expect(feature.claimKeys).toEqual({});
+  });
+
+  test("single claimKey is stored with qualified name '<feature>:<shortName>' (no kebab conversion)", () => {
+    const feature = defineFeature("drivers", (r) => {
+      r.claimKey("teamId", { type: "string" });
+    });
+    expect(feature.claimKeys["teamId"]).toBeDefined();
+    // Claim keys are NOT QNs — they keep the raw camelCase shortName so the
+    // authClaims resolver's `<feature>:<innerKey>` merge finds them.
+    expect(feature.claimKeys["teamId"]?.qualifiedName).toBe("drivers:teamId");
+    expect(feature.claimKeys["teamId"]?.type).toBe("string");
+  });
+
+  test("returns a typed ClaimKeyHandle whose `name` is the qualified key", () => {
+    let handle: ClaimKeyHandle | undefined;
+    defineFeature("drivers", (r) => {
+      handle = r.claimKey("teamId", { type: "string" });
+    });
+    expect(handle?.name).toBe("drivers:teamId");
+    expect(handle?.type).toBe("string");
+  });
+
+  test("duplicate short-name within one feature throws", () => {
+    expect(() =>
+      defineFeature("drivers", (r) => {
+        r.claimKey("teamId", { type: "string" });
+        r.claimKey("teamId", { type: "number" });
+      }),
+    ).toThrow(/Claim key "teamId" already declared/);
+  });
+
+  test("camelCase feature + shortName are preserved as-is", () => {
+    const feature = defineFeature("driverOrders", (r) => {
+      r.claimKey("regionId", { type: "string" });
+    });
+    expect(feature.claimKeys["regionId"]?.qualifiedName).toBe("driverOrders:regionId");
+  });
+});
+
+// --- Registry aggregation ---
+
+describe("Registry.getAllClaimKeys / getClaimKey", () => {
+  test("aggregates keys from all features", () => {
+    const drivers = defineFeature("drivers", (r) => {
+      r.claimKey("teamId", { type: "string" });
+      r.claimKey("regionId", { type: "number" });
+    });
+    const billing = defineFeature("billing", (r) => {
+      r.claimKey("plan", { type: "string" });
+    });
+    const reg = createRegistry([drivers, billing]);
+
+    const all = reg.getAllClaimKeys();
+    expect(all.size).toBe(3);
+    expect(all.has("drivers:teamId")).toBe(true);
+    expect(all.has("drivers:regionId")).toBe(true);
+    expect(all.has("billing:plan")).toBe(true);
+  });
+
+  test("getClaimKey returns the definition by qualified name", () => {
+    const drivers = defineFeature("drivers", (r) => {
+      r.claimKey("teamId", { type: "string" });
+    });
+    const reg = createRegistry([drivers]);
+
+    const def = reg.getClaimKey("drivers:teamId");
+    expect(def?.type).toBe("string");
+    expect(def?.shortName).toBe("teamId");
+  });
+
+  test("unknown qualified name → undefined", () => {
+    const reg = createRegistry([]);
+    expect(reg.getClaimKey("whoever:xyz")).toBeUndefined();
+  });
+});
+
+// --- readClaim() helper ---
+
+describe("readClaim() — type-narrowed claim access", () => {
+  const baseUser: SessionUser = {
+    id: "11111111-0000-4000-8000-000000000001",
+    tenantId: "22222222-0000-4000-8000-000000000001",
+    roles: ["User"],
+  };
+
+  function userWithClaims(claims: Record<string, unknown>): SessionUser {
+    return { ...baseUser, claims };
+  }
+
+  test("returns the value cast to the handle's JS type — string", () => {
+    const drivers = defineFeature("drivers", (r) => {
+      r.claimKey("teamId", { type: "string" });
+    });
+    const handle = drivers.claimKeys["teamId"];
+    if (!handle) throw new Error("handle missing");
+    const typedHandle: ClaimKeyHandle<"string"> = { name: handle.qualifiedName, type: "string" };
+
+    const user = userWithClaims({ "drivers:teamId": "eng" });
+    const teamId = readClaim(user, typedHandle);
+    // Type-narrowing: TS treats this as `string | undefined` — we just
+    // assert the runtime value came through untouched.
+    expect(teamId).toBe("eng");
+  });
+
+  test("number type", () => {
+    const handle: ClaimKeyHandle<"number"> = {
+      name: "drivers:region-id",
+      type: "number",
+    };
+    const user = userWithClaims({ "drivers:region-id": 7 });
+    expect(readClaim(user, handle)).toBe(7);
+  });
+
+  test("boolean type", () => {
+    const handle: ClaimKeyHandle<"boolean"> = {
+      name: "flags:is-beta",
+      type: "boolean",
+    };
+    const user = userWithClaims({ "flags:is-beta": true });
+    expect(readClaim(user, handle)).toBe(true);
+  });
+
+  test("string[] type", () => {
+    const handle: ClaimKeyHandle<"string[]"> = {
+      name: "flags:enabled",
+      type: "string[]",
+    };
+    const user = userWithClaims({ "flags:enabled": ["dark-mode", "new-checkout"] });
+    expect(readClaim(user, handle)).toEqual(["dark-mode", "new-checkout"]);
+  });
+
+  test("object type", () => {
+    const handle: ClaimKeyHandle<"object"> = {
+      name: "drivers:metadata",
+      type: "object",
+    };
+    const user = userWithClaims({ "drivers:metadata": { level: 5, tags: ["a"] } });
+    expect(readClaim(user, handle)).toEqual({ level: 5, tags: ["a"] });
+  });
+
+  test("undefined when user has no claims at all", () => {
+    const handle: ClaimKeyHandle<"string"> = {
+      name: "drivers:team-id",
+      type: "string",
+    };
+    // baseUser has no `claims` field at all.
+    expect(readClaim(baseUser, handle)).toBeUndefined();
+  });
+
+  test("undefined when claims is set but the specific key is missing", () => {
+    const handle: ClaimKeyHandle<"string"> = {
+      name: "drivers:team-id",
+      type: "string",
+    };
+    const user = userWithClaims({ "other:key": "x" });
+    expect(readClaim(user, handle)).toBeUndefined();
+  });
+
+  test("null value is treated the same as missing — returns undefined", () => {
+    // A feature that returned null instead of an actual string shouldn't
+    // surface as "null" through the typed helper — the contract is
+    // "present or undefined".
+    const handle: ClaimKeyHandle<"string"> = {
+      name: "drivers:team-id",
+      type: "string",
+    };
+    const user = userWithClaims({ "drivers:team-id": null });
+    expect(readClaim(user, handle)).toBeUndefined();
+  });
+});
+
+// --- Round-trip: r.claimKey → r.authClaims return → resolver merge → readClaim ---
+//
+// Regression guard against the class of bugs where the three stages of a
+// claim's lifecycle disagree on the key string:
+//
+//   1. r.claimKey creates the handle (`handle.name`)
+//   2. r.authClaims hook returns `{ inner: value }` — framework prefixes
+//      to `"<feature>:<inner>"` at merge time
+//   3. readClaim(user, handle) looks up `user.claims[handle.name]`
+//
+// If any stage applies a different transform (kebab-case on one side but
+// not the other, different prefix convention, ...) the round-trip silently
+// breaks — readClaim returns undefined even though the hook returned a
+// value. This test wires all three against a single feature definition so
+// any such drift surfaces as a failing unit test, not a broken sample.
+
+describe("round-trip: claimKey ↔ authClaims return ↔ readClaim", () => {
+  test("value set by the hook is retrievable via the handle from the same feature", async () => {
+    // Arrange a feature that declares a claim AND produces a value for it.
+    // The hook captures a closure-scoped value so the test can assert
+    // the hook's return survives merge + readClaim untouched.
+    const driverData = new Map<string, string>();
+    driverData.set("user-1", "team-alpha");
+
+    const feature = defineFeature("drivers", (r) => {
+      const teamId = r.claimKey("teamId", { type: "string" });
+      r.authClaims(async (user) => {
+        const team = driverData.get(user.id);
+        return team ? { teamId: team } : {};
+      });
+      return { Claims: { teamId } as const };
+    });
+
+    // Run the resolver directly — same code path the Dispatcher walks.
+    const { resolveAuthClaims } = await import("../../pipeline/auth-claims-resolver");
+    const reg = createRegistry([feature]);
+    const user: SessionUser = {
+      id: "user-1",
+      tenantId: "22222222-0000-4000-8000-000000000001",
+      roles: ["User"],
+    };
+
+    const claims = await resolveAuthClaims({
+      user,
+      hooks: reg.getAuthClaimsHooks(),
+      contextFactory: () => ({
+        db: {} as never,
+        queryAs: async () => {
+          throw new Error("unused");
+        },
+      }),
+    });
+
+    // readClaim on the SAME handle produced at registration finds the value.
+    const userWithClaims: SessionUser = { ...user, claims };
+    const teamId = readClaim(userWithClaims, feature.exports.Claims.teamId);
+    expect(teamId).toBe("team-alpha");
+  });
+
+  test("round-trip works for non-trivial feature names (camelCase preserved, not kebab'd)", async () => {
+    // This was the exact bug the kumiko dev-loop caught in the sample —
+    // early impl kebab'd the handle name but the resolver merged with the
+    // raw camelCase key, so readClaim missed. Lock the camelCase path in.
+    const feature = defineFeature("driverOrders", (r) => {
+      const regionId = r.claimKey("regionId", { type: "number" });
+      r.authClaims(async () => ({ regionId: 42 }));
+      return { Claims: { regionId } as const };
+    });
+
+    const { resolveAuthClaims } = await import("../../pipeline/auth-claims-resolver");
+    const reg = createRegistry([feature]);
+    const user: SessionUser = {
+      id: "user-1",
+      tenantId: "22222222-0000-4000-8000-000000000001",
+      roles: ["User"],
+    };
+
+    const claims = await resolveAuthClaims({
+      user,
+      hooks: reg.getAuthClaimsHooks(),
+      contextFactory: () => ({
+        db: {} as never,
+        queryAs: async () => {
+          throw new Error("unused");
+        },
+      }),
+    });
+
+    expect(claims["driverOrders:regionId"]).toBe(42);
+    const userWithClaims: SessionUser = { ...user, claims };
+    expect(readClaim(userWithClaims, feature.exports.Claims.regionId)).toBe(42);
+  });
+});

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

@@ -0,0 +1,236 @@
+import { describe, expect, expectTypeOf, test } from "vitest";
+import {
+  access,
+  createSystemConfig,
+  createTenantConfig,
+  createUserConfig,
+} from "../config-helpers";
+import type { ConfigKeyDefinition } from "../types";
+
+describe("access presets", () => {
+  test("access.all", () => {
+    expect(access.all).toEqual(["all"]);
+  });
+
+  test("access.admin", () => {
+    expect(access.admin).toEqual(["Admin", "SystemAdmin"]);
+  });
+
+  test("access.systemAdmin", () => {
+    expect(access.systemAdmin).toEqual(["SystemAdmin"]);
+  });
+
+  test("access.system", () => {
+    expect(access.system).toEqual(["system"]);
+  });
+
+  test("access.privileged covers framework auth + SystemAdmin", () => {
+    expect(access.privileged).toEqual(["system", "SystemAdmin"]);
+  });
+
+  test("access.authenticated covers any signed-in user role (no system)", () => {
+    expect(access.authenticated).toEqual(["User", "Admin", "SystemAdmin"]);
+  });
+
+  test("access.roles() creates custom role list", () => {
+    expect(access.roles("Billing", "Accounting")).toEqual(["Billing", "Accounting"]);
+  });
+});
+
+describe("createTenantConfig", () => {
+  test("defaults: admin writes, all reads", () => {
+    const key = createTenantConfig("text");
+    expect(key.scope).toBe("tenant");
+    expect(key.access.write).toEqual(["Admin", "SystemAdmin"]);
+    expect(key.access.read).toEqual(["all"]);
+  });
+
+  test("custom roles override defaults", () => {
+    const key = createTenantConfig("text", {
+      write: access.roles("Billing"),
+      read: access.roles("Admin", "Billing"),
+    });
+    expect(key.access.write).toEqual(["Billing"]);
+    expect(key.access.read).toEqual(["Admin", "Billing"]);
+  });
+
+  test("encrypted flag", () => {
+    const key = createTenantConfig("text", { encrypted: true });
+    expect(key.encrypted).toBe(true);
+  });
+
+  test("with default value", () => {
+    const key = createTenantConfig("number", { default: 42 });
+    expect(key.default).toBe(42);
+    expect(key.type).toBe("number");
+  });
+
+  test("select with options", () => {
+    const key = createTenantConfig("select", { options: ["de", "en", "fr"] });
+    expect(key.options).toEqual(["de", "en", "fr"]);
+  });
+});
+
+describe("createSystemConfig", () => {
+  test("defaults: system writes, admin reads", () => {
+    const key = createSystemConfig("number");
+    expect(key.scope).toBe("system");
+    expect(key.access.write).toEqual(["system"]);
+    expect(key.access.read).toEqual(["Admin", "SystemAdmin"]);
+  });
+
+  test("with default value", () => {
+    const key = createSystemConfig("number", { default: 50 });
+    expect(key.default).toBe(50);
+  });
+});
+
+describe("createUserConfig", () => {
+  test("defaults: all writes, all reads", () => {
+    const key = createUserConfig("boolean");
+    expect(key.scope).toBe("user");
+    expect(key.access.write).toEqual(["all"]);
+    expect(key.access.read).toEqual(["all"]);
+  });
+
+  test("with default value", () => {
+    const key = createUserConfig("boolean", { default: true });
+    expect(key.default).toBe(true);
+  });
+});
+
+// expectTypeOf + @ts-expect-error are the real assertions — they fail the
+// build if the helper generic widens. The expect() lines exist so the
+// fake-test guard sees runtime asserts and lint stays quiet on unused vars.
+describe("config helpers — type narrowing", () => {
+  test("type tag is preserved per helper", () => {
+    const numberKey = createTenantConfig("number", { default: 19 });
+    const boolKey = createUserConfig("boolean", { default: true });
+    const textKey = createSystemConfig("text", { default: "x" });
+    expectTypeOf(numberKey).toEqualTypeOf<ConfigKeyDefinition<"number">>();
+    expectTypeOf(boolKey).toEqualTypeOf<ConfigKeyDefinition<"boolean">>();
+    expectTypeOf(textKey).toEqualTypeOf<ConfigKeyDefinition<"text">>();
+    expect(numberKey.type).toBe("number");
+    expect(boolKey.type).toBe("boolean");
+    expect(textKey.type).toBe("text");
+  });
+
+  test("default value must match the type-tag primitive", () => {
+    // @ts-expect-error — number tag, string default
+    const wrongNumber = createTenantConfig("number", { default: "nope" });
+    // @ts-expect-error — boolean tag, number default
+    const wrongBool = createUserConfig("boolean", { default: 1 });
+    expect(wrongNumber.type).toBe("number");
+    expect(wrongBool.type).toBe("boolean");
+  });
+});
+
+describe("config helpers — bounds (number only)", () => {
+  test("bounds attach to the definition when provided", () => {
+    const key = createTenantConfig("number", {
+      default: 10,
+      bounds: { min: 1, max: 100 },
+    });
+    expect(key.bounds).toEqual({ min: 1, max: 100 });
+  });
+
+  test("bounds can be partial (min only)", () => {
+    const key = createTenantConfig("number", {
+      default: 10,
+      bounds: { min: 0 },
+    });
+    expect(key.bounds).toEqual({ min: 0 });
+  });
+
+  test("bounds can be partial (max only)", () => {
+    const key = createSystemConfig("number", {
+      default: 50,
+      bounds: { max: 1000 },
+    });
+    expect(key.bounds).toEqual({ max: 1000 });
+  });
+
+  test("no bounds → bounds field absent", () => {
+    const key = createTenantConfig("number", { default: 10 });
+    expect(key.bounds).toBeUndefined();
+  });
+
+  test("@ts-expect-error: bounds on non-number types is rejected", () => {
+    // @ts-expect-error — bounds only valid for "number"
+    const textKey = createTenantConfig("text", { bounds: { min: 1 } });
+    // @ts-expect-error — bounds only valid for "number"
+    const boolKey = createUserConfig("boolean", { bounds: { max: 1 } });
+    const selectKey = createSystemConfig("select", {
+      options: ["a", "b"],
+      // @ts-expect-error — bounds only valid for "number"
+      bounds: { min: 1 },
+    });
+    expect(textKey.type).toBe("text");
+    expect(boolKey.type).toBe("boolean");
+    expect(selectKey.type).toBe("select");
+  });
+});
+
+describe("config helpers — allowPerRequest opt-in", () => {
+  test("allowPerRequest=true attaches to the definition", () => {
+    const key = createTenantConfig("number", {
+      default: 10,
+      allowPerRequest: true,
+    });
+    expect(key.allowPerRequest).toBe(true);
+  });
+
+  test("allowPerRequest=false is omitted (same shape as absent)", () => {
+    const key = createTenantConfig("number", {
+      default: 10,
+      allowPerRequest: false,
+    });
+    expect(key.allowPerRequest).toBeUndefined();
+  });
+
+  test("no allowPerRequest → field absent (deny-by-default)", () => {
+    const key = createTenantConfig("number", { default: 10 });
+    expect(key.allowPerRequest).toBeUndefined();
+  });
+
+  test("@ts-expect-error: allowPerRequest on text is rejected at compile time", () => {
+    // @ts-expect-error — text keys can't opt in to per-request overrides
+    const textKey = createTenantConfig("text", { allowPerRequest: true });
+    expect(textKey.type).toBe("text");
+  });
+});
+
+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", {
+      default: 10,
+      computed: async () => 200,
+    });
+    expect(typeof key.computed).toBe("function");
+    if (!key.computed) throw new Error("unreachable");
+    const value = await key.computed({
+      tenantId: "00000000-0000-4000-8000-000000000001" as never,
+      userId: "u-1",
+      db: {} as never,
+    });
+    expect(value).toBe(200);
+  });
+
+  test("no computed → field absent on the definition", () => {
+    const key = createTenantConfig("number", { default: 10 });
+    expect(key.computed).toBeUndefined();
+  });
+
+  test("@ts-expect-error: computed return must match the type-tag", () => {
+    const wrongNumber = createTenantConfig("number", {
+      // @ts-expect-error — number tag, string return
+      computed: async () => "not-a-number",
+    });
+    const wrongBool = createUserConfig("boolean", {
+      // @ts-expect-error — boolean tag, number return
+      computed: async () => 1,
+    });
+    expect(wrongNumber.type).toBe("number");
+    expect(wrongBool.type).toBe("boolean");
+  });
+});