@cosmicdrift/kumiko-framework 0.209.1 → 0.210.0

package/src/engine/__tests__/field-access.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { checkWriteFieldRoles, filterReadFields, PII_MASKED_VALUE } from "../field-access";
+import { checkWriteFieldRoles, filterReadFields } from "../field-access";
 import type { EntityDefinition } from "../types";
 
 const entity: EntityDefinition = {
@@ -26,28 +26,6 @@ describe("filterReadFields", () => {
     expect(filtered["secret"]).toBe("visible");
   });
 
-  test("masks piiEncrypted fields instead of stripping them (kumiko-platform#463)", () => {
-    const entityWithPii: EntityDefinition = {
-      fields: {
-        ...entity.fields,
-        iban: {
-          type: "text",
-          piiEncrypted: true,
-          tenantOwned: true,
-          access: { read: { admin: "all" } },
-        },
-      },
-    };
-    const row = { id: 1, title: "Hello", secret: "hidden", iban: "DE89370400440532013000" };
-
-    const filteredForEditor = filterReadFields(entityWithPii, row, editor);
-    expect(filteredForEditor["secret"]).toBeUndefined();
-    expect(filteredForEditor["iban"]).toBe(PII_MASKED_VALUE);
-
-    const filteredForAdmin = filterReadFields(entityWithPii, row, admin);
-    expect(filteredForAdmin["iban"]).toBe("DE89370400440532013000");
-  });
-
   test("filters each row of an embedded list, keeping it an array", () => {
     const entityWithLines: EntityDefinition = {
       fields: {

package/src/engine/__tests__/store-table.test.ts

@@ -204,7 +204,10 @@ describe("createRegistry — store tables with PII-annotated fields (#820)", ()
     table: "rt_pii_probe",
     fields: {
       userId: createTextField({ required: true }),
-      ip: createTextField({ userOwned: { ownerField: "userId" } }),
+      ip: createTextField({
+        personal: { of: "userId" },
+        find: "none",
+      }),
     },
   });
   const piiMeta = deriveEntityTableMeta("rt-pii-probe", piiEntity, { source: "unmanaged" });

package/src/engine/boot-validator/pii-retention.ts

@@ -1,5 +1,5 @@
 import type { FeatureDefinition } from "../types";
-import type { FieldAccess, PiiAnnotations } from "../types/fields";
+import type { ResolvedPiiFlags } from "../types/fields";
 import {
   PII_DIRECT_NAME_HINTS,
   PII_USER_OWNED_NAME_HINTS,
@@ -24,7 +24,7 @@ const KEEP_FOR_PATTERN = /^\d+[hdwmy]$/;
 // A field carries a subject binding — pii/userOwned/tenantOwned mark
 // annotated content, subjectRef marks a bare FK into `user` with no
 // annotated content of its own but the same Art.17 obligations (#1645).
-function hasSubjectAnnotation(annot: PiiAnnotations): boolean {
+function hasSubjectAnnotation(annot: ResolvedPiiFlags): boolean {
   return Boolean(annot.pii || annot.userOwned || annot.tenantOwned || annot.subjectRef);
 }
 
@@ -43,7 +43,7 @@ function hasSubjectAnnotation(annot: PiiAnnotations): boolean {
 //
 // 3. Heuristik-Warnings: Field-Namen die typischerweise PII enthalten
 //    (email, name, phone, body, etc.) ohne Annotation → Boot-Warning.
-//    Mit `allowPlaintext: "<reason>"` unterdrückbar (geht in Audit).
+//    Mit `{ personal: false, reason: "<reason>" }` unterdrückbar (geht in Audit).
 //
 // 4. Retention-Integrity: retention.reference (wenn gesetzt) muss auf
 //    ein bestehendes Field zeigen (oder Framework-Timestamp). retention.
@@ -57,12 +57,12 @@ export function validatePiiAndRetention(feature: FeatureDefinition): void {
     const fieldsByName = entity.fields;
 
     for (const [fieldName, field] of Object.entries(fieldsByName)) {
-      // PiiAnnotations-Properties sind type-level optional. Auf Field-
-      // Defs die nicht via "& PiiAnnotations" erweitert sind (Boolean,
+      // ResolvedPiiFlags-Properties sind type-level optional. Auf Field-
+      // Defs die nicht via "& ResolvedPiiFlags" erweitert sind (Boolean,
       // Money, Reference, Embedded, Tz, LocatedTimestamp, File*, Image*)
       // liefert property-access undefined zur Runtime. Die TS-Compile-
       // Time-Validation hat dort schon abgelehnt → Cast ist safe.
-      const annot = field as PiiAnnotations; // @cast-boundary schema-walk
+      const annot = field as ResolvedPiiFlags; // @cast-boundary schema-walk
 
       const hasPii = Boolean(annot.pii);
       const hasUserOwned = Boolean(annot.userOwned);
@@ -71,7 +71,7 @@ export function validatePiiAndRetention(feature: FeatureDefinition): void {
 
       if (annotCount > 1) {
         throw new Error(
-          `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has multiple subject-key annotations (pii / userOwned / tenantOwned). Pick one — each field belongs to exactly one subject.`,
+          `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has multiple subject-key annotations (personal: "self" / "tenant" / { of: "<field>" }). Pick one — each field belongs to exactly one subject.`,
         );
       }
 
@@ -81,48 +81,16 @@ export function validatePiiAndRetention(feature: FeatureDefinition): void {
       if (annot.lookupable === true) {
         if (field.type !== "text") {
           throw new Error(
-            `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares { lookupable: true } but has type "${field.type}" — blind-index equality lookups only apply to text fields.`,
+            `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares find: "exact" (or "fuzzy") but has type "${field.type}" — blind-index equality lookups only apply to text fields.`,
           );
         }
         if (annotCount === 0) {
           throw new Error(
-            `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares { lookupable: true } without a subject annotation (pii / userOwned / tenantOwned). Plaintext fields don't need a blind index — add the subject annotation or drop lookupable.`,
+            `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares find: "exact" (or "fuzzy") without a subject annotation (personal: "self" / "tenant" / { of: "<field>" }). Plaintext fields don't need a blind index — add personal or set find: "none".`,
           );
         }
       }
 
-      // piiEncrypted (kumiko-platform#231/#456): a declarative alias over
-      // the subject-KMS — text only (storage stays the plaintext column
-      // with subject ciphertext, no separate envelope path).
-      const piiEncryptedFlag = field as { readonly piiEncrypted?: boolean }; // @cast-boundary schema-walk
-      if (piiEncryptedFlag.piiEncrypted === true && field.type !== "text") {
-        throw new Error(
-          `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares { piiEncrypted: true } but has type "${field.type}" — piiEncrypted only applies to text fields.`,
-        );
-      }
-      // piiEncrypted wiring (kumiko-platform#457): resolveSubjectForField/
-      // collectPiiSubjectFields only ever look at pii/userOwned/tenantOwned
-      // — piiEncrypted alone doesn't pick a subject. Without one of the
-      // three, the field would silently stay plaintext (no encrypt-on-
-      // write happens). Fail at boot like lookupable does, not at first read.
-      if (piiEncryptedFlag.piiEncrypted === true && annotCount === 0) {
-        throw new Error(
-          `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares { piiEncrypted: true } without a subject annotation (pii / userOwned / tenantOwned) — piiEncrypted alone doesn't encrypt anything, it only adds the access/masking layer on top of the subject-key encryption.`,
-        );
-      }
-      // piiEncrypted access model (kumiko-platform#460): field-level
-      // access.read already exists + is enforced (filterReadFields), but
-      // its default without an access config is "visible to everyone" —
-      // the wrong default for a field whose entire point is "only the
-      // legitimate owner may see the plaintext". Force an explicit choice
-      // instead of silently decrypting for every row-reader.
-      const accessFlag = field as { readonly access?: FieldAccess }; // @cast-boundary schema-walk
-      if (piiEncryptedFlag.piiEncrypted === true && !accessFlag.access?.read) {
-        throw new Error(
-          `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares { piiEncrypted: true } without { access: { read: [...] } } — without it the decrypted value is visible to anyone who can read the row. Set the roles allowed to see the plaintext.`,
-        );
-      }
-
       // sensitive-Felder liegen seit #967 als Tabellen-Ciphertext im Event-
       // Log — ohne ciphertext-at-rest würde der Append Klartext in die
       // immutable History schreiben.
@@ -136,7 +104,7 @@ export function validatePiiAndRetention(feature: FeatureDefinition): void {
         sensitiveFlags.encrypted !== true
       ) {
         throw new Error(
-          `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares { sensitive: true } without ciphertext-at-rest. Since #967 the event log stores sensitive fields as table ciphertext — add a subject annotation (pii / userOwned / tenantOwned) or { encrypted: true }.`,
+          `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares { sensitive: true } without ciphertext-at-rest. Since #967 the event log stores sensitive fields as table ciphertext — add a subject annotation (personal: "self" / "tenant" / { of: "<field>" }) or { encrypted: true }.`,
         );
       }
 
@@ -152,9 +120,9 @@ export function validatePiiAndRetention(feature: FeatureDefinition): void {
           readonly sortable?: boolean;
           readonly sensitive?: boolean;
         }; // @cast-boundary schema-walk
-        if ((annotCount > 0 || piiEncryptedFlag.piiEncrypted === true) && flags.sortable === true) {
+        if (annotCount > 0 && flags.sortable === true) {
           throw new Error(
-            `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" combines a subject-key annotation or { piiEncrypted: true } with { sortable: true } — sorting reads the projection column, which is ciphertext at rest. For equality lookups use { lookupable: true }; drop sortable or keep the field plaintext (allowPlaintext).`,
+            `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" combines a subject-key annotation with { sortable: true } — sorting reads the projection column, which is ciphertext at rest. For equality lookups use find: "exact"; drop sortable or keep the field plaintext (personal: false).`,
           );
         }
         if (flags.sensitive === true && flags.searchable === true) {
@@ -168,14 +136,14 @@ export function validatePiiAndRetention(feature: FeatureDefinition): void {
         const ownerName = annot.userOwned.ownerField;
         if (!ownerName || typeof ownerName !== "string") {
           throw new Error(
-            `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has userOwned without ownerField name`,
+            `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has personal: { of: ... } without an owner field name`,
           );
         }
         const ownerField = fieldsByName[ownerName];
         if (!ownerField) {
           const known = Object.keys(fieldsByName).sort().join(", ");
           throw new Error(
-            `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" references userOwned.ownerField "${ownerName}" but no such field exists. Known fields: ${known}`,
+            `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" references personal.of "${ownerName}" but no such field exists. Known fields: ${known}`,
           );
         }
         // Text is accepted alongside reference: the ES-framework carries
@@ -185,7 +153,7 @@ export function validatePiiAndRetention(feature: FeatureDefinition): void {
         // ownerField (the field's own value IS the owner id) rides on this.
         if (ownerField.type !== "reference" && ownerField.type !== "text") {
           throw new Error(
-            `[Feature ${feature.name}] userOwned.ownerField "${ownerName}" on entity "${entityName}" must be a reference or text (userId) field, got type "${ownerField.type}"`,
+            `[Feature ${feature.name}] personal.of "${ownerName}" on entity "${entityName}" must be a reference or text (userId) field, got type "${ownerField.type}"`,
           );
         }
         // Soft-Warning wenn das reference-target nicht offensichtlich user
@@ -197,7 +165,7 @@ export function validatePiiAndRetention(feature: FeatureDefinition): void {
           if (targetEntity !== "user") {
             // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
             console.warn(
-              `[kumiko:boot] [Feature ${feature.name}] userOwned.ownerField "${ownerName}" on entity "${entityName}" targets reference "${refTarget}" — typically should be a user reference. If intentional (custom subject-entity like employee/patient), ignore.`,
+              `[kumiko:boot] [Feature ${feature.name}] personal.of "${ownerName}" on entity "${entityName}" targets reference "${refTarget}" — typically should be a user reference. If intentional (custom subject-entity like employee/patient), ignore.`,
             );
           }
         }
@@ -206,24 +174,24 @@ export function validatePiiAndRetention(feature: FeatureDefinition): void {
       // PII-Heuristik: nur wenn keine Annotation gesetzt UND kein
       // allowPlaintext-Marker. Ergibt false positives auf Geschäftsdaten
       // mit personenartigem Namen (z.B. company.legalName) — Author
-      // unterdrückt mit { allowPlaintext: "is-business-data" }.
+      // unterdrückt mit { personal: false, reason: "is_business_data" }.
       const noAnnotation = annotCount === 0 && !annot.allowPlaintext;
       if (noAnnotation) {
         const lower = fieldName.toLowerCase();
         if (PII_DIRECT_NAME_HINTS.has(lower)) {
           // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
           console.warn(
-            `[kumiko:boot] [Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has a PII-typical name but no { pii: true } annotation. If this is PII, mark it. If business data, set { allowPlaintext: "is-business-data" } to silence.`,
+            `[kumiko:boot] [Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has a PII-typical name but no personal annotation. If this is PII, mark it { personal: "self", find: ... }. If business data, set { personal: false, reason: "is_business_data" } to silence.`,
           );
         } else if (PII_USER_OWNED_NAME_HINTS.has(lower)) {
           // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
           console.warn(
-            `[kumiko:boot] [Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has a user-content-typical name but no { userOwned } annotation. If this contains user-generated content, mark it { userOwned: { ownerField: "<authorIdField>" }}. If business data, set { allowPlaintext: "..." } to silence.`,
+            `[kumiko:boot] [Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has a user-content-typical name but no personal annotation. If this contains user-generated content, mark it { personal: { of: "<authorIdField>" }, find: ... }. If business data, set { personal: false, reason: "..." } to silence.`,
           );
         } else if (PII_USER_REFERENCE_NAME_HINTS.has(lower) && !annot.subjectRef) {
           // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
           console.warn(
-            `[kumiko:boot] [Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has a user-reference-typical name but no { subjectRef: true } annotation — a foreign key into \`user\` carries Art.17 obligations even with no annotated content on the entity. Mark it { subjectRef: true } AND register r.useExtension(EXT_USER_DATA, "${entityName}", …) — without the hook the V3 boot guard throws. Or { userOwned: { ownerField: "${fieldName}" } } on the field it owns. If business data, set { allowPlaintext: "..." } to silence.`,
+            `[kumiko:boot] [Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has a user-reference-typical name but no personal annotation — a foreign key into \`user\` carries Art.17 obligations even with no annotated content on the entity. Mark it { personal: "ref" } AND register r.useExtension(EXT_USER_DATA, "${entityName}", …) — without the hook the V3 boot guard throws. Or { personal: { of: "${fieldName}" } } on the field it owns. If business data, set { personal: false, reason: "..." } to silence.`,
           );
         }
       }
@@ -254,10 +222,10 @@ export function validatePiiAndRetention(feature: FeatureDefinition): void {
         // blockDelete on an entity with no subject field is the correct
         // "never auto-delete" choice; User-Forget never reaches those rows (#1622).
         const hasSubjectField = Object.values(fieldsByName).some(
-          (f) => hasSubjectAnnotation(f as PiiAnnotations), // @cast-boundary schema-walk
+          (f) => hasSubjectAnnotation(f as ResolvedPiiFlags), // @cast-boundary schema-walk
         );
         const hasAnonymize = Object.values(fieldsByName).some((f) => {
-          const a = f as PiiAnnotations; // @cast-boundary schema-walk
+          const a = f as ResolvedPiiFlags; // @cast-boundary schema-walk
           return Boolean(a.anonymize);
         });
         if (hasSubjectField && !hasAnonymize) {

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

@@ -139,9 +139,17 @@ export function buildConfigFeatureSchema(registry: Registry): ConfigFeatureSchem
       const shortId = `${feature}-${scope}`;
 
       screens.push(buildScreen(shortId, scope, feature, ordered, access, declaredTranslationKeys));
+      // A tenant/user-home key with an elevated write role (SystemAdmin on a
+      // tenant key, see ELEVATED_ROLES) surfaces the SAME feature under two
+      // audience navs (cascade-default screen + home screen) — both would
+      // otherwise carry the identical `${feature}.settings` label. Opt-in
+      // scoped override (`${feature}.settings.${scope}`) disambiguates only
+      // where a feature actually declares one; every single-scope feature
+      // keeps the plain key unchanged.
+      const scopedLabel = `${feature}.settings.${scope}`;
       navs.push({
         id: shortId,
-        label: `${feature}.settings`,
+        label: declaredTranslationKeys.has(scopedLabel) ? scopedLabel : `${feature}.settings`,
         parent: audienceNavShortId(scope),
         screen: shortId,
         icon: ordered[0]?.def.mask?.icon ?? "settings",

package/src/engine/factories.ts

@@ -10,6 +10,7 @@ import type {
   FieldsMap,
   FileFieldDef,
   FilesFieldDef,
+  Findability,
   ImageFieldDef,
   ImagesFieldDef,
   JsonbFieldDef,
@@ -18,6 +19,11 @@ import type {
   MoneyFieldDef,
   MultiSelectFieldDef,
   NumberFieldDef,
+  PersonalAnnotations,
+  PersonalAnnotationsLongText,
+  PersonalAnnotationsNoFind,
+  PersonalSubject,
+  ResolvedPiiFlags,
   RetentionDef,
   SelectFieldDef,
   TextFieldDef,
@@ -25,6 +31,56 @@ import type {
   TzFieldDef,
 } from "./types";
 
+type PersonalOverridesInput = {
+  readonly personal?: PersonalSubject | "ref" | false;
+  readonly find?: Findability;
+  readonly reason?: string;
+  readonly anonymize?: () => unknown | Promise<unknown>;
+};
+
+// Resolves the author-facing `personal`/`find` annotations (kumiko-framework#2250)
+// into the internal ResolvedPiiFlags every factory below merges into its
+// return value. `personal`, `find`, `reason` never survive into the field def.
+function expandPersonalAnnotations<T extends PersonalOverridesInput>(
+  overrides: T | undefined,
+): Omit<T, "personal" | "find" | "reason"> & ResolvedPiiFlags {
+  if (!overrides) {
+    return {} as Omit<T, "personal" | "find" | "reason"> & ResolvedPiiFlags;
+  }
+  const { personal, find, reason, anonymize, ...rest } = overrides;
+
+  let personalFlags: ResolvedPiiFlags = {};
+  if (personal === "self") {
+    personalFlags = { pii: true };
+  } else if (personal === "tenant") {
+    personalFlags = { tenantOwned: true };
+  } else if (personal === "ref") {
+    personalFlags = { subjectRef: true };
+  } else if (personal === false) {
+    personalFlags = { allowPlaintext: reason };
+  } else if (personal) {
+    personalFlags = { userOwned: { ownerField: personal.of } };
+  }
+
+  // `searchable`/`sensitive` live on the individual FieldDef, not on
+  // ResolvedPiiFlags — "fuzzy"/"secret" resolve into those too.
+  let findFlags: ResolvedPiiFlags & { searchable?: boolean; sensitive?: boolean } = {};
+  if (find === "exact") {
+    findFlags = { lookupable: true };
+  } else if (find === "fuzzy") {
+    findFlags = { lookupable: true, searchable: true };
+  } else if (find === "secret") {
+    findFlags = { sensitive: true };
+  }
+
+  return {
+    ...rest,
+    ...personalFlags,
+    ...findFlags,
+    ...(anonymize ? { anonymize } : {}),
+  } as Omit<T, "personal" | "find" | "reason"> & ResolvedPiiFlags;
+}
+
 // Generic über `R extends true | false` (statt `boolean`) damit
 // `createTextField({ required: true })` literal `required: true` im
 // Return-Type behält. `boolean` würde widenen — EntityTable<E>'s
@@ -33,7 +89,8 @@ import type {
 // degradieren. Default `R = false` matcht den runtime-default. Pattern
 // in jeder required-bearing factory unten.
 export function createTextField<R extends true | false = false>(
-  overrides?: Partial<Omit<TextFieldDef, "type" | "required">> & { required?: R },
+  overrides?: Partial<Omit<TextFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> &
+    PersonalAnnotations & { required?: R },
 ): TextFieldDef & { required: R } {
   return {
     type: "text",
@@ -41,7 +98,7 @@ export function createTextField<R extends true | false = false>(
     required: false,
     searchable: false,
     sortable: false,
-    ...overrides,
+    ...expandPersonalAnnotations(overrides),
   } as TextFieldDef & { required: R }; // @cast-boundary engine-payload
 }
 
@@ -67,12 +124,13 @@ export function createDerivedField(spec: DerivedFieldDef): DerivedFieldDef {
 }
 
 export function createLongTextField<R extends true | false = false>(
-  overrides?: Partial<Omit<LongTextFieldDef, "type" | "required">> & { required?: R },
+  overrides?: Partial<Omit<LongTextFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> &
+    PersonalAnnotationsLongText & { required?: R },
 ): LongTextFieldDef & { required: R } {
   return {
     type: "longText",
     required: false,
-    ...overrides,
+    ...expandPersonalAnnotations(overrides),
   } as LongTextFieldDef & { required: R }; // @cast-boundary engine-payload
 }
 
@@ -92,13 +150,14 @@ export function createSelectField<
   R extends true | false = false,
 >(
   opts: { options: TOptions } & Partial<
-    Omit<SelectFieldDef<TOptions>, "type" | "options" | "required">
-  > & { required?: R },
+    Omit<SelectFieldDef<TOptions>, "type" | "options" | "required" | keyof ResolvedPiiFlags>
+  > &
+    PersonalAnnotationsNoFind & { required?: R },
 ): SelectFieldDef<TOptions> & { required: R } {
   return {
     type: "select",
     required: false,
-    ...opts,
+    ...expandPersonalAnnotations(opts),
   } as SelectFieldDef<TOptions> & { required: R }; // @cast-boundary engine-payload
 }
 
@@ -124,12 +183,15 @@ export function createSelectField<
  * Wann statt `embedded` mit Booleans: bei mehr als ~5 Optionen.
  */
 export function createMultiSelectField<const TOptions extends readonly string[]>(
-  opts: { options: TOptions } & Partial<Omit<MultiSelectFieldDef<TOptions>, "type" | "options">>,
+  opts: { options: TOptions } & Partial<
+    Omit<MultiSelectFieldDef<TOptions>, "type" | "options" | keyof ResolvedPiiFlags>
+  > &
+    PersonalAnnotationsNoFind,
 ): MultiSelectFieldDef<TOptions> {
   return {
     type: "multiSelect",
     required: false,
-    ...opts,
+    ...expandPersonalAnnotations(opts),
   };
 }
 
@@ -140,22 +202,24 @@ export function createMultiSelectField<const TOptions extends readonly string[]>
  * instead (money-adjacent math)? Use `createDecimalField` (`numeric`).
  */
 export function createNumberField<R extends true | false = false>(
-  overrides?: Partial<Omit<NumberFieldDef, "type" | "required">> & { required?: R },
+  overrides?: Partial<Omit<NumberFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> &
+    PersonalAnnotationsNoFind & { required?: R },
 ): NumberFieldDef & { required: R } {
   return {
     type: "number",
     required: false,
-    ...overrides,
+    ...expandPersonalAnnotations(overrides),
   } as NumberFieldDef & { required: R }; // @cast-boundary engine-payload
 }
 
 export function createBigIntField<R extends true | false = false>(
-  overrides?: Partial<Omit<BigIntFieldDef, "type" | "required">> & { required?: R },
+  overrides?: Partial<Omit<BigIntFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> &
+    PersonalAnnotationsNoFind & { required?: R },
 ): BigIntFieldDef & { required: R } {
   return {
     type: "bigInt",
     required: false,
-    ...overrides,
+    ...expandPersonalAnnotations(overrides),
   } as BigIntFieldDef & { required: R }; // @cast-boundary engine-payload
 }
 
@@ -164,8 +228,9 @@ export function createBigIntField<R extends true | false = false>(
 // caveat (surfaced as JS number, safe ≤ 2^53).
 export function createDecimalField<R extends true | false = false>(
   config: { precision: number; scale: number } & Partial<
-    Omit<DecimalFieldDef, "type" | "precision" | "scale" | "required">
-  > & { required?: R },
+    Omit<DecimalFieldDef, "type" | "precision" | "scale" | "required" | keyof ResolvedPiiFlags>
+  > &
+    PersonalAnnotationsNoFind & { required?: R },
 ): DecimalFieldDef & { required: R } {
   // Fail at definition time, not at the first migration: numeric(p,s) requires
   // integer p ≥ 1 and 0 ≤ s ≤ p (Postgres rejects e.g. numeric(2,4), and the
@@ -186,7 +251,7 @@ export function createDecimalField<R extends true | false = false>(
   return {
     type: "decimal",
     required: false,
-    ...config,
+    ...expandPersonalAnnotations(config),
   } as DecimalFieldDef & { required: R }; // @cast-boundary engine-payload
 }
 
@@ -201,12 +266,13 @@ export function createMoneyField<R extends true | false = false>(
 
 export function createEmbeddedField(
   schema: EmbeddedFieldDef["schema"],
-  overrides?: Partial<Omit<EmbeddedFieldDef, "type" | "schema">>,
+  overrides?: Partial<Omit<EmbeddedFieldDef, "type" | "schema" | keyof ResolvedPiiFlags>> &
+    PersonalAnnotationsNoFind,
 ): EmbeddedFieldDef {
   return {
     type: "embedded",
     schema,
-    ...overrides,
+    ...expandPersonalAnnotations(overrides),
   };
 }
 
@@ -221,12 +287,15 @@ export function createEmbeddedField(
 // silently fall back to the single-object column type.
 export function createEmbeddedListField(
   schema: EmbeddedFieldDef["schema"],
-  overrides?: Partial<Omit<EmbeddedFieldDef, "type" | "schema" | "multiple">>,
+  overrides?: Partial<
+    Omit<EmbeddedFieldDef, "type" | "schema" | "multiple" | keyof ResolvedPiiFlags>
+  > &
+    PersonalAnnotationsNoFind,
 ): EmbeddedFieldDef & { multiple: true } {
   return {
     type: "embedded",
     schema,
-    ...overrides,
+    ...expandPersonalAnnotations(overrides),
     multiple: true,
   };
 }
@@ -235,20 +304,24 @@ export function createEmbeddedListField(
 // `{}`, NOT NULL. Hauptnutzer: custom-fields-Bundle (host-entity's
 // `customFields`-Spalte). Andere valid uses: tenant-config-blobs, AI-
 // inferred-metadata, future tags-arrays.
-export function createJsonbField(overrides?: Partial<Omit<JsonbFieldDef, "type">>): JsonbFieldDef {
+export function createJsonbField(
+  overrides?: Partial<Omit<JsonbFieldDef, "type" | keyof ResolvedPiiFlags>> &
+    PersonalAnnotationsNoFind,
+): JsonbFieldDef {
   return {
     type: "jsonb",
-    ...overrides,
+    ...expandPersonalAnnotations(overrides),
   };
 }
 
 export function createDateField<R extends true | false = false>(
-  overrides?: Partial<Omit<DateFieldDef, "type" | "required">> & { required?: R },
+  overrides?: Partial<Omit<DateFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> &
+    PersonalAnnotationsNoFind & { required?: R },
 ): DateFieldDef & { required: R } {
   return {
     type: "date",
     required: false,
-    ...overrides,
+    ...expandPersonalAnnotations(overrides),
   } as DateFieldDef & { required: R }; // @cast-boundary engine-payload
 }
 
@@ -261,13 +334,14 @@ export function createDateField<R extends true | false = false>(
  * das EIN atomares Feld statt eines lose verdrahteten Pairs erzeugt.
  */
 export function createTimestampField<R extends true | false = false>(
-  overrides?: Partial<Omit<TimestampFieldDef, "type" | "required">> & { required?: R },
+  overrides?: Partial<Omit<TimestampFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> &
+    PersonalAnnotationsNoFind & { required?: R },
 ): TimestampFieldDef & { required: R } {
   // Object-Build vermeidet hartcodiertes `required: false` im literal —
   // das würde TS dazu bringen, R auf `boolean` zu widenen statt das
   // literal `true`/`false` aus dem overrides-Argument zu inferieren.
   return {
-    ...overrides,
+    ...expandPersonalAnnotations(overrides),
     type: "timestamp",
     required: (overrides?.required ?? false) as R, // @cast-boundary engine-payload
   };
@@ -278,12 +352,13 @@ export function createTimestampField<R extends true | false = false>(
  * via `Intl.supportedValuesOf("timeZone")` geprüft (kommt im Zod-Schritt).
  */
 export function createTzField<R extends true | false = false>(
-  overrides?: Partial<Omit<TzFieldDef, "type" | "required">> & { required?: R },
+  overrides?: Partial<Omit<TzFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> &
+    PersonalAnnotationsNoFind & { required?: R },
 ): TzFieldDef & { required: R } {
   return {
     type: "tz",
     required: false,
-    ...overrides,
+    ...expandPersonalAnnotations(overrides),
   } as TzFieldDef & { required: R }; // @cast-boundary engine-payload
 }
 
@@ -318,12 +393,15 @@ export function createTzField<R extends true | false = false>(
  * separater Berechnung.
  */
 export function createLocatedTimestampField<R extends true | false = false>(
-  overrides?: Partial<Omit<LocatedTimestampFieldDef, "type" | "required">> & { required?: R },
+  overrides?: Partial<
+    Omit<LocatedTimestampFieldDef, "type" | "required" | keyof ResolvedPiiFlags>
+  > &
+    PersonalAnnotationsNoFind & { required?: R },
 ): LocatedTimestampFieldDef & { required: R } {
   return {
     type: "locatedTimestamp",
     required: false,
-    ...overrides,
+    ...expandPersonalAnnotations(overrides),
   } as LocatedTimestampFieldDef & { required: R }; // @cast-boundary engine-payload
 }
 

package/src/engine/field-access.ts

@@ -2,13 +2,6 @@ import type { DbRow } from "../db/connection";
 import { normalizeAccessEntry, userCanReadFieldRow, userCanWriteFieldRow } from "./ownership";
 import type { EntityDefinition, SessionUser } from "./types";
 
-// piiEncrypted fields deliberately break that silence (kumiko-platform#463):
-// the field's whole point is "a legitimate reader may see the plaintext",
-// so an unauthorized reader seeing the field exist-but-masked is the
-// intended signal, not a leak — unlike a secret whose existence itself
-// should stay hidden.
-export const PII_MASKED_VALUE = "••••••";
-
 // Field-level read filtering. Returns a copy of `data` with fields stripped
 // if the user's roles don't grant read access OR the ownership-rule for the
 // matching role doesn't accept this concrete row. Fields without access
@@ -18,8 +11,7 @@ export const PII_MASKED_VALUE = "••••••";
 // one place in the ownership system where silence is the right default:
 // reporting "you tried to read X but can't" leaks the field's existence.
 // Writes do the opposite (loud error) because a silent drop there masks
-// save-bugs. piiEncrypted fields are the one exception — see
-// PII_MASKED_VALUE above.
+// save-bugs.
 export function filterReadFields(
   entity: EntityDefinition,
   data: Readonly<Record<string, unknown>>,
@@ -37,10 +29,7 @@ export function filterReadFields(
 
     const accessMap = normalizeAccessEntry(field.access?.read);
     if (!userCanReadFieldRow(user, accessMap, data)) {
-      if ("piiEncrypted" in field && field.piiEncrypted === true) {
-        result[key] = PII_MASKED_VALUE;
-      }
-      continue; // entire field stripped (masked instead, for piiEncrypted)
+      continue; // entire field stripped
     }
 
     // For embedded fields: filter sub-fields with access restrictions.

package/src/engine/index.ts

@@ -341,6 +341,7 @@ export type {
   FieldRenderer,
   FileFieldDef,
   FilesFieldDef,
+  Findability,
   HandlerContext,
   HasManyRelation,
   HookMap,
@@ -357,6 +358,7 @@ export type {
   KumikoHandlerResultMap,
   LifecycleHookType,
   ListColumnSpec,
+  LongTextFindability,
   ManyToManyRelation,
   MspErrorMode,
   MspErrorPolicy,
@@ -376,7 +378,10 @@ export type {
   NotifyPriority,
   NumberFieldDef,
   OnDeleteStrategy,
-  PiiAnnotations,
+  PersonalAnnotations,
+  PersonalAnnotationsLongText,
+  PersonalAnnotationsNoFind,
+  PersonalSubject,
   PlatformComponent,
   PostDeleteHookFn,
   PostSaveHookFn,
@@ -392,6 +397,7 @@ export type {
   ReferenceDataDef,
   Registry,
   RelationDefinition,
+  ResolvedPiiFlags,
   RetentionDef,
   RowAction,
   SaveContext,