@cosmicdrift/kumiko-framework 0.326.0 → 0.327.0

package/src/crypto/__tests__/system-event-pii.test.ts

@@ -0,0 +1,77 @@
+// System events bypass the defineEvent catalog, so their PII stance lives in
+// a static map. An undeclared system type must fail closed (also without a
+// KMS), and every known system type must have a declared stance.
+
+import { afterEach, describe, expect, test } from "bun:test";
+import * as stepDispatchConstants from "../../engine/steps/_step-dispatch-constants";
+import type { TenantId } from "../../engine/types/identifiers";
+import { encryptEventPayloadPii } from "../event-pii";
+import { InMemoryKmsAdapter } from "../in-memory-kms-adapter";
+import {
+  configurePiiSubjectKms,
+  isPiiCiphertext,
+  resetPiiSubjectKmsForTests,
+} from "../pii-field-encryption";
+import type { EventSubjectEnvelope } from "../subject-resolver";
+import {
+  AGGREGATE_TRANSFERRED_EVENT_TYPE,
+  SYSTEM_EVENT_PII_STANCES,
+  SYSTEM_EVENT_PREFIX,
+} from "../system-event-pii";
+
+const ENVELOPE: EventSubjectEnvelope = {
+  tenantId: "6b2f4a0e-1c9d-4f3a-9d2e-0000000000e1" as TenantId,
+  aggregateType: "step-dispatch",
+  aggregateId: "6b2f4a0e-1c9d-4f3a-9d2e-0000000000e2",
+};
+
+afterEach(() => {
+  resetPiiSubjectKmsForTests();
+});
+
+describe("system event PII stances", () => {
+  test("every system event type constant has a declared stance", () => {
+    const declaredTypes = [
+      ...Object.entries(stepDispatchConstants)
+        .filter(([name]) => name.endsWith("_TYPE"))
+        .map(([, value]: [string, unknown]) => value)
+        .filter(
+          (value): value is string =>
+            typeof value === "string" && value.startsWith(SYSTEM_EVENT_PREFIX),
+        ),
+      AGGREGATE_TRANSFERRED_EVENT_TYPE,
+    ];
+    expect(declaredTypes.length).toBeGreaterThanOrEqual(11);
+    for (const type of declaredTypes) {
+      expect(SYSTEM_EVENT_PII_STANCES.has(type)).toBe(true);
+    }
+  });
+
+  test("an undeclared system type fails closed, even without a configured KMS", async () => {
+    await expect(
+      encryptEventPayloadPii(`${SYSTEM_EVENT_PREFIX}made.up`, { secret: "x" }, ENVELOPE),
+    ).rejects.toThrow(/System event "kumiko:system:made\.up" has no PII stance/);
+  });
+
+  test('a "none" stance passes the payload through untouched', async () => {
+    configurePiiSubjectKms(new InMemoryKmsAdapter());
+    const payload = { stepKind: "mail.send", status: 202 };
+    expect(
+      await encryptEventPayloadPii(stepDispatchConstants.STEP_DISPATCHED_TYPE, payload, ENVELOPE),
+    ).toBe(payload);
+  });
+
+  test("dispatch-requested encrypts its string fields under the per-dispatch record key", async () => {
+    configurePiiSubjectKms(new InMemoryKmsAdapter());
+    const out = await encryptEventPayloadPii(
+      stepDispatchConstants.STEP_DISPATCH_REQUESTED_TYPE,
+      { stepKind: "mail.send", to: '"a@example.com"', subject: "Hi", body: "Body" },
+      ENVELOPE,
+    );
+    expect(out["stepKind"]).toBe("mail.send");
+    for (const field of ["to", "subject", "body"]) {
+      expect(isPiiCiphertext(out[field])).toBe(true);
+      expect(String(out[field])).toContain(`record:step-dispatch:${ENVELOPE.aggregateId}`);
+    }
+  });
+});

package/src/crypto/event-pii.ts

@@ -4,7 +4,9 @@
 // path at all. `r.defineEvent(name, schema, { piiFields })` declares which
 // payload fields are PII and which payload field names the owning user;
 // createRegistry publishes the catalog and append() — the single write funnel
-// into kumiko_events — encrypts every catalogued field.
+// into kumiko_events — encrypts every catalogued field. `kumiko:system:*`
+// events skip the registry and take their stance from system-event-pii.ts
+// instead (fail-closed when missing).
 //
 // `piiFields` is a mandatory, explicit stance (fw#2558): a payload can only
 // go uncatalogued through a declared `piiFields: "none"`, never by omission —
@@ -12,10 +14,11 @@
 // silent no-op (forgetting the option) is now either an explicit "none" or a
 // missing subject KMS at encrypt-time, both visible states, not a gap.
 
-import type { EventPiiFields } from "@cosmicdrift/kumiko-types/handlers";
+import type { EventPiiFields, EventPiiStance } from "@cosmicdrift/kumiko-types/handlers";
 import { requestContext } from "../api/request-context";
 import { configuredPiiSubjectKms, encryptPiiValueForSubject } from "./pii-field-encryption";
 import { type EventSubjectEnvelope, resolveEventSubject } from "./subject-resolver";
+import { SYSTEM_EVENT_PII_STANCES, SYSTEM_EVENT_PREFIX } from "./system-event-pii";
 
 export type EventPiiCatalog = ReadonlyMap<string, EventPiiFields>;
 
@@ -36,6 +39,19 @@ export function resetEventPiiCatalogForTests(): void {
   catalog = new Map();
 }
 
+// System types are checked before the KMS gate: an undeclared one throws
+// even in plaintext rollout mode.
+function resolvePiiStance(eventType: string): EventPiiStance | undefined {
+  if (!eventType.startsWith(SYSTEM_EVENT_PREFIX)) return catalog.get(eventType);
+  const stance = SYSTEM_EVENT_PII_STANCES.get(eventType);
+  if (stance === undefined) {
+    throw new Error(
+      `System event "${eventType}" has no PII stance — declare one in SYSTEM_EVENT_PII_STANCES (crypto/system-event-pii.ts)`,
+    );
+  }
+  return stance;
+}
+
 // Encrypts catalogued payload fields under the declared subject's DEK
 // (user/tenant/self — resolveEventSubject, fw#2801). No-op when the event
 // type is uncatalogued or no subject KMS is configured (plaintext rollout
@@ -51,8 +67,8 @@ export async function encryptEventPayloadPii(
   payload: Record<string, unknown>,
   envelope: EventSubjectEnvelope,
 ): Promise<Record<string, unknown>> {
-  const piiFields = catalog.get(eventType);
-  if (!piiFields) return payload;
+  const piiFields = resolvePiiStance(eventType);
+  if (!piiFields || piiFields === "none") return payload;
   const kms = configuredPiiSubjectKms();
   if (!kms) return payload;
 

package/src/crypto/system-event-pii.ts

@@ -0,0 +1,57 @@
+// PII stance of every `kumiko:system:*` event. System events bypass the
+// registry (append-event-core), so they never reach the defineEvent catalog;
+// this static map is their catalog. encryptEventPayloadPii fails closed on a
+// system type with no entry here, so a new system event cannot ship its
+// payload as plaintext by omission.
+
+import type { EventPiiStance } from "@cosmicdrift/kumiko-types/handlers";
+import {
+  STEP_DISPATCH_FAILED_TYPE,
+  STEP_DISPATCH_REQUESTED_TYPE,
+  STEP_DISPATCHED_TYPE,
+  WORKFLOW_RESUMED_TYPE,
+  WORKFLOW_RETRY_SCHEDULED_TYPE,
+  WORKFLOW_RUN_COMPLETED_TYPE,
+  WORKFLOW_RUN_FAILED_TYPE,
+  WORKFLOW_RUN_STARTED_TYPE,
+  WORKFLOW_WAITING_FOR_EVENT_TYPE,
+  WORKFLOW_WAITING_TYPE,
+} from "../engine/steps/_step-dispatch-constants";
+
+export const SYSTEM_EVENT_PREFIX = "kumiko:system:";
+
+// Lives here (not in event-store/transfer.ts) so this module stays free of
+// an event-store import cycle; transfer.ts re-exports it.
+export const AGGREGATE_TRANSFERRED_EVENT_TYPE = `${SYSTEM_EVENT_PREFIX}aggregate.transferred`;
+
+const SELF = { personal: "self" } as const;
+
+// Workflow payloads carry `triggerPayload`, the stored payload of the trigger
+// event: catalogued fields there are already ciphertext, so "none" leaks nothing.
+export const SYSTEM_EVENT_PII_STANCES: ReadonlyMap<string, EventPiiStance> = new Map<
+  string,
+  EventPiiStance
+>([
+  [
+    STEP_DISPATCH_REQUESTED_TYPE,
+    {
+      to: SELF,
+      subject: SELF,
+      body: SELF,
+      from: SELF,
+      url: SELF,
+      headersJson: SELF,
+      bodyJson: SELF,
+    },
+  ],
+  [STEP_DISPATCHED_TYPE, "none"],
+  [STEP_DISPATCH_FAILED_TYPE, "none"],
+  [AGGREGATE_TRANSFERRED_EVENT_TYPE, "none"],
+  [WORKFLOW_WAITING_TYPE, "none"],
+  [WORKFLOW_WAITING_FOR_EVENT_TYPE, "none"],
+  [WORKFLOW_RESUMED_TYPE, "none"],
+  [WORKFLOW_RUN_STARTED_TYPE, "none"],
+  [WORKFLOW_RUN_COMPLETED_TYPE, "none"],
+  [WORKFLOW_RUN_FAILED_TYPE, "none"],
+  [WORKFLOW_RETRY_SCHEDULED_TYPE, "none"],
+]);

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/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/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 }),

package/src/engine/feature-builder-state.ts

@@ -1,3 +1,4 @@
+import type { WebSocketRouteDefinition } from "@cosmicdrift/kumiko-types/websocket-route";
 import type * as z from "zod";
 import type { ZodType } from "zod";
 import { LifecycleHookTypes } from "./constants";
@@ -99,6 +100,7 @@ export type FeatureBuilderState = {
   contentCollections: Record<string, ContentCollectionDefinition>;
   workspaces: Record<string, WorkspaceDefinition>;
   httpRoutes: Record<string, HttpRouteDefinition>;
+  webSocketRoutes: Record<string, WebSocketRouteDefinition>;
   translations: TranslationKeys;
   isSystemScoped: boolean;
   toggleableDefault: boolean | undefined;
@@ -160,6 +162,7 @@ export function createInitialFeatureBuilderState(): FeatureBuilderState {
     contentCollections: {},
     workspaces: {},
     httpRoutes: {},
+    webSocketRoutes: {},
     translations: {},
     isSystemScoped: false,
     toggleableDefault: undefined,

package/src/engine/feature-ui-extensions.ts

@@ -1,3 +1,9 @@
+import {
+  WEBSOCKET_MAX_CONNECTIONS_PER_USER_LIMIT,
+  WEBSOCKET_MAX_PAYLOAD_BYTES,
+  WEBSOCKET_ROUTE_PATH_PREFIX,
+  type WebSocketRouteDefinition,
+} from "@cosmicdrift/kumiko-types/websocket-route";
 import type { EntityTableMeta } from "../db/entity-table-meta";
 import { bindHookEscapeHatchGrant } from "../pipeline/system-identity-switch";
 import { LifecycleHookTypes } from "./constants";
@@ -514,6 +520,52 @@ export function buildUiExtensionsMethods<TName extends string>(
       }
       state.httpRoutes[key] = definition;
     },
+    webSocketRoute(definition: WebSocketRouteDefinition): void {
+      if (!definition.path.startsWith(WEBSOCKET_ROUTE_PATH_PREFIX)) {
+        throw new Error(
+          `[Feature ${name}] webSocketRoute path "${definition.path}" must start with ` +
+            `"${WEBSOCKET_ROUTE_PATH_PREFIX}" — only that namespace rides the /api/* auth chain ` +
+            "the upgrade relies on.",
+        );
+      }
+      if (definition.path.includes("*")) {
+        throw new Error(
+          `[Feature ${name}] webSocketRoute path "${definition.path}" must not contain "*" — ` +
+            "wildcards would let one route swallow unrelated /api/ws/* paths.",
+        );
+      }
+      const { maxMessageBytes } = definition;
+      if (
+        maxMessageBytes !== undefined &&
+        (!Number.isInteger(maxMessageBytes) ||
+          maxMessageBytes < 1 ||
+          maxMessageBytes > WEBSOCKET_MAX_PAYLOAD_BYTES)
+      ) {
+        throw new Error(
+          `[Feature ${name}] webSocketRoute "${definition.path}" maxMessageBytes must be an ` +
+            `integer between 1 and ${WEBSOCKET_MAX_PAYLOAD_BYTES}, got ${maxMessageBytes}.`,
+        );
+      }
+      const { maxConnectionsPerUser } = definition;
+      if (
+        maxConnectionsPerUser !== undefined &&
+        (!Number.isInteger(maxConnectionsPerUser) ||
+          maxConnectionsPerUser < 1 ||
+          maxConnectionsPerUser > WEBSOCKET_MAX_CONNECTIONS_PER_USER_LIMIT)
+      ) {
+        throw new Error(
+          `[Feature ${name}] webSocketRoute "${definition.path}" maxConnectionsPerUser must be an ` +
+            `integer between 1 and ${WEBSOCKET_MAX_CONNECTIONS_PER_USER_LIMIT}, got ${maxConnectionsPerUser}.`,
+        );
+      }
+      if (state.webSocketRoutes[definition.path]) {
+        throw new Error(
+          `[Feature ${name}] WebSocket route "${definition.path}" already registered. ` +
+            "path must be unique per feature.",
+        );
+      }
+      state.webSocketRoutes[definition.path] = definition;
+    },
     storeTable(meta: EntityTableMeta, options: StoreTableOptions): void {
       // Name comes from the meta itself — apps already give the table a
       // name when calling defineUnmanagedTable, no need to repeat it.

package/src/engine/index.ts

@@ -298,6 +298,10 @@ export type { TransitionGraph } from "./state-machine";
 export { defineTransitions, guardTransition } from "./state-machine";
 export { evaluateEventMatch } from "./steps/_event-match";
 export {
+  STEP_DISPATCH_AGGREGATE_TYPE,
+  STEP_DISPATCH_FAILED_TYPE,
+  STEP_DISPATCH_REQUESTED_TYPE,
+  STEP_DISPATCHED_TYPE,
   SUSPEND_SENTINEL,
   WORKFLOW_AGGREGATE_TYPE,
   WORKFLOW_RESUMED_TYPE,
@@ -308,6 +312,7 @@ export {
   WORKFLOW_WAITING_FOR_EVENT_TYPE,
   WORKFLOW_WAITING_TYPE,
 } from "./steps/_step-dispatch-constants";
+export { describeWorkflowStepError } from "./steps/describe-workflow-step-error";
 export {
   ANONYMOUS_ROLE,
   ANONYMOUS_USER_ID,

package/src/engine/steps/describe-workflow-step-error.ts

@@ -0,0 +1,6 @@
+// Workflow events (run-failed, retry.scheduled) outlive an Art. 17 erase, and a
+// raw error message can echo recipients or payload fragments. Events carry only
+// this generic text; the raw error goes to the log.
+export function describeWorkflowStepError(error: unknown): string {
+  return `workflow step failed (${error instanceof Error ? error.name : "unknown error"})`;
+}

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

@@ -33,7 +33,11 @@ defineStep<MailSendArgs, void>({
       type: STEP_DISPATCH_REQUESTED_TYPE,
       payload: {
         stepKind: "mail.send",
-        spec: { to, subject, body, ...(from && { from }) },
+        // Flat string fields: event PII encryption only handles top-level strings.
+        to: JSON.stringify(to),
+        subject,
+        body,
+        ...(from && { from }),
       },
     });
   },

package/src/engine/steps/retry.ts

@@ -7,6 +7,7 @@
 // after the backoff duration and re-enters the step at the same index.
 // After all attempts exhausted, the original error propagates.
 
+import { createFallbackLogger } from "../../logging";
 import { defineStep } from "../define-step";
 import { runStepList } from "../run-pipeline";
 import type { PipelineCtx, StepInstance } from "../types/step";
@@ -15,6 +16,9 @@ import {
   WORKFLOW_AGGREGATE_TYPE,
   WORKFLOW_RETRY_SCHEDULED_TYPE,
 } from "./_step-dispatch-constants";
+import { describeWorkflowStepError } from "./describe-workflow-step-error";
+
+const log = createFallbackLogger("workflow-retry");
 
 type RetryStepArgs = {
   readonly times: number;
@@ -47,6 +51,14 @@ defineStep<RetryStepArgs, undefined | typeof SUSPEND_SENTINEL>({
         throw error;
       }
 
+      log.warn("workflow step failed, retry scheduled", {
+        runId: ctx.workflow.runId,
+        workflowName: ctx.workflow.workflowName,
+        stepIndex: ctx.workflow.stepIndex,
+        attempt,
+        error: String(error),
+      });
+
       const backoffMs = calculateBackoff(attempt, args.backoff);
       const wakeAt = Temporal.Now.instant().add({ milliseconds: backoffMs }).toString();
 
@@ -60,7 +72,7 @@ defineStep<RetryStepArgs, undefined | typeof SUSPEND_SENTINEL>({
           maxAttempts,
           wakeAt,
           workflowName: ctx.workflow.workflowName,
-          error: String(error),
+          error: describeWorkflowStepError(error),
           triggerEventType: ctx.event.type,
           triggerPayload: ctx.event.payload,
           ...(ctx.workflow.definitionFingerprint && {

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

@@ -14,15 +14,6 @@ import {
   STEP_DISPATCH_REQUESTED_TYPE,
 } from "./_step-dispatch-constants";
 
-// Re-export for back-compat callers (bundled step-dispatcher imports
-// these). The canonical home is _step-dispatch-constants.ts.
-export {
-  STEP_DISPATCH_AGGREGATE_TYPE,
-  STEP_DISPATCH_FAILED_TYPE,
-  STEP_DISPATCH_REQUESTED_TYPE,
-  STEP_DISPATCHED_TYPE,
-} from "./_step-dispatch-constants";
-
 type WebhookHttpMethod = "POST" | "PUT" | "PATCH";
 
 // Name inside the tenant-owned secrets namespace
@@ -55,13 +46,12 @@ defineStep<WebhookSendArgs, void>({
       type: STEP_DISPATCH_REQUESTED_TYPE,
       payload: {
         stepKind: "webhook.send",
-        spec: {
-          url,
-          method: args.method ?? "POST",
-          headers,
-          body,
-          ...(args.auth && { auth: args.auth }),
-        },
+        // Flat string fields: event PII encryption only handles top-level strings.
+        url,
+        method: args.method ?? "POST",
+        headersJson: JSON.stringify(headers),
+        ...(body !== undefined && { bodyJson: JSON.stringify(body) }),
+        ...(args.auth && { auth: args.auth }),
         retry: args.retry ?? { times: 3, backoff: "exponential" },
       },
     });

package/src/engine/types/index.ts

@@ -367,6 +367,13 @@ export type {
   TreeNode,
   TreeNodeState,
 } from "@cosmicdrift/kumiko-types/tree-node";
+export type {
+  WebSocketConnection,
+  WebSocketMessageData,
+  WebSocketRouteConnectDeps,
+  WebSocketRouteDefinition,
+  WebSocketSessionHandlers,
+} from "@cosmicdrift/kumiko-types/websocket-route";
 export type { WorkspaceDefinition } from "@cosmicdrift/kumiko-types/workspace";
 // Re-export types that were duplicated in types.ts but are canonical in constants.ts
 export type {

package/src/event-store/provenance-append.ts

@@ -1,8 +1,8 @@
+import { SYSTEM_EVENT_PREFIX } from "../crypto/system-event-pii";
 import { runInSavepointIfSupported } from "../db/query";
 import { type TenantDb, unsafeRawForDeclaredStep, withUnsafeRawGrant } from "../db/tenant-db";
 import type { TenantId } from "../engine/types";
 import { AccessDeniedError, InternalError } from "../errors";
-import { SYSTEM_EVENT_PREFIX } from "../pipeline/append-event-core";
 import { append, type EventMetadata, getStreamVersion } from "./event-store";
 
 // Fixed by the framework, not the caller — the point of this entry point is