@cosmicdrift/kumiko-framework 0.322.0 → 0.323.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.322.0",
+  "version": "0.323.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>",
@@ -202,8 +202,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.322.0",
-    "@cosmicdrift/kumiko-types": "0.322.0",
+    "@cosmicdrift/kumiko-http": "0.323.0",
+    "@cosmicdrift/kumiko-types": "0.323.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -219,7 +219,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.322.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.323.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/auth-routes.ts

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import type { Context } from "hono";
 import { Hono } from "hono";
 import { deleteCookie, setCookie } from "hono/cookie";
+import type { ContentfulStatusCode } from "hono/utils/http-status";
 import type Redis from "ioredis";
 import * as z from "zod";
 import { buildSessionRoles } from "../engine/membership-roles";
@@ -13,7 +14,7 @@ import {
   SYSTEM_TENANT_ID,
   type TenantId,
 } from "../engine/types";
-import { NotFoundError } from "../errors";
+import { NotFoundError, toKumikoError, toWriteErrorInfo } from "../errors";
 import type { Dispatcher } from "../pipeline/dispatcher";
 import { assertUnreachable } from "../utils";
 import { parseRoles } from "../utils/serialization";
@@ -184,6 +185,10 @@ const InviteSignupCompleteBody = z.object({
   password: z.string().min(8).max(200),
 });
 
+const InviteInfoBody = z.object({
+  token: z.string().min(1),
+});
+
 // Shape guard for "handler not registered" — the only legitimate reason to
 // fall back to a single-tenant reply on /auth/tenants or /auth/switch-tenant.
 // Every other error (DB down, revoker throws, access denied, …) has to
@@ -503,6 +508,10 @@ export type InviteConfig = {
   readonly acceptHandler: string;
   readonly acceptWithLoginHandler: string;
   readonly signupCompleteHandler: string;
+  // Optional: qualified query handler name for the anonymous invite-info
+  // lookup (email + hasAccount for a pending invite, token not consumed).
+  // When unset, POST /auth/invite-info is not mounted.
+  readonly infoHandler?: string;
 };
 
 // Magic-Link Self-Signup. Anders als reset/verify NICHT HMAC-signed —
@@ -1315,6 +1324,39 @@ export function createAuthRoutes(
         ...landingPath,
       });
     });
+
+    // Anonymous, read-only invite lookup for the acceptance page: pre-fill
+    // the invited email and pick Branch 2 (existing account) vs Branch 3
+    // (new account) before the user submits. Token is never consumed here.
+    if (inv.infoHandler) {
+      const infoHandler = inv.infoHandler;
+      api.post(Routes.authInviteInfo, async (c) => {
+        const raw = await c.req.json().catch(() => null);
+        const parsed = InviteInfoBody.safeParse(raw);
+        if (!parsed.success) {
+          return c.json({ isSuccess: false, error: "invalid_body" }, 400);
+        }
+        try {
+          // @cast-boundary engine-payload — generic dispatcher.query result
+          const data = (await dispatcher.query(
+            infoHandler,
+            parsed.data,
+            createAnonymousUser(SYSTEM_TENANT_ID),
+          )) as { email: string; hasAccount: boolean };
+          return c.json({ isSuccess: true, ...data });
+        } catch (e) {
+          const err = toKumikoError(e);
+          // Same body shape as the write routes' `{ isSuccess: false, error:
+          // result.error }` (WriteErrorInfo) — this is a query, not a write,
+          // so there's no WriteResult to read `.error` off; toWriteErrorInfo
+          // builds the equivalent shape directly from the caught error.
+          return c.json(
+            { isSuccess: false, error: toWriteErrorInfo(err) },
+            err.httpStatus as ContentfulStatusCode, // @cast-boundary engine-payload
+          );
+        }
+      });
+    }
   }
 
   // POST /auth/logout — revokes the current session. Requires a valid JWT so

package/src/changes.json

@@ -1,4 +1,24 @@
 [
+  {
+    "version": "0.323.0",
+    "type": "improvement",
+    "title": "auth-routes: optional invite.infoHandler mounts POST /auth/invite-info",
+    "detail": "InviteConfig gained an optional infoHandler (qualified query-handler name). When set, createAuthRoutes mounts POST /auth/invite-info, dispatching the query anonymously and returning {isSuccess:true, email, hasAccount} or the query's serialized error.",
+    "migration": "No action needed: infoHandler is optional and existing invite configs without it are unaffected — the route simply isn't mounted."
+  },
+  {
+    "version": "0.323.0",
+    "type": "fix",
+    "title": "kms.eraseKey is now gated by the agent-risk floor for irreversible operations",
+    "migration": "`configurePiiSubjectKms(adapter)` now stores a wrapper whose `eraseKey`\nruns `assertIrreversibleOperationAllowed(\"kms.eraseKey\")` before\ndelegating — the same agent-risk floor `executor.forget()`/`delete()`\nalready enforce. A directly-dispatched write handler that calls\n`configuredPiiSubjectKms()!.eraseKey(...)` must resolve `agent.risk:\n\"high\"`, or the call is denied with `access_denied` /\n`irreversible_operation_requires_high_risk`.\n\nCron-triggered jobs and pipelines started by a `risk: \"high\"` handler are\nunaffected — they run outside any entry handler or already resolve\n\"high\". `crypto-shredding:write:forget-subject`, the manual\n`run-forget-cleanup` operator trigger, and framework-internal cleanup\nhooks already satisfy this."
+  },
+  {
+    "version": "0.323.0",
+    "type": "breaking",
+    "title": "createTextField/createLongTextField require an explicit personal-data stance",
+    "detail": "Both factories' `overrides` parameter is no longer optional and must\ninclude a `personal` stance:\n`{ personal: \"self\", find: \"exact\" | \"fuzzy\" | \"none\" | \"secret\" }`\n(longText: `find: \"none\" | \"secret\"`), `{ personal: \"tenant\", find: … }`,\n`{ personal: { of: \"<ownerField>\" }, find: … }`, `{ personal: \"ref\" }`, or\n`{ personal: false, reason: \"<why this is not personal data>\" }`. A\nmissing/malformed shape throws at the call site (`createTextField(...)` /\n`createLongTextField(...)` in the message, with every valid option\nlisted) instead of silently resolving to an unannotated field — this\nalso removes the #2918 boot-time deprecation warning, since the shape it\nwarned about can no longer be constructed.",
+    "migration": "Two call forms now throw: `createTextField()` / `createLongTextField()`\nwith no argument at all, and an options object with no `personal` key,\ne.g. `createTextField({ required: true })`. Add a stance to every call:\n\n  createTextField({ personal: \"self\", find: \"exact\" })\n  createTextField({ personal: \"tenant\", find: \"none\" })\n  createTextField({ personal: { of: \"authorId\" }, find: \"none\" })\n  createTextField({ personal: \"ref\" })\n  createTextField({ personal: false, reason: \"is_business_data\" })\n\n`personal: false` additionally requires a non-empty `reason` string.\n`find` is mandatory whenever `personal` names a subject (`\"self\"` /\n`\"tenant\"` / `{ of }`) — not for `\"ref\"` or `false`. The #2918 boot-time\ndeprecation warning for this shape is gone; there's nothing left for it\nto warn about.\n\nTo find remaining call sites (the #2919 codemod mode below is the\nmigration tool): `kumiko-guards guards\n--guard=\"Text-Field Personal-Stance Guard\"` flags every\nstatically-decidable call missing a stance. `bun\nnode_modules/@cosmicdrift/kumiko-framework/src/scripts/codemod/pii-personal-migration.ts\n<targetDir> --report-stance` classifies unannotated text/longText fields\nby name heuristic (direct/user-owned/user-reference/near-miss/\nunclassified) to help pick the right stance — it does not add one\nautomatically, since a wrong guess would be worse than the throw. This\ncodemod is not wired into `kumiko upgrade --apply`; run it by hand. It\nalso only transforms fields still carrying the OLD flag-based API\n(`pii`/`userOwned`/`tenantOwned`/`subjectRef`/`allowPlaintext`) — a field\nwith no annotation at all was never in its mapping table and needs a\nstance added by hand either way."
+  },
   {
     "version": "0.322.0",
     "type": "breaking",

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

@@ -13,6 +13,7 @@
 import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
 import type { EntityDefinition } from "../engine/types/fields";
 import type { TenantId } from "../engine/types/identifiers";
+import { assertIrreversibleOperationAllowed } from "../pipeline/irreversible-operation-gate";
 import {
   isLocalKeyKmsAdapter,
   KeyAlreadyExistsError,
@@ -231,6 +232,20 @@ export async function decryptPiiFieldValues(
 // (phase E); until then no production deployment can satisfy it.
 let injectedKms: LocalKeyKmsAdapter | undefined;
 
+// Explicit delegation: adapters are class instances with prototype methods (no spread/Object.create).
+function gateIrreversibleKmsErase(adapter: LocalKeyKmsAdapter): LocalKeyKmsAdapter {
+  return {
+    capabilities: adapter.capabilities,
+    createKey: (subject, ctx) => adapter.createKey(subject, ctx),
+    getKey: (subject, ctx) => adapter.getKey(subject, ctx),
+    health: () => adapter.health(),
+    eraseKey: async (subject, ctx) => {
+      assertIrreversibleOperationAllowed("kms.eraseKey");
+      await adapter.eraseKey(subject, ctx);
+    },
+  };
+}
+
 export function configurePiiSubjectKms(adapter: KmsAdapter | undefined): void {
   if (adapter !== undefined && !isLocalKeyKmsAdapter(adapter)) {
     throw new Error(
@@ -238,7 +253,7 @@ export function configurePiiSubjectKms(adapter: KmsAdapter | undefined): void {
         "(Vault transit) support lands with the BYOK adapter.",
     );
   }
-  injectedKms = adapter;
+  injectedKms = adapter && gateIrreversibleKmsErase(adapter);
 }
 
 export function configuredPiiSubjectKms(): LocalKeyKmsAdapter | undefined {

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

@@ -650,128 +650,6 @@ describe("validateBoot — PII annotations", () => {
     );
     expect(matchingWarn).toBeDefined();
   });
-
-  // --- #2918: deprecation warning for text fields without any stance ---
-
-  const NO_STANCE = "declares no personal stance";
-
-  test("text field without a personal stance warns, naming feature, entity and field", () => {
-    const feature = defineFeature("test", (r) => {
-      r.entity(
-        "invoice",
-        createEntity({
-          fields: {
-            externalRef: { ...unannotatedText },
-          },
-        }),
-      );
-    });
-    validateBoot([feature]);
-    const matchingWarn = warnSpy.mock.calls.find((args: unknown[]) =>
-      String(args[0]).includes(NO_STANCE),
-    );
-    expect(matchingWarn).toBeDefined();
-    const message = String((matchingWarn as unknown[])[0]);
-    expect(message).toContain("[Feature test]");
-    expect(message).toContain('Field "externalRef" on entity "invoice"');
-    expect(message).toContain('{ reason: "..." }');
-  });
-
-  test("longText field without a personal stance warns", () => {
-    const feature = defineFeature("test", (r) => {
-      r.entity(
-        "invoice",
-        createEntity({
-          fields: {
-            remarks: { ...unannotatedLongText },
-          },
-        }),
-      );
-    });
-    validateBoot([feature]);
-    const matchingWarn = warnSpy.mock.calls.find((args: unknown[]) =>
-      String(args[0]).includes(NO_STANCE),
-    );
-    expect(matchingWarn).toBeDefined();
-  });
-
-  test("personal: false with a reason silences the stance warning", () => {
-    const feature = defineFeature("test", (r) => {
-      r.entity(
-        "invoice",
-        createEntity({
-          fields: {
-            externalRef: createTextField({
-              personal: false,
-              reason: "is_business_data",
-            }),
-          },
-        }),
-      );
-    });
-    validateBoot([feature]);
-    const matchingWarn = warnSpy.mock.calls.find((args: unknown[]) =>
-      String(args[0]).includes(NO_STANCE),
-    );
-    expect(matchingWarn).toBeUndefined();
-  });
-
-  test("personal: self silences the stance warning", () => {
-    const feature = defineFeature("test", (r) => {
-      r.entity(
-        "invoice",
-        createEntity({
-          fields: {
-            externalRef: createTextField({
-              personal: "self",
-              find: "none",
-            }),
-          },
-        }),
-      );
-    });
-    validateBoot([feature]);
-    const matchingWarn = warnSpy.mock.calls.find((args: unknown[]) =>
-      String(args[0]).includes(NO_STANCE),
-    );
-    expect(matchingWarn).toBeUndefined();
-  });
-
-  test("personal: ref silences the stance warning", () => {
-    const feature = defineFeature("test", (r) => {
-      r.entity(
-        "invoice",
-        createEntity({
-          fields: {
-            ownerRef: createTextField({ personal: "ref" }),
-          },
-        }),
-      );
-    });
-    validateBoot([feature]);
-    const matchingWarn = warnSpy.mock.calls.find((args: unknown[]) =>
-      String(args[0]).includes(NO_STANCE),
-    );
-    expect(matchingWarn).toBeUndefined();
-  });
-
-  test("number field without a personal stance does not warn", () => {
-    const feature = defineFeature("test", (r) => {
-      r.entity(
-        "invoice",
-        createEntity({
-          fields: {
-            total: { type: "number", required: false },
-          },
-        }),
-      );
-    });
-    validateBoot([feature]);
-    const matchingWarn = warnSpy.mock.calls.find((args: unknown[]) =>
-      String(args[0]).includes(NO_STANCE),
-    );
-    expect(matchingWarn).toBeUndefined();
-  });
 });
 
 describe("validateBoot — retention", () => {

package/src/engine/__tests__/factories-long-text.test.ts

@@ -17,9 +17,11 @@ import type { LongTextFieldDef } from "../types";
 // =============================================================================
 
 describe("createLongTextField — runtime shape", () => {
-  test("default returns { type: 'longText', required: false }", () => {
-    const f = createLongTextField();
-    expect(f).toEqual({ type: "longText", required: false });
+  test("kumiko-framework#2921: no argument throws — a longText field must declare a personal stance", () => {
+    expect(() =>
+      // @ts-expect-error overrides (with a personal stance) is now required
+      createLongTextField(),
+    ).toThrow(/must declare an explicit personal-data stance/);
   });
 
   test("required: true is preserved as literal in the return type", () => {

package/src/engine/__tests__/factories-personal.test.ts

@@ -3,21 +3,84 @@
 // ../factories, exercised through the public factory functions.
 
 import { describe, expect, test } from "bun:test";
-import { createLongTextField, createTextField, createTimestampField } from "../factories";
+import {
+  createLongTextField,
+  createNumberField,
+  createTextField,
+  createTimestampField,
+} from "../factories";
 
 describe("createTextField — personal/find resolution", () => {
-  test("no annotation at all: no PII flags, no personal/find/reason leak into the field", () => {
-    const f = createTextField({ required: true });
-    expect(f).toEqual({
-      type: "text",
-      maxLength: 200,
-      required: true,
-      searchable: false,
-      sortable: false,
-    });
-    expect(f).not.toHaveProperty("personal");
-    expect(f).not.toHaveProperty("find");
-    expect(f).not.toHaveProperty("reason");
+  // kumiko-framework#2921 — a text field can no longer be constructed
+  // without declaring whose data it holds, neither at the type level nor
+  // at runtime (fail-closed for untyped JS callers).
+  test("no argument at all throws", () => {
+    expect(() =>
+      // @ts-expect-error overrides (with a personal stance) is now required
+      createTextField(),
+    ).toThrow(/must declare an explicit personal-data stance/);
+  });
+
+  test("options without `personal` throws", () => {
+    expect(() =>
+      // @ts-expect-error `personal` is required on the options object
+      createTextField({ required: true }),
+    ).toThrow(/createTextField\(\.\.\.\) must declare an explicit personal-data stance/);
+  });
+
+  test("an untyped JS caller passing null throws the same guidance instead of a raw TypeError", () => {
+    // Simulated untyped-boundary call — a real JS consumer has no compiler
+    // to reject this, so the runtime gate must catch it. Cast only here.
+    const call = () => createTextField(null as unknown as Parameters<typeof createTextField>[0]);
+    expect(call).toThrow(/must declare an explicit personal-data stance/);
+  });
+
+  test("an untyped JS caller passing personal: null throws the guidance message, not a raw TypeError", () => {
+    // Same untyped-boundary simulation, but `personal` itself is null
+    // instead of the whole options object — the object-branch subject
+    // check must not dereference `.of` on it.
+    const call = () =>
+      createTextField({ personal: null } as unknown as Parameters<typeof createTextField>[0]);
+    expect(call).toThrow(/must declare an explicit personal-data stance/);
+  });
+
+  test('personal: "self" without find throws', () => {
+    expect(() =>
+      // @ts-expect-error `find` is required alongside a named subject
+      createTextField({ personal: "self" }),
+    ).toThrow(/must declare an explicit personal-data stance/);
+  });
+
+  test("personal: false without a reason throws", () => {
+    expect(() =>
+      // @ts-expect-error `reason` is required alongside `personal: false`
+      createTextField({ personal: false }),
+    ).toThrow(/must declare an explicit personal-data stance/);
+  });
+
+  test("personal: false with a reason works", () => {
+    const f = createTextField({ personal: false, reason: "is_business_data" });
+    expect(f.allowPlaintext).toBe("is_business_data");
+  });
+
+  test("an invalid personal value throws and lists every valid stance", () => {
+    const call = () =>
+      createTextField({
+        // @ts-expect-error "yes" is not a valid personal stance
+        personal: "yes",
+      });
+    expect(call).toThrow(/must declare an explicit personal-data stance/);
+    try {
+      call();
+      throw new Error("expected createTextField to throw");
+    } catch (error) {
+      const message = String(error);
+      expect(message).toContain('personal: "self"');
+      expect(message).toContain('personal: "tenant"');
+      expect(message).toContain('personal: { of: "<ownerField>" }');
+      expect(message).toContain('personal: "ref"');
+      expect(message).toContain("personal: false, reason:");
+    }
   });
 
   test('personal: "self", find: "exact" → pii + lookupable', () => {
@@ -108,6 +171,16 @@ describe("createLongTextField — restricted find (PersonalAnnotationsLongText)"
     expect(f.lookupable).toBeUndefined();
     expect(f).not.toHaveProperty("searchable");
   });
+
+  test('find: "exact" is a createTextField-only value — createLongTextField rejects it', () => {
+    expect(() =>
+      createLongTextField({
+        personal: "self",
+        // @ts-expect-error "exact"/"fuzzy" don't exist on LongTextFindability
+        find: "exact",
+      }),
+    ).toThrow(/must declare an explicit personal-data stance/);
+  });
 });
 
 describe("createTimestampField — personal without find (PersonalAnnotationsNoFind)", () => {
@@ -127,4 +200,17 @@ describe("createTimestampField — personal without find (PersonalAnnotationsNoF
     const f = createTimestampField({ personal: false, reason: "server-generated, not user data" });
     expect(f.allowPlaintext).toBe("server-generated, not user data");
   });
+
+  // kumiko-framework#2921 only tightens text/longText — NoFind factories
+  // keep `personal` optional and stay callable without an argument.
+  test("createTimestampField() without any argument still works", () => {
+    const f = createTimestampField();
+    expect(f).toEqual({ type: "timestamp", required: false });
+  });
+
+  test("createNumberField() without any argument still works", () => {
+    const f = createNumberField();
+    expect(f.type).toBe("number");
+    expect(f).not.toHaveProperty("personal");
+  });
 });

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

@@ -213,14 +213,6 @@ export function validatePiiAndRetention(feature: FeatureDefinition): void {
           console.warn(
             `[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}", …) for Art.17 coverage — this warning is the only boot-time check for that, registering the hook is not enforced. Or { personal: { of: "${fieldName}" } } on the field it owns. If business data, set { personal: false, reason: "..." } to silence.`,
           );
-        } else if (!annot.subjectRef && (field.type === "text" || field.type === "longText")) {
-          // Deprecation step towards #2810, where a text field without a
-          // stance becomes a boot error. Only text/longText: the other field
-          // types keep `personal` optional.
-          // 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}" (type "${field.type}") declares no personal stance. Text fields will require one — this warning becomes a boot error in a future release (#2810). Declare { personal: "self" | "tenant" | "ref" | { of: "<ownerField>" } | false }; "false" additionally needs { reason: "..." } stating why the value is not personal data.`,
-          );
         }
       }
     }

package/src/engine/factories.ts

@@ -88,6 +88,77 @@ function expandPersonalAnnotations<T extends PersonalOverridesInput>(
   } as Omit<T, "personal" | "find" | "reason"> & ResolvedPiiFlags;
 }
 
+type TextFieldStanceFactory = "createTextField" | "createLongTextField";
+
+// `find` is mandatory once a subject is named (types require it — see
+// PersonalAnnotations / PersonalAnnotationsLongText), but the valid values
+// differ per factory: longText has no lookup/search machinery.
+const TEXT_FIELD_STANCE_FIND_VALUES: Record<TextFieldStanceFactory, readonly Findability[]> = {
+  createTextField: ["exact", "fuzzy", "none", "secret"],
+  createLongTextField: ["none", "secret"],
+};
+
+function textFieldStanceHint(factoryName: TextFieldStanceFactory): string {
+  const find = TEXT_FIELD_STANCE_FIND_VALUES[factoryName].map((f) => `"${f}"`).join(" | ");
+  return (
+    `{ personal: "self", find: ${find} }, ` +
+    `{ personal: "tenant", find: ${find} }, ` +
+    `{ personal: { of: "<ownerField>" }, find: ${find} }, ` +
+    `{ personal: "ref" }, or ` +
+    `{ personal: false, reason: "<why this is not personal data>" }`
+  );
+}
+
+function missingTextFieldStanceError(factoryName: TextFieldStanceFactory): Error {
+  return new Error(
+    `${factoryName}(...) must declare an explicit personal-data stance — a text field must state whose data it holds and (unless it isn't personal data) how findable it needs to stay (kumiko-framework#2921). Pass one of: ${textFieldStanceHint(factoryName)}. Run \`kumiko-guards guards --guard="Text-Field Personal-Stance Guard"\` to find remaining call sites.`,
+  );
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+// Fail-closed stance gate (kumiko-framework#2921) for the two text-shaped
+// factories — runs before expandPersonalAnnotations so an untyped JS caller
+// (no compiler to stop it) can't slip an unannotated text field past the
+// type layer either. `overrides` is `unknown` here on purpose: the typed
+// signature above already rejects a missing/malformed shape at compile
+// time, this re-checks the same shape at the runtime boundary.
+function assertTextFieldStance(factoryName: TextFieldStanceFactory, overrides: unknown): void {
+  if (overrides === null || typeof overrides !== "object") {
+    throw missingTextFieldStanceError(factoryName);
+  }
+  // @cast-boundary runtime-guard — re-validated field by field below before
+  // any value is trusted.
+  const { personal, find, reason } = overrides as PersonalOverridesInput;
+  if (personal === undefined || personal === null) {
+    throw missingTextFieldStanceError(factoryName);
+  }
+  if (personal === "ref") {
+    // skip: a user reference carries no content of its own, so no `find` applies
+    return;
+  }
+  if (personal === false) {
+    if (!isNonEmptyString(reason)) {
+      throw missingTextFieldStanceError(factoryName);
+    }
+    // skip: plaintext by declaration, `find` only applies to a named subject
+    return;
+  }
+  const hasValidSubject =
+    personal === "self" ||
+    personal === "tenant" ||
+    (typeof personal === "object" && isNonEmptyString(personal.of));
+  if (!hasValidSubject) {
+    throw missingTextFieldStanceError(factoryName);
+  }
+  const validFinds = TEXT_FIELD_STANCE_FIND_VALUES[factoryName];
+  if (typeof find !== "string" || !(validFinds as readonly string[]).includes(find)) {
+    throw missingTextFieldStanceError(factoryName);
+  }
+}
+
 // 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
@@ -96,9 +167,10 @@ function expandPersonalAnnotations<T extends PersonalOverridesInput>(
 // 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" | keyof ResolvedPiiFlags>> &
+  overrides: Partial<Omit<TextFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> &
     PersonalAnnotations & { required?: R },
 ): TextFieldDef & { required: R } {
+  assertTextFieldStance("createTextField", overrides);
   return {
     type: "text",
     maxLength: 200,
@@ -131,9 +203,10 @@ export function createDerivedField(spec: DerivedFieldDef): DerivedFieldDef {
 }
 
 export function createLongTextField<R extends true | false = false>(
-  overrides?: Partial<Omit<LongTextFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> &
+  overrides: Partial<Omit<LongTextFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> &
     PersonalAnnotationsLongText & { required?: R },
 ): LongTextFieldDef & { required: R } {
+  assertTextFieldStance("createLongTextField", overrides);
   return {
     type: "longText",
     required: false,

package/src/pipeline/irreversible-operation-gate.ts

@@ -11,9 +11,13 @@ export function isIrreversibleEntityVerb(
   return verb === "forget" || !entity.softDelete;
 }
 
-// No entryHandler means the call didn't originate from a directly-dispatched
-// handler (job, MSP/consumer apply, seed, afterCommit hook, HTTP route
-// without a handler) — those are outside agent reach and stay ungated.
+// The gate reads the directly dispatched entry handler; a write dispatched inside a deferred
+// context (afterCommit hook, job, consumer) gets its own entryHandler and is gated too. Direct
+// executor/KMS calls without one stay ungated in exactly two cases: deleting derived data
+// rebuildable from a reversible source (document-ingest-foundation's forget-extract-with-file-ref
+// consumer, re-created on fileRef.restored), and pipelines started by a risk "high" handler or a
+// cron scan (forget cleanup, retention, tenant destroy). A deferred context can't return
+// irreversibleOperationRequiresHighRisk to the agent synchronously, so the gate sits at the primitives.
 export function assertIrreversibleOperationAllowed(operation: string): void {
   const entryHandler = requestContext.get()?.entryHandler;
   // skip: no entry handler (see above) or the entry handler already resolves "high".