@cosmicdrift/kumiko-framework 0.322.0 → 0.324.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.322.0",
+  "version": "0.324.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.324.0",
+    "@cosmicdrift/kumiko-types": "0.324.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.324.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,36 @@
 [
+  {
+    "version": "0.324.0",
+    "type": "breaking",
+    "title": "Writes on readAsInstruction fields now require agent.risk \"high\" on the directly-dispatched handler",
+    "migration": "New field flag `readAsInstruction: true` on `text`, `longText`, and `jsonb`\nfields (`@cosmicdrift/kumiko-types`) marks a field whose value a later run\nreads as an instruction — a prompt, rule, or template. Any create/update\nwhose payload writes such a field must resolve `agent.risk: \"high\"` on the\ndirectly-dispatched entry handler, or the executor gate denies it with\n`access_denied` / `instruction_field_write_requires_high_risk` before any\nDB write. This is opt-in per field, but touches every write path once a\nfield carries the flag — consumer checklist:\n\n1. Mark fields that a later run reads as an instruction (prompts, rules,\n   templates) with `readAsInstruction: true`.\n2. Update your own handlers that write such a field via\n   `executor.create`/`executor.update`, or delegate into one via\n   `ctx.write`/`writeAs`, to `agent: { risk: \"high\" }` — the directly\n   called handler must carry it, delegation does not inherit it.\n3. Standard entity-convention create/update handlers on an entity with such\n   a field now default to \"high\" automatically; declaring a lower\n   `agent.risk` on one is a define-time error, same as the delete floor\n   from #3345.\n4. An update whose payload doesn't include the flagged field stays allowed\n   unchanged — the gate checks payload presence after `preSave`, not\n   whether the value actually changed.\n5. Not gated: `delete`/`restore` (they don't write the field; the existing\n   irreversible-delete floor still applies), and your own domain events\n   applied via `ctx.appendEvent` whose projection writes a flagged field —\n   route such writes through the executor primitives (`create`/`update`)\n   to get the gate.\n6. On `create`, a flagged field with a `default` counts as written even if\n   the payload omits it — `applyDefaults` runs before the gate. A custom\n   mid-risk create handler whose payload leaves the field out is denied\n   just the same, and a standard create with `excludeFields` on such a\n   field still resolves to \"high\"."
+  },
+  {
+    "version": "0.324.0",
+    "type": "improvement",
+    "title": "TestStack.drainJobs() waits deterministically for jobs and their follow-up consumers",
+    "detail": "Migration note: replace `waitFor` polling on a job's side effect with `await\nstack.drainJobs()`; it rejects with the job's name and error on final\nfailure. New `JobRunner.countPendingJobs()` — hand-written `JobRunner`\nstubs (test doubles) must add it."
+  },
+  {
+    "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/db/event-store-executor-write.ts

@@ -1,4 +1,5 @@
 import { checkWriteFieldOwnership } from "../engine/field-access";
+import { instructionFieldNames } from "../engine/instruction-fields";
 import { userCanCreateFieldRow, userCanWriteFieldRow } from "../engine/ownership";
 import { SYSTEM_ROLE, SYSTEM_USER_ID } from "../engine/system-user";
 import type { EntityId, SessionUser } from "../engine/types";
@@ -19,6 +20,7 @@ import {
   getStreamVersion,
 } from "../event-store";
 import {
+  assertInstructionFieldWriteAllowed,
   assertIrreversibleOperationAllowed,
   isIrreversibleEntityVerb,
 } from "../pipeline/irreversible-operation-gate";
@@ -122,6 +124,7 @@ export function createWriteVerbs(
     assertStreamWritable,
     loadExpectSnapshot,
   } = ctx;
+  const entityInstructionFieldNames = instructionFieldNames(entity);
 
   return {
     async create(payload, user, db, options) {
@@ -152,6 +155,12 @@ export function createWriteVerbs(
 
       // After preSave so derived fields count, before the event append so nothing persists.
       assertPersonalDataWrite(db, tableNameOf(table), Object.keys(data), entity);
+      assertInstructionFieldWriteAllowed(
+        entityName,
+        "create",
+        Object.keys(data),
+        entityInstructionFieldNames,
+      );
 
       // H.2 — entity-level write-ownership on create. No oldRow exists, so
       // only the new row is checked. No Straddle concern for creates.
@@ -344,6 +353,12 @@ export function createWriteVerbs(
 
       // After preSave so derived fields count, before the event append so nothing persists.
       assertPersonalDataWrite(db, tableNameOf(table), Object.keys(changes), entity);
+      assertInstructionFieldWriteAllowed(
+        entityName,
+        "update",
+        Object.keys(changes),
+        entityInstructionFieldNames,
+      );
 
       // H.2 — entity-level write-ownership on update. Load old row (already
       // done above), build post-change row via shallow merge. Straddle-safe

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__/entity-handlers.test.ts

@@ -13,7 +13,7 @@ import {
   type EntityCrudRegistrar,
   registerEntityCrud,
 } from "../entity-handlers";
-import { createEntity, createTextField } from "../factories";
+import { createEntity, createLongTextField, createTextField } from "../factories";
 // Barrel import, not "../entity-handlers": covers that entityListSchema is
 // actually re-exported through engine/index.ts.
 import { entityListSchema, resolveAgentExposure } from "../index";
@@ -37,6 +37,31 @@ const noteEntitySoftDelete = createEntity({
   softDelete: true,
 });
 
+const promptEntity = createEntity({
+  table: "prompts",
+  fields: {
+    label: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+    body: createLongTextField({
+      personal: false,
+      reason: "test_fixture",
+      readAsInstruction: true,
+    }),
+  },
+});
+
+const promptEntityDefaultedBody = createEntity({
+  table: "prompts_defaulted",
+  fields: {
+    label: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+    body: createLongTextField({
+      personal: false,
+      reason: "test_fixture",
+      readAsInstruction: true,
+      default: "system default prompt",
+    }),
+  },
+});
+
 const adminAccess = { access: { roles: ["Admin"] } } as const;
 
 describe("defineEntityWriteHandler", () => {
@@ -138,6 +163,42 @@ describe("defineEntityWriteHandler", () => {
     expect(def.agent).toBeUndefined();
     expect(resolveAgentExposure(def, "write").risk).toBe("mid");
   });
+
+  test("standard create on an entity with a readAsInstruction field defaults agent.risk to high", () => {
+    const def = defineEntityCreateHandler("prompt", promptEntity, adminAccess);
+    expect(resolveAgentExposure(def, "write").risk).toBe("high");
+  });
+
+  test("standard update on an entity with a readAsInstruction field defaults agent.risk to high", () => {
+    const def = defineEntityUpdateHandler("prompt", promptEntity, adminAccess);
+    expect(resolveAgentExposure(def, "write").risk).toBe("high");
+  });
+
+  test("declaring mid on a readAsInstruction-writing standard handler throws", () => {
+    expect(() =>
+      defineEntityUpdateHandler("prompt", promptEntity, {
+        access: { roles: ["Admin"] },
+        agent: { risk: "mid" },
+      }),
+    ).toThrow(/agent\.risk must be "high"/);
+  });
+
+  test("update with excludeFields excluding all readAsInstruction fields is not forced to high", () => {
+    const def = defineEntityUpdateHandler("prompt", promptEntity, {
+      access: { roles: ["Admin"] },
+      excludeFields: ["body"],
+    });
+    expect(def.agent).toBeUndefined();
+    expect(resolveAgentExposure(def, "write").risk).toBe("mid");
+  });
+
+  test("create excluding a readAsInstruction field that has a default is still forced to high", () => {
+    const def = defineEntityCreateHandler("prompt", promptEntityDefaultedBody, {
+      access: { roles: ["Admin"] },
+      excludeFields: ["body"],
+    });
+    expect(resolveAgentExposure(def, "write").risk).toBe("high");
+  });
 });
 
 describe("defineEntityQueryHandler", () => {

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.`,
-          );
         }
       }
     }