@cosmicdrift/kumiko-framework 0.326.1 → 0.328.0

package/src/db/__tests__/apply-entity-event-removed-column.integration.test.ts

@@ -0,0 +1,109 @@
+// A historical `<entity>.updated` event may carry a field that has since been
+// removed from the entity and its table. Replaying it during a projection
+// rebuild must drop the unknown column instead of failing the whole rebuild.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { createEntity, createTextField, defineFeature } from "../../engine";
+import { append } from "../../event-store";
+import { createProjectionStateTable, rebuildProjection } from "../../pipeline";
+import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
+import { createEventStoreExecutor } from "../event-store-executor";
+import { asRawClient } from "../query";
+import { buildEntityTable } from "../table-builder";
+import { createTenantDb, type TenantDb } from "../tenant-db";
+
+const noteEntity = createEntity({
+  table: "read_removed_column_notes",
+  fields: {
+    title: createTextField({ personal: false, reason: "test_fixture", required: true }),
+  },
+});
+const noteTable = buildEntityTable("removed-note", noteEntity);
+
+const feature = defineFeature("removedcol", (r) => {
+  r.entity("removed-note", noteEntity);
+});
+
+const admin = TestUsers.admin;
+const PROJECTION = "removedcol:projection:removed-note-entity";
+const AGGREGATE_ID = "00000000-0000-4000-8000-0000000000aa";
+
+let stack: TestStack;
+let tdb: TenantDb;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [feature] });
+  await unsafeCreateEntityTable(stack.db, noteEntity, "removed-note");
+  await createProjectionStateTable(stack.db);
+  tdb = createTenantDb(stack.db, admin.tenantId);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe(
+    `TRUNCATE kumiko_events, read_removed_column_notes, kumiko_projections RESTART IDENTITY CASCADE`,
+  );
+});
+
+async function appendHistoricalEvents(): Promise<void> {
+  await append(stack.db, {
+    aggregateId: AGGREGATE_ID,
+    aggregateType: "removed-note",
+    tenantId: admin.tenantId,
+    expectedVersion: 0,
+    type: "removed-note.created",
+    payload: { title: "old", legacyNote: "legacy" },
+    metadata: { userId: admin.id },
+  });
+  await append(stack.db, {
+    aggregateId: AGGREGATE_ID,
+    aggregateType: "removed-note",
+    tenantId: admin.tenantId,
+    expectedVersion: 1,
+    type: "removed-note.updated",
+    payload: {
+      changes: { title: "new", legacyNote: "gone" },
+      previous: { title: "old", legacyNote: "legacy" },
+    },
+    metadata: { userId: admin.id },
+  });
+}
+
+async function readRow(): Promise<{ title: string; version: number } | undefined> {
+  const rows = (await asRawClient(stack.db).unsafe(
+    `SELECT title, version FROM read_removed_column_notes WHERE id = $1::uuid`,
+    [AGGREGATE_ID],
+  )) as ReadonlyArray<{ title: string; version: number }>;
+  return rows[0];
+}
+
+describe("applyEntityEvent — event field no longer on the entity", () => {
+  test("rebuild replays created + updated events that carry a removed field", async () => {
+    await appendHistoricalEvents();
+
+    const result = await rebuildProjection(PROJECTION, { db: stack.db, registry: stack.registry });
+
+    expect(result.eventsProcessed).toBe(2);
+    expect(await readRow()).toMatchObject({ title: "new", version: 2 });
+  });
+
+  test("live update after the rebuild still works", async () => {
+    await appendHistoricalEvents();
+    await rebuildProjection(PROJECTION, { db: stack.db, registry: stack.registry });
+
+    const executor = createEventStoreExecutor(noteTable, noteEntity, {
+      entityName: "removed-note",
+    });
+    const updated = await executor.update(
+      { id: AGGREGATE_ID, version: 2, changes: { title: "live" } },
+      admin,
+      tdb,
+    );
+
+    expect(updated.isSuccess).toBe(true);
+    expect(await readRow()).toMatchObject({ title: "live", version: 3 });
+  });
+});

package/src/db/queries/backfill-pii.ts

@@ -37,8 +37,8 @@
 //   Both stages are opt-in and off by default; without them an unresolvable
 //   subject still fails loud into `failures`, as before.
 //
-// Snapshots of touched aggregates are dropped (they may cache plaintext);
-// the next snapshotting load recreates them. AFTER a run, rebuild the
+// Snapshots of touched aggregates are dropped per batch (they may cache
+// plaintext); the next snapshotting load recreates them. AFTER a run, rebuild the
 // affected projections — applyEntityEvent materializes ciphertext AND the
 // blind-index columns, which keeps equality lookups (login by email) alive.
 
@@ -50,6 +50,7 @@ import {
   KeyErasedError,
   KeyNotFoundError,
   type KmsContext,
+  type LocalKeyKmsAdapter,
   type SubjectId,
 } from "../../crypto/kms-adapter";
 import {
@@ -67,7 +68,7 @@ import {
 import type { EntityDefinition, Registry, TenantId } from "../../engine/types";
 import type { DbRunner } from "../connection";
 import { resolveTableName } from "../entity-table-meta";
-import { isUndefinedTable } from "../pg-error";
+import { tableExists } from "../schema-inspection";
 import { toSnakeCase } from "../table-builder";
 
 const LIFECYCLE_VERBS = ["created", "updated", "deleted", "restored", "forgotten"] as const;
@@ -92,6 +93,19 @@ export type PiiBackfillResult = {
   readonly failures: readonly PiiBackfillFailure[];
 };
 
+export type PiiBackfillScanCache = {
+  forgottenAggregates?: ReadonlySet<string>;
+};
+
+export type PiiBackfillBatchResult = PiiBackfillResult & {
+  // Last scanned event id; null when the batch was empty.
+  readonly lastEventId: string | null;
+  readonly scannedAll: boolean;
+  readonly firstFailedEventId: string | null;
+  readonly touchedAggregateTypes: readonly string[];
+  readonly touchedEventTypes: readonly string[];
+};
+
 export type PiiBackfillOptions = {
   readonly batchSize?: number;
   // Scan + count only, write nothing — including the subject KMS: outcomes
@@ -105,6 +119,12 @@ export type PiiBackfillOptions = {
   readonly eraseUnresolvableSubjects?: boolean;
 };
 
+export type PiiBackfillBatchOptions = PiiBackfillOptions & {
+  readonly afterEventId?: bigint | string;
+  // Caller-held so the forgotten-set full scan is shared across batches.
+  readonly scanCache?: PiiBackfillScanCache;
+};
+
 type EventRow = {
   readonly id: bigint | string;
   readonly aggregate_id: string;
@@ -116,36 +136,94 @@ type EventRow = {
 
 type FieldOutcome = "unchanged" | "encrypted" | "erased";
 
-export async function backfillEventPiiEncryption(
-  db: DbRunner,
-  registry: Registry,
-  options: PiiBackfillOptions = {},
-): Promise<PiiBackfillResult> {
+type PiiTargets = {
+  readonly entityTargets: ReadonlyMap<
+    string,
+    { readonly entity: EntityDefinition; readonly piiFields: readonly string[] }
+  >;
+  readonly eventCatalog: ReturnType<typeof configuredEventPiiCatalog>;
+};
+
+function collectPiiTargets(registry: Registry): PiiTargets {
+  const entityTargets = new Map<
+    string,
+    { readonly entity: EntityDefinition; readonly piiFields: readonly string[] }
+  >();
+  for (const [name, entity] of registry.getAllEntities()) {
+    const piiFields = collectPiiSubjectFields(entity);
+    if (piiFields.length > 0) entityTargets.set(name, { entity, piiFields });
+  }
+  return { entityTargets, eventCatalog: configuredEventPiiCatalog() };
+}
+
+function requireLocalKeySubjectKms(caller: string): LocalKeyKmsAdapter {
   const kms = configuredPiiSubjectKms();
   if (!kms) {
     throw new Error(
-      "backfillEventPiiEncryption requires a configured subject KMS — boot with " +
+      `${caller} requires a configured subject KMS — boot with ` +
         "runProdApp({ kms }) / configurePiiSubjectKms(adapter) before running the backfill.",
     );
   }
   if (!isLocalKeyKmsAdapter(kms)) {
-    throw new Error("backfillEventPiiEncryption requires a local-key KMS adapter");
+    throw new Error(`${caller} requires a local-key KMS adapter`);
   }
-  const subjectKms = kms;
+  return kms;
+}
+
+export async function backfillEventPiiEncryption(
+  db: DbRunner,
+  registry: Registry,
+  options: PiiBackfillOptions = {},
+): Promise<PiiBackfillResult> {
+  requireLocalKeySubjectKms("backfillEventPiiEncryption");
+  const total = {
+    scannedEvents: 0,
+    updatedEvents: 0,
+    encryptedFields: 0,
+    erasedFields: 0,
+    ownerFromProjection: 0,
+    erasedUnresolvable: 0,
+    deletedSnapshots: 0,
+  };
+  const failures: PiiBackfillFailure[] = [];
+  const scanCache: PiiBackfillScanCache = {};
+  let afterEventId: string = "0";
+
+  for (;;) {
+    const batch = await backfillEventPiiEncryptionBatch(db, registry, {
+      ...options,
+      afterEventId,
+      scanCache,
+    });
+    total.scannedEvents += batch.scannedEvents;
+    total.updatedEvents += batch.updatedEvents;
+    total.encryptedFields += batch.encryptedFields;
+    total.erasedFields += batch.erasedFields;
+    total.ownerFromProjection += batch.ownerFromProjection;
+    total.erasedUnresolvable += batch.erasedUnresolvable;
+    total.deletedSnapshots += batch.deletedSnapshots;
+    failures.push(...batch.failures);
+    if (batch.lastEventId === null || batch.scannedAll) break;
+    afterEventId = batch.lastEventId;
+  }
+  return { ...total, failures };
+}
+
+// Processes exactly one batch. Snapshots of the batch's touched aggregates are
+// dropped inside the same call so an abort between batches never leaves a
+// snapshot that caches plaintext for an already-encrypted stream.
+export async function backfillEventPiiEncryptionBatch(
+  db: DbRunner,
+  registry: Registry,
+  options: PiiBackfillBatchOptions = {},
+): Promise<PiiBackfillBatchResult> {
+  const subjectKms = requireLocalKeySubjectKms("backfillEventPiiEncryptionBatch");
   const batchSize = options.batchSize ?? 500;
   const raw = asRawClient(db);
   const kmsCtx: KmsContext = { requestId: "pii-backfill" };
+  const scanCache = options.scanCache ?? {};
 
-  const entityTargets = new Map<
-    string,
-    { readonly entity: EntityDefinition; readonly piiFields: readonly string[] }
-  >();
-  for (const [name, entity] of registry.getAllEntities()) {
-    const piiFields = collectPiiSubjectFields(entity);
-    if (piiFields.length > 0) entityTargets.set(name, { entity, piiFields });
-  }
-  const eventCatalog = configuredEventPiiCatalog();
-
+  const { entityTargets, eventCatalog } = collectPiiTargets(registry);
   const aggregateTypes = [...entityTargets.keys()];
   const catalogTypes = [...eventCatalog.keys()];
   const result = {
@@ -158,65 +236,65 @@ export async function backfillEventPiiEncryption(
     deletedSnapshots: 0,
     failures: [] as PiiBackfillFailure[],
   };
-  if (aggregateTypes.length === 0 && catalogTypes.length === 0) return result;
-
-  // Pre-KMS forgets left no key tombstone — the *.forgotten event on the
-  // stream is the only durable marker. Collect once; aggregate_id doubles
-  // as the user id for user-subject lookups.
-  const forgottenRows = (await raw.unsafe(
-    `SELECT DISTINCT "aggregate_id" FROM "kumiko_events" WHERE "type" LIKE '%.forgotten'`,
-  )) as ReadonlyArray<{ aggregate_id: string }>;
-  const forgottenAggregates = new Set(forgottenRows.map((r) => r.aggregate_id));
-
+  const emptyBatch = (): PiiBackfillBatchResult => ({
+    ...result,
+    lastEventId: null,
+    scannedAll: true,
+    firstFailedEventId: null,
+    touchedAggregateTypes: [],
+    touchedEventTypes: [],
+  });
+  if (aggregateTypes.length === 0 && catalogTypes.length === 0) return emptyBatch();
+
+  const rows = (await raw.unsafe(
+    `SELECT "id", "aggregate_id", "aggregate_type", "tenant_id", "type", "payload"
+       FROM "kumiko_events"
+      WHERE ("aggregate_type" = ANY($1::text[]) OR "type" = ANY($2::text[])) AND "id" > $3::bigint
+      ORDER BY "id" ASC
+      LIMIT $4`,
+    [aggregateTypes, catalogTypes, String(options.afterEventId ?? 0), batchSize],
+  )) as ReadonlyArray<EventRow>;
+  const last = rows[rows.length - 1];
+  if (last === undefined) return emptyBatch();
+
+  const projectionOwnersByType = await loadProjectionOwners(rows);
   const touchedAggregates = new Set<string>();
-  let cursor = "0";
-
-  for (;;) {
-    const rows = (await raw.unsafe(
-      `SELECT "id", "aggregate_id", "aggregate_type", "tenant_id", "type", "payload"
-         FROM "kumiko_events"
-        WHERE ("aggregate_type" = ANY($1::text[]) OR "type" = ANY($2::text[])) AND "id" > $3::bigint
-        ORDER BY "id" ASC
-        LIMIT $4`,
-      [aggregateTypes, catalogTypes, cursor, batchSize],
-    )) as ReadonlyArray<EventRow>;
-    if (rows.length === 0) break;
-
-    const projectionOwnersByType = await loadProjectionOwners(rows);
-
-    for (const row of rows) {
-      result.scannedEvents++;
-      try {
-        const outcome = await transformEvent(row, projectionOwnersByType.get(row.aggregate_type));
-        if (outcome === null) continue;
-        result.encryptedFields += outcome.encrypted;
-        result.erasedFields += outcome.erased;
-        result.ownerFromProjection += outcome.ownerFromProjection;
-        result.erasedUnresolvable += outcome.erasedUnresolvable;
-        if (!options.dryRun) {
-          await raw.unsafe(`UPDATE "kumiko_events" SET "payload" = $1::jsonb WHERE "id" = $2`, [
-            outcome.payload,
-            row.id,
-          ]);
-        }
-        result.updatedEvents++;
-        touchedAggregates.add(row.aggregate_id);
-      } catch (e) {
-        const reason = e instanceof Error ? e.message : String(e);
-        result.failures.push({
-          eventId: String(row.id),
-          reason:
-            e instanceof SubjectResolutionError
-              ? `${reason} (retry with { resolveOwnerFromProjection: true } to resolve the owner ` +
-                "from the entity's projection table, and/or { eraseUnresolvableSubjects: true } to " +
-                "erase fields whose subject stays unresolvable)"
-              : reason,
-        });
+  const touchedAggregateTypes = new Set<string>();
+  const touchedEventTypes = new Set<string>();
+  let firstFailedEventId: string | null = null;
+
+  for (const row of rows) {
+    result.scannedEvents++;
+    try {
+      const outcome = await transformEvent(row, projectionOwnersByType.get(row.aggregate_type));
+      if (outcome === null) continue;
+      result.encryptedFields += outcome.encrypted;
+      result.erasedFields += outcome.erased;
+      result.ownerFromProjection += outcome.ownerFromProjection;
+      result.erasedUnresolvable += outcome.erasedUnresolvable;
+      if (!options.dryRun) {
+        await raw.unsafe(`UPDATE "kumiko_events" SET "payload" = $1::jsonb WHERE "id" = $2`, [
+          outcome.payload,
+          row.id,
+        ]);
       }
+      result.updatedEvents++;
+      touchedAggregates.add(row.aggregate_id);
+      touchedAggregateTypes.add(row.aggregate_type);
+      touchedEventTypes.add(row.type);
+    } catch (e) {
+      const reason = e instanceof Error ? e.message : String(e);
+      firstFailedEventId ??= String(row.id);
+      result.failures.push({
+        eventId: String(row.id),
+        reason:
+          e instanceof SubjectResolutionError
+            ? `${reason} (retry with { resolveOwnerFromProjection: true } to resolve the owner ` +
+              "from the entity's projection table, and/or { eraseUnresolvableSubjects: true } to " +
+              "erase fields whose subject stays unresolvable)"
+            : reason,
+      });
     }
-    const last = rows[rows.length - 1];
-    if (last === undefined) break;
-    cursor = String(last.id);
   }
 
   // Snapshots may cache the plaintext state of touched aggregates.
@@ -228,7 +306,28 @@ export async function backfillEventPiiEncryption(
     result.deletedSnapshots = deleted.length;
   }
 
-  return result;
+  return {
+    ...result,
+    lastEventId: String(last.id),
+    scannedAll: rows.length < batchSize,
+    firstFailedEventId,
+    touchedAggregateTypes: [...touchedAggregateTypes],
+    touchedEventTypes: [...touchedEventTypes],
+  };
+
+  // Full-scan of the store — only paid once a plaintext field actually needs
+  // encrypting, so a catch-up run over already-encrypted events never runs it.
+  async function loadForgottenAggregates(): Promise<ReadonlySet<string>> {
+    if (scanCache.forgottenAggregates) return scanCache.forgottenAggregates;
+    // Pre-KMS forgets left no key tombstone — the *.forgotten event on the
+    // stream is the only durable marker. aggregate_id doubles as the user id
+    // for user-subject lookups.
+    const forgottenRows = (await raw.unsafe(
+      `SELECT DISTINCT "aggregate_id" FROM "kumiko_events" WHERE "type" LIKE '%.forgotten'`,
+    )) as ReadonlyArray<{ aggregate_id: string }>;
+    scanCache.forgottenAggregates = new Set(forgottenRows.map((r) => r.aggregate_id));
+    return scanCache.forgottenAggregates;
+  }
 
   async function loadProjectionOwners(
     rows: readonly EventRow[],
@@ -249,7 +348,10 @@ export async function backfillEventPiiEncryption(
       if (!target) continue;
       const tableName = resolveTableName(aggregateType, target.entity, undefined);
       const ownersById = new Map<string, Record<string, unknown>>();
-      try {
+      // Existence check instead of catching undefined_table: a caught SQL error
+      // aborts the surrounding transaction (25P02). Entity never mounted/rebuilt
+      // → stage 3 still gets a chance; this batch just contributes no owners.
+      if (await tableExists(db, `public.${tableName}`)) {
         const projectionRows = (await raw.unsafe(
           `SELECT * FROM ${quoteIdent(tableName)} WHERE "id" = ANY($1::uuid[])`,
           [[...ids]],
@@ -260,10 +362,6 @@ export async function backfillEventPiiEncryption(
             ownersById.set(id, projectionRowToCamel(target.entity, projectionRow));
           }
         }
-      } catch (e) {
-        // Entity never mounted/rebuilt (no projection table yet) — stage 3
-        // still gets a chance; this batch just contributes no owners.
-        if (!isUndefinedTable(e)) throw e;
       }
       byType.set(aggregateType, ownersById);
     }
@@ -367,7 +465,7 @@ export async function backfillEventPiiEncryption(
       if (value === null || value === undefined) return "unchanged";
       if (typeof value !== "string") return "unchanged";
       if (isPiiCiphertext(value) || value === PII_ERASED_SENTINEL) return "unchanged";
-      if (isForgottenSubject(subject, row.aggregate_id)) {
+      if (await isForgottenSubject(subject, row.aggregate_id)) {
         section[field] = PII_ERASED_SENTINEL;
         return "erased";
       }
@@ -400,7 +498,8 @@ export async function backfillEventPiiEncryption(
     }
   }
 
-  function isForgottenSubject(subject: SubjectId, aggregateId: string): boolean {
+  async function isForgottenSubject(subject: SubjectId, aggregateId: string): Promise<boolean> {
+    const forgottenAggregates = await loadForgottenAggregates();
     if (forgottenAggregates.has(aggregateId)) return true;
     return subject.kind === "user" && forgottenAggregates.has(subject.userId);
   }

package/src/db/queries/pii-backfill-state.ts

@@ -0,0 +1,33 @@
+import type { AnyDb } from "../query";
+import { asRawClient } from "../query";
+
+export type PiiBackfillStateRow = { readonly cursor: string; readonly completed: boolean };
+
+export async function readPiiBackfillState(
+  db: AnyDb,
+  fingerprint: string,
+): Promise<PiiBackfillStateRow | null> {
+  const rows = (await asRawClient(db).unsafe(
+    `SELECT "cursor_event_id"::text AS "cursor", "completed_at" IS NOT NULL AS "completed"
+       FROM "kumiko_pii_backfill_state" WHERE "fingerprint" = $1`,
+    [fingerprint],
+  )) as ReadonlyArray<PiiBackfillStateRow>;
+  return rows[0] ?? null;
+}
+
+export async function persistPiiBackfillState(
+  db: AnyDb,
+  fingerprint: string,
+  cursor: bigint,
+  markCompleted: boolean,
+): Promise<void> {
+  await asRawClient(db).unsafe(
+    `INSERT INTO "kumiko_pii_backfill_state" ("fingerprint", "cursor_event_id", "completed_at", "updated_at")
+     VALUES ($1, $2::bigint, CASE WHEN $3::boolean THEN now() ELSE NULL END, now())
+     ON CONFLICT ("fingerprint") DO UPDATE SET
+       "cursor_event_id" = GREATEST("kumiko_pii_backfill_state"."cursor_event_id", EXCLUDED."cursor_event_id"),
+       "completed_at" = COALESCE("kumiko_pii_backfill_state"."completed_at", EXCLUDED."completed_at"),
+       "updated_at" = now()`,
+    [fingerprint, cursor.toString(), markCompleted],
+  );
+}

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

@@ -392,6 +392,32 @@ describe("buildAppSchema", () => {
     expect(fields["categories"]?.["maxRows"]).toBeUndefined();
   });
 
+  test("Select: optionTones überleben die Projection", () => {
+    const entity = {
+      fields: {
+        status: {
+          type: "select",
+          options: ["open", "closed"],
+          optionTones: { closed: "bad" },
+        },
+        area: { type: "select", options: ["a", "b"] },
+      },
+    } as unknown as EntityDefinition;
+
+    const f = defineFeature("ent", (r) => {
+      r.entity("thing", entity);
+    });
+    const app = buildAppSchema(createRegistry([f]));
+    const fields = (
+      app.features[0]!.entities["thing"] as unknown as {
+        fields: Record<string, Record<string, unknown>>;
+      }
+    ).fields;
+
+    expect(fields["status"]?.["optionTones"]).toEqual({ closed: "bad" });
+    expect(fields["area"]?.["optionTones"]).toBeUndefined();
+  });
+
   test("MultiSelectFieldDef: alle Keys sind in projectField bewusst eingeordnet", () => {
     // Bounded completeness check, scoped to MultiSelectFieldDef's own key set
     // (packages/types/src/fields.ts) — NOT a general FieldDefinition lockstep.

package/src/engine/__tests__/describe-workflow-step-error.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, test } from "bun:test";
+import { describeWorkflowStepError } from "../steps/describe-workflow-step-error";
+
+describe("describeWorkflowStepError", () => {
+  test("uses the error class name and never the message", () => {
+    const text = describeWorkflowStepError(new TypeError("send to jane.doe@example.com failed"));
+    expect(text).toBe("workflow step failed (TypeError)");
+    expect(text).not.toContain("jane.doe@example.com");
+  });
+
+  test("non-Error throwables are described as unknown and not stringified", () => {
+    expect(describeWorkflowStepError("jane.doe@example.com")).toBe(
+      "workflow step failed (unknown error)",
+    );
+    expect(describeWorkflowStepError(undefined)).toBe("workflow step failed (unknown error)");
+  });
+});

package/src/engine/__tests__/steps-mail-send.test.ts

@@ -84,8 +84,9 @@ describe("mail.send run", () => {
     expect(eventArg.aggregateType).toBe(STEP_DISPATCH_AGGREGATE_TYPE);
     expect(eventArg.type).toBe(STEP_DISPATCH_REQUESTED_TYPE);
     expect(eventArg.payload.stepKind).toBe("mail.send");
-    expect(eventArg.payload.spec).toMatchObject({
-      to: "user@example.com",
+    expect(eventArg.payload).toEqual({
+      stepKind: "mail.send",
+      to: JSON.stringify("user@example.com"),
       subject: "Test",
       body: "Body text",
     });
@@ -119,10 +120,10 @@ describe("mail.send run", () => {
     );
 
     const eventArg = mockUnsafeAppendEvent.mock.calls[0]![0];
-    expect(eventArg.payload.spec.from).toBe("system@example.com");
+    expect(eventArg.payload.from).toBe("system@example.com");
   });
 
-  it("omits from from the spec when not provided", async () => {
+  it("omits from from the payload when not provided", async () => {
     const stepDef = getStep("mail.send");
 
     await stepDef!.run(
@@ -131,6 +132,6 @@ describe("mail.send run", () => {
     );
 
     const eventArg = mockUnsafeAppendEvent.mock.calls[0]![0];
-    expect(eventArg.payload.spec.from).toBeUndefined();
+    expect(eventArg.payload.from).toBeUndefined();
   });
 });

package/src/engine/__tests__/steps-webhook-send.test.ts

@@ -73,8 +73,9 @@ describe("webhook.send run", () => {
     expect(eventArg.aggregateType).toBe(STEP_DISPATCH_AGGREGATE_TYPE);
     expect(eventArg.type).toBe(STEP_DISPATCH_REQUESTED_TYPE);
     expect(eventArg.payload.stepKind).toBe("webhook.send");
-    expect(eventArg.payload.spec.url).toBe("https://hooks.example/test");
-    expect(eventArg.payload.spec.body).toEqual({ event: "incident-opened", id: "abc" });
+    expect(eventArg.payload.url).toBe("https://hooks.example/test");
+    expect(JSON.parse(eventArg.payload.bodyJson)).toEqual({ event: "incident-opened", id: "abc" });
+    expect(eventArg.payload.headersJson).toBe("{}");
   });
 
   it("resolves function-based url and body resolvers", async () => {
@@ -96,10 +97,8 @@ describe("webhook.send run", () => {
     expect(mockUnsafeAppendEvent).toHaveBeenCalledWith(
       expect.objectContaining({
         payload: expect.objectContaining({
-          spec: expect.objectContaining({
-            url: "https://hooks.example/dynamic",
-            body: { key: "value" },
-          }),
+          url: "https://hooks.example/dynamic",
+          bodyJson: JSON.stringify({ key: "value" }),
         }),
       }),
     );
@@ -111,7 +110,7 @@ describe("webhook.send run", () => {
     await stepDef!.run({ url: "https://hooks.example/test", mode: "deferred" }, mockCtx);
 
     const eventArg = mockUnsafeAppendEvent.mock.calls[0]![0];
-    expect(eventArg.payload.spec.method).toBe("POST");
+    expect(eventArg.payload.method).toBe("POST");
   });
 
   it("defaults retry to 3x exponential when not specified", async () => {
@@ -123,6 +122,15 @@ describe("webhook.send run", () => {
     expect(eventArg.payload.retry).toEqual({ times: 3, backoff: "exponential" });
   });
 
+  it("omits bodyJson when no body is given", async () => {
+    const stepDef = getStep("webhook.send");
+
+    await stepDef!.run({ url: "https://hooks.example/test", mode: "deferred" }, mockCtx);
+
+    const eventArg = mockUnsafeAppendEvent.mock.calls[0]![0];
+    expect("bodyJson" in eventArg.payload).toBe(false);
+  });
+
   it("passes auth config through when provided", async () => {
     const stepDef = getStep("webhook.send");
     const auth = { kind: "bearer" as const, secret: "WEBHOOK_TOKEN" };
@@ -130,6 +138,6 @@ describe("webhook.send run", () => {
     await stepDef!.run({ url: "https://hooks.example/secured", mode: "deferred", auth }, mockCtx);
 
     const eventArg = mockUnsafeAppendEvent.mock.calls[0]![0];
-    expect(eventArg.payload.spec.auth).toEqual(auth);
+    expect(eventArg.payload.auth).toEqual(auth);
   });
 });

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

@@ -450,6 +450,8 @@ function projectField(fieldDef: FieldDefinition): FieldDefinition {
   if (isJsonSafeValue(def["default"])) out["default"] = def["default"];
   // Select: options-Liste ist plain JSON, durchschicken.
   if (Array.isArray(def["options"])) out["options"] = def["options"];
+  if (isPlainObject(def["optionTones"]) && isJsonSafeValue(def["optionTones"]))
+    out["optionTones"] = def["optionTones"];
   // Reference: entity-Target + labelField + multiple müssen zum Renderer.
   // Der ReferenceInput baut die Options-Query aus refEntity/refFeature und
   // resolved das Label über labelField — ohne diese Properties fällt das

package/src/engine/define-feature.ts

@@ -160,6 +160,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
     contentCollections: state.contentCollections,
     workspaces: state.workspaces,
     httpRoutes: state.httpRoutes,
+    webSocketRoutes: state.webSocketRoutes,
     storeTables: state.storeTables,
     ...(state.treeActions !== undefined && { treeActions: state.treeActions }),
     ...(state.envSchema !== undefined && { envSchema: state.envSchema }),