@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

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

@@ -14,6 +14,7 @@ import {
   createTextField,
 } from "../factories";
 import { createApp, createRegistry, defineFeature } from "../index";
+import { buildMinimalCtx } from "./_pipeline-test-utils";
 
 // --- defineFeature ---
 
@@ -41,7 +42,9 @@ describe("defineFeature", () => {
         r.describe("first");
         r.describe("second");
       }),
-    ).toThrow(/r\.describe\(\) called twice/);
+    ).toThrow(
+      "[Feature test] r.describe() called twice — a feature's description is declared once",
+    );
   });
 
   test("r.describe() throws on empty or whitespace-only text", () => {
@@ -116,6 +119,33 @@ describe("defineFeature", () => {
     expect(ref?.name).toBe("order:list");
   });
 
+  test("streamHandler registers on feature.streamHandlers with schema/access/handler intact", async () => {
+    let ref: { name: string } | undefined;
+    const feature = defineFeature("test", (r) => {
+      ref = r.streamHandler(
+        "chat:complete",
+        z.object({ prompt: z.string() }),
+        async function* (query) {
+          yield `echo:${query.payload.prompt}`;
+        },
+        { access: { openToAll: true } },
+      );
+    });
+    expect(ref?.name).toBe("chat:complete");
+
+    const stored = feature.streamHandlers["chat:complete"];
+    expect(stored?.access).toEqual({ openToAll: true });
+
+    const chunks: string[] = [];
+    for await (const chunk of stored!.handler(
+      { type: "chat:complete", payload: { prompt: "hi" }, user: createTestUser() },
+      buildMinimalCtx(),
+    )) {
+      chunks.push(chunk as string);
+    }
+    expect(chunks).toEqual(["echo:hi"]);
+  });
+
   test("r.defineEvent returns typed EventDef and registers on feature", () => {
     let eventRef: { name: string } | undefined;
     const feature = defineFeature("orders", (r) => {
@@ -274,6 +304,24 @@ describe("defineFeature", () => {
       }),
     ).toThrow(/r\.uiHints\(\) called twice/);
   });
+
+  test("r.toggleable() throws when called twice", () => {
+    expect(() =>
+      defineFeature("test", (r) => {
+        r.toggleable({ default: true });
+        r.toggleable({ default: false });
+      }),
+    ).toThrow(/r\.toggleable\(\) called twice/);
+  });
+
+  test("r.envSchema() throws when called twice", () => {
+    expect(() =>
+      defineFeature("test", (r) => {
+        r.envSchema(z.object({ FOO: z.string() }));
+        r.envSchema(z.object({ BAR: z.string() }));
+      }),
+    ).toThrow(/r\.envSchema\(\) called twice/);
+  });
 });
 
 // --- Field Factories ---
@@ -419,6 +467,22 @@ describe("createRegistry", () => {
     expect(all["profile:nav.title"]).toEqual({ de: "Profil", en: "Profile" });
   });
 
+  // #1105: a feature that already qualifies its own translation keys (nav
+  // labels referencing "featureName:..." verbatim, see cap-counter) must not
+  // be double-prefixed — else server-side t() can never resolve them.
+  test("does not double-prefix translation keys that already carry the feature's own namespace", () => {
+    const f = defineFeature("cap-counter", (r) => {
+      r.translations({
+        keys: { "cap-counter:nav.cap-list": { de: "Limits", en: "Caps" } },
+      });
+    });
+
+    const registry = createRegistry([f]);
+    const all = registry.getAllTranslations();
+    expect(all["cap-counter:nav.cap-list"]).toEqual({ de: "Limits", en: "Caps" });
+    expect(all["cap-counter:cap-counter:nav.cap-list"]).toBeUndefined();
+  });
+
   test("throws when write handler is not entity-mapped in feature with field-access", () => {
     const feature = defineFeature("hr", (r) => {
       r.entity(
@@ -675,6 +739,36 @@ describe("createApp", () => {
     ).not.toThrow();
   });
 
+  test("validates stream handler roles against app-defined roles (#1442)", () => {
+    const feature = defineFeature("admin", (r) => {
+      r.streamHandler("admin.tail", z.object({}), async function* () {}, {
+        access: { roles: ["SuperAdmin"] },
+      });
+    });
+
+    expect(() =>
+      createApp({
+        roles: ["Admin", "User"] as const,
+        features: [feature],
+      }),
+    ).toThrow(/unknown role.*SuperAdmin/i);
+  });
+
+  test("passes when stream handler roles are valid (#1442)", () => {
+    const feature = defineFeature("admin", (r) => {
+      r.streamHandler("admin.tail", z.object({}), async function* () {}, {
+        access: { roles: ["Admin"] },
+      });
+    });
+
+    expect(() =>
+      createApp({
+        roles: ["Admin", "User"] as const,
+        features: [feature],
+      }),
+    ).not.toThrow();
+  });
+
   test("createApp returns registry", () => {
     const feature = defineFeature("test", () => {});
     const app = createApp({ roles: ["Admin"] as const, features: [feature] });
@@ -1188,6 +1282,50 @@ describe("r.config()", () => {
   });
 });
 
+// --- r.config() single-key overload ---
+
+describe("r.config() single-key overload", () => {
+  test("returns a bare handle with the same qualified name the multi-key form would produce", () => {
+    let viaSingleKey!: { readonly name: string; readonly type: "boolean" };
+    let viaMultiKey!: { readonly defaultVat: { readonly name: string; readonly type: "number" } };
+    defineFeature("invoicing", (r) => {
+      viaSingleKey = r.config("enabled", createTenantConfig("boolean", { default: false }));
+    });
+    defineFeature("invoicing2", (r) => {
+      viaMultiKey = r.config({
+        keys: { defaultVat: createTenantConfig("number", { default: 19 }) },
+      });
+    });
+
+    expect(viaSingleKey.name).toBe("invoicing:config:enabled");
+    expect(viaSingleKey.type).toBe("boolean");
+    // Structural check: the single-key form's handle is exactly what
+    // {keys:{one}} would have produced for that single key — same shape,
+    // same qualification scheme.
+    expect(viaMultiKey.defaultVat.name).toBe("invoicing2:config:default-vat");
+  });
+
+  test("registers the key on the feature exactly like the multi-key form would", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.config("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.config("monthlyTotalCents", createSystemConfig("number", { default: 0 }));
+    });
+    expect(handle.name).toBe("billing-core:config:monthly-total-cents");
+  });
+});
+
 // --- Relations ---
 
 describe("r.relation()", () => {
@@ -1325,6 +1463,30 @@ describe("registry relations", () => {
     // Last write wins
     expect((rels["roles"] as { through: { table: string } }).through.table).toBe("UR2");
   });
+
+  test("getRelations aggregates relations on the same entity from two different features", () => {
+    const core = defineFeature("core", (r) => {
+      r.entity("user", createEntity({ table: "Users", fields: {} }));
+      r.entity("role", createEntity({ table: "Roles", fields: {} }));
+      r.relation("user", "roles", {
+        type: "manyToMany",
+        target: "role",
+        through: { table: "UserRoles", sourceKey: "userId", targetKey: "roleId" },
+      });
+    });
+    const billing = defineFeature("billing", (r) => {
+      r.entity("invoice", createEntity({ table: "Invoices", fields: {} }));
+      r.relation("user", "invoices", {
+        type: "hasMany",
+        target: "invoice",
+        foreignKey: "userId",
+      });
+    });
+
+    const registry = createRegistry([core, billing]);
+    const rels = registry.getRelations("user");
+    expect(Object.keys(rels).sort()).toEqual(["invoices", "roles"]);
+  });
 });
 
 // --- Global Search (new tenant-based API) ---

package/src/engine/__tests__/entity-handlers.test.ts

@@ -10,8 +10,11 @@ import {
   defineEntityUpdateHandler,
   defineEntityWriteHandler,
   defineProjectionQueryHandler,
+  type EntityCrudRegistrar,
+  registerEntityCrud,
 } from "../entity-handlers";
 import { createEntity, createTextField } from "../factories";
+import type { QueryHandlerDef, WriteHandlerDef } from "../types";
 
 const VALID_UUID = "00000000-0000-4000-8000-000000000001";
 
@@ -272,3 +275,80 @@ describe("Verb-specific entity-handler factories", () => {
     expect(typeof legacyApi.handler).toBe("function");
   });
 });
+
+function createCrudRegistrarMock(): {
+  readonly r: EntityCrudRegistrar;
+  readonly entities: Record<string, unknown>;
+  readonly writes: WriteHandlerDef[];
+  readonly queries: QueryHandlerDef[];
+} {
+  const entities: Record<string, unknown> = {};
+  const writes: WriteHandlerDef[] = [];
+  const queries: QueryHandlerDef[] = [];
+  const r: EntityCrudRegistrar = {
+    entity(name, definition) {
+      entities[name] = definition;
+    },
+    writeHandler(def) {
+      writes.push(def);
+    },
+    queryHandler(def) {
+      queries.push(def);
+    },
+  };
+  return { r, entities, writes, queries };
+}
+
+describe("registerEntityCrud", () => {
+  test("registers entity + standard handlers (restore only when softDelete)", () => {
+    const { r, entities, writes, queries } = createCrudRegistrarMock();
+    registerEntityCrud(r, "note", noteEntitySoftDelete, {
+      write: { access: { roles: ["Admin"] } },
+      read: { access: { openToAll: true } },
+    });
+    expect(entities["note"]).toBe(noteEntitySoftDelete);
+    expect(writes.map((w) => w.name)).toEqual([
+      "note:create",
+      "note:update",
+      "note:delete",
+      "note:restore",
+    ]);
+    expect(queries.map((q) => q.name)).toEqual(["note:list", "note:detail"]);
+    expect(writes[0]?.access).toEqual({ roles: ["Admin"] });
+    expect(queries[0]?.access).toEqual({ openToAll: true });
+  });
+
+  test("verbs.delete: false skips delete handler", () => {
+    const { r, writes } = createCrudRegistrarMock();
+    registerEntityCrud(r, "note", noteEntity, {
+      verbs: { delete: false },
+    });
+    expect(writes.map((w) => w.name)).toEqual(["note:create", "note:update"]);
+  });
+
+  test("no options → handlers have no access (no implicit openToAll)", () => {
+    const { r, writes, queries } = createCrudRegistrarMock();
+    registerEntityCrud(r, "note", noteEntity);
+    for (const def of [...writes, ...queries]) {
+      expect(def.access).toBeUndefined();
+    }
+  });
+
+  test("restore verb on entity without softDelete throws", () => {
+    const { r } = createCrudRegistrarMock();
+    expect(() => registerEntityCrud(r, "note", noteEntity, { verbs: { restore: true } })).toThrow(
+      /softDelete/,
+    );
+  });
+
+  test("registerEntity: false skips r.entity when already registered", () => {
+    const { r, entities, writes } = createCrudRegistrarMock();
+    r.entity("note", noteEntity);
+    registerEntityCrud(r, "note", noteEntity, {
+      registerEntity: false,
+      verbs: { update: false, delete: false, restore: false, list: false, detail: false },
+    });
+    expect(Object.keys(entities)).toEqual(["note"]);
+    expect(writes.map((w) => w.name)).toEqual(["note:create"]);
+  });
+});

package/src/engine/__tests__/event-migration-declarative.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { defineFeature } from "../define-feature";
+import type { DeclarativeEventMigration, EventUpcastCtx } from "../types";
+
+// Transforms under test are pure — ctx is never touched.
+const upcastCtx = {} as EventUpcastCtx;
+
+function compile(spec: DeclarativeEventMigration) {
+  const feature = defineFeature("billing", (r) => {
+    r.defineEvent("invoicePaid", z.unknown(), {
+      version: 2,
+      migrations: [{ fromVersion: 1, toVersion: 2, transform: spec }],
+    });
+  });
+  const def = feature.eventMigrations["invoicePaid"]?.[0];
+  if (!def) throw new Error("migration not registered");
+  return (payload: unknown) => def.transform(payload, upcastCtx);
+}
+
+describe("declarative eventMigration", () => {
+  test("rename moves the value and drops the old key; missing source is a no-op", async () => {
+    const run = compile({ rename: { amount: "amountCents", missing: "other" } });
+    expect(await run({ amount: 5, currency: "EUR" })).toEqual({
+      amountCents: 5,
+      currency: "EUR",
+    });
+  });
+
+  test("default fills absent keys only — existing values win", async () => {
+    const run = compile({ default: { currency: "EUR", status: "open" } });
+    expect(await run({ currency: "CHF" })).toEqual({ currency: "CHF", status: "open" });
+  });
+
+  test("map runs after rename on the new key; absent keys are skipped", async () => {
+    const run = compile({
+      rename: { amount: "amountCents" },
+      map: { amountCents: (v) => Math.round(Number(v) * 100), missing: () => "never" },
+    });
+    expect(await run({ amount: 19.99 })).toEqual({ amountCents: 1999 });
+  });
+
+  test("non-object payload fails loud", () => {
+    const run = compile({ default: { a: 1 } });
+    expect(() => run("not-an-object")).toThrow(/object payload/);
+    expect(() => run([1, 2])).toThrow(/object payload/);
+  });
+
+  test("two rename sources mapping to the same target fail loud at registration", () => {
+    expect(() => compile({ rename: { amount: "total", subtotal: "total" } })).toThrow(
+      /rename collision.*"total"/,
+    );
+  });
+
+  test("imperative function variant is stored untouched", () => {
+    const fn = (payload: unknown) => payload;
+    const feature = defineFeature("billing", (r) => {
+      r.defineEvent("invoicePaid", z.unknown(), {
+        version: 2,
+        migrations: [{ fromVersion: 1, toVersion: 2, transform: fn }],
+      });
+    });
+    expect(feature.eventMigrations["invoicePaid"]?.[0]?.transform).toBe(fn);
+  });
+});

package/src/engine/__tests__/event-type-map-augmentation.test.ts

@@ -0,0 +1,24 @@
+// Type-only fixture for the KumikoEventTypeMap declaration-merging channel
+// (#1394). event-type-map.ts moved the marker interfaces behind a re-export
+// chain (kumiko-types -> engine/types/event-type-map.ts shim -> engine
+// barrel), while the codegen augmentation channel
+// (dev-server/src/codegen/render.ts) still targets
+// `declare module "@cosmicdrift/kumiko-framework/engine"`. If a future
+// change breaks that re-export chain, augmentation silently stops merging
+// and every event payload falls back to `unknown` with no compile error —
+// this test only catches it because tsc checks the `declare module` below
+// against the SAME specifier the codegen emits.
+import { expectTypeOf, test } from "bun:test";
+import type { KumikoEventTypeMap } from "@cosmicdrift/kumiko-framework/engine";
+
+declare module "@cosmicdrift/kumiko-framework/engine" {
+  interface KumikoEventTypeMap {
+    "event-type-map-fixture:probe.created": { readonly probe: true };
+  }
+}
+
+test("augmenting KumikoEventTypeMap via the engine specifier merges into the relocated interface", () => {
+  expectTypeOf<KumikoEventTypeMap["event-type-map-fixture:probe.created"]>().toEqualTypeOf<{
+    readonly probe: true;
+  }>();
+});

package/src/engine/__tests__/extend-entity-projection.test.ts

@@ -0,0 +1,123 @@
+// r.extendEntityProjection — registrar/registry contracts (#759). The
+// runtime rebuild-replay behaviour is proven in
+// custom-fields/__tests__/custom-fields.integration.test.ts.
+
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { defineFeature } from "../define-feature";
+import { createEntity, createTextField } from "../factories";
+import { createRegistry } from "../registry";
+
+function exampleEntity(name = "unit") {
+  return createEntity({
+    table: name,
+    fields: { name: createTextField() },
+  });
+}
+
+const noopApply = async (): Promise<void> => {};
+
+describe("r.extendEntityProjection — registration", () => {
+  test("merges apply keys + extraSources into the implicit projection", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("unit", exampleEntity());
+      const setEvent = r.defineEvent("custom-field-set", z.object({ fieldKey: z.string() }));
+      r.extendEntityProjection("unit", {
+        sources: ["field-definition"],
+        apply: { [setEvent.name]: noopApply },
+      });
+    });
+    const registry = createRegistry([feature]);
+    const projection = registry.getAllProjections().get("test:projection:unit-entity");
+    expect(projection).toBeDefined();
+    expect(projection?.apply["test:event:custom-field-set"]).toBe(noopApply);
+    expect(projection?.apply["unit.created"]).toBeDefined();
+    expect(projection?.extraSources).toEqual(["field-definition"]);
+    expect(projection?.source).toBe("unit");
+  });
+
+  test("extension source equal to the entity name is not duplicated into extraSources", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("unit", exampleEntity());
+      const setEvent = r.defineEvent("custom-field-set", z.object({ fieldKey: z.string() }));
+      r.extendEntityProjection("unit", {
+        sources: ["unit"],
+        apply: { [setEvent.name]: noopApply },
+      });
+    });
+    const registry = createRegistry([feature]);
+    const projection = registry.getAllProjections().get("test:projection:unit-entity");
+    expect(projection?.extraSources).toBeUndefined();
+  });
+
+  test("auto-verb of a registered extraSources entity is a valid apply-key", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("unit", exampleEntity());
+      r.entity("field-definition", exampleEntity("field_definitions"));
+      r.extendEntityProjection("unit", {
+        sources: ["field-definition"],
+        apply: { "field-definition.deleted": noopApply },
+      });
+    });
+    const registry = createRegistry([feature]);
+    const projection = registry.getAllProjections().get("test:projection:unit-entity");
+    expect(projection?.apply["field-definition.deleted"]).toBe(noopApply);
+  });
+
+  test("registration order is free: extension before r.entity in the same feature", () => {
+    const feature = defineFeature("test", (r) => {
+      const setEvent = r.defineEvent("custom-field-set", z.object({ fieldKey: z.string() }));
+      r.extendEntityProjection("unit", { apply: { [setEvent.name]: noopApply } });
+      r.entity("unit", exampleEntity());
+    });
+    const registry = createRegistry([feature]);
+    const projection = registry.getAllProjections().get("test:projection:unit-entity");
+    expect(projection?.apply["test:event:custom-field-set"]).toBe(noopApply);
+  });
+
+  test("empty apply throws at registration time", () => {
+    expect(() =>
+      defineFeature("test", (r) => {
+        r.entity("unit", exampleEntity());
+        r.extendEntityProjection("unit", { apply: {} });
+      }),
+    ).toThrow(/no apply handlers/);
+  });
+});
+
+describe("r.extendEntityProjection — registry-build validation", () => {
+  test("unknown entity fails at registry build", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("unit", exampleEntity());
+      const setEvent = r.defineEvent("custom-field-set", z.object({ fieldKey: z.string() }));
+      r.extendEntityProjection("typo-entity", { apply: { [setEvent.name]: noopApply } });
+    });
+    expect(() => createRegistry([feature])).toThrow(/no r\.entity/);
+  });
+
+  test("apply-key collision with a lifecycle apply fails at registry build", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("unit", exampleEntity());
+      r.extendEntityProjection("unit", { apply: { "unit.created": noopApply } });
+    });
+    expect(() => createRegistry([feature])).toThrow(/collides/);
+  });
+
+  test("apply-key collision between two extensions fails at registry build", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("unit", exampleEntity());
+      const setEvent = r.defineEvent("custom-field-set", z.object({ fieldKey: z.string() }));
+      r.extendEntityProjection("unit", { apply: { [setEvent.name]: noopApply } });
+      r.extendEntityProjection("unit", { apply: { [setEvent.name]: noopApply } });
+    });
+    expect(() => createRegistry([feature])).toThrow(/collides/);
+  });
+
+  test("unknown apply-key (neither auto-verb nor domain event) fails at registry build", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("unit", exampleEntity());
+      r.extendEntityProjection("unit", { apply: { "customField.set": noopApply } });
+    });
+    expect(() => createRegistry([feature])).toThrow(/no such event/);
+  });
+});

package/src/engine/__tests__/factories-time.test.ts

@@ -1,17 +1,12 @@
 // Unit-Tests für die neuen Time-Field-Factories
-// (createTimestampField, createTzField, locatedTimestamp).
+// (createTimestampField, createTzField, createLocatedTimestampField).
 //
 // Test-Fokus: korrektes Field-Shape + locatedBy-Marker-Verdrahtung. Die
 // echte TZ-Konvertierung (Wall-Clock ↔ UTC) testen wir später beim
 // DB-Wrapper-Schritt.
 
 import { describe, expect, test } from "bun:test";
-import {
-  createLocatedTimestampField,
-  createTimestampField,
-  createTzField,
-  locatedTimestamp,
-} from "../factories";
+import { createLocatedTimestampField, createTimestampField, createTzField } from "../factories";
 
 describe("createTimestampField", () => {
   test("default-Form ist nicht-required UTC-Instant ohne locatedBy", () => {
@@ -57,65 +52,6 @@ describe("createTzField", () => {
   });
 });
 
-describe("locatedTimestamp(name) Helper", () => {
-  test("erzeugt korrektes Pair aus <name>At + <name>Tz mit locatedBy-Verdrahtung", () => {
-    const fields = locatedTimestamp("pickup");
-    expect(fields).toEqual({
-      pickupAt: { type: "timestamp", locatedBy: "pickupTz" },
-      pickupTz: { type: "tz" },
-    });
-  });
-
-  test("required-Override propagiert auf BEIDE Felder", () => {
-    const fields = locatedTimestamp("delivery", { required: true });
-    expect(fields).toEqual({
-      deliveryAt: { type: "timestamp", locatedBy: "deliveryTz", required: true },
-      deliveryTz: { type: "tz", required: true },
-    });
-  });
-
-  test("access-Override propagiert auf BEIDE Felder (Field-Level Read-Access)", () => {
-    const fields = locatedTimestamp("internal", {
-      access: { read: ["Dispatcher"] },
-    });
-    expect(fields).toEqual({
-      internalAt: {
-        type: "timestamp",
-        locatedBy: "internalTz",
-        access: { read: ["Dispatcher"] },
-      },
-      internalTz: { type: "tz", access: { read: ["Dispatcher"] } },
-    });
-  });
-
-  test("locatedBy-Marker zeigt immer auf das EIGENE Tz-Feld (nicht auf einen anderen Namen)", () => {
-    // Das ist der Kern des Patterns — wenn die zwei Felder nicht
-    // konsistent verdrahtet sind, fliegt der Boot-Validator (kommt in
-    // späterer Iteration). Hier prüfen wir die Helper-Garantie.
-    for (const name of ["a", "x_y", "long_field_name"]) {
-      const fields = locatedTimestamp(name);
-      const at = fields[`${name}At`];
-      if (at?.type !== "timestamp") throw new Error("at field missing");
-      expect(at.locatedBy).toBe(`${name}Tz`);
-    }
-  });
-
-  test("Spread in createEntity-fields Kompositions-tauglich", () => {
-    // Realer Use-Case: pickup + delivery in einer Entity, plus normale Felder.
-    const entityFields = {
-      ...locatedTimestamp("pickup"),
-      ...locatedTimestamp("delivery"),
-      // Kein Konflikt zwischen den beiden Pairs.
-    };
-    expect(Object.keys(entityFields).sort()).toEqual([
-      "deliveryAt",
-      "deliveryTz",
-      "pickupAt",
-      "pickupTz",
-    ]);
-  });
-});
-
 describe("createLocatedTimestampField (Phase A — atomarer Field-Type)", () => {
   test("default-Form ist nicht-required mit type 'locatedTimestamp'", () => {
     expect(createLocatedTimestampField()).toEqual({

package/src/engine/__tests__/feature-crud-shorthand.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, test } from "bun:test";
+import { defineFeature } from "../define-feature";
+import { createEntity, createTextField } from "../factories";
+
+const taskEntity = createEntity({
+  table: "crud_shorthand_tasks",
+  fields: { title: createTextField({ required: true }) },
+  softDelete: true,
+});
+
+describe("r.crud", () => {
+  test("registers the entity + full CRUD handler set, same as registerEntityCrud", () => {
+    const write = { access: { roles: ["Admin"] } } as const;
+    const read = { access: { openToAll: true } } as const;
+
+    const feature = defineFeature("via-crud", (r) => {
+      r.crud("task", taskEntity, { write, read });
+    });
+
+    expect(Object.keys(feature.entities ?? {})).toEqual(["task"]);
+    expect(Object.keys(feature.writeHandlers ?? {}).sort()).toEqual(
+      ["task:create", "task:delete", "task:restore", "task:update"].sort(),
+    );
+    expect(Object.keys(feature.queryHandlers ?? {}).sort()).toEqual(
+      ["task:detail", "task:list"].sort(),
+    );
+  });
+});

package/src/engine/__tests__/feature-manifest.test.ts

@@ -1,6 +1,11 @@
 import { describe, expect, test } from "bun:test";
 import { ConfigScopes } from "../constants";
-import { buildManifestFromRegistry, createRegistry, defineFeature } from "../index";
+import {
+  buildManifestFromRegistry,
+  createRegistry,
+  createSystemConfig,
+  defineFeature,
+} from "../index";
 
 const boolKey = {
   type: "boolean",
@@ -104,4 +109,29 @@ describe("buildManifestFromRegistry — deterministic codepoint sort (#330)", ()
     });
     expect(noHints && "uiHints" in noHints).toBe(false);
   });
+
+  // #1039: backing:"secrets" routes the value through the envelope-encrypted
+  // secrets store — the manifest must report encrypted:true even without an
+  // explicit `encrypted` flag, so generated docs don't mislabel Stripe-style
+  // secret-backed config keys as plaintext. (createConfigKey never emits an
+  // explicit `encrypted: false` — falsy opts.encrypted just omits the field —
+  // so there's no "explicit false wins" case to pin here.)
+  test("encrypted flag — backing:secrets implies encrypted:true without an explicit flag", () => {
+    const feature = defineFeature("demo", (r) => {
+      r.config({
+        keys: {
+          "api-key": createSystemConfig("text", { backing: "secrets" }),
+          "plain-flag": createSystemConfig("boolean", {}),
+        },
+      });
+    });
+    const registry = createRegistry([feature]);
+
+    const manifest = buildManifestFromRegistry(registry, { source: "test" });
+    const demo = manifest.features.find((f) => f.name === "demo");
+    const byKey = (key: string) => demo?.configKeys.find((k) => k.key === key);
+
+    expect(byKey("api-key")?.encrypted).toBe(true);
+    expect(byKey("plain-flag")?.encrypted).toBe(false);
+  });
 });