@cosmicdrift/kumiko-framework 0.209.1 → 0.211.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.209.1",
+  "version": "0.211.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>",
@@ -190,7 +190,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.209.1",
+    "@cosmicdrift/kumiko-types": "0.211.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -206,7 +206,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.209.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.211.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/__tests__/entity-permalink-open.integration.test.ts

@@ -26,7 +26,12 @@ import {
 const noteEntity = createEntity({
   table: "read_permalink_notes",
   fields: {
-    title: createTextField({ required: true, maxLength: 160, allowPlaintext: "is-business-data" }),
+    title: createTextField({
+      required: true,
+      maxLength: 160,
+      personal: false,
+      reason: "is_business_data",
+    }),
   },
 });
 

package/src/changes.json

@@ -1,4 +1,60 @@
 [
+  {
+    "version": "0.209.1",
+    "type": "breaking",
+    "title": "Job runs no longer go through the event store; read_job_runs table renamed to store_job_runs (fw#2243).",
+    "detail": "Job runs (jobRun) no longer go through the event store. Every job execution used to append a run-started + run-completed/run-failed event replayed through two inline projections — in the busiest apps this was ~99% of all events ever written, for data nothing else replays or subscribes to. onJobStart/onJobComplete/onJobFailed now write straight into the (renamed) store_job_runs / store_job_run_logs tables, with a new daily jobs:job:retention-cleanup job (retentionDays, default 30) purging old rows so the tables don't grow forever.",
+    "migration": "Breaking for raw-SQL consumers: the table is renamed read_job_runs → store_job_runs (store_job_run_logs is unchanged). The migration drops read_job_runs outright — old run history is not preserved, it was operational/debug data, not a system of record. Apps that only use the shipped job-runs-screen/jobs:query:* handlers are unaffected; apps with a raw SQL dependency on read_job_runs need a follow-up on their side."
+  },
+  {
+    "version": "0.201.0",
+    "type": "breaking",
+    "title": "IdempotencyGuard.check()/.store() gain a discriminated result + token param on top of the 0.198.0 signature (fw#2139).",
+    "detail": "Fixes two idempotency-lock races that could let a duplicate request re-run a write handler or silently overwrite a fresher cached result. `waitTimeoutMs` (how long a duplicate request waits for the in-flight one) is now clamped to always exceed `pendingTtlSeconds` (the in-progress lock's own TTL) — previously the defaults (30s lock vs. 25s wait) let a retry give up and re-execute the handler while the original call was still legitimately running. `IdempotencyGuard.store()` now does an atomic compare-and-swap against the exact lock token the calling run acquired (Redis EVAL) instead of an unconditional SET, so a stale, slow-finishing run can no longer stomp the result a reclaiming run already persisted after the lock expired. `IdempotencyGuard.check()` now returns a discriminated `{ status: \"cached\", result }` / `{ status: \"acquired\", token }` union instead of `string | null`, and `store()` takes the acquired token as a new parameter.",
+    "migration": "Layered on top of the 0.198.0 signature change: check() is now check(tenantId, userId, requestId) returning { status: \"cached\", result } | { status: \"acquired\", token }; store() is now store(tenantId, userId, requestId, token). Both call sites in this repo (dispatch-batch.ts, the dispatcher test mock) are already updated; any code outside this repo calling IdempotencyGuard directly needs the same update."
+  },
+  {
+    "version": "0.201.0",
+    "type": "breaking",
+    "title": "GET /files/:id now sniffs bytes and serves svg/txt/csv/json/md as application/octet-stream instead of inline (fw#2140).",
+    "detail": "GET /files/:id served the stored mimeType as Content-Type without verifying it against the file's actual bytes — a client can declare any MIME at upload time, so an attacker could upload real HTML/SVG content and have it served back with a trusted-looking Content-Type from the app origin, enabling stored XSS. Uploads themselves are still accepted regardless of declared MIME (this is unchanged); the fix hardens serving instead. The download route now sniffs the file's magic bytes and only serves the sniffed Content-Type inline when it matches a known-safe binary signature (png/jpeg/gif/webp/pdf) AND matches the declared MIME from upload. Anything else — including a genuine mismatch, or file types with no reliable binary signature such as svg/txt/csv/json/md — is now served as application/octet-stream. This also adds X-Content-Type-Options: nosniff to GET /files/:id, which previously had none.",
+    "migration": "Breaking for consumers that render uploaded svg/txt/csv/json/md files inline (e.g. an <img src> pointing at GET /files/:id): those now download as application/octet-stream instead of rendering. Route such content through a purpose-built safe viewer if inline rendering is required."
+  },
+  {
+    "version": "0.198.0",
+    "type": "breaking",
+    "title": "IdempotencyGuard.check/.store signature changed to (tenantId, userId, requestId); SqlExpression is branded (fw#2049).",
+    "detail": "Security hardening (audit \"Welle 2\"): closes a request-supplied-JSON-can-forge-raw-SQL path and a cross-tenant idempotency-cache collision. `SqlExpression` is now branded — only the `sql` template tag and `sql.raw(...)` produce a value the query layer recognizes as raw SQL; an object literal built by hand (`{ kind: \"sql-expr\", sql: ..., params: ... }`) is no longer treated as raw SQL and gets bound as an ordinary JSON parameter instead, surfacing as a broken query rather than a silent vulnerability. `IdempotencyGuard.check`/`.store` moved from `(requestId)` to `(tenantId, userId, requestId)` so the idempotency cache can no longer be hit across tenants/users by an attacker who guesses or replays a requestId; the Redis key format changed from `${prefix}${requestId}` to `${prefix}${tenantId}:${userId}:${requestId}` with no compatibility shim.",
+    "migration": "Replace any hand-built SqlExpression object literal with the `sql` tag or `sql.raw(...)`. Any custom IdempotencyGuard implementation, or code calling `.check`/`.store` directly (outside the dispatcher's own runBatch, which already updated), needs the new (tenantId, userId, requestId) signature. On deploy, in-flight idempotent retries older than the request's own retry window may execute a second time — same as a first-ever request, not a correctness issue, just not a cache hit."
+  },
+  {
+    "version": "0.198.0",
+    "type": "breaking",
+    "title": "event-store-executor.list() now throws 422 search_adapter_not_wired instead of returning unfiltered results (fw#2032).",
+    "detail": "event-store-executor.list() silently dropped payload.search when no SearchAdapter was wired (neither at build time via options.searchAdapter nor at runtime via runtimeOptions.searchAdapter) — the list came back unfiltered, indistinguishable from a real search result. Now throws UnprocessableError (code: \"unprocessable\", details.reason: \"search_adapter_not_wired\", details.entity) instead.",
+    "migration": "Breaking for consumers whose entities are searchable but have no SearchAdapter wired: a search request that used to silently no-op now returns a 422. Wire a SearchAdapter (e.g. Meilisearch) for the entity, or stop marking the field/screen searchable."
+  },
+  {
+    "version": "0.198.0",
+    "type": "breaking",
+    "title": "NavIconKey closed union replaces icon?: string on nav/config-mask definitions (fw#2055).",
+    "detail": "NavDefinition.icon, ContentCollectionDefinition.nav.icon, ScreenNavSugar.icon and ConfigMask.icon were all icon?: string — any typo (icon: \"seting\") compiled fine and silently fell back to a dot in the sidebar. New NavIconKey union (@cosmicdrift/kumiko-types/nav-icon, re-exported from @cosmicdrift/kumiko-framework/{engine,ui-types}) types all four against the closed set of keys the web renderer actually registers, so an unregistered icon key is now a compile error at the r.nav()/r.screen({ nav })/config-mask call site instead of a missing icon at runtime. packages/renderer-web's NAV_ICONS map is checked against the same union via `as const satisfies Record<NavIconKey, …>`, so the type and the map can no longer drift.",
+    "migration": "Breaking for any app that passes an icon key outside the vocabulary in packages/types/src/nav-icon.ts — such a call site will fail to compile after this bump. Fix the typo or add the missing key to both NavIconKey and renderer-web's NAV_ICONS map in the same change."
+  },
+  {
+    "version": "0.193.0",
+    "type": "breaking",
+    "title": "Image fields get named derived variants; ImageFieldDef/ImagesFieldDef.thumbnails removed (fw#1973).",
+    "detail": "createImageField now accepts variants: Record<string, VariantSpec> — boot-validated named derived-image specs, served via GET /api/files/:id/variant/:name behind the same tenant + access guard as the download. A request carries only a NAME, never a spec, so no caller can drive an arbitrary render. The edit-form preview loads the first declared variant instead of the original.",
+    "migration": "ImageFieldDef.thumbnails / ImagesFieldDef.thumbnails are removed — the flag was never read by anything. Replace any reliance on it with a declared variants entry."
+  },
+  {
+    "version": "0.189.0",
+    "type": "breaking",
+    "title": "createDateField now backs a real Postgres DATE column, round-trips as Temporal.PlainDate (fw#1924).",
+    "detail": "type:\"date\" fields were silently aliased onto the same instant()/TIMESTAMPTZ column as type:\"timestamp\": reads returned a full ISO instant (\"2026-03-15T00:00:00Z\"), writes expected a bare \"yyyy-mm-dd\" string bound to a timestamptz column through the session's TimeZone — both directions were timezone-dependent for what is meant to be a pure calendar-day value. A date field now serializes as \"2026-03-15\" (Temporal.PlainDate's own toJSON()); a non-form client that Instant-parses a date field's JSON value now throws. Write shape is unchanged (bare \"yyyy-mm-dd\").",
+    "migration": "Managed (event-sourced projection) tables: the generator emits DROP TABLE + CREATE TABLE and replays from the event log automatically — factor in replay cost for entities with a large event history. Unmanaged (store_*, direct-write) tables: the generator emits an in-place ALTER TABLE … ALTER COLUMN … TYPE date USING (col AT TIME ZONE 'UTC')::date, anchored explicitly at UTC — do not hand-write a bare ALTER COLUMN … TYPE date without USING, which falls back to Postgres's session-TimeZone-dependent implicit cast."
+  },
   {
     "version": "0.177.0",
     "type": "breaking",

package/src/crypto/__tests__/blind-index.test.ts

@@ -24,7 +24,7 @@ const TEST_KEY = decodeBlindIndexKey(TEST_KEY_B64);
 
 const userLikeEntity = createEntity({
   fields: {
-    email: createTextField({ required: true, pii: true, lookupable: true }),
+    email: createTextField({ required: true, personal: "self", find: "exact" }),
     role: createTextField(),
   },
   table: "bidx_users",

package/src/crypto/__tests__/pii-field-encryption.test.ts

@@ -26,7 +26,7 @@ const KMS_CTX: KmsContext = { requestId: "test" };
 
 const userLikeEntity = createEntity({
   fields: {
-    email: createTextField({ required: true, pii: true }),
+    email: createTextField({ required: true, personal: "self", find: "none" }),
     role: createTextField(),
   },
   table: "pii_users",
@@ -34,7 +34,10 @@ const userLikeEntity = createEntity({
 
 const commentEntity = createEntity({
   fields: {
-    body: createTextField({ userOwned: { ownerField: "authorId" } }),
+    body: createTextField({
+      personal: { of: "authorId" },
+      find: "none",
+    }),
     authorId: createTextField({ required: true }),
   },
   table: "pii_comments",
@@ -42,7 +45,10 @@ const commentEntity = createEntity({
 
 const brandingEntity = createEntity({
   fields: {
-    brandColor: createTextField({ tenantOwned: true }),
+    brandColor: createTextField({
+      personal: "tenant",
+      find: "none",
+    }),
   },
   table: "pii_branding",
 });
@@ -225,14 +231,14 @@ describe("encryptPiiFieldValues / decryptPiiFieldValues", () => {
   });
 });
 
-describe("piiEncrypted alias (kumiko-platform#457)", () => {
-  test("piiEncrypted + tenantOwned round-trips through the same subject-KMS pipeline", async () => {
+describe("tenant-owned field encryption (kumiko-platform#457)", () => {
+  test("tenant-owned field round-trips through the subject-KMS pipeline", async () => {
     const kms = new InMemoryKmsAdapter();
     const brandingWithAccess = createEntity({
       fields: {
         iban: createTextField({
-          piiEncrypted: true,
-          tenantOwned: true,
+          personal: "tenant",
+          find: "none",
           access: { read: ["TenantAdmin"] },
         }),
       },
@@ -250,11 +256,11 @@ describe("piiEncrypted alias (kumiko-platform#457)", () => {
     expect(read["iban"]).toBe("DE89370400440532013000");
   });
 
-  test("piiEncrypted field is covered by subject erasure (Art. 17, kumiko-platform#461)", async () => {
+  test("tenant-annotated field becomes unreadable after subject erasure (Art. 17, kumiko-platform#461)", async () => {
     const kms = new InMemoryKmsAdapter();
     const brandingWithAccess = createEntity({
       fields: {
-        iban: createTextField({ piiEncrypted: true, tenantOwned: true }),
+        iban: createTextField({ personal: "tenant", find: "none" }),
       },
       table: "pii_branding_iban_erasure",
     });
@@ -263,7 +269,7 @@ describe("piiEncrypted alias (kumiko-platform#457)", () => {
     const stored = await encryptPiiFieldValues(row, brandingWithAccess, fields, kms, KMS_CTX);
 
     // Erasure is subject-keyed, not field-flag-keyed — kms.eraseKey doesn't
-    // know or care that this field is piiEncrypted vs. plain tenantOwned.
+    // know or care about the field's `personal` annotation, just the subject.
     await kms.eraseKey({ kind: "tenant", tenantId: UUID_B });
 
     const read = await decryptPiiFieldValues(stored, fields, kms, KMS_CTX);

package/src/crypto/__tests__/subject-resolver.test.ts

@@ -8,7 +8,7 @@ import {
 
 const userLikeEntity = createEntity({
   fields: {
-    email: createTextField({ required: true, pii: true }),
+    email: createTextField({ required: true, personal: "self", find: "none" }),
     role: createTextField(),
   },
   table: "resolver_users",
@@ -17,7 +17,10 @@ const userLikeEntity = createEntity({
 
 const commentEntity = createEntity({
   fields: {
-    body: createTextField({ userOwned: { ownerField: "authorId" } }),
+    body: createTextField({
+      personal: { of: "authorId" },
+      find: "none",
+    }),
     authorId: createTextField({ required: true }),
   },
   table: "resolver_comments",
@@ -25,7 +28,10 @@ const commentEntity = createEntity({
 
 const brandingEntity = createEntity({
   fields: {
-    brandColor: createTextField({ tenantOwned: true }),
+    brandColor: createTextField({
+      personal: "tenant",
+      find: "none",
+    }),
   },
   table: "resolver_branding",
 });

package/src/db/__tests__/blind-index.integration.test.ts

@@ -36,7 +36,7 @@ const TEST_KEY = decodeBlindIndexKey(TEST_KEY_B64);
 const personEntity = createEntity({
   table: "read_bidx_persons",
   fields: {
-    email: createTextField({ required: true, pii: true, lookupable: true }),
+    email: createTextField({ required: true, personal: "self", find: "exact" }),
     firstName: createTextField(),
   },
 });

package/src/db/__tests__/cursor.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { decodeCursor, encodeCursor } from "../cursor";
+import { decodeCursor, decodeKeysetCursor, encodeCursor, encodeKeysetCursor } from "../cursor";
 
 describe("encodeCursor / decodeCursor", () => {
   test("round-trips string ids", () => {
@@ -15,3 +15,28 @@ describe("encodeCursor / decodeCursor", () => {
     expect(() => decodeCursor(encodeCursor(""))).toThrow(/Invalid cursor/);
   });
 });
+
+describe("encodeKeysetCursor / decodeKeysetCursor", () => {
+  test("round-trips a sort value alongside the id", () => {
+    const id = "0194a1b2-c3d4-7890-abcd-ef1234567890";
+    const decoded = decodeKeysetCursor(encodeKeysetCursor("2026-03-01", id));
+    expect(decoded).toEqual({ id, sortValue: "2026-03-01" });
+  });
+
+  test("round-trips a null sort value as null, not undefined", () => {
+    const id = "0194a1b2-c3d4-7890-abcd-ef1234567890";
+    const decoded = decodeKeysetCursor(encodeKeysetCursor(null, id));
+    expect(decoded.sortValue).toBeNull();
+  });
+
+  test("decodes a legacy id-only cursor with sortValue undefined", () => {
+    const decoded = decodeKeysetCursor(encodeCursor("abc-123"));
+    expect(decoded).toEqual({ id: "abc-123", sortValue: undefined });
+  });
+
+  test("treats a JSON payload that isn't a valid keyset cursor as a legacy id", () => {
+    const cursor = encodeCursor('{"nope":1}');
+    expect(() => decodeKeysetCursor(cursor)).not.toThrow();
+    expect(decodeKeysetCursor(cursor)).toEqual({ id: '{"nope":1}', sortValue: undefined });
+  });
+});

package/src/db/__tests__/eagerload.integration.test.ts

@@ -49,7 +49,7 @@ const contactEntity = createEntity({
   table: "el_contacts",
   fields: {
     name: createTextField({ required: true }),
-    email: createTextField({ required: true, tenantOwned: true }),
+    email: createTextField({ required: true, personal: "tenant", find: "none" }),
     iban: createTextField({ required: true, encrypted: true }),
   },
 });
@@ -71,7 +71,7 @@ const ownedContactEntity = createEntity({
   table: "el_owned_contacts",
   fields: {
     name: createTextField({ required: true }),
-    email: createTextField({ required: true, tenantOwned: true }),
+    email: createTextField({ required: true, personal: "tenant", find: "none" }),
     iban: createTextField({ required: true, encrypted: true }),
   },
   access: { read: { admin: from("user:id", "ownerId") } },
@@ -85,7 +85,7 @@ const unrestrictedContactEntity = createEntity({
   table: "el_unrestricted_contacts",
   fields: {
     name: createTextField({ required: true }),
-    email: createTextField({ required: true, tenantOwned: true }),
+    email: createTextField({ required: true, personal: "tenant", find: "none" }),
   },
   access: { read: { admin: "all", member: "all" } },
 });

package/src/db/__tests__/entity-table-meta-source.test.ts

@@ -15,7 +15,10 @@ const entity = createEntity({
   table: "source-probe",
   fields: {
     userId: createTextField({ required: true }),
-    ip: createTextField({ userOwned: { ownerField: "userId" } }),
+    ip: createTextField({
+      personal: { of: "userId" },
+      find: "none",
+    }),
   },
 });
 

package/src/db/__tests__/event-store-executor-context.pii-roundtrip.test.ts

@@ -20,7 +20,7 @@ describe("event-store-executor-context — encryptForStorage/decryptForRead laye
       // Both markers at once — the auth-mfa.totpSecret/recoveryCodes shape
       // that first surfaced the ordering bug (pii-subject-encryption
       // integration test).
-      secretNote: createTextField({ encrypted: true, userOwned: { ownerField: "userId" } }),
+      secretNote: createTextField({ encrypted: true, personal: { of: "userId" }, find: "none" }),
     },
   });
   const encryption = createTestEnvelopeCipher(TEST_KEY);

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

@@ -7,11 +7,12 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db";
 import { asRawClient } from "../../db/query";
-import { createEntity, createNumberField, createTextField } from "../../engine";
+import { createDateField, createEntity, createNumberField, createTextField } from "../../engine";
 import { UnprocessableError } from "../../errors";
 import { createEventsTable } from "../../event-store";
 import { TestUsers, unsafeCreateEntityTable } from "../../stack";
 import { ensureTemporalPolyfill } from "../../time/polyfill";
+import { encodeCursor } from "../cursor";
 import { createEventStoreExecutor } from "../event-store-executor";
 import { buildEntityTable } from "../table-builder";
 import { createTenantDb, type TenantDb } from "../tenant-db";
@@ -21,6 +22,7 @@ const entity = createEntity({
   fields: {
     title: createTextField({ required: true, sortable: true }),
     rank: createNumberField({ sortable: true }),
+    dueDate: createDateField({ sortable: true }),
   },
 });
 const table = buildEntityTable("pagerItem", entity);
@@ -498,3 +500,144 @@ describe("event-store-executor.list — runtime SearchAdapter (Tier 2.7e Audit-F
     expect(res.rows).toHaveLength(0);
   });
 });
+
+describe("event-store-executor.list — keyset cursor mit custom sort (#2265)", () => {
+  const exec = createEventStoreExecutor(table, entity, { entityName: "pagerItem" });
+
+  async function collectPages(
+    sort: string,
+    direction: "asc" | "desc",
+    pageSize: number,
+  ): Promise<{ ids: string[]; iterations: number }> {
+    const ids: string[] = [];
+    let cursor: string | undefined;
+    let iterations = 0;
+    while (iterations < 10) {
+      iterations++;
+      const res = await exec.list(
+        { limit: pageSize, cursor, sort, sortDirection: direction },
+        admin,
+        tdb,
+      );
+      ids.push(...res.rows.map((r) => r["id"] as string));
+      if (res.nextCursor === null) break;
+      cursor = res.nextCursor;
+    }
+    return { ids, iterations };
+  }
+
+  test("Issue-Repro: Seite 2 dupliziert nicht mehr die letzte Zeile von Seite 1 und überspringt nicht die älteste", async () => {
+    await exec.create({ title: "re-1001", dueDate: "2026-01-15" }, admin, tdb);
+    await exec.create({ title: "re-1002", dueDate: "2026-02-15" }, admin, tdb);
+    await exec.create({ title: "re-1003", dueDate: "2026-03-15" }, admin, tdb);
+
+    const page1 = await exec.list({ limit: 2, sort: "dueDate", sortDirection: "desc" }, admin, tdb);
+    expect(page1.rows.map((r) => r["title"])).toEqual(["re-1003", "re-1002"]);
+    expect(page1.nextCursor).not.toBeNull();
+
+    const page2 = await exec.list(
+      {
+        limit: 2,
+        cursor: page1.nextCursor ?? undefined,
+        sort: "dueDate",
+        sortDirection: "desc",
+        totalCount: true,
+      },
+      admin,
+      tdb,
+    );
+    expect(page2.rows.map((r) => r["title"])).toEqual(["re-1001"]);
+    expect(page2.rows.map((r) => r["title"])).not.toContain("re-1003");
+    // total reuses the same WHERE (cursor boundary included) as the page
+    // query — this pins that the keyset boundary's extra param doesn't
+    // desync the shared `params` array between the two queries.
+    expect(page2.total).toBe(1);
+  });
+
+  test.each(["asc", "desc"] as const)(
+    "Voll-Sweep mit Ties (sort=dueDate, %s) matcht die Referenz-Abfrage exakt",
+    async (direction) => {
+      // Interleaved seed order (round-robin across dueDates) decorrelates
+      // uuidv7 id order from dueDate order — a grouped seed (all of date A,
+      // then all of date B, ...) would leave id order and asc-dueDate order
+      // coincidentally identical, letting the pre-fix id-only cursor
+      // boundary pass this test by accident.
+      const dueDates = ["2026-01-10", "2026-02-10", "2026-03-10", "2026-04-10"];
+      for (let i = 0; i < 3; i++) {
+        for (const dueDate of dueDates) {
+          await exec.create({ title: `tie-${dueDate}-${i}`, dueDate }, admin, tdb);
+        }
+      }
+
+      const reference = await exec.list(
+        { limit: 50, sort: "dueDate", sortDirection: direction },
+        admin,
+        tdb,
+      );
+      const referenceIds = reference.rows.map((r) => r["id"] as string);
+      expect(referenceIds).toHaveLength(12);
+
+      const { ids, iterations } = await collectPages("dueDate", direction, 5);
+      expect(iterations).toBeLessThan(10);
+      expect(ids).toEqual(referenceIds);
+      expect(new Set(ids).size).toBe(12);
+    },
+  );
+
+  test.each(["asc", "desc"] as const)(
+    "Voll-Sweep mit NULL dueDate (%s) matcht die Referenz-Abfrage exakt",
+    async (direction) => {
+      const seedPlan: Array<{ title: string; dueDate?: string }> = [
+        { title: "n-1" },
+        { title: "d-1", dueDate: "2026-01-05" },
+        { title: "n-2" },
+        { title: "d-2", dueDate: "2026-02-05" },
+        { title: "d-3", dueDate: "2026-01-05" },
+        { title: "n-3" },
+        { title: "d-4", dueDate: "2026-03-05" },
+        { title: "n-4" },
+        { title: "d-5", dueDate: "2026-02-05" },
+      ];
+      for (const row of seedPlan) {
+        await exec.create(
+          row.dueDate === undefined
+            ? { title: row.title }
+            : { title: row.title, dueDate: row.dueDate },
+          admin,
+          tdb,
+        );
+      }
+
+      const reference = await exec.list(
+        { limit: 50, sort: "dueDate", sortDirection: direction },
+        admin,
+        tdb,
+      );
+      const referenceIds = reference.rows.map((r) => r["id"] as string);
+      expect(referenceIds).toHaveLength(9);
+
+      const { ids, iterations } = await collectPages("dueDate", direction, 2);
+      expect(iterations).toBeLessThan(10);
+      expect(ids).toEqual(referenceIds);
+      expect(new Set(ids).size).toBe(9);
+    },
+  );
+
+  test("Rückwärtskompatibilität: legacy id-only Cursor + custom sort wirft nicht und fällt auf die id-Grenze zurück", async () => {
+    const created: string[] = [];
+    for (let i = 0; i < 5; i++) {
+      const res = await exec.create({ title: `legacy-${i}`, dueDate: "2026-05-01" }, admin, tdb);
+      if (!res.isSuccess) throw new Error("create failed");
+      created.push(String(res.data.id));
+    }
+    const legacyCursor = encodeCursor(created[0] as string);
+
+    const call = exec.list({ limit: 50, cursor: legacyCursor, sort: "dueDate" }, admin, tdb);
+    await expect(call).resolves.toBeDefined();
+
+    const res = await call;
+    const returnedIds = res.rows.map((r) => r["id"] as string);
+    expect(returnedIds).not.toContain(created[0]);
+    expect(returnedIds).toEqual(created.slice(1));
+  });
+});

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

@@ -693,8 +693,11 @@ describe("event-store-executor — entity cache + encrypted fields", () => {
 const piiEntity = createEntity({
   table: "read_es_exec_pii",
   fields: {
-    email: createTextField({ required: true, pii: true }),
-    note: createTextField({ userOwned: { ownerField: "authorId" } }),
+    email: createTextField({ required: true, personal: "self", find: "none" }),
+    note: createTextField({
+      personal: { of: "authorId" },
+      find: "none",
+    }),
     authorId: createTextField(),
     plain: createTextField(),
   },

package/src/db/__tests__/implicit-projection-equivalence.integration.test.ts

@@ -250,7 +250,7 @@ const sensitiveEntity = createEntity({
   table: sensitiveTable,
   fields: {
     email: createTextField({ required: true }),
-    apiKey: createTextField({ sensitive: true, pii: true, lookupable: true }),
+    apiKey: createTextField({ personal: "self", find: "exact" }),
   },
 });
 

package/src/db/cursor.ts

@@ -13,3 +13,35 @@ export function decodeCursor(cursor: string): string {
   if (decoded === "") throw new Error(`Invalid cursor: ${cursor}`);
   return decoded;
 }
+
+type KeysetCursorPayload = { readonly v: string | null; readonly i: string };
+
+export type DecodedKeysetCursor = {
+  readonly id: string;
+  // undefined = legacy id-only cursor still in flight from a client
+  readonly sortValue: string | null | undefined;
+};
+
+export function encodeKeysetCursor(sortValue: string | null, id: string): string {
+  return encodeCursor(JSON.stringify({ v: sortValue, i: id } satisfies KeysetCursorPayload));
+}
+
+export function decodeKeysetCursor(cursor: string): DecodedKeysetCursor {
+  const decoded = decodeCursor(cursor);
+  return parseKeysetPayload(decoded) ?? { id: decoded, sortValue: undefined };
+}
+
+function parseKeysetPayload(decoded: string): DecodedKeysetCursor | null {
+  if (!decoded.startsWith("{")) return null;
+  let raw: unknown;
+  try {
+    raw = JSON.parse(decoded);
+  } catch {
+    return null;
+  }
+  if (typeof raw !== "object" || raw === null) return null;
+  const { v, i } = raw as Record<string, unknown>;
+  if (typeof i !== "string" || i === "") return null;
+  if (v !== null && typeof v !== "string") return null;
+  return { id: i, sortValue: v };
+}