@cosmicdrift/kumiko-framework 0.321.0 → 0.323.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.321.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.321.0",
-    "@cosmicdrift/kumiko-types": "0.321.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.321.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/api/index.ts

@@ -75,7 +75,11 @@ export type {
 export { isSafeLandingPath } from "./post-auth-landing";
 export type { RedisSseBroker, RedisSseBrokerOptions } from "./redis-sse-broker";
 export { createDefaultSseBroker, createRedisSseBroker, isRedisSseBroker } from "./redis-sse-broker";
-export { type RequestContextData, requestContext } from "./request-context";
+export {
+  type RequestContextData,
+  requestContext,
+  runAsDirectCallEntry,
+} from "./request-context";
 export {
   buildRequestContextDataFromRequest,
   requestIdMiddleware,

package/src/api/request-context.ts

@@ -1,5 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { isPersonalDataGated, type WriteOrigin } from "@cosmicdrift/kumiko-types/event-store-types";
+import type { AgentRisk } from "@cosmicdrift/kumiko-types/handlers";
 import { generateId } from "../utils";
 
 // Request-scoped propagation. Populated by the HTTP middleware and by the
@@ -54,6 +55,10 @@ export type RequestContextData = {
   // Only ever a gated origin. Read by job enqueue and event-store.append();
   // dispatch roots never narrow from it, only jobs inherit explicitly.
   readonly writeOrigin?: WriteOrigin;
+  // The handler directly invoked by the dispatcher (not a nested ctx.write/
+  // writeAs target) — nested dispatches inherit it unchanged, so the
+  // irreversible-operation gate always sees the outermost caller's risk.
+  readonly entryHandler?: { readonly qn: string; readonly risk: AgentRisk };
 };
 
 const storage = new AsyncLocalStorage<RequestContextData>();
@@ -77,7 +82,11 @@ export const requestContext = {
 // when there is no surrounding request (job-runner, event-dispatcher) —
 // requestId/correlationId are mandatory, `get()` may be undefined.
 export function runWithOrigin<T>(
-  origin: { readonly feature?: string; readonly handler?: string },
+  origin: {
+    readonly feature?: string;
+    readonly handler?: string;
+    readonly entryHandler?: { readonly qn: string; readonly risk: AgentRisk };
+  },
   fn: () => T,
 ): T {
   const current = requestContext.get();
@@ -89,11 +98,24 @@ export function runWithOrigin<T>(
       correlationId: current?.correlationId ?? requestId,
       feature: origin.feature,
       handler: origin.handler,
+      // The outermost dispatch wins — a nested ctx.write/writeAs must not
+      // overwrite the entry handler that the irreversible-operation gate reads.
+      entryHandler: current?.entryHandler ?? origin.entryHandler,
     },
     fn,
   );
 }
 
+// Clears entryHandler so the next dispatch inside fn becomes the new entry —
+// used by dispatchToolCall so the invoked tool handler, not the surrounding
+// turn/approve handler, is what the irreversible-operation gate sees.
+export function runAsDirectCallEntry<T>(fn: () => T): T {
+  const current = requestContext.get();
+  if (!current) return fn();
+  const { entryHandler: _entryHandler, ...rest } = current;
+  return requestContext.run(rest, fn);
+}
+
 // An ungated origin never mints a scope: seeds and boot writes keep their missing context.
 export function runWithWriteOrigin<T>(origin: WriteOrigin, fn: () => T): T {
   const current = requestContext.get();

package/src/changes.json

@@ -1,4 +1,36 @@
 [
+  {
+    "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",
+    "title": "Irreversible writes now require agent.risk \"high\" on the directly-dispatched handler",
+    "migration": "Any write handler reachable as the directly-dispatched entry point that\nperforms `executor.forget()` (any entity) or `executor.delete()` on an\nentity without `softDelete` must resolve `agent.risk: \"high\"`, or the\nexecutor gate now denies it with `access_denied` /\n`irreversible_operation_requires_high_risk` before any DB read.\n\nThree breaking changes ship together:\n1. Add `agent: { risk: \"high\" }` to your own write handler if it directly\n   runs `forget` or a hard `delete` on a non-softDelete entity.\n2. Delegating via `ctx.write`/`ctx.writeAs` from a lower-risk handler into\n   a high-risk forget/hard-delete handler no longer inherits the inner\n   handler's risk — the outermost/entry handler's declared risk governs,\n   so the delegating handler itself must be \"high\".\n3. Declaring `agent.risk` below \"high\" on a standard entity-convention\n   delete handler for a non-softDelete entity is now a define-time/boot\n   error instead of a silently-accepted setting.\n\nStandard entity-convention delete handlers on a non-softDelete entity now\ndefault to \"high\" automatically (no more implicit \"always allow\").\n\n`dispatchToolCall` treats the invoked tool itself as the entry handler,\nnot the surrounding turn/approve write handler that dispatched it — a\nmid-risk \"approve\" handler can safely invoke a high-risk tool directly,\nbut a mid-risk tool that itself delegates to a high-risk handler via\n`ctx.write`/`writeAs` is still denied per rule 2.\n\n`runAsDirectCallEntry` (framework `/api`) is the one sanctioned entry\nboundary: it clears the entry handler so the next dispatch counts as the\ndirectly called one. `dispatchToolCall` uses it because the human\nconfirmation happens in approve; do not use it to lift a handler past\nthe floor.\n\nRemaining gap: `afterCommit` hooks, jobs, and event consumers are not\ngated by this floor — they have no directly-dispatched entry handler to\nattribute risk to."
+  },
+  {
+    "version": "0.322.0",
+    "type": "improvement",
+    "title": "Translation values may now be CLDR plural-form objects, resolved per locale with Intl.PluralRules",
+    "migration": "A translation entry's value type widens from `string` to\n`string | PluralForms`, so an existing `TranslationEntry` locale value can\nnow also be an object with `one`/`few`/`many`/`other` (etc.) CLDR\ncategories, where `other` is required:\n\n```ts\n{ de: { one: \"{count} Status-Seite\", other: \"{count} Status-Seiten\" } }\n```\n\n`createI18n(...).t(key, locale, { count })` resolves the CLDR category for\nthe given locale via a per-locale-cached `Intl.PluralRules` and interpolates\n`{count}`; it falls back to `other` when `count` is missing/non-finite, the\nlocale tag is invalid, or `Intl.PluralRules` is unavailable (older Hermes).\n`mailT` and the renderer's `translateWithFallbacks` resolve plural values\nthe same way, through the shared `resolveTranslationValue` helper.\n\nExisting string-only translations keep working unchanged. Code that reads\nvalues back out of a bundle (`TranslationBundle`, `TranslationsByLocale`,\n`TranslationEntry`) and annotates them as `string` no longer typechecks:\nannotate as `TranslationValue` (from `@cosmicdrift/kumiko-framework/ui-types`)\nor flatten with `translationValueOtherText(value)`."
+  },
   {
     "version": "0.321.0",
     "type": "improvement",

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

@@ -18,6 +18,10 @@ import {
   VersionConflictError as EventStoreVersionConflict,
   getStreamVersion,
 } from "../event-store";
+import {
+  assertIrreversibleOperationAllowed,
+  isIrreversibleEntityVerb,
+} from "../pipeline/irreversible-operation-gate";
 import { generateId } from "../utils";
 import { applyEntityEvent } from "./apply-entity-event";
 import { flattenCompoundTypes, rehydrateCompoundTypes } from "./compound-types";
@@ -586,6 +590,9 @@ export function createWriteVerbs(
     },
 
     async delete(payload, user, db) {
+      if (isIrreversibleEntityVerb("delete", entity)) {
+        assertIrreversibleOperationAllowed(`${entityName}.delete (entity has no softDelete)`);
+      }
       const runner = tenantDbRunner(db);
       const existing = await loadById(payload.id, db);
       if (!existing) return writeFailure(new NotFoundError(entityName, payload.id));
@@ -684,6 +691,7 @@ export function createWriteVerbs(
     // the erasure replays on rebuild (created → forgotten → row gone). Loads
     // without the isDeleted filter so trashed (soft-deleted) rows are erased too.
     async forget(payload, user, db) {
+      assertIrreversibleOperationAllowed(`${entityName}.forget`);
       const runner = tenantDbRunner(db);
       const raw = await db.fetchOne<Record<string, unknown>>(table, { id: payload.id });
       if (!raw) return writeFailure(new NotFoundError(entityName, payload.id));

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

@@ -110,6 +110,34 @@ describe("defineEntityWriteHandler", () => {
     // @ts-expect-error access is required since fw#2855 — no implicit openToAll.
     expect(() => defineEntityCreateHandler("note", noteEntity)).toThrow();
   });
+
+  test("delete on an entity without softDelete defaults agent.risk to high", () => {
+    const def = defineEntityDeleteHandler("note", noteEntity, adminAccess);
+    expect(resolveAgentExposure(def, "write").risk).toBe("high");
+  });
+
+  test("delete on an entity without softDelete preserves other agent hints while forcing risk high", () => {
+    const def = defineEntityDeleteHandler("note", noteEntity, {
+      access: { roles: ["Admin"] },
+      agent: { expose: false },
+    });
+    expect(def.agent).toEqual({ expose: false, risk: "high" });
+  });
+
+  test("delete on an entity without softDelete throws when agent.risk is explicitly set below high", () => {
+    expect(() =>
+      defineEntityDeleteHandler("note", noteEntity, {
+        access: { roles: ["Admin"] },
+        agent: { risk: "mid" },
+      }),
+    ).toThrow(/agent\.risk must be "high"/);
+  });
+
+  test("delete on a softDelete entity leaves agent hints untouched", () => {
+    const def = defineEntityDeleteHandler("note", noteEntitySoftDelete, adminAccess);
+    expect(def.agent).toBeUndefined();
+    expect(resolveAgentExposure(def, "write").risk).toBe("mid");
+  });
 });
 
 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.`,
-          );
         }
       }
     }