@cosmicdrift/kumiko-framework 0.365.1 → 0.367.0

package/agents/examples/state-machine.md

@@ -567,7 +567,7 @@ import type { InvoiceStatus } from "./reducer";
 export { invoiceEntity } from "./entities/invoice";
 
 export const stateMachineFeature = defineFeature("billing", (r) => {
-  r.entity("invoice", invoiceEntity);
+  r.entity({ name: "invoice", ...invoiceEntity });
 
   // Domain events — one per intent. Names live in events.ts so the reducer
   // and the projection stay in sync. The auto "invoice.created" event from

package/agents/examples/tags-basic.md

@@ -85,7 +85,7 @@ See the [tags feature reference](/en/bundled-features/tags/) for the full set.
 tags             → core bundle: tag + tag-assignment entities,
                    create/assign/remove handlers, list queries
 note-management  → our feature: a plain `note` entity. Declares
-                   r.requires("tags") only so the bundle is mounted —
+                   r.requires({ features: ["tags"] }) only so the bundle is mounted —
                    the note itself is completely tag-agnostic.
 ```
 
@@ -321,9 +321,9 @@ export const noteFeature = defineFeature("note-management", (r) => {
   // tags is non-optional for this recipe: the demo tags notes. The note
   // feature itself stays completely tag-agnostic — it only declares the
   // dependency so the bundle is mounted.
-  r.requires("tags");
+  r.requires({ features: ["tags"] });
 
-  r.entity("note", noteEntity);
+  r.entity({ name: "note", ...noteEntity });
 
   r.writeHandler({
     name: "note:create",

package/agents/examples/tenant-settings.md

@@ -35,7 +35,7 @@ export const invoiceEntity = createEntity({
 });
 
 export const invoiceFeature = defineFeature("invoice", (r) => {
-  r.entity("invoice", invoiceEntity);
+  r.entity({ name: "invoice", ...invoiceEntity });
   r.writeHandler(
     defineCreateWithTenantDefaults("invoice", invoiceEntity, {
       access: { roles: ["Admin"] },
@@ -263,7 +263,7 @@ export const invoiceEntity = createEntity({
 const ACCESS = { roles: ["Admin"] } as const;
 
 export const invoiceFeature = defineFeature("invoice", (r) => {
-  r.entity("invoice", invoiceEntity);
+  r.entity({ name: "invoice", ...invoiceEntity });
   r.writeHandler(
     defineCreateWithTenantDefaults("invoice", invoiceEntity, {
       access: ACCESS,

package/agents/examples/timezones.md

@@ -336,12 +336,12 @@ export const timezonesFeature = defineFeature("timezones", (r) => {
   });
   r.writeHandler(defineEntityDeleteHandler("delivery", deliveryEntity, adminWrite));
 
-  r.queryHandler(
-    "day-window",
-    z.object({
+  r.queryHandler({
+    name: "day-window",
+    schema: z.object({
       zone: z.string().refine(isValidIanaTimeZone, { message: "Invalid IANA timezone" }),
     }),
-    async (query, ctx) => {
+    handler: async (query, ctx) => {
       const { start, end } = ctx.tz.todayRange(query.payload.zone);
       return {
         zone: query.payload.zone,
@@ -350,17 +350,17 @@ export const timezonesFeature = defineFeature("timezones", (r) => {
         end: end.toString(),
       };
     },
-    openRead,
-  );
+    ...openRead,
+  });
 
-  r.queryHandler(
-    "zone-at",
-    z.object({ latitude: z.number(), longitude: z.number() }),
-    async (query, ctx) => {
+  r.queryHandler({
+    name: "zone-at",
+    schema: z.object({ latitude: z.number(), longitude: z.number() }),
+    handler: async (query, ctx) => {
       const zone = await ctx.tz.fromCoordinates(query.payload);
       return { zone };
     },
-    openRead,
-  );
+    ...openRead,
+  });
 });
 ```

package/agents/examples/user-data-rights.md

@@ -19,8 +19,8 @@ forget logic:
 
 ```ts illustration
 defineFeature("notes", (r) => {
-  r.requires("user-data-rights");
-  r.entity("note", noteEntity);
+  r.requires({ features: ["user-data-rights"] });
+  r.entity({ name: "note", ...noteEntity });
 
   r.useExtension(EXT_USER_DATA, "note", {
     export: async (ctx) => ({
@@ -133,6 +133,10 @@ import {
   tenantRetentionOverrideEntity,
 } from "@cosmicdrift/kumiko-bundled-features/data-retention";
 import { createSessionsFeature } from "@cosmicdrift/kumiko-bundled-features/sessions";
+import {
+  tenantMembershipEntity,
+  tenantMembershipsTable,
+} from "@cosmicdrift/kumiko-bundled-features/tenant";
 import {
   createUserFeature,
   USER_STATUS,
@@ -144,7 +148,7 @@ import {
   runForgetCleanup,
   runUserExport,
 } from "@cosmicdrift/kumiko-bundled-features/user-data-rights";
-import { asRawClient, insertOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { insertOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { EXT_USER_DATA } from "@cosmicdrift/kumiko-framework/engine";
 import {
   setupTestStack,
@@ -185,23 +189,7 @@ beforeAll(async () => {
   await unsafeCreateEntityTable(stack.db, noteEntity);
   await unsafeCreateEntityTable(stack.db, tenantRetentionOverrideEntity);
   await unsafeCreateEntityTable(stack.db, tenantComplianceProfileEntity);
-  await asRawClient(stack.db).unsafe(`
-    CREATE TABLE IF NOT EXISTS read_tenant_memberships (
-      id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-      tenant_id UUID NOT NULL,
-      user_id TEXT NOT NULL,
-      version INTEGER NOT NULL DEFAULT 0,
-      inserted_at TIMESTAMPTZ NOT NULL DEFAULT now(),
-      modified_at TIMESTAMPTZ NOT NULL DEFAULT now(),
-      inserted_by_id TEXT,
-      modified_by_id TEXT,
-      is_deleted BOOLEAN NOT NULL DEFAULT false,
-      deleted_at TIMESTAMPTZ,
-      deleted_by_id TEXT,
-      roles TEXT NOT NULL DEFAULT '[]',
-      UNIQUE(user_id, tenant_id)
-    )
-  `);
+  await unsafeCreateEntityTable(stack.db, tenantMembershipEntity);
 });
 
 afterAll(async () => {
@@ -233,14 +221,11 @@ async function seedAlice(opts: { gracePeriodEnd?: Instant; status?: string } = {
     status: opts.status ?? USER_STATUS.Active,
     gracePeriodEnd: opts.gracePeriodEnd ?? null,
   });
-  await asRawClient(stack.db).unsafe(
-    `
-    INSERT INTO read_tenant_memberships (tenant_id, user_id, roles)
-    VALUES ($1, $2, '["Member"]')
-    ON CONFLICT DO NOTHING
-  `,
-    [TENANT_A, ALICE_ID],
-  );
+  await seedRow(stack.db, tenantMembershipsTable, {
+    tenantId: TENANT_A,
+    userId: ALICE_ID,
+    roles: '["Member"]',
+  });
 }
 
 async function seedNote(id: string, title: string): Promise<void> {
@@ -375,7 +360,7 @@ export const noteEntity = createEntity({
 export const notesTable = deriveEntityTableMeta("note", noteEntity, { source: "unmanaged" });
 
 export const notesFeature = defineFeature("notes", (r) => {
-  r.requires("user-data-rights");
+  r.requires({ features: ["user-data-rights"] });
   // store_notes is a direct-write store: the forget hook below `updateMany`/
   // `deleteMany`s rows WITHOUT emitting lifecycle events. r.entity would make
   // it a rebuildable implicit projection whose replay finds zero note events

package/agents/examples/user-profile.md

@@ -187,7 +187,7 @@ export function createAccountFeature(): FeatureDefinition {
         "entry — user-profile registers the `profile` screen itself " +
         "(fw#2312 declarative projectionDetail).",
     );
-    r.requires("user-profile");
+    r.requires({ features: ["user-profile"] });
 
     r.nav({
       id: "profile",

package/agents/examples/webhook-step.md

@@ -436,7 +436,7 @@ const incidentExecutor = createEventStoreExecutor(incidentTable, incidentEntity,
 const INCIDENT_HOOK_URL = "https://hooks.example/incident";
 
 export const webhookDemoFeature = defineFeature("webhook-demo", (r) => {
-  r.entity("incident", incidentEntity);
+  r.entity({ name: "incident", ...incidentEntity });
   r.requires.step("webhook.send");
   r.requires.step("mail.send");
   r.requires.step("callFeature");

package/agents/examples/writeform-section.md

@@ -127,10 +127,16 @@ describe("writeform-section sample — boot-validator catches author mistakes",
   test("a writeForm field without its pseudo-entity translation key fails boot", () => {
     const broken = defineFeature("broken-note-desk", (r) => {
       r.translations({ keys: { "screen:x.title": { en: "X" } } });
-      r.queryHandler("foo:detail", z.object({ id: z.string() }), async () => ({}), {
+      r.queryHandler({
+        name: "foo:detail",
+        schema: z.object({ id: z.string() }),
+        handler: async () => ({}),
         access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
-      r.writeHandler("save", z.object({}), async () => ({ isSuccess: true as const, data: null }), {
+      r.writeHandler({
+        name: "save",
+        schema: z.object({}),
+        handler: async () => ({ isSuccess: true as const, data: null }),
         access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
       r.screen({
@@ -249,19 +255,19 @@ export const noteDeskFeature = defineFeature("note-desk", (r) => {
     access: open.access,
   });
 
-  r.queryHandler(
-    "note:summary",
-    z.object({ id: z.string() }),
-    async (query) => ({ id: query.payload.id, ...NOTE_DETAIL_FIELDS }),
-    open,
-  );
-
-  r.writeHandler(
-    "note:comment",
-    commentPayloadSchema,
-    async () => ({ isSuccess: true as const, data: null }),
-    open,
-  );
+  r.queryHandler({
+    name: "note:summary",
+    schema: z.object({ id: z.string() }),
+    handler: async (query) => ({ id: query.payload.id, ...NOTE_DETAIL_FIELDS }),
+    ...open,
+  });
+
+  r.writeHandler({
+    name: "note:comment",
+    schema: commentPayloadSchema,
+    handler: async () => ({ isSuccess: true as const, data: null }),
+    ...open,
+  });
 
   r.screen({
     id: "note-detail",

package/agents/features.md

@@ -106,7 +106,7 @@ Requires: `delivery`, `secrets`
 
 ## channel-email
 
-Wires an `EmailTransport` (typically `mail-transport-smtp` in production, `createInMemoryTransport()` in tests) into the delivery system as the `email` channel. Requires `delivery`; pass an `EmailChannelOptions` with a `transport` and a `resolveEmail` function that maps a user ID to their email address. Mails render from stored templates (`renderer-mail-html`): a notification routed to this channel needs `template` + `meta` on `r.notification`, otherwise its delivery fails.
+Wires an `EmailTransport` (typically `mail-transport-smtp` in production, `createInMemoryTransport()` in tests) into the delivery system as the `email` channel. Requires `delivery`; pass an `EmailChannelOptions` with a `transport` and a `resolveEmail` function that maps a user ID to their email address. Mails render from stored templates (`renderer-mail-html`): a notification routed to this channel needs `template` + `meta` on `r.notification`, otherwise its delivery fails. Pass `tenantTransport: tenantMailTransport` (from `mail-foundation`) to send each tenant's mail through its own configured provider: a broken provider fails the send, a tenant without one uses the app `transport`. Notifications declared with `unsubscribe: true` get a signed `data.unsubscribeUrl` from delivery, which turns into the `List-Unsubscribe` headers.
 
 Category: notifications
 
@@ -206,7 +206,7 @@ Exposes APIs: `retention.policyFor`
 
 ## delivery
 
-The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). Inside a write handler the delivery runs after the write has committed (the call returns `{ kind: "deferred" }`, a rolled-back write sends nothing); `immediate: true` delivers synchronously and returns `{ kind: "dispatched", deliveries }`. It stores per-user channel preferences in the `notification-preference` entity, opt-outs for no-account recipient addresses in `notification-address-opt-out` (keyed by a blind-index hash, never the plaintext address), logs every attempt to `store_delivery_attempts`, and enforces idempotency and rate-limiting — add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything. Unsubscribe/resubscribe links are served by `createUnsubscribeRoutes({ secret })` mounted via the app's `extraRoutes` at `/api/delivery/unsubscribe` and `/api/delivery/resubscribe`: `GET /unsubscribe?token=` renders a confirmation page (no write), `POST /unsubscribe` performs the opt-out (RFC 8058 one-click, token from the form body or query), `POST /resubscribe` undoes it (JSON `{token}` or form body only, never the query — reachable by a mail-client link prefetcher) — sign links with `signUnsubscribeToken` / `signAddressUnsubscribeToken` using the same secret. `channel-email` sets `List-Unsubscribe` / `List-Unsubscribe-Post` automatically when a message's `data.unsubscribeUrl` points at the unsubscribe route.
+The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). Inside a write handler the delivery runs after the write has committed (the call returns `{ kind: "deferred" }`, a rolled-back write sends nothing); `immediate: true` delivers synchronously and returns `{ kind: "dispatched", deliveries }`. It stores per-user channel preferences in the `notification-preference` entity, opt-outs for no-account recipient addresses in `notification-address-opt-out` (keyed by a blind-index hash, never the plaintext address), logs every attempt to `store_delivery_attempts`, and enforces idempotency and rate-limiting — add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything. Unsubscribe/resubscribe links are served by `createUnsubscribeRoutes({ secret })` mounted via the app's `extraRoutes` at `/api/delivery/unsubscribe` and `/api/delivery/resubscribe`: `GET /unsubscribe?token=` renders a confirmation page (no write), `POST /unsubscribe` performs the opt-out (RFC 8058 one-click, token from the form body or query), `POST /resubscribe` undoes it (JSON `{token}` or form body only, never the query — reachable by a mail-client link prefetcher) — sign links with `signUnsubscribeToken` / `signAddressUnsubscribeToken` using the same secret. `channel-email` sets `List-Unsubscribe` / `List-Unsubscribe-Post` automatically when a message's `data.unsubscribeUrl` points at the unsubscribe route. A notification declared with `unsubscribe: true` gets that link from delivery itself when the service has `unsubscribeLinks` (`runProdApp` option `unsubscribe: { secret }` mounts the routes and wires it; base URL from `auth.publicOrigin`, `auth.mail.baseUrl` or `APP_BASE_URL`): user recipients get a user token, `route` recipients an address token (needs a blind-index key, otherwise no link); a `data.unsubscribeUrl` from the caller wins. `unsubscribe.tenantOrigin: (ctx) => origin | null` points the link at the tenant's own host (subdomain or custom domain, must serve this app's `/api`); null, a throw or a non-https value fall back to the app origin. The token carries the mail's locale, so the confirmation and result pages render in the mail's language. To react to a no-account opt-out (e.g. remove the app's own subscriber row), declare `r.job(name, { trigger: { on: DeliveryHandlers.unsubscribeAddress } }, handler)` on a lane the app consumes: it runs after each committed opt-out, also an idempotent repeat, with `unsubscribeAddressPayloadSchema` (`addressHash`, `notificationType`, `channel`) as payload and the tenant in `ctx.triggeredBy.tenantId`; match the subscriber via `hashUnsubscribeAddress(email)`. Declare `unsubscribeUrl` as an optional template variable if the mail body shows it.
 
 Category: notifications
 
@@ -413,7 +413,7 @@ German UI and mail copy for framework screens. Opt-in; not included by includeBu
 
 ## mail-foundation
 
-Defines the `mailTransport` extension point and a per-tenant `provider` config key that selects which registered transport plugin to use at runtime. Call `createTransportForTenant(ctx, tenantId)` to get an `EmailTransport` ready for sending — use this feature together with at least one `mail-transport-*` feature; use `delivery` + `channel-email` instead when you need the full notification pipeline with delivery attempts and user preferences.
+Defines the `mailTransport` extension point and a per-tenant `provider` config key that selects which registered transport plugin to use at runtime. Call `createTransportForTenant(ctx, tenantId)` to get an `EmailTransport` ready for sending — use this feature together with at least one `mail-transport-*` feature; use `delivery` + `channel-email` instead when you need the full notification pipeline with delivery attempts and user preferences. Pass `tenantMailTransport` as `tenantTransport` to `createChannelEmailFeature` so a tenant with a provider configured sends delivery mails through its own transport and other tenants through the app transport.
 
 Category: notifications
 
@@ -538,7 +538,7 @@ Requires: `template-resolver`
 
 ## renderer-mail-html
 
-A `renderer-foundation` plugin that handles `RenderRequest { kind: "mail" }` and returns `{ subject, html, text, previewText? }` suitable for sending via `channel-email`. The mail template (`kind: "mail"`, document HTML, subject in `meta`) resolves through `template-resolver`'s DB fallback, its body is compiled to Handlebars by template-resolver and rendered with escaping, then placed into an MJML layout (`kind: "mail-layout"`, slug `default` unless `meta.layoutSlug` says otherwise, an in-code structured layout with the tenant branding logo and accent color as last resort) that `mjml()` compiles to email-safe table HTML, with `html-to-text` producing the plain-text alternative. An optional `footer` resolver adds the platform imprint, privacy link and footer text below every structured layout, and an optional `brandSuffix` resolver adds a word after the tenant name in the brand row of the in-code layout. Mail meta `headerChip`, `tone` and `footerNote` add a chip beside the brand, the tone of the top line and chip, and a note above the site and unsubscribe links of the card. Seed an editable system layout with `seedSystemMailLayout(db)`. Requires `renderer-foundation` + `template-resolver`.
+A `renderer-foundation` plugin that handles `RenderRequest { kind: "mail" }` and returns `{ subject, html, text, previewText? }` suitable for sending via `channel-email`. The mail template (`kind: "mail"`, document HTML, subject in `meta`) resolves through `template-resolver`'s DB fallback, its body is compiled to Handlebars by template-resolver and rendered with escaping, then placed into an MJML layout (`kind: "mail-layout"`, slug `default` unless `meta.layoutSlug` says otherwise, an in-code structured layout with the tenant branding logo and accent color as last resort) that `mjml()` compiles to email-safe table HTML, with `html-to-text` producing the plain-text alternative. An optional `footer` resolver adds the platform imprint, privacy link and footer text below every structured layout, an optional `brandSuffix` resolver adds a word after the tenant name in the brand row of the in-code layout, and an optional `siteUrl` resolver supplies the site link of the card when the tenant branding has no site URL (without either, the link is left out). The brand row and `data-resource="logo"` images use the branding logo upload, or the branding logo https address when no file is uploaded. Mail meta `headerChip`, `tone` and `footerNote` add a chip beside the brand, the tone of the top line and chip, and a note above the site and unsubscribe links of the card. Seed an editable system layout with `seedSystemMailLayout(db)`. Requires `renderer-foundation` + `template-resolver`.
 
 Requires: `renderer-foundation`, `template-resolver`
 

package/agents/widgets.md

@@ -147,6 +147,9 @@ Value exports of `@cosmicdrift/kumiko-renderer-web`.
 | `createKumikoApp` |  |
 | `createPublicSurface` |  |
 | `createStaticLocaleResolver` | Default-Resolver für Apps ohne eigene i18n-Schicht. |
+| `downloadFileRef` |  |
+| `fetchFileRefBlob` |  |
+| `fileNameFromContentDisposition` |  |
 | `filterAppSchemaNavsByAllowlist` |  |
 | `filterByAccess` |  |
 | `formatMoney` |  |
@@ -158,6 +161,7 @@ Value exports of `@cosmicdrift/kumiko-renderer-web`.
 | `readLoadedBuild` |  |
 | `reparentAppSchemaNavs` |  |
 | `resolveDefaultId` |  |
+| `saveBlobAsFile` |  |
 | `smoothPath` | Quadratic-durch-Mittelpunkte-Trick: glättet die Zick-Zack-Linie ohne Overshoot (~5 Zeilen statt Catmull-Rom/Bezier-Fit). |
 | `synthesizeActionFormEntity` | Baut eine minimale EntityDefinition aus den Inline-Fields eines ActionForm- oder SecretMint-Screens. |
 | `synthesizeActionFormScreen` | Wandelt ein ActionFormScreenDefinition oder SecretMintScreenDefinition in die EntityEditScreen-Shape die RenderEdit erwartet. |
@@ -178,4 +182,5 @@ Value exports of `@cosmicdrift/kumiko-renderer-web`.
 
 | Name | Description |
 | --- | --- |
+| `FileDownloadFailedError` |  |
 | `FileUploadFailedError` | Carries the server's own `error` message when the upload endpoint sent one. |

package/dist/api/server.js

@@ -6,6 +6,7 @@ import { buildAppSchema } from "../engine/build-app-schema.js";
 import { EXT_FILE_PROVIDER, EXT_PRINCIPAL_STATUS } from "../engine/extension-names.js";
 import { projectAppSchemaForRoles } from "../engine/project-app-schema-for-roles.js";
 import { runsInLane } from "../engine/run-in.js";
+import { resolveDisabledFeatureNames, stripDisabledFeaturesFromAppSchema, } from "../engine/strip-disabled-features-from-app-schema.js";
 import { createAnonymousUser, createSystemUser, isAnonymousSessionUser, } from "../engine/system-user.js";
 import { isFileField, } from "../engine/types/index.js";
 import { assertSeedModeNotInProduction } from "../event-store/seed-clock.js";
@@ -673,15 +674,22 @@ export function buildServer(options) {
     // not the whole app's schema) and cached per role key. Tenant is
     // deliberately NOT part of the key: the projection depends only on
     // roles, and per-tenant caching would grow unboundedly across tenants
-    // that share the same role set.
+    // that share the same role set. What IS part of the key: the sorted set of
+    // features the caller's tenant has switched off (r.toggleable) — few
+    // distinct sets, so the cache stays small. The resolver is read per request
+    // because run{Dev,Prod}App fill it in after the server is built.
     let fullSchema;
     const projectedSchemaCache = new Map();
-    app.get(`/api${Routes.schema}`, (c) => {
+    app.get(`/api${Routes.schema}`, async (c) => {
         const user = getUser(c);
         if (isMissingOrAnonymousUser(user)) {
             return unauthenticatedResponse(c);
         }
-        const roleKey = JSON.stringify([...new Set(user?.roles ?? [])].sort());
+        const effectiveFeatures = options.dispatcherOptions?.effectiveFeatures;
+        const disabledFeatureNames = effectiveFeatures === undefined
+            ? []
+            : await resolveDisabledFeatureNames(options.registry, effectiveFeatures, user.tenantId);
+        const roleKey = JSON.stringify([[...new Set(user?.roles ?? [])].sort(), disabledFeatureNames]);
         let cached = projectedSchemaCache.get(roleKey);
         if (cached === undefined) {
             if (fullSchema === undefined) {
@@ -689,7 +697,7 @@ export function buildServer(options) {
                     searchAdapterMissing: !options.context.searchAdapter,
                 });
             }
-            const projected = projectAppSchemaForRoles(fullSchema, user?.roles ?? []);
+            const projected = projectAppSchemaForRoles(stripDisabledFeaturesFromAppSchema(fullSchema, options.registry, disabledFeatureNames), user?.roles ?? []);
             const json = JSON.stringify(projected);
             cached = { json, etag: computeStrongEtag(json) };
             projectedSchemaCache.set(roleKey, cached);

package/dist/bun-db/query.js

@@ -861,6 +861,21 @@ export async function unsafeReadRetrying(db, sqlText, params) {
         throw lastErr;
     }
 }
+function selectColumnList(info, fields) {
+    if (fields === undefined)
+        return "*";
+    if (fields.length === 0) {
+        throw new Error(`selectMany: fields must not be empty for "${info.name}"`);
+    }
+    return fields
+        .map((field) => {
+        if (!info.hasColumn(field)) {
+            throw new Error(`selectMany: fields entry "${field}" is not a column of "${info.name}"`);
+        }
+        return quoteIdent(info.columnOf(field));
+    })
+        .join(", ");
+}
 // biome-ignore lint/suspicious/noExplicitAny: opt-in default loosens row type for unannotated test fixtures
 export async function selectMany(db, table, where, options) {
     const scoped = tenantDbDelegate(db);
@@ -868,7 +883,7 @@ export async function selectMany(db, table, where, options) {
         return scoped.selectMany(table, where, options);
     }
     const info = extractTableInfo(table);
-    let sqlText = `SELECT * FROM ${quoteIdent(info.name)}`;
+    let sqlText = `SELECT ${selectColumnList(info, options?.fields)} FROM ${quoteIdent(info.name)}`;
     let values = [];
     if (where && Object.keys(where).length > 0) {
         const w = buildWhereClause(info, where, 1);

package/dist/db/entity-table-meta.js

@@ -358,8 +358,8 @@ export const buildEntityTableMeta = deriveEntityTableMeta;
 function sqlExpressionText(where) {
     return isSqlExpression(where) ? where.text : undefined;
 }
-// Validates that a backing Drizzle table (declared via `r.entity(name, def,
-// { table })`) is a SUPERSET of the field-derived meta: every column the
+// Validates that a backing Drizzle table (declared via `r.entity({ name, ...def,
+// backingTable })`) is a SUPERSET of the field-derived meta: every column the
 // entity fields produce must exist on the table with the same pgType +
 // notNull. Ride-along columns/indexes the table adds on top (envelope,
 // uniqueIndex, …) are exactly the point — they pass. A field with no matching
@@ -371,13 +371,13 @@ export function assertBackingTableSuperset(entityName, fieldMeta, tableMeta) {
     for (const fieldCol of fieldMeta.columns) {
         const tableCol = tableCols.get(fieldCol.name);
         if (!tableCol) {
-            throw new Error(`r.entity("${entityName}", …, { table }): the backing table ` +
+            throw new Error(`r.entity({ name: "${entityName}", …, backingTable }): the backing table ` +
                 `"${tableMeta.tableName}" is missing column "${fieldCol.name}" that the ` +
                 "entity field declares. The table must be a superset of the entity's " +
                 "fields — add the column to the table or remove the field.");
         }
         if (tableCol.pgType !== fieldCol.pgType || tableCol.notNull !== fieldCol.notNull) {
-            throw new Error(`r.entity("${entityName}", …, { table }): column "${fieldCol.name}" ` +
+            throw new Error(`r.entity({ name: "${entityName}", …, backingTable }): column "${fieldCol.name}" ` +
                 `disagrees between entity field (${fieldCol.pgType}, ` +
                 `notNull=${fieldCol.notNull}) and backing table "${tableMeta.tableName}" ` +
                 `(${tableCol.pgType}, notNull=${tableCol.notNull}). Align them.`);

package/dist/db/queries/seed-context.js

@@ -1,6 +1,5 @@
 import { unsafeReadRetrying } from "../query.js";
 import { tableExists } from "../schema-inspection.js";
-import { SOFT_DELETE_LIVE_ROW_PREDICATE } from "../table-builder.js";
 export async function selectUserByEmail(db, email) {
     const rows = await unsafeReadRetrying(db, `SELECT id::text AS id, email, tenant_id::text AS tenant_id
      FROM read_users
@@ -27,11 +26,12 @@ export async function selectAllTenants(db) {
 }
 // Column names are fixed fragments; every filter value is a bound parameter.
 // template-resolver is an optional feature — without its table the answer is
-// "no templates", not an error.
+// "no templates", not an error. The template entity has no soft delete, so the
+// table has no is_deleted column to filter on.
 export async function selectTemplateResources(db, filter) {
     if (!(await tableExists(db, "read_template_resources")))
         return [];
-    const conditions = ["tenant_id = $1", SOFT_DELETE_LIVE_ROW_PREDICATE];
+    const conditions = ["tenant_id = $1"];
     const params = [filter.tenantId];
     for (const [column, value] of [
         ["slug", filter.slug],

package/dist/engine/boot-validator/api-ext.js

@@ -25,7 +25,7 @@ export function validateApiExposureMatching(feature, allExposedApis, featureMap)
         }
         const allDeps = [...feature.requires, ...feature.optionalRequires];
         if (!allDeps.includes(providerFeature)) {
-            throw new Error(`[Feature ${feature.name}] r.usesApi("${apiName}") is exposed by "${providerFeature}" but feature is not in requires/optionalRequires. Add r.requires("${providerFeature}").`);
+            throw new Error(`[Feature ${feature.name}] r.usesApi("${apiName}") is exposed by "${providerFeature}" but feature is not in requires/optionalRequires. Add r.requires({ features: ["${providerFeature}"] }).`);
         }
         // Sanity: provider feature actually exists in this app's feature set.
         // Should always be true if allExposedApis was built from `features`,
@@ -48,7 +48,7 @@ export function validateExtensionUsages(feature, extensionProviders) {
         }
         const allDeps = [...feature.requires, ...feature.optionalRequires];
         if (!allDeps.includes(providerFeature)) {
-            throw new Error(`Feature "${feature.name}" uses extension "${usage.extensionName}" but missing requires("${providerFeature}"). Add r.requires("${providerFeature}").`);
+            throw new Error(`Feature "${feature.name}" uses extension "${usage.extensionName}" but missing requires("${providerFeature}"). Add r.requires({ features: ["${providerFeature}"] }).`);
         }
     }
 }

package/dist/engine/boot-validator/config-deps.js

@@ -2,7 +2,7 @@ import { optionsQueryFieldRefs } from "@cosmicdrift/kumiko-types/fields";
 import { isEncryptedAtRest } from "../config-helpers.js";
 // --- Toggleable-dependency warnings ---
 //
-// When feature A declares r.requires("B") and B is toggleable with
+// When feature A declares r.requires({ features: ["B"] }) and B is toggleable with
 // default=false, A is effectively disabled out-of-the-box until someone
 // flips B on globally. That's usually an oversight — the dev either meant
 // optionalRequires, or forgot to ship B with default=true. We warn (not

package/dist/engine/boot-validator/handler-field-references.js

@@ -1,16 +1,9 @@
-import { readHandlerFieldReference } from "../handler-field-references.js";
+import { readHandlerFieldReferences } from "../handler-field-references.js";
 import { parseRefTarget } from "../parse-ref-target.js";
-import { getZodObjectShape } from "./zod-shape.js";
 function validateHandlerGroup(feature, featureMap, handlers, handlerNoun) {
     for (const [handlerName, def] of Object.entries(handlers)) {
-        const shape = getZodObjectShape(def.schema);
-        if (shape === undefined)
-            continue;
-        for (const fieldName of Object.keys(shape)) {
-            const where = `Input field "${fieldName}" of ${handlerNoun} "${handlerName}"`;
-            const reading = readHandlerFieldReference(def.schema, fieldName);
-            if (reading.kind === "none")
-                continue;
+        for (const { path, reading } of readHandlerFieldReferences(def.schema)) {
+            const where = `Input field "${path}" of ${handlerNoun} "${handlerName}"`;
             if (reading.kind === "invalid") {
                 throw new Error(`[Feature ${feature.name}] ${where} has an invalid meta references value ${JSON.stringify(reading.raw)}. ` +
                     `Use "<entity>", "<feature>:<entity>" or { entity, by? }.`);

package/dist/engine/boot-validator/screens.js

@@ -2216,7 +2216,7 @@ function assertRefTargetRegistered(prefix, subject, refTarget, currentFeatureNam
     const targetFeature = featureMap.get(target.featureName);
     if (targetFeature === undefined) {
         throw new Error(`${prefix} ${subject} targets entity "${refTarget}", but feature "${target.featureName}" is not ` +
-            `mounted — mount it and declare r.requires("${target.featureName}").`);
+            `mounted — mount it and declare r.requires({ features: ["${target.featureName}"] }).`);
     }
     if (targetFeature.entities?.[target.entityName] === undefined) {
         throw new Error(`${prefix} ${subject} targets entity "${refTarget}", which does not resolve to a ` +

package/dist/engine/build-app-schema.js

@@ -20,12 +20,9 @@
 //   Translations: verbatim feature.translations (raw r.translations keys,
 //                 unfiltered — see FeatureSchema.translations doc)
 //
-// Feature-Toggles: BISHER NICHT GEFILTERT. Wenn ein Feature über die
-// feature-toggles-bundled-feature global deaktiviert ist, erscheint es
-// trotzdem im AppSchema. Reason: die Toggle-Auflösung lebt im pipeline-
-// dispatcher, nicht in der Registry, und wir haben hier keinen TenantDb-
-// Kontext um sie zu lesen. TODO wenn das ein realer Use-Case wird:
-// `effectiveFeatures` Argument annehmen und über alle iterations filtern.
+// Feature toggles: this schema is tenant-independent and lists every feature.
+// The schema route strips features the caller's tenant has switched off
+// (r.toggleable) via stripDisabledFeaturesFromAppSchema.
 import { ZodObject } from "zod";
 import { collectUrlPrefillFieldsByScreenQn } from "./boot-validator/url-prefill-fields.js";
 import { buildConfigFeatureSchema, SETTINGS_HUB_FEATURE, } from "./build-config-feature-schema.js";

package/dist/engine/define-feature.js

@@ -2,7 +2,7 @@ import { createInitialFeatureBuilderState } from "./feature-builder-state.js";
 import { buildConfigEventsJobsMethods } from "./feature-config-events-jobs.js";
 import { buildEntityHandlerMethods } from "./feature-entity-handlers.js";
 import { buildUiExtensionsMethods } from "./feature-ui-extensions.js";
-import { unwrapArrayForm } from "./object-form.js";
+import { isObjectArgument, throwPositionalFormRemoved, unwrapArrayForm } from "./object-form.js";
 // `TExports` lets the setup callback hand back a typed object that
 // downstream features can import (e.g. `tenantFeature.exports.config`). The
 // runtime always packs whatever setup returns into `featureDef.exports` —
@@ -15,10 +15,8 @@ import { unwrapArrayForm } from "./object-form.js";
 // for `ctx.appendEvent({ type: eventDef.name, ... })` lights up. Apps
 // that don't care can keep the default-string and use the wrapper-based
 // strict-mode (string-literal types per call-site) like before.
-// requires/optionalRequires accept either variadic strings (hand-written
-// call sites) or a single `{ features }` object (the feature-ast renderer's
-// canonical Object-Form for Designer/AI-generated code) — see the matching
-// overloads on RequiresApi / FeatureRegistrar['optionalRequires'].
+// optionalRequires accepts either variadic strings or a single `{ features }` object; requires
+// takes only the object (see RequiresApi).
 function resolveFeatureNamesArgs(args) {
     return unwrapArrayForm(args, "features");
 }
@@ -50,6 +48,8 @@ export function defineFeature(name, setup, settings) {
         },
         requires: (() => {
             const fn = (...args) => {
+                if (!args.every(isObjectArgument))
+                    throwPositionalFormRemoved(name, "requires");
                 state.requires.push(...resolveFeatureNamesArgs(args));
             };
             fn.projection = (tableName) => {

package/dist/engine/entity-handlers.d.ts

@@ -63,5 +63,5 @@ export declare function defineProjectionQueryHandler(name: string, projectionQua
     };
     escapeHatch?: EscapeHatchDeclaration;
 }): QueryHandlerDef;
-/** Register standard entity CRUD handlers in one call. Access stays explicit — no openToAll default. */
-export declare function registerEntityCrud(r: EntityCrudRegistrar, entityName: string, entity: EntityDefinition, options?: RegisterEntityCrudOptions): void;
+/** Backs `r.crud`: registers the standard entity CRUD handlers. Access stays explicit — no openToAll default. */
+export declare function registerCrudHandlers(r: EntityCrudRegistrar, entityName: string, entity: EntityDefinition, options?: RegisterEntityCrudOptions): void;

package/dist/engine/entity-handlers.js

@@ -551,21 +551,21 @@ function defaultCrudVerbs(entity) {
         detail: true,
     };
 }
-/** Register standard entity CRUD handlers in one call. Access stays explicit — no openToAll default. */
-export function registerEntityCrud(r, entityName, entity, options) {
+/** Backs `r.crud`: registers the standard entity CRUD handlers. Access stays explicit — no openToAll default. */
+export function registerCrudHandlers(r, entityName, entity, options) {
     const verbs = { ...defaultCrudVerbs(entity), ...options?.verbs };
     if (verbs.restore && entity.softDelete !== true) {
         throw new Error(`restore requested but entity "${entityName}" has no softDelete: true`);
     }
     if (options?.registerEntity !== false) {
-        r.entity(entityName, entity);
+        r.entity({ name: entityName, ...entity });
     }
     const writeOpts = options?.write;
     const readOpts = options?.read;
     const requireAccess = (verb, access) => {
         if (!access) {
-            throw new Error(`registerEntityCrud("${entityName}", verb: "${verb}"): no access rule resolved. ` +
-                `Set write.access/read.access on registerEntityCrud's options, or verbAccess.${verb}.`);
+            throw new Error(`r.crud("${entityName}", …): no access rule resolved for verb "${verb}". ` +
+                `Set write.access/read.access in r.crud's options, or verbAccess.${verb}.`);
         }
         return access;
     };