@cosmicdrift/kumiko-framework 0.105.1 → 0.108.0

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

@@ -109,7 +109,7 @@ function scalarDefault(field: FieldDefinition): unknown {
 // to entity creates/updates/etc should reference this helper instead of
 // hardcoding the string — a future rename in the executor then surfaces
 // as a type error at every call site rather than a silent miss.
-export type EntityLifecycleVerb = "created" | "updated" | "deleted" | "restored";
+export type EntityLifecycleVerb = "created" | "updated" | "deleted" | "restored" | "forgotten";
 
 export function entityEventName(entityName: string, verb: EntityLifecycleVerb): string {
   return `${entityName}.${verb}`;
@@ -187,6 +187,16 @@ export type EventStoreExecutor = {
     db: TenantDb,
   ) => Promise<WriteResult<DeleteContext>>;
 
+  // Hard-purge (Art. 17 erasure). Like delete, but emits `<entity>.forgotten`
+  // which hard-deletes the row even for softDelete entities — and, being an
+  // auto-verb replayed by the implicit projection, the erasure survives a
+  // rebuild (created → forgotten → row gone). Reaches soft-deleted rows too.
+  forget: (
+    payload: { id: EntityId },
+    user: SessionUser,
+    db: TenantDb,
+  ) => Promise<WriteResult<DeleteContext>>;
+
   restore: (
     payload: { id: EntityId },
     user: SessionUser,
@@ -645,7 +655,10 @@ export function createEventStoreExecutor(
         // you'd have to snapshot-and-diff on every apply, and replays would
         // break. Storage cost is acceptable (rows are bounded), correctness is
         // not negotiable. Sensitive fields are stripped from BOTH halves so
-        // they never reach the immutable event log.
+        // they never reach the immutable event log. `previous` came from
+        // loadById(), which decrypts — re-encrypt it before it's persisted so
+        // an `encrypted` field's plaintext doesn't land in the immutable log
+        // (flatChanges is already ciphertext from encryptForStorage above).
         const event = await append(db.raw, {
           aggregateId: String(payload.id),
           aggregateType: entityName,
@@ -654,7 +667,7 @@ export function createEventStoreExecutor(
           type: entityEventName(entityName, "updated"),
           payload: {
             changes: stripSensitive(flatChanges),
-            previous: stripSensitive(previous),
+            previous: stripSensitive(encryptForStorage(previous)),
           },
           metadata: buildEventMetadata(user),
         });
@@ -755,13 +768,16 @@ export function createEventStoreExecutor(
       // projections and downstream consumers need to reverse any aggregates —
       // a `{}`-payload delete would make cross-aggregate projections impossible
       // to rebuild from the event log alone. Sensitive fields are stripped.
+      // `existing` came from loadById(), which decrypts — re-encrypt before
+      // persisting so an `encrypted` field's plaintext doesn't land in the
+      // immutable log.
       const event = await append(db.raw, {
         aggregateId: String(payload.id),
         aggregateType: entityName,
         tenantId: streamTenantFor(user),
         expectedVersion: currentVersion,
         type: entityEventName(entityName, "deleted"),
-        payload: { previous: stripSensitive(existing) },
+        payload: { previous: stripSensitive(encryptForStorage(existing)) },
         metadata: buildEventMetadata(user),
       });
 
@@ -787,6 +803,64 @@ export function createEventStoreExecutor(
       };
     },
 
+    // Hard-purge (Art. 17). Same shape as delete(), but emits `forgotten` which
+    // hard-deletes the row regardless of softDelete — and, being an auto-verb,
+    // the erasure replays on rebuild (created → forgotten → row gone). Loads
+    // without the isDeleted filter so trashed (soft-deleted) rows are erased too.
+    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);
+
+      if (!userCanWriteFieldRow(user, entity.access?.write, existing, existing)) {
+        return writeFailure(
+          new UnprocessableError("ownership_denied", {
+            i18nKey: "errors.ownershipDenied",
+            details: {
+              scope: "entity",
+              entityName,
+              action: "delete",
+              userId: user.id,
+              entityId: payload.id,
+            },
+          }),
+        );
+      }
+
+      await assertStreamWritable(db, payload.id, streamTenantFor(user));
+      const currentVersion = await getStreamVersion(
+        db.raw,
+        String(payload.id),
+        streamTenantFor(user),
+      );
+
+      const event = await append(db.raw, {
+        aggregateId: String(payload.id),
+        aggregateType: entityName,
+        tenantId: streamTenantFor(user),
+        expectedVersion: currentVersion,
+        type: entityEventName(entityName, "forgotten"),
+        payload: { previous: stripSensitive(existing) },
+        metadata: buildEventMetadata(user),
+      });
+
+      const forgetResult = await applyEntityEvent(event, table, entity, db.raw);
+      if (forgetResult.kind !== "applied") {
+        return writeFailure(
+          new InternalError({ message: "projection forget: applyEntityEvent skipped" }),
+        );
+      }
+
+      if (entityCache && entityName) {
+        await entityCache.del(user.tenantId, entityName, payload.id);
+      }
+
+      return {
+        isSuccess: true,
+        data: { kind: "delete", id: payload.id, data: existing, entityName, event },
+      };
+    },
+
     async restore(payload, user, db) {
       if (!softDelete) {
         return writeFailure(
@@ -859,7 +933,13 @@ export function createEventStoreExecutor(
       }
 
       // Read-Side Auto-Convert für Compound-Types (parallel zu update/list).
-      const restoredHydrated = rehydrateCompoundTypes(restored as DbRow, entity) as DbRow;
+      // decryptForRead matches create/update/list/detail: the caller-facing
+      // 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(
+        rehydrateCompoundTypes(restored as DbRow, entity) as DbRow,
+      );
 
       return {
         isSuccess: true,
@@ -868,7 +948,7 @@ export function createEventStoreExecutor(
           id: payload.id,
           data: restoredHydrated,
           changes: { isDeleted: false },
-          previous: data,
+          previous: decryptForRead(data),
           isNew: false,
           entityName,
           event,
@@ -1073,7 +1153,10 @@ export function createEventStoreExecutor(
             const checkRows = await loadWithOwnership(db, idWhere, ownership);
             if (checkRows.length === 0) return null;
           }
-          return withStreamVersion(cached);
+          // 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));
         }
       }
 
@@ -1085,7 +1168,7 @@ export function createEventStoreExecutor(
       const coerced = coerceRow(row, rowInfo);
 
       if (entityCache && entityName) {
-        await entityCache.set(user.tenantId, entityName, payload.id, coerced);
+        await entityCache.set(user.tenantId, entityName, payload.id, encryptForStorage(coerced));
       }
 
       return withStreamVersion(coerced);

package/src/db/queries/shadow-swap.ts

@@ -104,7 +104,7 @@ export async function fenceLiveTable(
   // Postgres treats lock_timeout = 0 as "no timeout" (wait forever) — the
   // opposite of fail-fast. Reject it so a 0/negative value can't silently
   // turn the fence into an unbounded wait.
-  if (lockTimeoutMs <= 0) {
+  if (Math.trunc(lockTimeoutMs) <= 0) {
     throw new Error(`fenceLockTimeoutMs must be > 0, got ${lockTimeoutMs}`);
   }
   const raw = asRawClient(tx);

package/src/db/query.ts

@@ -17,6 +17,7 @@ export {
   insertMany,
   insertOne,
   type OrderByClause,
+  runInSavepoint,
   type SelectOptions,
   selectMany,
   type TableInfo,

package/src/db/table-builder.ts

@@ -365,12 +365,34 @@ type SoftDeleteColumnsType = {
   readonly deletedById: NullCol<string>;
 };
 
+// ── ES-write brand ──────────────────────────────────────────────────────
+// A managed projection is only writable through the executor (event →
+// rebuild-safe). To make a direct write a *compile* error rather than a
+// convention, EntityTable carries a phantom `unique symbol` prop; the public
+// write helpers reject anything that has it (see NotExecutorOnly + query.ts).
+// The symbol key dodges SchemaTable's `[field: string]: unknown` index
+// signature (string index sigs don't cover symbol keys), so the brand
+// survives the type-erasure that would swallow a plain marker prop — and the
+// executor seam (applyEntityEvent) erases `table` to TableColumns<any>, which
+// carries no such prop, so the one legitimate writer stays green.
+declare const EXECUTOR_ONLY: unique symbol;
+export interface ExecutorOnly {
+  readonly [EXECUTOR_ONLY]: true;
+}
+// Negative brand for write-helper params: a branded EntityTable is NOT
+// assignable (its `true` clashes with `never`), while unmanaged EntityTableMeta
+// and erased SchemaTable pass (they lack the prop, so `?: never` is satisfied).
+export type NotExecutorOnly = {
+  readonly [EXECUTOR_ONLY]?: never;
+};
+
 export type EntityTable<E extends EntityDefinition = EntityDefinition> =
   TableColumns<// biome-ignore lint/suspicious/noExplicitAny: drizzle's internal table-config stays generic; we layer typed columns on top via the intersection below.
   any> &
     BaseColumnsType<E> &
     SoftDeleteColumnsType &
-    ColumnsForEntity<E["fields"]>;
+    ColumnsForEntity<E["fields"]> &
+    ExecutorOnly;
 
 export function buildBaseColumns(softDelete: boolean, idType: "serial" | "uuid" = "uuid") {
   const idColumn =

package/src/db/tenant-db.ts

@@ -53,6 +53,12 @@ export type TenantDb = {
     set: Record<string, unknown>,
     where: WhereObject,
   ): Promise<readonly T[]>;
+  // Method-form writes (ctx.db.insertOne/updateMany/deleteMany) keep the erased
+  // Table param: the executor-only brand is enforced on the free-function
+  // helpers (the reflexive path all production writes take), while method-form
+  // on a branded table is covered by the guard-direct-entity-writes AST guard
+  // (P5) — branding it here would force every push+write test into casts for
+  // zero production benefit (no prod code writes a projection via method-form).
   deleteMany(table: Table, where: WhereObject): Promise<void>;
 };
 

package/src/engine/__tests__/boot-validator-gdpr-storage.test.ts

@@ -10,6 +10,7 @@ import {
   validateGdprStoragePersistence,
 } from "../boot-validator/gdpr-storage";
 import { defineFeature } from "../define-feature";
+import { EXT_USER_DATA } from "../extension-names";
 
 const udr = () => defineFeature("user-data-rights", () => {});
 const fileProvider = (name: string) =>
@@ -94,7 +95,7 @@ describe("validateGdprHookCompleteness (V2)", () => {
 
   test("export + delete hooks → no warn", () => {
     const f = defineFeature("my-feature", (r) => {
-      r.useExtension("userData", "myEntity", { export: exportFn, delete: deleteFn });
+      r.useExtension(EXT_USER_DATA, "myEntity", { export: exportFn, delete: deleteFn });
     });
     validateGdprHookCompleteness([f]);
     expect(warnSpy).not.toHaveBeenCalled();
@@ -102,7 +103,7 @@ describe("validateGdprHookCompleteness (V2)", () => {
 
   test("export hook without delete hook → Art.17 warn", () => {
     const f = defineFeature("my-feature", (r) => {
-      r.useExtension("userData", "myEntity", { export: exportFn });
+      r.useExtension(EXT_USER_DATA, "myEntity", { export: exportFn });
     });
     validateGdprHookCompleteness([f]);
     expect(warnSpy).toHaveBeenCalledTimes(1);
@@ -114,7 +115,7 @@ describe("validateGdprHookCompleteness (V2)", () => {
 
   test("delete hook only (no export) → no warn", () => {
     const f = defineFeature("my-feature", (r) => {
-      r.useExtension("userData", "myEntity", { delete: deleteFn });
+      r.useExtension(EXT_USER_DATA, "myEntity", { delete: deleteFn });
     });
     validateGdprHookCompleteness([f]);
     expect(warnSpy).not.toHaveBeenCalled();
@@ -130,10 +131,10 @@ describe("validateGdprHookCompleteness (V2)", () => {
 
   test("multiple features, one missing delete → one warn per missing hook", () => {
     const good = defineFeature("good", (r) => {
-      r.useExtension("userData", "entityA", { export: exportFn, delete: deleteFn });
+      r.useExtension(EXT_USER_DATA, "entityA", { export: exportFn, delete: deleteFn });
     });
     const bad = defineFeature("bad", (r) => {
-      r.useExtension("userData", "entityB", { export: exportFn });
+      r.useExtension(EXT_USER_DATA, "entityB", { export: exportFn });
     });
     validateGdprHookCompleteness([good, bad]);
     expect(warnSpy).toHaveBeenCalledTimes(1);

package/src/engine/__tests__/boot-validator.test.ts

@@ -5,6 +5,7 @@ import { table, text } from "../../db/dialect";
 import { validateBoot } from "../boot-validator";
 import { createSystemConfig, createTenantConfig } from "../config-helpers";
 import {
+  createDerivedField,
   createEntity,
   createMultiSelectField,
   createTextField,
@@ -168,6 +169,56 @@ describe("boot-validator", () => {
     expect(() => validateBoot(features)).toThrow(/ENCRYPTION_KEY.*required/i);
   });
 
+  test("rejects encrypted text field that is also filterable", () => {
+    // AES-GCM draws a random IV per call, so the ciphertext is non-
+    // deterministic — an equality filter on it would never match, even
+    // against the identical plaintext.
+    process.env["ENCRYPTION_KEY"] = "test-key";
+    try {
+      const features = [
+        defineFeature("a", (r) => {
+          r.entity(
+            "doc",
+            createEntity({
+              table: "Docs",
+              fields: {
+                secret: { type: "text", encrypted: true, filterable: true },
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/secret.*encrypted and filterable/i);
+    } finally {
+      delete process.env["ENCRYPTION_KEY"];
+    }
+  });
+
+  test("rejects a unique index on an encrypted column", () => {
+    // Same non-determinism as the filterable case: a unique index can never
+    // detect a real duplicate plaintext behind two different ciphertexts.
+    process.env["ENCRYPTION_KEY"] = "test-key";
+    try {
+      const features = [
+        defineFeature("a", (r) => {
+          r.entity(
+            "doc",
+            createEntity({
+              table: "Docs",
+              fields: {
+                secret: { type: "text", encrypted: true },
+              },
+              indexes: [{ columns: ["secret"], unique: true }],
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/secret.*encrypted.*unique index/i);
+    } finally {
+      delete process.env["ENCRYPTION_KEY"];
+    }
+  });
+
   // --- index-validator longText block ---
 
   test("rejects longText field in entity.indexes (longText is not indexable)", () => {
@@ -309,6 +360,46 @@ describe("boot-validator", () => {
     );
   });
 
+  // --- derivedFields / fields collision ---
+
+  test("throws when a derivedFields key conflicts with a stored field", () => {
+    const features = [
+      defineFeature("a", (r) => {
+        r.entity(
+          "item",
+          createEntity({
+            table: "Items",
+            fields: { status: createTextField() },
+            derivedFields: {
+              status: createDerivedField({ valueType: "text", derive: () => "computed" }),
+            },
+          }),
+        );
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(
+      /entity "item".*derivedFields key "status".*conflicts/i,
+    );
+  });
+
+  test("passes when derivedFields keys don't conflict with stored fields", () => {
+    const features = [
+      defineFeature("a", (r) => {
+        r.entity(
+          "item",
+          createEntity({
+            table: "Items",
+            fields: { status: createTextField() },
+            derivedFields: {
+              statusLabel: createDerivedField({ valueType: "text", derive: () => "computed" }),
+            },
+          }),
+        );
+      }),
+    ];
+    expect(() => validateBoot(features)).not.toThrow();
+  });
+
   // --- Config key cross-feature references ---
 
   test("throws when readsConfig references non-existent key", () => {
@@ -1195,6 +1286,13 @@ describe("boot-validator", () => {
         ]),
       ).toThrow(/tags/);
     });
+
+    test("labeled column on a non-field WITHOUT a renderer → Throw (label alone isn't enough)", () => {
+      // Regression (697/1): renderer is what actually draws a virtual column —
+      // a label with no renderer would push an empty, unrendered column into
+      // the view model instead of a real typo-guard.
+      expect(() => validateBoot([noteFeature({ field: "tags", label: "Tags" })])).toThrow(/tags/);
+    });
   });
 
   // --- entityList: pagination + sort validation ---
@@ -1981,6 +2079,118 @@ describe("boot-validator", () => {
       });
       expect(() => validateBoot([list, consumer])).not.toThrow();
     });
+
+    test("cross-feature navigate to an entityEdit screen WITHOUT entityId → Throw", () => {
+      // Regression: the renderer's same-feature row["id"] fallback never
+      // fires for a cross-feature target, so the edit screen would silently
+      // open with no entity context at runtime. The validator must catch it
+      // at boot instead.
+      const list = defineFeature("shop", (r) => {
+        r.entity("product", createEntity({ fields: { name: createTextField() } }));
+        r.screen({
+          id: "product-list",
+          type: "entityList",
+          entity: "product",
+          columns: ["name"],
+          rowActions: [
+            { kind: "navigate", id: "edit", label: "actions.edit", screen: "invoice-edit" },
+          ],
+        });
+      });
+      const consumer = defineFeature("billing", (r) => {
+        r.entity("invoice", createEntity({ fields: { name: createTextField() } }));
+        r.screen({
+          id: "invoice-edit",
+          type: "entityEdit",
+          entity: "invoice",
+          layout: { sections: [{ columns: 1, fields: ["name"] }] },
+        });
+      });
+      expect(() => validateBoot([list, consumer])).toThrow(
+        /rowAction "edit".*cross-feature to entityEdit screen "invoice-edit".*without an explicit entityId/,
+      );
+    });
+
+    test("cross-feature navigate to an entityEdit screen WITH entityId → kein Throw", () => {
+      const list = defineFeature("shop", (r) => {
+        r.entity(
+          "product",
+          createEntity({ fields: { name: createTextField(), invoiceId: createTextField() } }),
+        );
+        r.screen({
+          id: "product-list",
+          type: "entityList",
+          entity: "product",
+          columns: ["name"],
+          rowActions: [
+            {
+              kind: "navigate",
+              id: "edit",
+              label: "actions.edit",
+              screen: "invoice-edit",
+              entityId: "invoiceId",
+            },
+          ],
+        });
+      });
+      const consumer = defineFeature("billing", (r) => {
+        r.entity("invoice", createEntity({ fields: { name: createTextField() } }));
+        r.screen({
+          id: "invoice-edit",
+          type: "entityEdit",
+          entity: "invoice",
+          layout: { sections: [{ columns: 1, fields: ["name"] }] },
+        });
+      });
+      expect(() => validateBoot([list, consumer])).not.toThrow();
+    });
+
+    test("same-feature navigate to entityEdit WITHOUT entityId → kein Throw (same-feature fallback applies)", () => {
+      const feature = defineFeature("shop", (r) => {
+        r.entity("product", createEntity({ fields: { name: createTextField() } }));
+        r.screen({
+          id: "product-list",
+          type: "entityList",
+          entity: "product",
+          columns: ["name"],
+          rowActions: [
+            { kind: "navigate", id: "edit", label: "actions.edit", screen: "product-edit" },
+          ],
+        });
+        r.screen({
+          id: "product-edit",
+          type: "entityEdit",
+          entity: "product",
+          layout: { sections: [{ columns: 1, fields: ["name"] }] },
+        });
+      });
+      expect(() => validateBoot([feature])).not.toThrow();
+    });
+  });
+
+  // --- Screen short-id collision across features ---
+  describe("screen short-id collisions across features", () => {
+    test("two features registering the same short screen-id → Throw", () => {
+      const a = defineFeature("shop", (r) => {
+        r.screen({ id: "settings", type: "custom", renderer: { react: "stub" } });
+      });
+      const b = defineFeature("billing", (r) => {
+        r.screen({ id: "settings", type: "custom", renderer: { react: "stub" } });
+      });
+      expect(() => validateBoot([a, b])).toThrow(
+        /Screen short-id "settings" is registered by 2 features \(shop, billing\)/,
+      );
+    });
+
+    test("distinct short-ids across features → kein Throw", () => {
+      const a = defineFeature("shop", (r) => {
+        r.screen({ id: "shop-settings", type: "custom", renderer: { react: "stub" } });
+      });
+      const b = defineFeature("billing", (r) => {
+        r.screen({ id: "billing-settings", type: "custom", renderer: { react: "stub" } });
+      });
+      expect(() => validateBoot([a, b])).not.toThrow();
+    });
   });
 
   // --- Tier 2.7e: rowAction rowClick (Row-Body-Klick) ---

package/src/engine/__tests__/build-config-feature-schema.test.ts

@@ -256,6 +256,27 @@ describe("buildConfigFeatureSchema — access + workspace", () => {
     expect(out.navs.find((n) => n.id === "audience-tenant")?.access).toEqual({ openToAll: true });
   });
 
+  test("openToAll collapse holds regardless of key declaration order (516/2)", () => {
+    // The test above only ever puts the openToAll key first, so
+    // unionAccessRules's short-circuit (`if ("openToAll" in rule) return`)
+    // never actually has to walk past a role-restricted rule to prove it —
+    // `gated` here comes FIRST so a hypothetical short-circuit-on-first-only
+    // implementation would fail this one even though it passed the other.
+    const mixedWriteReversed = defineFeature("mixedwritereversed", (r) => {
+      r.config({
+        keys: {
+          gated: createTenantConfig("text", { mask: { title: "mwr.gated" } }), // default admin write
+          open: createTenantConfig("text", { write: access.all, mask: { title: "mwr.open" } }),
+        },
+      });
+    });
+    const out = buildConfigFeatureSchema(createRegistry([mixedWriteReversed]));
+    const screen = out.screens.find((s) => s.id === "mixedwritereversed-tenant");
+    if (screen?.type !== "configEdit")
+      throw new Error('expected configEdit screen "mixedwritereversed-tenant"');
+    expect(screen.access).toEqual({ openToAll: true });
+  });
+
   test("returns empty (no workspace) when no key opts into the hub via mask", () => {
     const plain = defineFeature("plain", (r) => {
       r.config({ keys: { secret: createSystemConfig("text", {}) } });

package/src/engine/__tests__/define-feature-entity-mapping.test.ts

@@ -29,8 +29,14 @@ describe("defineFeature — bare CRUD verb → entity mapping", () => {
   });
 
   test("feature-name match wins (the fallback is the secondary path)", () => {
+    // Two entities (516/1): with only "note" registered, this would also
+    // pass via the single-entity fallback, proving nothing about the
+    // name-match branch specifically. A second entity ("tag") disables the
+    // fallback (entityKeys.length !== 1), so success here can only come
+    // from entities[name] matching — the branch this test claims to cover.
     const f = defineFeature("note", (r) => {
       r.entity("note", noteEntity);
+      r.entity("tag", tagEntity);
       r.writeHandler(bareCreate);
     });
     expect(f.handlerEntityMappings?.["create"]).toBe("note");