@cosmicdrift/kumiko-framework 0.109.0 → 0.111.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.109.0",
+  "version": "0.111.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -181,7 +181,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.109.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.111.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/__tests__/batch.integration.test.ts

@@ -1,6 +1,7 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { seedRow } from "@cosmicdrift/kumiko-framework/testing";
 import { z } from "zod";
+import type { TableColumns } from "../../db/dialect";
 import { createEventStoreExecutor } from "../../db/event-store-executor";
 import { asRawClient, selectMany } from "../../db/query";
 import { buildEntityTable } from "../../db/table-builder";
@@ -36,7 +37,9 @@ const auditEntity = createEntity({
     itemId: createTextField({ required: true }),
   },
 });
-const auditTable = buildEntityTable("audit", auditEntity);
+// Brand (#742) is compile-time-only; the postSave hook writes this sink via method-form,
+// so hold it at the unbranded TableColumns view (identical runtime shape).
+const auditTable: TableColumns = buildEntityTable("audit", auditEntity);
 
 // Hook invocation logs — reset per test. Captures which phase each hook saw.
 const inTxHookLog: Array<{ id: EntityId; name: string }> = [];

package/src/bun-db/__tests__/write-brand.test.ts

@@ -8,6 +8,7 @@
 import { expect, test } from "bun:test";
 import { defineUnmanagedTable } from "../../db/entity-table-meta";
 import { buildEntityTable } from "../../db/table-builder";
+import type { TenantDb } from "../../db/tenant-db";
 import { createEntity, createTextField } from "../../engine";
 import { type AnyDb, deleteMany, insertOne, selectMany, updateMany } from "../query";
 
@@ -41,8 +42,28 @@ async function _readAllowsManagedEntity(db: AnyDb): Promise<void> {
   await selectMany(db, brandedEntity, { id: "1" });
 }
 
+// Method-form (ctx.db.insertOne/updateMany/deleteMany) rejects the brand too — a
+// projection written past its event stream is wiped on rebuild whether the write
+// went through the free function or the TenantDb method.
+async function _methodFormRejectsManagedEntity(db: TenantDb): Promise<void> {
+  // @ts-expect-error — managed EntityTable is executor-only; method-form insert is a compile error.
+  await db.insertOne(brandedEntity, { title: "x" });
+  // @ts-expect-error — method-form update on a managed EntityTable is rejected.
+  await db.updateMany(brandedEntity, { title: "y" }, { id: "1" });
+  // @ts-expect-error — method-form delete on a managed EntityTable is rejected.
+  await db.deleteMany(brandedEntity, { id: "1" });
+}
+
+async function _methodFormReadAllowsManagedEntity(db: TenantDb): Promise<void> {
+  // Method-form reads on a managed EntityTable stay fine (reads keep the plain param).
+  await db.selectMany(brandedEntity, { id: "1" });
+  await db.fetchOne(brandedEntity, { id: "1" });
+}
+
 test("ES-write brand: compile-time contracts are wired", () => {
   expect(_writeRejectsManagedEntity).toBeDefined();
   expect(_writeAllowsUnmanagedTable).toBeDefined();
   expect(_readAllowsManagedEntity).toBeDefined();
+  expect(_methodFormRejectsManagedEntity).toBeDefined();
+  expect(_methodFormReadAllowsManagedEntity).toBeDefined();
 });

package/src/db/__tests__/config-seed.integration.test.ts

@@ -10,10 +10,11 @@ import {
   SYSTEM_TENANT_ID,
 } from "../../engine";
 import type { ConfigSeedDef, Registry } from "../../engine/types";
+import { createEnvMasterKeyProvider } from "../../secrets/env-master-key-provider";
+import { createEnvelopeCipher } from "../../secrets/envelope-cipher";
 import { unsafeCreateEntityTable } from "../../stack";
 import { ensureTemporalPolyfill } from "../../time/polyfill";
 import { seedConfigValues } from "../config-seed";
-import { createEncryptionProvider } from "../encryption";
 import { buildEntityTable } from "../table-builder";
 
 // --- Test Entity ---
@@ -51,8 +52,15 @@ const mockRegistry = {
 } as unknown as Registry;
 
 // --- Helpers ---
-const encryption = createEncryptionProvider(
-  Buffer.from("0123456789abcdef0123456789abcdef").toString("base64"),
+const encryption = createEnvelopeCipher(
+  createEnvMasterKeyProvider({
+    env: {
+      KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "1",
+      KUMIKO_SECRETS_MASTER_KEY_V1: Buffer.from("0123456789abcdef0123456789abcdef").toString(
+        "base64",
+      ),
+    },
+  }),
 );
 
 let testDb: BunTestDb;
@@ -214,7 +222,7 @@ describe("seedConfigValues", () => {
 
     await expect(
       seedConfigValues(seeds, configTable, configEntity, mockRegistry, testDb.db),
-    ).rejects.toThrow(/encrypted but no EncryptionProvider/);
+    ).rejects.toThrow(/encrypted but no EnvelopeCipher/);
   });
 
   test("encrypted seed with provider stores ciphertext, not plaintext", async () => {
@@ -240,7 +248,7 @@ describe("seedConfigValues", () => {
     // resolver later runs `decrypt → JSON.parse` to get the primitive
     // back; we replay the same round-trip here.
     expect(row!.value).not.toContain("sk_live_secret_token");
-    expect(JSON.parse(encryption.decrypt(row!.value))).toBe("sk_live_secret_token");
+    expect(JSON.parse(await encryption.decrypt(row!.value))).toBe("sk_live_secret_token");
   });
 
   test("race-safe parallel boot — two concurrent calls result in 1 created + 1 skipped", async () => {

package/src/db/__tests__/entity-field-encryption.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { createEntity, createTextField } from "../../engine";
-import { createEncryptionProvider } from "../encryption";
+import { createTestEnvelopeCipher } from "../../testing";
 import {
   collectEncryptedFieldNames,
   decryptEntityFieldValues,
@@ -18,25 +18,25 @@ describe("entity-field-encryption", () => {
     },
   });
   const encryptedFields = collectEncryptedFieldNames(entity);
-  const encryption = createEncryptionProvider(TEST_KEY);
+  const encryption = createTestEnvelopeCipher(TEST_KEY);
 
   test("collectEncryptedFieldNames finds encrypted text fields only", () => {
     expect([...encryptedFields]).toEqual(["secretNote"]);
   });
 
-  test("encrypt on write / decrypt on read round-trip", () => {
+  test("encrypt on write / decrypt on read round-trip", async () => {
     const plain = { email: "a@b.de", secretNote: "top secret" };
-    const stored = encryptEntityFieldValues(plain, encryptedFields, encryption);
+    const stored = await encryptEntityFieldValues(plain, encryptedFields, encryption);
     expect(stored["email"]).toBe(plain.email);
     expect(stored["secretNote"]).not.toBe("top secret");
 
-    const read = decryptEntityFieldValues(stored, encryptedFields, encryption);
+    const read = await decryptEntityFieldValues(stored, encryptedFields, encryption);
     expect(read).toEqual(plain);
   });
 
-  test("onlyKeys limits encryption to changed fields", () => {
+  test("onlyKeys limits encryption to changed fields", async () => {
     const row = { email: "a@b.de", secretNote: "note" };
-    const stored = encryptEntityFieldValues(row, encryptedFields, encryption, {
+    const stored = await encryptEntityFieldValues(row, encryptedFields, encryption, {
       onlyKeys: ["secretNote"],
     });
     expect(stored["email"]).toBe("a@b.de");

package/src/db/__tests__/event-store-executor.integration.test.ts

@@ -10,7 +10,7 @@ import {
   testTenantId,
   unsafeCreateEntityTable,
 } from "../../stack";
-import { createEncryptionProvider } from "../encryption";
+import { createTestEnvelopeCipher } from "../../testing";
 import { resetEntityFieldEncryptionCacheForTests } from "../entity-field-encryption";
 import { createEventStoreExecutor } from "../event-store-executor";
 import { buildEntityTable } from "../table-builder";
@@ -324,7 +324,7 @@ const encryptedSoftDeleteEntity = createEntity({
 const encryptedSoftDeleteTable = buildEntityTable("esExecEncSoft", encryptedSoftDeleteEntity);
 
 describe("event-store-executor — encrypted fields", () => {
-  const encryption = createEncryptionProvider(ENCRYPTION_TEST_KEY);
+  const encryption = createTestEnvelopeCipher(ENCRYPTION_TEST_KEY);
   const crud = createEventStoreExecutor(encryptedTable, encryptedEntity, {
     entityName: "esExecEncrypted",
     encryption,
@@ -337,7 +337,6 @@ describe("event-store-executor — encrypted fields", () => {
   );
 
   beforeAll(async () => {
-    process.env["ENCRYPTION_KEY"] = ENCRYPTION_TEST_KEY;
     resetEntityFieldEncryptionCacheForTests();
     await unsafeCreateEntityTable(testDb.db, encryptedEntity, "esExecEncrypted");
     await unsafeCreateEntityTable(testDb.db, encryptedSoftDeleteEntity, "esExecEncSoft");
@@ -524,7 +523,7 @@ describe("event-store-executor — entity cache + encrypted fields", () => {
       store.delete(`${tenantId}:${name}:${id}`);
     },
   };
-  const encryption = createEncryptionProvider(ENCRYPTION_TEST_KEY);
+  const encryption = createTestEnvelopeCipher(ENCRYPTION_TEST_KEY);
   const cachedEncryptedCrud = createEventStoreExecutor(encryptedTable, encryptedEntity, {
     entityName: "esExecEncrypted",
     entityCache,

package/src/db/__tests__/tenant-db-where-merge.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import { createEntity, createTextField } from "../../engine";
 import { testTenantId } from "../../stack";
+import type { TableColumns } from "../dialect";
 import { buildEntityTable } from "../table-builder";
 import { createTenantDb } from "../tenant-db";
 
@@ -13,7 +14,9 @@ const entity = createEntity({
   table: "merge_items",
   fields: { name: createTextField({ required: true }) },
 });
-const table = buildEntityTable("mergeItem", entity);
+// Brand (#742) is compile-time-only; hold the handle at the unbranded TableColumns
+// view so the method-form scoping test still compiles (runtime shape is identical).
+const table: TableColumns = buildEntityTable("mergeItem", entity);
 
 const own = testTenantId(1);
 const foreign = testTenantId(2);

package/src/db/__tests__/tenant-db.integration.test.ts

@@ -10,7 +10,7 @@ import {
   unsafeCreateEntityTable,
   unsafePushTables,
 } from "../../stack";
-import { table as pgTable, serial, text, timestamp } from "../dialect";
+import { table as pgTable, serial, type TableColumns, text, timestamp } from "../dialect";
 import { buildEntityTable } from "../table-builder";
 import { createTenantDb } from "../tenant-db";
 
@@ -26,7 +26,11 @@ const entity = createEntity({
   softDelete: true,
 });
 
-const table = buildEntityTable("tenantDbItem", entity);
+// The ES-write brand (#742) is a compile-time phantom — no runtime property. This
+// suite exercises TenantDb method-form scoping on a real entity table, so the handle
+// is held at the unbranded TableColumns view: identical runtime shape, and both reads
+// and method-form writes accept it (a branded EntityTable is now rejected).
+const table: TableColumns = buildEntityTable("tenantDbItem", entity);
 
 // --- System table (no tenantId — like job_runs) ---
 

package/src/db/config-seed.ts

@@ -2,8 +2,8 @@ import { v5 as uuidv5 } from "uuid";
 import type { EntityDefinition } from "../engine";
 import { createSystemUser, SYSTEM_TENANT_ID } from "../engine";
 import type { ConfigSeedDef, Registry } from "../engine/types";
+import type { EnvelopeCipher } from "../secrets/envelope-cipher";
 import type { DbConnection } from "./connection";
-import type { EncryptionProvider } from "./encryption";
 import { createEventStoreExecutor } from "./event-store-executor";
 import type { EntityTable } from "./table-builder";
 import { createTenantDb } from "./tenant-db";
@@ -30,7 +30,7 @@ export async function seedConfigValues<E extends EntityDefinition>(
   entity: E,
   registry: Registry,
   db: DbConnection,
-  encryption?: EncryptionProvider,
+  cipher?: EnvelopeCipher,
 ): Promise<{ created: number; skipped: number }> {
   let created = 0;
   let skipped = 0;
@@ -48,12 +48,12 @@ export async function seedConfigValues<E extends EntityDefinition>(
       continue;
     }
 
-    // Encrypted keys without an encryption provider would silently write
-    // plaintext to a column the resolver later tries to decrypt — fail
-    // loud at boot, not on first read in prod.
-    if (keyDef.encrypted && !encryption) {
+    // Encrypted keys without a cipher would silently write plaintext to a
+    // column the resolver later tries to decrypt — fail loud at boot, not
+    // on first read in prod.
+    if (keyDef.encrypted && !cipher) {
       throw new Error(
-        `seedConfigValues: key "${seed.key}" is encrypted but no EncryptionProvider was supplied.`,
+        `seedConfigValues: key "${seed.key}" is encrypted but no EnvelopeCipher was supplied.`,
       );
     }
 
@@ -77,8 +77,8 @@ export async function seedConfigValues<E extends EntityDefinition>(
     const aggregateId = uuidv5(idSource, CONFIG_SEED_NS);
 
     let value = JSON.stringify(seed.value);
-    if (keyDef.encrypted && encryption) {
-      value = encryption.encrypt(value);
+    if (keyDef.encrypted && cipher) {
+      value = await cipher.encrypt(value, { tenantId });
     }
 
     const payload: Record<string, unknown> = {

package/src/db/encryption.ts

@@ -9,6 +9,13 @@ export type EncryptionProvider = {
   decrypt(ciphertext: string): string;
 };
 
+/**
+ * @deprecated Legacy single-key format: base64(iv+tag+ct) with NO key id —
+ * a key change makes existing ciphertexts permanently undecryptable. Use
+ * `createEnvelopeCipher` (@cosmicdrift/kumiko-framework/secrets) for new code; this
+ * provider remains only as the decrypt-fallback for pre-envelope values
+ * (EnvelopeCipherOptions.legacy) until a re-encrypt job migrated them.
+ */
 export function createEncryptionProvider(key: string): EncryptionProvider {
   // Key must be 32 bytes for AES-256
   const keyBuffer = Buffer.from(key, "base64");

package/src/db/entity-field-encryption.ts

@@ -1,6 +1,13 @@
-import type { EntityDefinition } from "../engine/types";
-import type { EncryptionProvider } from "./encryption";
-import { createEncryptionProvider } from "./encryption";
+// Entity-field encryption (`encrypted: true` on text/longText fields),
+// backed by the same envelope cipher as encrypted config values: JSON
+// StoredEnvelope in the TEXT column, kekVersion per value, legacy
+// single-key ciphertexts (pre-envelope ENCRYPTION_KEY era) readable via
+// the cipher's legacy fallback until re-encrypted.
+
+import type { EntityDefinition, TenantId } from "../engine/types";
+import { createEnvMasterKeyProvider } from "../secrets/env-master-key-provider";
+import type { EnvelopeCipher } from "../secrets/envelope-cipher";
+import type { KeyScope } from "../secrets/types";
 
 export function collectEncryptedFieldNames(entity: EntityDefinition): ReadonlySet<string> {
   const names = new Set<string>();
@@ -12,70 +19,120 @@ export function collectEncryptedFieldNames(entity: EntityDefinition): ReadonlySe
   return names;
 }
 
-function encryptFieldValue(
+// BYOK hook: thread the row's tenant to the cipher when the row carries one
+// (system-scope rows may not).
+function scopeOf(row: Record<string, unknown>): KeyScope | undefined {
+  const tenantId = row["tenantId"];
+  return typeof tenantId === "string" ? { tenantId: tenantId as TenantId } : undefined; // @cast-boundary db-row
+}
+
+async function encryptFieldValue(
   fieldName: string,
   value: unknown,
-  encryption: EncryptionProvider,
-): string {
+  cipher: EnvelopeCipher,
+  scope: KeyScope | undefined,
+): Promise<string> {
   if (value === null || value === undefined) {
     throw new Error(`encrypted field "${fieldName}" cannot be null or undefined`);
   }
   if (typeof value !== "string") {
     throw new Error(`encrypted field "${fieldName}" must be a string, got ${typeof value}`);
   }
-  return encryption.encrypt(value);
+  return cipher.encrypt(value, scope);
 }
 
-export function encryptEntityFieldValues(
+export async function encryptEntityFieldValues(
   row: Record<string, unknown>,
   encryptedFields: ReadonlySet<string>,
-  encryption: EncryptionProvider,
+  cipher: EnvelopeCipher,
   opts?: { onlyKeys?: Iterable<string> },
-): Record<string, unknown> {
+): Promise<Record<string, unknown>> {
   if (encryptedFields.size === 0) return row;
   const only = opts?.onlyKeys ? new Set(opts.onlyKeys) : null;
   const out = { ...row };
+  const scope = scopeOf(row);
   for (const name of encryptedFields) {
     if (only && !only.has(name)) continue;
     if (!(name in out)) continue;
     const value = out[name];
     if (value === null || value === undefined) continue;
-    out[name] = encryptFieldValue(name, value, encryption);
+    out[name] = await encryptFieldValue(name, value, cipher, scope);
   }
   return out;
 }
 
-export function decryptEntityFieldValues(
+export async function decryptEntityFieldValues(
   row: Record<string, unknown>,
   encryptedFields: ReadonlySet<string>,
-  encryption: EncryptionProvider,
-): Record<string, unknown> {
+  cipher: EnvelopeCipher,
+): Promise<Record<string, unknown>> {
   if (encryptedFields.size === 0) return row;
   const out = { ...row };
+  const scope = scopeOf(row);
   for (const name of encryptedFields) {
     const value = out[name];
     if (value === null || value === undefined) continue;
     if (typeof value !== "string") continue;
-    out[name] = encryption.decrypt(value);
+    out[name] = await cipher.decrypt(value, scope);
   }
   return out;
 }
 
-let cachedProvider: EncryptionProvider | undefined;
+// Boot-injected app-wide cipher. run{Prod,Dev}App (and test setups that
+// exercise encrypted fields) call configureEntityFieldEncryption once with
+// the same cipher instance the config feature uses; executors resolve it
+// lazily so entities without encrypted fields never touch it.
+let injectedCipher: EnvelopeCipher | undefined;
 
-export function resolveEntityFieldEncryption(): EncryptionProvider {
-  if (cachedProvider) return cachedProvider;
-  const key = process.env["ENCRYPTION_KEY"];
-  if (!key) {
+export function configureEntityFieldEncryption(cipher: EnvelopeCipher | undefined): void {
+  injectedCipher = cipher;
+}
+
+export function resolveEntityFieldEncryption(): EnvelopeCipher {
+  if (!injectedCipher) {
     throw new Error(
-      "ENCRYPTION_KEY environment variable is required (encrypted entity fields in use)",
+      "entity-field encryption is not configured — encrypted entity fields need a master key " +
+        "(KUMIKO_SECRETS_MASTER_KEY_V<n>); run{Prod,Dev}App wire the cipher automatically, " +
+        "custom boots call configureEntityFieldEncryption(cipher).",
     );
   }
-  cachedProvider = createEncryptionProvider(key);
-  return cachedProvider;
+  return injectedCipher;
+}
+
+// Non-throwing probe for callers that degrade gracefully (DSGVO export
+// replaces encrypted fields with an explicit marker instead of failing
+// the whole export when no cipher is wired).
+export function configuredEntityFieldEncryption(): EnvelopeCipher | undefined {
+  return injectedCipher;
 }
 
 /** @internal test-only */
 export function resetEntityFieldEncryptionCacheForTests(): void {
-  cachedProvider = undefined;
+  injectedCipher = undefined;
+}
+
+// Boot-time availability probe for validateBoot: either a cipher was
+// injected, or the env keyring must be constructible — eager construction
+// surfaces missing AND malformed keys (wrong length, bad base64) at boot
+// instead of on the first encrypted read in prod. validateBoot runs before
+// configureEntityFieldEncryption, so the env probe is the common path.
+export function validateEntityFieldEncryptionAvailable(): void {
+  // skip: an injected cipher (test seam / custom KMS) satisfies availability
+  if (injectedCipher) return;
+  try {
+    createEnvMasterKeyProvider({
+      env: {
+        ...process.env,
+        KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION:
+          process.env["KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION"] ?? "1",
+      },
+    });
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `encrypted entity fields in use but no usable master key (${reason}) — set ` +
+        "KUMIKO_SECRETS_MASTER_KEY_V1 (32 bytes, base64) or inject a cipher via " +
+        "configureEntityFieldEncryption().",
+    );
+  }
 }

package/src/db/event-store-executor.ts

@@ -39,13 +39,13 @@ import {
 } from "../event-store";
 import type { EntityCache } from "../pipeline/entity-cache";
 import type { SearchAdapter } from "../search/types";
+import type { EnvelopeCipher } from "../secrets/envelope-cipher";
 import { assertUnreachable, generateId } from "../utils";
 import { applyEntityEvent } from "./apply-entity-event";
 import { flattenCompoundTypes, rehydrateCompoundTypes } from "./compound-types";
 import type { DbRow } from "./connection";
 import { decodeCursor, encodeCursor } from "./cursor";
 import type { TableColumns } from "./dialect";
-import type { EncryptionProvider } from "./encryption";
 import {
   collectEncryptedFieldNames,
   decryptEntityFieldValues,
@@ -119,8 +119,8 @@ export type EventStoreExecutorOptions = {
   searchAdapter?: SearchAdapter;
   entityName: string; // required — the aggregateType marker on every event
   entityCache?: EntityCache;
-  /** Override ENCRYPTION_KEY for entity fields marked `encrypted: true`. */
-  encryption?: EncryptionProvider;
+  /** Override the boot-injected cipher for fields marked `encrypted: true`. */
+  encryption?: EnvelopeCipher;
 };
 
 // F8 helper: PG-23505 (unique-violation) catched aus applyEntityEvent
@@ -307,24 +307,28 @@ export function createEventStoreExecutor(
   const encryptedFields = collectEncryptedFieldNames(entity);
   const hasEncryptedFields = encryptedFields.size > 0;
 
-  function encryptionProvider(): EncryptionProvider {
+  function fieldCipher(): EnvelopeCipher {
     if (options.encryption) return options.encryption;
     return resolveEntityFieldEncryption();
   }
 
-  function encryptForStorage(
+  // Async on purpose: the envelope cipher wraps/unwraps DEKs via the
+  // MasterKeyProvider. Callers MUST await — a missed await here writes
+  // "[object Promise]" into the projection, which the Promise return
+  // types turn into a compile error at every call site.
+  async function encryptForStorage(
     row: Record<string, unknown>,
     onlyKeys?: Iterable<string>,
-  ): Record<string, unknown> {
+  ): Promise<Record<string, unknown>> {
     if (!hasEncryptedFields) return row;
-    return encryptEntityFieldValues(row, encryptedFields, encryptionProvider(), {
+    return encryptEntityFieldValues(row, encryptedFields, fieldCipher(), {
       ...(onlyKeys !== undefined && { onlyKeys }),
     });
   }
 
-  function decryptForRead(row: Record<string, unknown>): Record<string, unknown> {
+  async function decryptForRead(row: Record<string, unknown>): Promise<Record<string, unknown>> {
     if (!hasEncryptedFields) return row;
-    return decryptEntityFieldValues(row, encryptedFields, encryptionProvider());
+    return decryptEntityFieldValues(row, encryptedFields, fieldCipher());
   }
 
   function applyDefaults(payload: Record<string, unknown>): Record<string, unknown> {
@@ -356,7 +360,7 @@ export function createEventStoreExecutor(
   async function loadById(id: EntityId, db: TenantDb): Promise<Record<string, unknown> | null> {
     const row = await db.fetchOne(table, idFilter(id));
     if (!row) return null;
-    return decryptForRead(rehydrateCompoundTypes(row as DbRow, entity));
+    return await decryptForRead(rehydrateCompoundTypes(row as DbRow, entity));
   }
 
   // Archive guard for the CRUD write paths. Archived streams are read-only —
@@ -465,7 +469,7 @@ export function createEventStoreExecutor(
       // Alle Compound-Types (locatedTimestamp, money, ...) gehen durch
       // dieselbe Pipeline. Caller schickt combined API-Form, Framework
       // speichert flat DB-Form. Siehe db/compound-types.ts.
-      const flatData = encryptForStorage(flattenCompoundTypes(data, entity));
+      const flatData = await encryptForStorage(flattenCompoundTypes(data, entity));
 
       // 1. Append event (same TX as the projection write — both must succeed
       //    or both roll back; the dispatcher wraps both in one transaction).
@@ -541,7 +545,9 @@ export function createEventStoreExecutor(
       const row = result.row;
       // Read-Side Auto-Convert: DB-Form → API-combined-Form für alle
       // Compound-Types in einem Pass.
-      const projection = decryptForRead(rehydrateCompoundTypes(row as DbRow, entity) as DbRow);
+      const projection = await decryptForRead(
+        rehydrateCompoundTypes(row as DbRow, entity) as DbRow,
+      );
 
       if (entityCache && entityName) {
         await entityCache.del(user.tenantId, entityName, aggregateId);
@@ -644,7 +650,7 @@ export function createEventStoreExecutor(
 
       try {
         // Compound-Types Auto-Convert (alle in einem Pass).
-        const flatChanges = encryptForStorage(
+        const flatChanges = await encryptForStorage(
           flattenCompoundTypes(payload.changes, entity),
           Object.keys(payload.changes),
         );
@@ -667,7 +673,7 @@ export function createEventStoreExecutor(
           type: entityEventName(entityName, "updated"),
           payload: {
             changes: stripSensitive(flatChanges),
-            previous: stripSensitive(encryptForStorage(previous)),
+            previous: stripSensitive(await encryptForStorage(previous)),
           },
           metadata: buildEventMetadata(user),
         });
@@ -695,7 +701,7 @@ export function createEventStoreExecutor(
           return writeFailure(new InternalError({ message: "projection update returned no row" }));
         }
         const row = result.row;
-        const data = decryptForRead(rehydrateCompoundTypes(row as DbRow, entity) as DbRow);
+        const data = await decryptForRead(rehydrateCompoundTypes(row as DbRow, entity) as DbRow);
 
         if (entityCache && entityName) {
           await entityCache.del(user.tenantId, entityName, payload.id);
@@ -777,7 +783,7 @@ export function createEventStoreExecutor(
         tenantId: streamTenantFor(user),
         expectedVersion: currentVersion,
         type: entityEventName(entityName, "deleted"),
-        payload: { previous: stripSensitive(encryptForStorage(existing)) },
+        payload: { previous: stripSensitive(await encryptForStorage(existing)) },
         metadata: buildEventMetadata(user),
       });
 
@@ -810,7 +816,7 @@ export function createEventStoreExecutor(
     async forget(payload, user, db) {
       const raw = await db.fetchOne<Record<string, unknown>>(table, { id: payload.id });
       if (!raw) return writeFailure(new NotFoundError(entityName, payload.id));
-      const existing = decryptForRead(rehydrateCompoundTypes(raw as DbRow, entity) as DbRow);
+      const existing = await decryptForRead(rehydrateCompoundTypes(raw as DbRow, entity) as DbRow);
 
       if (!userCanWriteFieldRow(user, entity.access?.write, existing, existing)) {
         return writeFailure(
@@ -937,7 +943,7 @@ export function createEventStoreExecutor(
       // row and `previous` snapshot must be plaintext for `encrypted` fields,
       // same as every other executor method — `data`/`restored` are raw rows
       // (selectMany / applyEntityEvent), never decrypted before this point.
-      const restoredHydrated = decryptForRead(
+      const restoredHydrated = await decryptForRead(
         rehydrateCompoundTypes(restored as DbRow, entity) as DbRow,
       );
 
@@ -948,7 +954,7 @@ export function createEventStoreExecutor(
           id: payload.id,
           data: restoredHydrated,
           changes: { isDeleted: false },
-          previous: decryptForRead(data),
+          previous: await decryptForRead(data),
           isNew: false,
           entityName,
           event,
@@ -1082,8 +1088,10 @@ export function createEventStoreExecutor(
       const rawRows = await executeRawQuery<Record<string, unknown>>(db.raw, listSql, params);
       // Read-Side rehydrate pro Row + snake→camel coercion für driver-agnostic Feldnamen
       const tableInfo = extractTableInfo(table);
-      const rows = rawRows.map((r) =>
-        coerceRow(decryptForRead(rehydrateCompoundTypes(r, entity)), tableInfo),
+      const rows = await Promise.all(
+        rawRows.map(async (r) =>
+          coerceRow(await decryptForRead(rehydrateCompoundTypes(r, entity)), tableInfo),
+        ),
       );
 
       // list rows carry the READ-ROW version (display-only), never an optimistic-lock
@@ -1156,19 +1164,24 @@ export function createEventStoreExecutor(
           // Cached rows are stored re-encrypted (see the `set` below) so an
           // `encrypted` field's plaintext never sits in a second at-rest
           // store (Redis) the field-encryption feature doesn't cover.
-          return withStreamVersion(decryptForRead(cached));
+          return withStreamVersion(await decryptForRead(cached));
         }
       }
 
       const rows = await loadWithOwnership(db, idWhere, ownership);
       const raw = rows[0];
       if (!raw) return null;
-      const row = decryptForRead(rehydrateCompoundTypes(raw, entity));
+      const row = await decryptForRead(rehydrateCompoundTypes(raw, entity));
       const rowInfo = extractTableInfo(table);
       const coerced = coerceRow(row, rowInfo);
 
       if (entityCache && entityName) {
-        await entityCache.set(user.tenantId, entityName, payload.id, encryptForStorage(coerced));
+        await entityCache.set(
+          user.tenantId,
+          entityName,
+          payload.id,
+          await encryptForStorage(coerced),
+        );
       }
 
       return withStreamVersion(coerced);