@cosmicdrift/kumiko-framework 0.365.0 → 0.366.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) => ({
@@ -375,7 +375,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

@@ -68,7 +68,7 @@ bun test
 ```ts
 // webhook-step integration test — drives r.step.webhook.send end-to-end:
 // handler appends step.dispatch-requested in TX, dispatcher subscription
-// drains after COMMIT and calls the (stubbed) fetch, follow-up
+// enqueues a delivery job after COMMIT, the job calls the (stubbed) fetch, follow-up
 // step.dispatched / step.dispatch-failed events land on the same stream.
 
 import { afterAll, beforeAll, beforeEach, describe, expect, mock, test } from "bun:test";
@@ -140,6 +140,7 @@ beforeAll(async () => {
   stack = await setupTestStack({
     features: [createStepDispatcherFeature(), createSecretsFeature(), webhookDemoFeature],
     systemHooks: [],
+    jobs: { consumerLane: "worker" },
     extraContext: ({ db, registry }) => ({
       secrets: createSecretsContext({ db, masterKeyProvider, registry }),
     }),
@@ -184,6 +185,7 @@ describe("webhook-step Sample", () => {
 
     // Drain dispatcher (MSP runs async via runOnce in test mode)
     await stack.eventDispatcher?.runOnce();
+    await stack.drainJobs();
 
     expect(fetchMock).toHaveBeenCalledTimes(1);
     const [calledUrl, init] = fetchMock.mock.calls[0]!;
@@ -202,6 +204,7 @@ describe("webhook-step Sample", () => {
     expect(id).toMatch(/^[0-9a-f-]{36}$/);
 
     await stack.eventDispatcher?.runOnce();
+    await stack.drainJobs();
 
     expect(mailMock).toHaveBeenCalledTimes(1);
     expect(mailMock).toHaveBeenCalledWith(
@@ -231,6 +234,7 @@ describe("webhook-step Sample", () => {
 
     // And the inner handler's webhook fired
     await stack.eventDispatcher?.runOnce();
+    await stack.drainJobs();
     expect(fetchMock).toHaveBeenCalledTimes(1);
   });
 
@@ -243,6 +247,7 @@ describe("webhook-step Sample", () => {
     expect(res.status).toBe(500);
 
     await stack.eventDispatcher?.runOnce();
+    await stack.drainJobs();
 
     expect(fetchMock).not.toHaveBeenCalled();
     const rows = await selectMany(stack.db, incidentTable);
@@ -261,6 +266,7 @@ describe("access-denied — role-restricted handlers", () => {
     );
     expect(error.code).toBe("access_denied");
     await stack.eventDispatcher?.runOnce();
+    await stack.drainJobs();
     expect(mailMock).not.toHaveBeenCalled();
   });
 
@@ -287,6 +293,7 @@ describe("access-denied — role-restricted handlers", () => {
     );
     expect(error.code).toBe("access_denied");
     await stack.eventDispatcher?.runOnce();
+    await stack.drainJobs();
     expect(fetchMock).not.toHaveBeenCalled();
   });
 });
@@ -317,6 +324,7 @@ describe("incident:open-authenticated — tenant-owned webhook auth secret", ()
       adminB,
     );
     await stack.eventDispatcher?.runOnce();
+    await stack.drainJobs();
 
     expect(fetchMock).toHaveBeenCalledTimes(1);
     const [, init] = fetchMock.mock.calls[0]!;
@@ -348,6 +356,7 @@ describe("incident:open-authenticated — tenant-owned webhook auth secret", ()
       adminA,
     );
     await stack.eventDispatcher?.runOnce();
+    await stack.drainJobs();
 
     expect(fetchMock).not.toHaveBeenCalled();
 
@@ -378,6 +387,7 @@ describe("incident:open-authenticated — tenant-owned webhook auth secret", ()
       adminC,
     );
     await stack.eventDispatcher?.runOnce();
+    await stack.drainJobs();
 
     expect(fetchMock).not.toHaveBeenCalled();
     const failedEvents = await selectMany(stack.db, eventsTable, {
@@ -426,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

@@ -594,7 +594,7 @@ Exposes APIs: `sessions.revokeAllForUser`
 
 ## step-dispatcher
 
-Internal system feature that drains deferred Tier-2 side-effects (currently `webhook.send` and `mail.send`) after their originating transaction commits. Listens via `r.multiStreamProjection` on the `kumiko:system:step.dispatch-requested` system event, performs the actual HTTP or mail delivery, then appends `kumiko:system:step.dispatched` or `kumiko:system:step.dispatch-failed` back onto the same stream so the outcome is recorded in the event log without a separate status table. Mount this feature explicitly via `createStepDispatcherFeature()` in your app's feature list alongside any features that use `r.step.webhook.send` or `r.step.mail.send`. Requires the `secrets` feature (`createSecretsFeature()`) to be mounted — `webhook.send` auth resolves per-tenant through it, under `step-dispatcher:webhook-auth.<name>`. Every `webhook.send` request carries `Idempotency-Key: <dispatch stream id>`, stable across redeliveries of the same dispatch request; an explicit `Idempotency-Key` in `headers` takes precedence.
+Internal system feature that drains deferred Tier-2 side-effects (currently `webhook.send` and `mail.send`) after their originating transaction commits. An `r.multiStreamProjection` on the `kumiko:system:step.dispatch-requested` system event enqueues one `step-dispatcher:job:deliver` BullMQ job per dispatch (Redis carries only the stream id and tenant, never the request payload). The job performs the actual HTTP or mail delivery and appends `kumiko:system:step.dispatched` or `kumiko:system:step.dispatch-failed` back onto the same stream, so the outcome is recorded in the event log without a separate status table. Transient failures (network error, timeout, 5xx, 408, 429, any mail adapter failure) are retried 3 times with exponential backoff; the outcome is recorded after the final attempt and the payload key is erased only then. Permanent failures (invalid url, blocked host, other 4xx, unavailable auth secret) are recorded immediately. At most 2 deliveries per tenant run at once (`maxPerTenant` with `onLimit: "defer"`), so a slow receiver of one tenant does not delay other tenants. Requires a job runner (Redis) and a worker consuming the job's default `worker` lane; without a job runner the projection fails loudly. Mount this feature explicitly via `createStepDispatcherFeature()` in your app's feature list alongside any features that use `r.step.webhook.send` or `r.step.mail.send`. Requires the `secrets` feature (`createSecretsFeature()`) to be mounted — `webhook.send` auth resolves per-tenant through it, under `step-dispatcher:webhook-auth.<name>`. Every `webhook.send` request carries `Idempotency-Key: <dispatch stream id>`, stable across retries and redeliveries of the same dispatch request; an explicit `Idempotency-Key` in `headers` takes precedence.
 
 Category: infrastructure
 

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";
@@ -310,6 +311,13 @@ export function buildServer(options) {
     const searchConsumerEnabled = options.eventDispatcher?.systemConsumers?.search ?? true;
     const jobTriggerConsumerEnabled = options.eventDispatcher?.systemConsumers?.jobTrigger ?? true;
     const jobRunnerForTriggers = options.dispatcherOptions?.jobRunner;
+    const mspJobs = jobRunnerForTriggers?.dispatch
+        ? {
+            dispatch: async (jobName, payload, dispatchOptions) => {
+                await jobRunnerForTriggers.dispatch?.(jobName, payload, dispatchOptions);
+            },
+        }
+        : undefined;
     const systemConsumers = [];
     if (sseConsumerEnabled) {
         systemConsumers.push(createSseBroadcastEventConsumer(sseBroker));
@@ -391,6 +399,7 @@ export function buildServer(options) {
                 ...(mspOwner && { callerFeature: mspOwner }),
                 ...(mspFiles && { files: mspFiles }),
                 ...(contextWithObservability.secrets && { secrets: contextWithObservability.secrets }),
+                ...(mspJobs && { jobs: mspJobs }),
                 ...(mspFiles && {
                     derivatives: createDerivativesContext({
                         files: mspFiles,
@@ -665,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) {
@@ -681,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/crypto/in-memory-kms-adapter.js

@@ -1,7 +1,8 @@
 import { randomBytes } from "node:crypto";
 import { KeyAlreadyExistsError, KeyErasedError, KeyNotFoundError, subjectIdToKey, } from "./kms-adapter.js";
 // Non-persistent adapter for tests and dev mode. Erased entries stay as
-// tombstones so the create-after-erase contract holds within a process.
+// tombstones (also for never-keyed subjects) so the create-after-erase
+// contract holds within a process.
 export class InMemoryKmsAdapter {
     capabilities = { mode: "local-key" };
     keys = new Map();
@@ -20,12 +21,8 @@ export class InMemoryKmsAdapter {
         return entry.key;
     }
     async eraseKey(subject) {
-        const entry = this.keys.get(subjectIdToKey(subject));
-        // skip: eraseKey is contractually idempotent — unknown subject is a no-op
-        if (!entry)
-            return;
-        entry.key = null;
-        entry.erased = true;
+        // A never-keyed subject gets a tombstone too, so createKey cannot mint one later.
+        this.keys.set(subjectIdToKey(subject), { key: null, erased: true });
     }
     async health() {
         return { ok: true, latencyMs: 0 };

package/dist/crypto/pg-kms-adapter.js

@@ -107,15 +107,19 @@ export class PgKmsAdapter {
     }
     async eraseKey(subject, ctx) {
         await this.ensureSchema();
-        // Guard on erased_at IS NULL keeps repeat erases from overwriting the
-        // original tombstone audit fields; unknown subjects update zero rows.
+        // Upsert: a never-keyed subject (pre-KMS plaintext) still gets a tombstone,
+        // so a later createKey cannot mint a fresh key and re-encrypt the plaintext.
+        // The erased_at IS NULL guard keeps repeat erases from overwriting the
+        // original tombstone audit fields.
         await this.sql `
-      UPDATE kumiko_subject_keys
+      INSERT INTO kumiko_subject_keys (subject_id, cipher_key, kek_version, erased_at, erased_by, erase_reason)
+      VALUES (${subjectIdToKey(subject)}, NULL, ${this.kekVersion}, now(), ${ctx.userId ?? null}, ${ctx.eraseReason ?? null})
+      ON CONFLICT (subject_id) DO UPDATE
       SET cipher_key = NULL,
           erased_at = now(),
-          erased_by = ${ctx.userId ?? null},
-          erase_reason = ${ctx.eraseReason ?? null}
-      WHERE subject_id = ${subjectIdToKey(subject)} AND erased_at IS NULL`;
+          erased_by = EXCLUDED.erased_by,
+          erase_reason = EXCLUDED.erase_reason
+      WHERE kumiko_subject_keys.erased_at IS NULL`;
     }
     async health() {
         const start = Date.now();

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/event-store-executor-write.js

@@ -169,7 +169,7 @@ export function createWriteVerbs(ctx) {
                     failure: writeFailure(new FrameworkVersionConflict({
                         entityId: id,
                         expectedVersion: currentVersion,
-                        currentVersion: -1,
+                        currentVersion: await versionAfterConflict(runner, String(id), streamTenantFor(user, streamTenantId)),
                     })),
                 };
             }
@@ -181,6 +181,16 @@ export function createWriteVerbs(ctx) {
             throw e;
         }
     }
+    // After a lost append race the stream version read before the append is stale;
+    // report the actual one. -1 when the lookup itself fails.
+    async function versionAfterConflict(runner, aggregateId, tenantId) {
+        try {
+            return await getStreamVersion(runner, aggregateId, tenantId);
+        }
+        catch {
+            return -1;
+        }
+    }
     async function expectedStreamVersion(db, id, streamTenant, expect) {
         const snapshot = await loadExpectSnapshot(db, id, streamTenant, Object.keys(expect));
         const row = snapshot.row;
@@ -298,13 +308,7 @@ export function createWriteVerbs(ctx) {
             }
             catch (e) {
                 if (e instanceof EventStoreVersionConflict) {
-                    let currentVersion = -1;
-                    try {
-                        currentVersion = await getStreamVersion(runner, aggregateId, streamTenantFor(user, streamTenantId));
-                    }
-                    catch {
-                        // Lookup failure — keep the sentinel.
-                    }
+                    const currentVersion = await versionAfterConflict(runner, aggregateId, streamTenantFor(user, streamTenantId));
                     return writeFailure(new FrameworkVersionConflict({
                         entityId: aggregateId,
                         expectedVersion: 0,
@@ -603,7 +607,7 @@ export function createWriteVerbs(ctx) {
                     return writeFailure(new FrameworkVersionConflict({
                         entityId: payload.id,
                         expectedVersion: payload.version ?? 0,
-                        currentVersion,
+                        currentVersion: await versionAfterConflict(runner, String(payload.id), streamTenant),
                     }));
                 }
                 if (e instanceof EventStoreIdempotentAppendConflict) {
@@ -675,7 +679,7 @@ export function createWriteVerbs(ctx) {
                     return writeFailure(new FrameworkVersionConflict({
                         entityId: payload.id,
                         expectedVersion: currentVersion,
-                        currentVersion: -1,
+                        currentVersion: await versionAfterConflict(runner, String(payload.id), streamTenantFor(user, streamTenantId)),
                     }));
                 }
                 if (e instanceof EventStoreIdempotentAppendConflict) {
@@ -760,7 +764,7 @@ export function createWriteVerbs(ctx) {
                     return writeFailure(new FrameworkVersionConflict({
                         entityId: payload.id,
                         expectedVersion: currentVersion,
-                        currentVersion: -1,
+                        currentVersion: await versionAfterConflict(runner, String(payload.id), streamTenantFor(user, streamTenantId)),
                     }));
                 }
                 if (e instanceof EventStoreIdempotentAppendConflict) {
@@ -825,7 +829,7 @@ export function createWriteVerbs(ctx) {
             // table. Rows predating the subject-KMS rollout may still hold plaintext
             // pii, and envelope encryption is not idempotent: decrypt, then
             // re-encrypt as delete does.
-            const previousPlain = await decryptForRead(data);
+            const previousPlain = await decryptForRead(rehydrateCompoundTypes(data, entity));
             const appended = await appendRestoredEvent(runner, user, payload.id, previousPlain, streamTenantId, currentVersion);
             if ("failure" in appended)
                 return appended.failure;

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";