@cosmicdrift/kumiko-framework 0.400.0 → 0.401.0

package/AGENTS.md

@@ -113,8 +113,9 @@ the field types reject a text field without that stance.
 `personal: false, reason: "is_business_data"` (a snake_case reason) for
 business data. For personal data name the subject, `personal: "self"`,
 `personal: { of: "<ownerField>" }` or `personal: "tenant"`, plus
-`find: "exact" | "fuzzy" | "none" | "secret"`. A plain foreign key to a user
-is `personal: "ref"`. `personal: "self"` is for the row that is the user.
+`find: "exact" | "fuzzy" | "none" | "secret"`. A foreign key to a user
+is `createReferenceField({ entity: "user:user" })`, which defaults to
+`personal: "ref"`; `personal: false` on it fails at boot. `personal: "self"` is for the row that is the user.
 When the record itself is the person, such as a contact or a customer that
 is not a user, use `personal: { of: "id" }`; the entity then needs a uuid
 `id`. The framework encrypts personal fields per subject and
@@ -306,7 +307,7 @@ as bundled features.
 | Business logic beyond CRUD | `r.writeHandler` / `r.queryHandler` with `createEntityExecutor` | `agents/examples/custom-handlers.md` |
 | Filtered lists and counts | Executor `list` with `filter` and `totalCount` | `agents/examples/custom-handlers.md` |
 | Key figures on a dashboard | `dashboard` screen with `stat` / `stat-group` panels and a query handler | `agents/examples/dashboard-stats.md` |
-| Relations between entities | `r.relation(entity, name, { type, target, foreignKey, onDelete })` | `agents/examples/relations.md` |
+| Relations between entities | `createReferenceField({ entity })` for the foreign key (user ids: `entity: "user:user"`), `r.relation(entity, name, { type, target, foreignKey, onDelete })` | `agents/examples/relations.md` |
 | Structured sub-objects in a field | Embedded fields | `agents/examples/embedded.md` |
 | List, edit, custom screens and navs | `r.screen`, `r.nav` | `agents/examples/screens-nav.md` |
 | A record page with header, metrics, tabs | `projectionDetail` with `header`, `metrics`, `layout.mode: "tabs"` | `agents/examples/record-detail-layout.md` |

package/agents/api/framework-engine.md

@@ -45,6 +45,7 @@ function createLongTextField<R extends true | false = false>(overrides: Partial<
 function createMoneyField<R extends true | false = false>(overrides?: Partial<Omit<MoneyFieldDef, "type" | "required">> & { required?: R; }): MoneyFieldDef & { required: R; };
 function createMultiSelectField<const TOptions extends string[]>(opts: { options: TOptions; } & Partial<Omit<MultiSelectFieldDef<TOptions>, "type" | "options" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): MultiSelectFieldDef<TOptions>; // Multi-select field — N values from a fixed option list.
 function createNumberField<R extends true | false = false>(overrides?: Partial<Omit<NumberFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & { required?: R; }): NumberFieldDef & { required: R; }; // Numeric field — `double precision` column by default (fractional values allowed end to end).
+function createReferenceField<R extends true | false = false>(opts: { entity: string; } & Partial<Omit<ReferenceFieldDef, "type" | "entity" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & { required?: R; }): ReferenceFieldDef & { required: R; }; // Foreign key to another entity (`"customer"` or `"feature:entity"`), stored as a UUID.
 function createRegistry(rawFeatures: FeatureDefinition[]): Registry;
 function createSeed(opts: CreateSeedOptions): ConfigSeedDef;
 function createSelectField<const TOptions extends string[], R extends true | false = false>(opts: { options: TOptions; } & Partial<Omit<SelectFieldDef<NoInfer<TOptions>>, "type" | "options" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & { required?: R; }): SelectFieldDef<TOptions> & { required: R; };
@@ -60,14 +61,14 @@ function createUserConfig<T extends ConfigKeyType>(type: T, opts?: ConfigKeyOpti
 function declareEscapeHatch(declaration: EscapeHatchDeclaration): void;
 function dedupeFeatures(features: FeatureDefinition[]): FeatureDefinition[];
 function defineApply<TPayload = Record<string, unknown>>(fn: (event: StoredEvent<TPayload>, tx: ExecutorManagedRunner, table: ProjectionTable) => Promise<void>): SingleStreamApplyFn;
-function defineEntityCreateHandler(entityName: string, entity: EntityDefinition, options: EntityWriteHandlerOptions): WriteHandlerDef;
-function defineEntityDeleteHandler(entityName: string, entity: EntityDefinition, options: EntityHandlerOptions): WriteHandlerDef;
+function defineEntityCreateHandler(entityName: string, entity: EntityDefinition, options: EntityWriteHandlerOptions): EntityWriteHandlerDef;
+function defineEntityDeleteHandler(entityName: string, entity: EntityDefinition, options: EntityHandlerOptions): EntityWriteHandlerDef;
 function defineEntityDetailHandler(entityName: string, entity: EntityDefinition, options: EntityQueryHandlerOptions): QueryHandlerDef;
 function defineEntityListHandler(entityName: string, entity: EntityDefinition, options: EntityQueryHandlerOptions): QueryHandlerDef;
 function defineEntityQueryHandler(name: string, entity: EntityDefinition, options: EntityQueryHandlerOptions): QueryHandlerDef;
-function defineEntityRestoreHandler(entityName: string, entity: EntityDefinition, options: EntityHandlerOptions): WriteHandlerDef;
-function defineEntityUpdateHandler(entityName: string, entity: EntityDefinition, options: EntityWriteHandlerOptions): WriteHandlerDef;
-function defineEntityWriteHandler(name: string, entity: EntityDefinition, options: EntityWriteHandlerOptions): WriteHandlerDef;
+function defineEntityRestoreHandler(entityName: string, entity: EntityDefinition, options: EntityHandlerOptions): EntityWriteHandlerDef;
+function defineEntityUpdateHandler(entityName: string, entity: EntityDefinition, options: EntityWriteHandlerOptions): EntityWriteHandlerDef;
+function defineEntityWriteHandler(name: string, entity: EntityDefinition, options: EntityWriteHandlerOptions): EntityWriteHandlerDef;
 function defineFeature<const TName extends string, TExports = undefined>(name: TName, setup: (r: FeatureRegistrar<TName>) => TExports, settings?: DefineFeatureSettings): FeatureDefinition & { exports: TExports; };
 function defineMspApply<TPayload = Record<string, unknown>>(fn: (event: StoredEvent<TPayload>, tx: ExecutorManagedRunner, ctx: MultiStreamApplyContext) => Promise<void>): MultiStreamApplyFn;
 function definePagedQueryHandler<const TName extends string, TSchema extends ZodType, TRow = unknown, TMap extends object = KumikoEventTypeMap>(def: QueryHandlerDefinition<TName, TSchema, CursorResult<TRow>, TMap>, ..._noSecretInResponse: true extends ContainsSecret<CursorResult<TRow>> ? [ secretLeak: "A handler response must not contain a Secret<> — call .reveal() and return the plaintext, or drop the field." ] : [ ]): PagedQueryHandlerDefinition<TName, TSchema, TRow, TMap>;
@@ -1713,6 +1714,7 @@ type ValidateBootOptions = {
   env?: Readonly<Record<string, string | undefined>>; // Env the encrypted-field master-key probe reads.
   entityFieldCipher?: EnvelopeCipher; // The cipher the runner injects after validation (built from the app's `masterKey` or the env keyring).
   requiredLocales?: string[]; // Locales every translation key must carry across all mounted features (locale packages count).
+  requireFieldValueTranslations?: boolean; // Require translations for the values that entityList columns and entityEdit fields display: select/multiSelect option labels and the column headers and select options of embedded lists.
 };
 type ValidationError = {
   field: string;

package/agents/api/testing-stack.md

@@ -13,6 +13,7 @@ function createRequestHelper(app: Hono, jwt: JwtHelper, options?: RequestHelperO
 function createTestDb(arg?: string | CreateTestDbOptions): Promise<TestDb>;
 function createTestRedis(opts?: CreateTestRedisOptions): Promise<TestRedis>;
 function drainEventConsumers(stack: Pick<TestStack, "db" | "eventDispatcher">, consumerNames: [ string, ...string[] ], options?: { maxPasses?: number; }): Promise<void>;
+function dropTestDb(baseUrl: string, dbName: string): Promise<void>;
 function pushEntityProjectionTables(stack: DbHolder, registry: Registry): Promise<void>; // Push all implicit-projection tables — one per `r.entity()` — that the registry knows about.
 function resetEventStore(stack: { db: unknown; eventDispatcher?: EventDispatcher; }, extraTables?: (unknown | string)[]): Promise<void>; // Wipes event store + framework-state + the given feature read-models in one TRUNCATE, then re-registers the event-consumer state rows.
 function setupTestStack(options: TestStackOptions): Promise<TestStack>;

package/agents/api/types.md

@@ -903,6 +903,16 @@ type WorkflowTrigger = // Trigger configuration for a workflow.
 type NumericDerivedOp = Exclude<EmbeddedDerivedCellDef["op"], "inRange">;
 ```
 
+## packages/framework/src/engine/entity-handlers.ts
+
+```ts
+type EntityWriteHandlerDef = WriteHandlerDef & { // The phase slots are always unset on entity handlers, so a consumer can spread one into its own handler and add typed phases without inheriting the slot types.
+  reserveBeforeTransaction?: undefined;
+  beforeTransaction?: undefined;
+  beforeTransactionWhenNested?: undefined;
+};
+```
+
 ## packages/framework/src/engine/event-helpers.ts
 
 ```ts
@@ -3162,10 +3172,14 @@ type ReadGateDef = {
     entity: string;
     field: string;
   }; // Row readable only if at least one live row of `entity` with `field` = row.id is readable through that entity's own parentRef gate (host visibility).
+  allLinks?: {
+    entity: string;
+    field: string;
+  }; // Like `anyLink`, but every live link row must be readable, and there must be at least one.
   fileOwner?: {
     field: string;
   }; // Row readable only if the file_ref in `field` is live and readable through its owner: owner row readable (ownership, parentRef, handler gate) and the field read access on the file_ref's fieldName passes.
-  linkExemptRoles?: string[]; // Roles that skip `anyLink` (they also see unlinked rows).
+  linkExemptRoles?: string[]; // Roles that skip `anyLink` / `allLinks` (they also see unlinked rows).
 };
 ```
 

package/agents/api.md

@@ -8,13 +8,13 @@ Format: one line per function or constant, object and options types as property
 
 | Import path | File | Exports |
 | --- | --- | --- |
-| `@cosmicdrift/kumiko-framework/engine` | `api/framework-engine.md` | 411 |
+| `@cosmicdrift/kumiko-framework/engine` | `api/framework-engine.md` | 412 |
 | `@cosmicdrift/kumiko-framework/errors` | `api/framework-errors.md` | 25 |
 | `@cosmicdrift/kumiko-framework/ui-types` | `api/framework-ui-types.md` | 154 |
 | `@cosmicdrift/kumiko-framework/db` | `api/framework-db.md` | 150 |
 | `@cosmicdrift/kumiko-framework/event-store` | `api/framework-event-store.md` | 38 |
 | `@cosmicdrift/kumiko-framework/seeding` | `api/framework-seeding.md` | 6 |
 | `@cosmicdrift/kumiko-renderer/web` | `api/renderer-web.md` | 298 |
-| `@cosmicdrift/kumiko-testing/stack` | `api/testing-stack.md` | 21 |
+| `@cosmicdrift/kumiko-testing/stack` | `api/testing-stack.md` | 22 |
 | `@cosmicdrift/kumiko-testing/helpers` | `api/testing-helpers.md` | 71 |
 | `@cosmicdrift/kumiko-dev-server/testing` | `api/dev-server-testing.md` | 5 |

package/agents/examples/relations.md

@@ -217,7 +217,12 @@ describe("cascade: deleting member removes tasks", () => {
 
 ```ts
 import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
-import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createEntity,
+  createReferenceField,
+  createTextField,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
 
 export const teamEntity = createEntity({
   table: "read_sample_teams",
@@ -230,7 +235,12 @@ export const memberEntity = createEntity({
   table: "read_sample_members",
   fields: {
     name: createTextField({ personal: { of: "id" }, find: "none", required: true }),
-    teamId: createTextField({ personal: false, reason: "is_system_identifier", required: true }),
+    teamId: createReferenceField({
+      entity: "team",
+      personal: false,
+      reason: "is_system_identifier",
+      required: true,
+    }),
     role: createTextField({ personal: false, reason: "is_business_data" }),
   },
 });
@@ -239,7 +249,7 @@ export const taskEntity = createEntity({
   table: "read_sample_member_tasks",
   fields: {
     title: createTextField({ personal: false, reason: "is_business_data", required: true }),
-    memberId: createTextField({ personal: "ref", required: true }),
+    memberId: createReferenceField({ entity: "member", personal: "ref", required: true }),
   },
 });
 

package/dist/config/index.d.ts

@@ -20,7 +20,7 @@ export type AppPorts = {
     readonly infra?: AppInfraPorts;
 };
 /** The boot-validator options an app owns; `env` and the cipher are injected by the runners. */
-export type AppValidateBootOptions = Pick<ValidateBootOptions, "navAllowlist" | "navAllowlistExempt" | "requiredLocales" | "warnOnUniqueAccessRoles">;
+export type AppValidateBootOptions = Pick<ValidateBootOptions, "navAllowlist" | "navAllowlistExempt" | "requiredLocales" | "requireFieldValueTranslations" | "warnOnUniqueAccessRoles">;
 export type AppConfig = {
     /** Features mounted in every environment: dev, tests, prod. */
     readonly features: readonly FeatureDefinition[];

package/dist/db/read-gate-clause.js

@@ -42,7 +42,9 @@ function liveRowSql(entity, table, alias) {
 function isRoleExempt(gate, user) {
     return user.roles.some((role) => gate.linkExemptRoles?.includes(role) === true);
 }
-function anyLinkClause(input, link) {
+// "any": one readable live link suffices. "all": additionally no live link may be unreadable;
+// COALESCE keeps a NULL from the ownership SQL from counting as readable.
+function linkClause(input, link, mode) {
     const { option, user, db, tableName } = input;
     const linkEntity = option.entities.get(link.entity);
     if (linkEntity?.parentRef === undefined)
@@ -56,18 +58,24 @@ function anyLinkClause(input, link) {
     if (linkOwnership.kind === "empty")
         return EMPTY;
     const sql = new GateSql();
-    const conditions = [
+    const linkRowsOfThisRow = () => [
         `"${LINK_ALIAS}"."${physicalColumnName(linkTable, link.field)}"::text = "${tableName}"."${physicalColumnName(input.table, "id")}"::text`,
         ...tenantScopeSql(sql, db, linkTable, LINK_ALIAS),
         ...liveRowSql(linkEntity, linkTable, LINK_ALIAS),
     ];
+    const existsLink = (conditions) => `EXISTS (SELECT 1 FROM "${linkTableName}" AS "${LINK_ALIAS}" WHERE ${conditions.join(" AND ")})`;
+    const readable = linkRowsOfThisRow();
     if (linkOwnership.kind === "sql")
-        conditions.push(sql.embed(linkOwnership));
-    return {
-        kind: "sql",
-        sqlText: `EXISTS (SELECT 1 FROM "${linkTableName}" AS "${LINK_ALIAS}" WHERE ${conditions.join(" AND ")})`,
-        params: sql.params,
-    };
+        readable.push(sql.embed(linkOwnership));
+    let sqlText = existsLink(readable);
+    if (mode === "all" && linkOwnership.kind === "sql") {
+        const unreadable = [
+            ...linkRowsOfThisRow(),
+            `NOT COALESCE((${sql.embed(linkOwnership)}), FALSE)`,
+        ];
+        sqlText = `(${sqlText} AND NOT ${existsLink(unreadable)})`;
+    }
+    return { kind: "sql", sqlText, params: sql.params };
 }
 // Every registered entity with a file field can own a file. Join rows and gated entities
 // are left out: their readability is not resolvable without recursion.
@@ -178,8 +186,13 @@ export function buildReadGateClause(entity, table, tableName, user, db, option)
         return EMPTY;
     const input = { entity, table, tableName, user, db, option };
     let clause = PASS;
-    if (gate.anyLink !== undefined && !isRoleExempt(gate, user)) {
-        clause = combineClauses(clause, anyLinkClause(input, gate.anyLink));
+    if (!isRoleExempt(gate, user)) {
+        if (gate.anyLink !== undefined) {
+            clause = combineClauses(clause, linkClause(input, gate.anyLink, "any"));
+        }
+        if (gate.allLinks !== undefined) {
+            clause = combineClauses(clause, linkClause(input, gate.allLinks, "all"));
+        }
     }
     if (gate.fileOwner !== undefined) {
         clause = combineClauses(clause, fileOwnerClause(input, gate.fileOwner.field));

package/dist/engine/boot-validator/boot-options.d.ts

@@ -30,4 +30,9 @@ export type ValidateBootOptions = {
      *  (locale packages count). Without it a key can ship in one language and
      *  silently fall back at runtime for users of the others. */
     readonly requiredLocales?: readonly string[];
+    /** Require translations for the values that entityList columns and entityEdit
+     *  fields display: select/multiSelect option labels and the column headers
+     *  and select options of embedded lists. Without them the UI shows raw
+     *  option values and sub-field names. Opt-in (default false). */
+    readonly requireFieldValueTranslations?: boolean;
 };

package/dist/engine/boot-validator/boot-phases-app.js

@@ -9,7 +9,7 @@ import { validateExtensionPreSaveWiring } from "./entity-handler.js";
 import { validateEntityListScreens } from "./entity-list-screens.js";
 import { validateGdprStoragePersistence } from "./gdpr-storage.js";
 import { validateGlobalTenancyEntities } from "./global-tenancy.js";
-import { validateI18nSurfaceKeys, validateRequiredLocales, validateTranslationLocaleConsistency, } from "./i18n-keys.js";
+import { validateFieldValueTranslations, validateI18nSurfaceKeys, validateRequiredLocales, validateTranslationLocaleConsistency, } from "./i18n-keys.js";
 import { validateNavCycles } from "./nav.js";
 import { validateProjectionListScreens, validateRelatedListSectionQueries, } from "./projection-list-screens.js";
 import { validateQueryOutputColumns } from "./query-output-columns.js";
@@ -25,6 +25,10 @@ const APP_CHECKS_AFTER_I18N = [
         check: "validateRequiredLocales",
         run: (c) => validateRequiredLocales(c.features, c.options?.requiredLocales),
     },
+    {
+        check: "validateFieldValueTranslations",
+        run: (c) => validateFieldValueTranslations(c.features, c.options?.requireFieldValueTranslations),
+    },
     { check: "validateEntityListScreens", run: (c) => validateEntityListScreens(c.features) },
     {
         check: "validateSubmitPrefilledHiddenFields",

package/dist/engine/boot-validator/field-conditions.js

@@ -77,9 +77,19 @@ function assertFileSubField(where, sub) {
             throw new Error(`${where} has invalid maxSize "${sub.maxSize}". Use e.g. "10mb", "500kb".`);
         }
     }
-    if (sub.accept?.some((ext) => ext.length === 0)) {
+    assertAcceptEntries(where, sub.accept);
+}
+// validateFile compares accept entries with the lower-cased last file-name segment, so only
+// bare lower-case extensions can ever match.
+const BARE_EXTENSION = /^[a-z0-9]+$/;
+function assertAcceptEntries(where, accept) {
+    if (accept?.some((ext) => ext.length === 0)) {
         throw new Error(`${where} has an empty entry in accept. List file extensions like "pdf".`);
     }
+    const offender = accept?.find((entry) => !BARE_EXTENSION.test(entry));
+    if (offender !== undefined) {
+        throw new Error(`${where} has accept entry "${offender}", which can never match an uploaded file. accept takes bare lower-case file extensions without dot, MIME type or wildcard: use "pdf" instead of ".pdf" or "application/pdf".`);
+    }
 }
 function assertSelectSubFieldTones(where, sub) {
     // skip: only select sub-fields with declared tones have tones to check
@@ -168,6 +178,14 @@ function assertField(feature, entityName, entity, fieldName, field) {
     }
     if (field.type === "embedded")
         assertEmbeddedField(where, field);
+    if (isFileAcceptField(field))
+        assertAcceptEntries(where, field.accept);
+}
+function isFileAcceptField(field) {
+    return (field.type === "file" ||
+        field.type === "files" ||
+        field.type === "image" ||
+        field.type === "images");
 }
 export function validateFieldConditions(feature) {
     for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {

package/dist/engine/boot-validator/i18n-keys.d.ts

@@ -2,3 +2,4 @@ import type { FeatureDefinition, Registry } from "../types/index.ts";
 export declare function validateI18nSurfaceKeys(features: readonly FeatureDefinition[], registry: Registry): void;
 export declare function validateTranslationLocaleConsistency(features: readonly FeatureDefinition[]): void;
 export declare function validateRequiredLocales(features: readonly FeatureDefinition[], requiredLocales: readonly string[] | undefined): void;
+export declare function validateFieldValueTranslations(features: readonly FeatureDefinition[], enabled: boolean | undefined): void;

package/dist/engine/boot-validator/i18n-keys.js

@@ -1,4 +1,4 @@
-import { buildEffectiveTranslationKeys, featureHasI18nSurface, findRequiredLocaleGaps, findTranslationLocaleGaps, requiredKeysFromFeature, requiredKeysFromNav, requiredKeysFromScreen, requiredKeysFromWorkspace, screenTitleKey, } from "../../i18n/required-surface-keys.js";
+import { buildEffectiveTranslationKeys, featureHasI18nSurface, fieldValueTranslationKeysFromFeature, findRequiredLocaleGaps, findTranslationLocaleGaps, requiredKeysFromFeature, requiredKeysFromNav, requiredKeysFromScreen, requiredKeysFromWorkspace, screenTitleKey, } from "../../i18n/required-surface-keys.js";
 import { buildConfigFeatureSchema, SETTINGS_HUB_FEATURE, } from "../build-config-feature-schema.js";
 import { EXTENSION_SELECTOR_HINT_KEY } from "../extension-selector-plugins.js";
 function isDormantSecretsScreen(screen) {
@@ -100,3 +100,19 @@ export function validateRequiredLocales(features, requiredLocales) {
         throw new Error(`${lines.join("\n")}\nThe app requires locales [${requiredLocales.join(", ")}] for every translation key; load the matching locale package or add the missing translations.`);
     }
 }
+export function validateFieldValueTranslations(features, enabled) {
+    // skip: opt-in rule, off unless the app enables requireFieldValueTranslations
+    if (enabled !== true)
+        return;
+    const defined = buildEffectiveTranslationKeys(features);
+    const missing = [];
+    for (const feature of features) {
+        for (const key of fieldValueTranslationKeysFromFeature(feature)) {
+            if (!hasDefinedTranslation(defined, key))
+                missing.push(`  - ${feature.name}: ${key}`);
+        }
+    }
+    if (missing.length > 0) {
+        throw new Error(`[i18n] ${missing.length} select option / embedded-cell translation key(s) missing (requireFieldValueTranslations):\n${missing.join("\n")}\nAdd them via r.translations(...) in the owning feature.`);
+    }
+}

package/dist/engine/boot-validator/pii-retention.js

@@ -1,5 +1,6 @@
 import { holdsFileRefs } from "../../files/file-field-slots.js";
 import { createFallbackLogger } from "../../logging/utils.js";
+import { isUserEntityReference } from "../user-entity-reference.js";
 import { PII_DIRECT_NAME_HINTS, PII_USER_OWNED_NAME_HINTS, PII_USER_REFERENCE_NAME_HINTS, } from "./entity-handler.js";
 const log = createFallbackLogger("kumiko:boot");
 // Framework-managed timestamp fields may be used as retention.reference
@@ -134,6 +135,7 @@ export function validatePiiAndRetention(feature) {
 const FIELD_RULES = [
     rejectMultipleSubjectAnnotations,
     rejectTextWithoutPersonalStance,
+    rejectPlaintextUserReference,
     rejectInvalidLookupable,
     rejectSensitiveWithoutCiphertextAtRest,
     validateWriteOnlyField,
@@ -180,6 +182,16 @@ function rejectTextWithoutPersonalStance(input) {
         throw new Error(`${fieldLocation(input)} (type "${field.type}") declares no personal stance. Build it with createTextField / createLongTextField and { personal: "self" | "tenant" | "ref" | { of: "<ownerField>" } | false }; false additionally needs { reason: "..." } stating why the value is not personal data.`);
     }
 }
+function rejectPlaintextUserReference(input) {
+    const { field, flags } = input;
+    // skip: only a plaintext reference to the user entity is a violation
+    if (field.type !== "reference" || !flags.allowPlaintext)
+        return;
+    // skip: references to other entities may stay plaintext
+    if (!isUserEntityReference(field.entity))
+        return;
+    throw new Error(`${fieldLocation(input)} references the user entity "${field.entity}" with { personal: false } — a user id is a pseudonym that falls under Art.17 forget. Use createReferenceField({ entity: "${field.entity}" }) or { personal: "ref" }.`);
+}
 // lookupable: only text fields with a subject annotation are supported. Without
 // a subject, the value remains plaintext, so a blind index would be a
 // second deterministic copy without any benefit.
@@ -263,8 +275,7 @@ function warnOnNonUserOwnerReference(input, ownerName, ownerField) {
     if (ownerField.type !== "reference")
         return;
     const refTarget = ownerField.entity;
-    const targetEntity = refTarget.includes(":") ? refTarget.split(":")[1] : refTarget;
-    if (targetEntity !== "user") {
+    if (!isUserEntityReference(refTarget)) {
         log.warn(`[Feature ${input.featureName}] personal.of "${ownerName}" on entity "${input.entityName}" targets reference "${refTarget}" — typically should be a user reference. If intentional (custom subject-entity like employee/patient), ignore.`);
     }
 }

package/dist/engine/boot-validator/read-gate.js

@@ -4,16 +4,16 @@ import { findEntity } from "./parent-ref.js";
 function fail(check, message) {
     throw new Error(`[Kumiko ReadGate] entity "${check.entityName}" (feature: "${check.feature.name}"): ${message}`);
 }
-function validateAnyLink(check, anyLink) {
-    const link = findEntity(check.featureMap, anyLink.entity);
+function validateLink(check, key, gateLink) {
+    const link = findEntity(check.featureMap, gateLink.entity);
     if (link === undefined) {
-        fail(check, `readGate.anyLink.entity "${anyLink.entity}" is not registered.`);
+        fail(check, `readGate.${key}.entity "${gateLink.entity}" is not registered.`);
     }
     if (link.parentRef === undefined) {
-        fail(check, `readGate.anyLink.entity "${anyLink.entity}" must declare a parentRef; its host visibility is what the gate checks.`);
+        fail(check, `readGate.${key}.entity "${gateLink.entity}" must declare a parentRef; its host visibility is what the gate checks.`);
     }
-    if (link.fields[anyLink.field] === undefined) {
-        fail(check, `readGate.anyLink.field "${anyLink.field}" is not a field of "${anyLink.entity}".`);
+    if (link.fields[gateLink.field] === undefined) {
+        fail(check, `readGate.${key}.field "${gateLink.field}" is not a field of "${gateLink.entity}".`);
     }
 }
 function validateFileOwner(check, fileOwner) {
@@ -45,8 +45,13 @@ export function validateReadGates(feature, featureMap) {
         if (entity.parentRef !== undefined) {
             fail(check, "readGate and parentRef cannot be combined; a gated entity cannot be a join row.");
         }
+        if (gate.anyLink !== undefined && gate.allLinks !== undefined) {
+            fail(check, "readGate declares both anyLink and allLinks; pick one.");
+        }
         if (gate.anyLink !== undefined)
-            validateAnyLink(check, gate.anyLink);
+            validateLink(check, "anyLink", gate.anyLink);
+        if (gate.allLinks !== undefined)
+            validateLink(check, "allLinks", gate.allLinks);
         if (gate.fileOwner !== undefined)
             validateFileOwner(check, gate.fileOwner);
         validateNoHandWrittenReaders(check);

package/dist/engine/entity-handlers.d.ts

@@ -59,12 +59,19 @@ export declare const entityListSchema: z.ZodObject<{
         }, z.core.$strip>>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-export declare function defineEntityWriteHandler(name: string, entity: EntityDefinition, options: EntityWriteHandlerOptions): WriteHandlerDef;
+/** The phase slots are always unset on entity handlers, so a consumer can spread one into its own
+ *  handler and add typed phases without inheriting the slot types. */
+export type EntityWriteHandlerDef = WriteHandlerDef & {
+    readonly reserveBeforeTransaction?: undefined;
+    readonly beforeTransaction?: undefined;
+    readonly beforeTransactionWhenNested?: undefined;
+};
+export declare function defineEntityWriteHandler(name: string, entity: EntityDefinition, options: EntityWriteHandlerOptions): EntityWriteHandlerDef;
 export declare function defineEntityQueryHandler(name: string, entity: EntityDefinition, options: EntityQueryHandlerOptions): QueryHandlerDef;
-export declare function defineEntityCreateHandler(entityName: string, entity: EntityDefinition, options: EntityWriteHandlerOptions): WriteHandlerDef;
-export declare function defineEntityUpdateHandler(entityName: string, entity: EntityDefinition, options: EntityWriteHandlerOptions): WriteHandlerDef;
-export declare function defineEntityDeleteHandler(entityName: string, entity: EntityDefinition, options: EntityHandlerOptions): WriteHandlerDef;
-export declare function defineEntityRestoreHandler(entityName: string, entity: EntityDefinition, options: EntityHandlerOptions): WriteHandlerDef;
+export declare function defineEntityCreateHandler(entityName: string, entity: EntityDefinition, options: EntityWriteHandlerOptions): EntityWriteHandlerDef;
+export declare function defineEntityUpdateHandler(entityName: string, entity: EntityDefinition, options: EntityWriteHandlerOptions): EntityWriteHandlerDef;
+export declare function defineEntityDeleteHandler(entityName: string, entity: EntityDefinition, options: EntityHandlerOptions): EntityWriteHandlerDef;
+export declare function defineEntityRestoreHandler(entityName: string, entity: EntityDefinition, options: EntityHandlerOptions): EntityWriteHandlerDef;
 export declare function defineEntityListHandler(entityName: string, entity: EntityDefinition, options: EntityQueryHandlerOptions): QueryHandlerDef;
 export declare function defineEntityDetailHandler(entityName: string, entity: EntityDefinition, options: EntityQueryHandlerOptions): QueryHandlerDef;
 export declare function createEntityExecutor<E extends EntityDefinition>(entityName: string, entity: E): {

package/dist/engine/factories.d.ts

@@ -1,4 +1,4 @@
-import type { BigIntFieldDef, BooleanFieldDef, DateFieldDef, DecimalFieldDef, DerivedFieldDef, EmbeddedFieldDef, EntityDefinition, EntityIndexDef, EntityLongTextFieldDef, EntityTextFieldDef, FieldsMap, FileFieldDef, FilesFieldDef, ImageFieldDef, ImagesFieldDef, JsonbFieldDef, LocatedTimestampFieldDef, LongTextFieldDef, MoneyFieldDef, MultiSelectFieldDef, NumberFieldDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, ResolvedPiiFlags, RetentionDef, SelectFieldDef, TimestampFieldDef, TzFieldDef } from "@cosmicdrift/kumiko-types/fields";
+import type { BigIntFieldDef, BooleanFieldDef, DateFieldDef, DecimalFieldDef, DerivedFieldDef, EmbeddedFieldDef, EntityDefinition, EntityIndexDef, EntityLongTextFieldDef, EntityTextFieldDef, FieldsMap, FileFieldDef, FilesFieldDef, ImageFieldDef, ImagesFieldDef, JsonbFieldDef, LocatedTimestampFieldDef, LongTextFieldDef, MoneyFieldDef, MultiSelectFieldDef, NumberFieldDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, ReferenceFieldDef, ResolvedPiiFlags, RetentionDef, SelectFieldDef, TimestampFieldDef, TzFieldDef } from "@cosmicdrift/kumiko-types/fields";
 import type { EntityTenancy } from "@cosmicdrift/kumiko-types/tenancy-brand";
 import type { TextFieldDef } from "./types/index.ts";
 export declare function createTextField<R extends true | false = false>(overrides: Partial<Omit<TextFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotations & {
@@ -40,6 +40,18 @@ export declare function createSelectField<const TOptions extends readonly string
 }): SelectFieldDef<TOptions> & {
     required: R;
 };
+/**
+ * Foreign key to another entity (`"customer"` or `"feature:entity"`), stored as a UUID.
+ * A reference to the user entity defaults to `personal: "ref"`; `personal: false` is
+ * rejected there because a user id is personal data.
+ */
+export declare function createReferenceField<R extends true | false = false>(opts: {
+    entity: string;
+} & Partial<Omit<ReferenceFieldDef, "type" | "entity" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & {
+    required?: R;
+}): ReferenceFieldDef & {
+    required: R;
+};
 /**
  * Multi-select field — N values from a fixed option list.
  *

package/dist/engine/factories.js

@@ -1,4 +1,5 @@
 import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { isUserEntityReference } from "./user-entity-reference.js";
 // `personal: { of: "id" }` means the row itself is the subject, not a
 // referenced user — resolves to `recordOwned` instead of `userOwned`.
 const RECORD_OWNER_FIELD = "id";
@@ -167,6 +168,23 @@ export function createSelectField(opts) {
         ...expandPersonalAnnotations(opts),
     }; // @cast-boundary engine-payload
 }
+/**
+ * Foreign key to another entity (`"customer"` or `"feature:entity"`), stored as a UUID.
+ * A reference to the user entity defaults to `personal: "ref"`; `personal: false` is
+ * rejected there because a user id is personal data.
+ */
+export function createReferenceField(opts) {
+    const targetsUser = isUserEntityReference(opts.entity);
+    if (targetsUser && opts.personal === false) {
+        throw new Error(`createReferenceField({ entity: "${opts.entity}" }): personal: false is not allowed for a reference to the user entity — a user id is personal data. Drop the annotation or use { personal: "ref" }.`);
+    }
+    const withUserDefault = targetsUser && opts.personal === undefined ? { ...opts, personal: "ref" } : opts;
+    return {
+        type: "reference",
+        required: false,
+        ...expandPersonalAnnotations(withUserDefault),
+    }; // @cast-boundary engine-payload
+}
 /**
  * Multi-select field — N values from a fixed option list.
  *

package/dist/engine/index.d.ts

@@ -57,7 +57,7 @@ export type { StorageProviderDestroyTenantHook, StorageProviderHookCtx, } from "
 export { isTenantDataExtensionHooks, type TenantDataDestroyHook, type TenantDataHookCtx, } from "./extensions/tenant-data.ts";
 export { isTenantResourceExtensionHooks, type TenantDestroyHookResult, type TenantResourceDestroyHook, type TenantResourceHookCtx, } from "./extensions/tenant-resource.ts";
 export type { TenantUserModel, UserDataDeleteHook, UserDataDeleteStrategy, UserDataExportHook, UserDataExportSnippet, UserDataHookCtx, UserDataStorageProvider, } from "./extensions/user-data.ts";
-export { createBigIntField, createBooleanField, createDateField, createDecimalField, createDerivedField, createEmbeddedField, createEmbeddedListField, createEntity, createFileField, createFilesField, createImageField, createImagesField, createJsonbField, createLocatedTimestampField, createLongTextField, createMoneyField, createMultiSelectField, createNumberField, createSelectField, createTextField, createTimestampField, createTzField, } from "./factories.ts";
+export { createBigIntField, createBooleanField, createDateField, createDecimalField, createDerivedField, createEmbeddedField, createEmbeddedListField, createEntity, createFileField, createFilesField, createImageField, createImagesField, createJsonbField, createLocatedTimestampField, createLongTextField, createMoneyField, createMultiSelectField, createNumberField, createReferenceField, createSelectField, createTextField, createTimestampField, createTzField, } from "./factories.ts";
 export { type ChangelogEntry, compareVersions, filterEntriesAfter, parseFeatureChangelog, } from "./feature-changelog.ts";
 export { buildManifestFromRegistry, type FeatureManifest, type ManifestConfigKey, type ManifestExtension, type ManifestFeature, type ManifestSecret, type ManifestSystemEvent, serializeManifest, } from "./feature-manifest.ts";
 export { filterReadFields, maskWriteOnlyFields, } from "./field-access.ts";

package/dist/engine/index.js

@@ -36,7 +36,7 @@ export { extensionSelectorTargets, SELECTED_EXTENSIONS_QUERY, selectablePluginId
 export { extensionUsageEscapeHatchReason } from "./extensions/escape-hatch-usage.js";
 export { isTenantDataExtensionHooks, } from "./extensions/tenant-data.js";
 export { isTenantResourceExtensionHooks, } from "./extensions/tenant-resource.js";
-export { createBigIntField, createBooleanField, createDateField, createDecimalField, createDerivedField, createEmbeddedField, createEmbeddedListField, createEntity, createFileField, createFilesField, createImageField, createImagesField, createJsonbField, createLocatedTimestampField, createLongTextField, createMoneyField, createMultiSelectField, createNumberField, createSelectField, createTextField, createTimestampField, createTzField, } from "./factories.js";
+export { createBigIntField, createBooleanField, createDateField, createDecimalField, createDerivedField, createEmbeddedField, createEmbeddedListField, createEntity, createFileField, createFilesField, createImageField, createImagesField, createJsonbField, createLocatedTimestampField, createLongTextField, createMoneyField, createMultiSelectField, createNumberField, createReferenceField, createSelectField, createTextField, createTimestampField, createTzField, } from "./factories.js";
 export { compareVersions, filterEntriesAfter, parseFeatureChangelog, } from "./feature-changelog.js";
 export { buildManifestFromRegistry, serializeManifest, } from "./feature-manifest.js";
 export { filterReadFields, maskWriteOnlyFields, } from "./field-access.js";

package/dist/engine/user-entity-reference.d.ts

@@ -0,0 +1,2 @@
+/** True when a reference field's `entity` ("user" or "<feature>:user") targets the user entity. */
+export declare function isUserEntityReference(referenceTarget: string): boolean;

package/dist/engine/user-entity-reference.js

@@ -0,0 +1,7 @@
+/** True when a reference field's `entity` ("user" or "<feature>:user") targets the user entity. */
+export function isUserEntityReference(referenceTarget) {
+    const entityName = referenceTarget.includes(":")
+        ? referenceTarget.split(":")[1]
+        : referenceTarget;
+    return entityName === "user";
+}

package/dist/files/index.d.ts

@@ -20,6 +20,8 @@ export { createInMemoryFileProvider } from "./in-memory-provider.ts";
 export { createLocalProvider } from "./local-provider.ts";
 export type { FileProviderContext, FileProviderPlugin, FileProviderResolver, } from "./provider-resolver.ts";
 export { createFileProviderForTenant, isFileProviderPlugin, } from "./provider-resolver.ts";
+export type { FileRefOwner, RebindFileRefContext, RebindFileRefOutcome, } from "./rebind-file-ref.ts";
+export { rebindFileRef } from "./rebind-file-ref.ts";
 export { filesStorageTrackingFeature, tenantStorageUsageTable, transferTenantStorageUsage, } from "./storage-tracking.ts";
 export type { FileStorageProvider, SignedUrlOptions, } from "./types.ts";
 export { assertSafeStorageKey, buildStorageKey, normalizeMimeType, sniffMimeType, tenantExportPrefix, tenantStoragePrefixes, validateFile, } from "./types.ts";

package/dist/files/index.js

@@ -15,6 +15,7 @@ export { configuredMaxUploadBytes, readFilesRouteOptions, resolveMaxUploadBodyBy
 export { createInMemoryFileProvider } from "./in-memory-provider.js";
 export { createLocalProvider } from "./local-provider.js";
 export { createFileProviderForTenant, isFileProviderPlugin, } from "./provider-resolver.js";
+export { rebindFileRef } from "./rebind-file-ref.js";
 export { filesStorageTrackingFeature, tenantStorageUsageTable, transferTenantStorageUsage, } from "./storage-tracking.js";
 export { assertSafeStorageKey, buildStorageKey, normalizeMimeType, sniffMimeType, tenantExportPrefix, tenantStoragePrefixes, validateFile, } from "./types.js";
 export { fileUploadLedgerTable, withUploadLedger, } from "./upload-ledger.js";

package/dist/files/rebind-file-ref.d.ts

@@ -0,0 +1,41 @@
+import type { TenantDb } from "../db/tenant-db.ts";
+import type { Registry, SessionUser } from "../engine/types/index.ts";
+import { type CanReadFileRefContext } from "./can-caller-read-file-ref.ts";
+export type RebindFileRefContext = {
+    readonly db: TenantDb;
+    readonly registry: Registry;
+    readonly user: SessionUser;
+    readonly dispatch?: CanReadFileRefContext["dispatch"];
+};
+export type FileRefOwner = {
+    readonly entityType: string;
+    readonly entityId: string;
+    readonly fieldName: string;
+};
+export type RebindFileRefOutcome = "rebound" | "not-found" | "moved" | "version-conflict";
+/**
+ * Moves a bound file from one record's file field to another's, for a record that takes over a
+ * file uploaded elsewhere (an upload record, a mail attachment). Server code only; pending uploads
+ * go through bindPendingFileRef.
+ *
+ * Only files of the caller's tenant are found ("not-found" otherwise, as for unknown ids). The
+ * file must still sit at `from`; "moved" means it does not (any more), for example because a
+ * parallel rebind took it first. A file already at `to` answers "rebound" without a write. The
+ * target must be a registered file field whose accept/maxSize the file fits (InternalError /
+ * UnprocessableError). Unless the caller is the framework system user, the caller must be able
+ * to read the file and to write both the source record and field (it must not be locked, and an
+ * entity without update handler leaves the move to the system user) and the target record and
+ * field (AccessDeniedError, RecordLockedError); the system user skips these checks, and only the
+ * target record has to exist (NotFoundError). The update is checked against the file's stream
+ * version read here, so a bind committing in between returns "version-conflict"; the source row
+ * stays locked until the surrounding transaction commits, so a lock set on `from` in between is
+ * either seen or waits. Rebind first, then save the id into
+ * the target field: the save accepts a file already bound to that record, and the source record
+ * no longer disposes of it when its field is cleared or the record is deleted.
+ * A handler passes its ctx; a job passes `{ db, registry, user: ctx.systemUser }`.
+ */
+export declare function rebindFileRef(ctx: RebindFileRefContext, args: {
+    readonly fileRefId: string;
+    readonly from: FileRefOwner;
+    readonly to: FileRefOwner;
+}): Promise<RebindFileRefOutcome>;

package/dist/files/rebind-file-ref.js

@@ -0,0 +1,170 @@
+import { isUuid } from "@cosmicdrift/kumiko-types/identifiers";
+import { isFrameworkSystemUser } from "../db/lock-guard.js";
+import { selectRowForUpdateById } from "../db/queries/entity-read.js";
+import { asEntityTableMeta } from "../db/table-introspection.js";
+import { tenantDbRunner } from "../db/tenant-db-runner.js";
+import { RecordLockedError } from "../errors/classes.js";
+import { AccessDeniedError, InternalError, NotFoundError, reraiseAsKumikoError, } from "../errors/index.js";
+import { assertRowFitsBindTarget } from "./bind-pending-file-refs.js";
+import { canCallerReadFileRef } from "./can-caller-read-file-ref.js";
+import { getFileRefExecutor } from "./create-file-ref.js";
+import { loadFileRefRows } from "./load-save-file-refs.js";
+import { createRecordReadCheck } from "./record-read-check.js";
+import { createRecordWriteCheck, findImplicitEntityTable, RecordWriteDecisions, } from "./record-write-check.js";
+const CONCURRENT_WRITE_ERROR_CODES = ["version_conflict", "unique_violation"];
+function nullableString(value) {
+    return value === null || typeof value === "string";
+}
+// The file guard (and an app's accessGuard) reads these columns; a row missing one is corrupt.
+async function loadRow(ctx, fileRefId) {
+    if (!isUuid(fileRefId))
+        return undefined;
+    const row = (await loadFileRefRows(ctx.db, [fileRefId], ctx.user.tenantId)).get(fileRefId);
+    if (row === undefined)
+        return undefined;
+    const { tenantId, storageKey, fileName, mimeType, size, entityType, entityId, fieldName } = row;
+    const { insertedById, version } = row;
+    if (typeof tenantId !== "string" ||
+        typeof storageKey !== "string" ||
+        typeof fileName !== "string" ||
+        typeof mimeType !== "string" ||
+        typeof size !== "number" ||
+        typeof version !== "number" ||
+        !nullableString(entityType) ||
+        !nullableString(entityId) ||
+        !nullableString(fieldName) ||
+        !nullableString(insertedById)) {
+        return undefined;
+    }
+    return {
+        fileRef: {
+            id: fileRefId,
+            tenantId,
+            storageKey,
+            fileName,
+            mimeType,
+            size,
+            entityType,
+            entityId,
+            fieldName,
+            insertedById,
+        },
+        version,
+    };
+}
+function isOwnedBy(fileRef, owner) {
+    return (fileRef.entityType === owner.entityType &&
+        fileRef.entityId === owner.entityId &&
+        fileRef.fieldName === owner.fieldName);
+}
+// Holds the source row until commit, so a lock or ownership change committed by another
+// transaction is either seen by the write check below or waits for this rebind to finish.
+async function lockSourceRow(ctx, from) {
+    const table = findImplicitEntityTable(ctx.registry, from.entityType);
+    const tableName = asEntityTableMeta(table)?.tableName;
+    // skip: no stored row to lock; the write check below answers not_found for it
+    if (tableName === undefined)
+        return;
+    await selectRowForUpdateById(tenantDbRunner(ctx.db), tableName, from.entityId);
+}
+// A caller other than the system job must be able to read the file today and must be able to
+// write both records as a save of them would: the source it takes the file from (unlocked, and
+// with an update handler the caller passes; without one only the system job may move the file),
+// and the target field it puts the file into.
+async function assertCallerMayMove(ctx, fileRef, from, to) {
+    if (!(await canCallerReadFileRef(ctx, fileRef))) {
+        throw new AccessDeniedError({ message: `rebindFileRef: file ${fileRef.id} is not readable` });
+    }
+    const canWriteRecord = createRecordWriteCheck({
+        registry: ctx.registry,
+        canReadRecord: createRecordReadCheck(ctx.registry, (qn, payload) => ctx.dispatch.query(qn, payload)),
+        tenantDbFor: () => ctx.db,
+    });
+    await lockSourceRow(ctx, from);
+    const sourceDecision = await canWriteRecord({ ...from, user: ctx.user });
+    if (sourceDecision === RecordWriteDecisions.locked) {
+        throw new RecordLockedError({ entityName: from.entityType, entityId: from.entityId });
+    }
+    if (sourceDecision !== RecordWriteDecisions.writable) {
+        throw new AccessDeniedError({
+            message: `rebindFileRef: source ${from.entityType}.${from.fieldName} of ${from.entityId} is not writable`,
+            details: { decision: sourceDecision },
+        });
+    }
+    const decision = await canWriteRecord({ ...to, user: ctx.user });
+    if (decision !== RecordWriteDecisions.writable) {
+        throw new AccessDeniedError({
+            message: `rebindFileRef: ${to.entityType}.${to.fieldName} of ${to.entityId} is not writable`,
+            details: { decision },
+        });
+    }
+}
+// The caller checks find the target as a side effect; the system path needs its own lookup so a
+// job cannot point a file at a record that does not exist in its tenant.
+async function assertTargetRecordExists(ctx, to) {
+    const entity = ctx.registry.getEntity(to.entityType);
+    const table = findImplicitEntityTable(ctx.registry, to.entityType);
+    const row = entity === undefined || table === undefined
+        ? undefined
+        : await ctx.db.fetchOne(table, {
+            id: to.entityId,
+            ...(entity.softDelete === true && { isDeleted: false }),
+        });
+    if (row === undefined)
+        throw new NotFoundError(to.entityType, to.entityId);
+}
+/**
+ * Moves a bound file from one record's file field to another's, for a record that takes over a
+ * file uploaded elsewhere (an upload record, a mail attachment). Server code only; pending uploads
+ * go through bindPendingFileRef.
+ *
+ * Only files of the caller's tenant are found ("not-found" otherwise, as for unknown ids). The
+ * file must still sit at `from`; "moved" means it does not (any more), for example because a
+ * parallel rebind took it first. A file already at `to` answers "rebound" without a write. The
+ * target must be a registered file field whose accept/maxSize the file fits (InternalError /
+ * UnprocessableError). Unless the caller is the framework system user, the caller must be able
+ * to read the file and to write both the source record and field (it must not be locked, and an
+ * entity without update handler leaves the move to the system user) and the target record and
+ * field (AccessDeniedError, RecordLockedError); the system user skips these checks, and only the
+ * target record has to exist (NotFoundError). The update is checked against the file's stream
+ * version read here, so a bind committing in between returns "version-conflict"; the source row
+ * stays locked until the surrounding transaction commits, so a lock set on `from` in between is
+ * either seen or waits. Rebind first, then save the id into
+ * the target field: the save accepts a file already bound to that record, and the source record
+ * no longer disposes of it when its field is cleared or the record is deleted.
+ * A handler passes its ctx; a job passes `{ db, registry, user: ctx.systemUser }`.
+ */
+export async function rebindFileRef(ctx, args) {
+    const { fileRefId, from, to } = args;
+    const loaded = await loadRow(ctx, fileRefId);
+    if (loaded === undefined)
+        return "not-found";
+    const { fileRef, version } = loaded;
+    if (isOwnedBy(fileRef, to))
+        return "rebound";
+    if (!isOwnedBy(fileRef, from))
+        return "moved";
+    assertRowFitsBindTarget(ctx.registry, { entityName: to.entityType, fieldName: to.fieldName }, fileRef);
+    if (isFrameworkSystemUser(ctx.user)) {
+        await assertTargetRecordExists(ctx, to);
+    }
+    else {
+        const { dispatch } = ctx;
+        if (dispatch === undefined) {
+            throw new InternalError({
+                message: "rebindFileRef: a caller other than the system user needs ctx.dispatch.query",
+            });
+        }
+        await assertCallerMayMove({ ...ctx, dispatch }, fileRef, from, to);
+    }
+    const moved = await getFileRefExecutor().update({
+        id: fileRefId,
+        version,
+        changes: { entityType: to.entityType, entityId: to.entityId, fieldName: to.fieldName },
+    }, ctx.user, ctx.db);
+    if (moved.isSuccess)
+        return "rebound";
+    if (CONCURRENT_WRITE_ERROR_CODES.includes(moved.error.code))
+        return "version-conflict";
+    throw reraiseAsKumikoError(moved.error);
+}

package/dist/i18n/required-surface-keys.d.ts

@@ -56,3 +56,9 @@ export type RequiredLocaleGap = {
  * reported as gap owners.
  */
 export declare function findRequiredLocaleGaps(features: readonly FeatureDefinition[], requiredLocales: readonly string[]): readonly RequiredLocaleGap[];
+export declare function embeddedCellLabelKey(featureName: string, entityName: string, fieldName: string, subFieldName: string): string;
+export declare function embeddedCellOptionLabelKey(featureName: string, entityName: string, fieldName: string, subFieldName: string, value: string): string;
+/** Keys for select option labels and embedded-list cells that the screens of one feature
+ *  display. Opt-in via `requireFieldValueTranslations`: without them the renderer falls back
+ *  to the raw option value or sub-field name. */
+export declare function fieldValueTranslationKeysFromFeature(feature: FeatureDefinition): readonly string[];

package/dist/i18n/required-surface-keys.js

@@ -596,3 +596,64 @@ export function findRequiredLocaleGaps(features, requiredLocales) {
     }
     return gaps;
 }
+export function embeddedCellLabelKey(featureName, entityName, fieldName, subFieldName) {
+    return `${fieldLabelKey(featureName, entityName, fieldName)}:cell:${subFieldName}`;
+}
+export function embeddedCellOptionLabelKey(featureName, entityName, fieldName, subFieldName, value) {
+    return `${embeddedCellLabelKey(featureName, entityName, fieldName, subFieldName)}:option:${value}`;
+}
+function pushFieldValueTranslationKeys(out, featureName, entityName, fieldName, def, includeEmbeddedCells) {
+    if (def.type === "select" || def.type === "multiSelect") {
+        for (const value of def.options) {
+            out.add(selectFacetOptionKey(featureName, entityName, fieldName, value));
+        }
+        // skip: option keys are complete, nothing else to collect for select fields
+        return;
+    }
+    // skip: only multi-row embedded fields render cell labels
+    if (!includeEmbeddedCells || def.type !== "embedded" || def.multiple !== true)
+        return;
+    for (const [subName, sub] of Object.entries(def.schema)) {
+        out.add(embeddedCellLabelKey(featureName, entityName, fieldName, subName));
+        if (sub.type !== "select")
+            continue;
+        for (const value of sub.options) {
+            out.add(embeddedCellOptionLabelKey(featureName, entityName, fieldName, subName, value));
+        }
+    }
+}
+/** Keys for select option labels and embedded-list cells that the screens of one feature
+ *  display. Opt-in via `requireFieldValueTranslations`: without them the renderer falls back
+ *  to the raw option value or sub-field name. */
+export function fieldValueTranslationKeysFromFeature(feature) {
+    const out = new Set();
+    for (const screen of Object.values(feature.screens)) {
+        if (screen.type === "entityList") {
+            const entity = feature.entities?.[screen.entity];
+            if (!entity)
+                continue;
+            for (const col of screen.columns) {
+                const { field } = normalizeListColumn(col);
+                const def = entity.fields[field];
+                if (def)
+                    pushFieldValueTranslationKeys(out, feature.name, screen.entity, field, def, false);
+            }
+        }
+        else if (screen.type === "entityEdit") {
+            const entity = feature.entities?.[screen.entity];
+            if (!entity)
+                continue;
+            for (const section of screen.layout.sections) {
+                if (isExtensionEditSection(section) || section.kind === "relatedList")
+                    continue;
+                for (const spec of sectionFieldSpecs(section)) {
+                    const field = editFieldName(spec);
+                    const def = entity.fields[field];
+                    if (def)
+                        pushFieldValueTranslationKeys(out, feature.name, screen.entity, field, def, true);
+                }
+            }
+        }
+    }
+    return [...out];
+}

package/dist/schema-cli/validate-boot-input.js

@@ -41,8 +41,10 @@ export function parseValidateBootOptions(raw) {
     const navAllowlistExempt = readOptionalOption(raw, "navAllowlistExempt", isStringSet, "a Set<string>");
     const warnOnUniqueAccessRoles = readOptionalOption(raw, "warnOnUniqueAccessRoles", isBoolean, "a boolean");
     const requiredLocales = readOptionalOption(raw, "requiredLocales", isNonEmptyStringArray, "an array of non-empty strings");
+    const requireFieldValueTranslations = readOptionalOption(raw, "requireFieldValueTranslations", isBoolean, "a boolean");
     return {
         ...(requiredLocales !== undefined && { requiredLocales }),
+        ...(requireFieldValueTranslations !== undefined && { requireFieldValueTranslations }),
         ...(navAllowlist !== undefined && { navAllowlist }),
         ...(navAllowlistExempt !== undefined && { navAllowlistExempt }),
         ...(warnOnUniqueAccessRoles !== undefined && { warnOnUniqueAccessRoles }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.400.0",
+  "version": "0.401.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -203,7 +203,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.400.0",
+    "@cosmicdrift/kumiko-types": "0.401.0",
     "bullmq": "^5.76.7",
     "hono": "^4.13.14",
     "i18next": "^26.1.0",
@@ -225,7 +225,7 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-testing": "0.400.0",
+    "@cosmicdrift/kumiko-testing": "0.401.0",
     "bun-types": "^1.4.4",
     "fflate": "^0.8.3",
     "meilisearch": "^0.58.0",

package/src/changes.json

@@ -1,4 +1,17 @@
 [
+  {
+    "version": "0.401.0",
+    "type": "improvement",
+    "title": "rebindFileRef, readGate allLinks with documents linkReadMode, documents tab entity fix",
+    "detail": "`rebindFileRef(ctx, { fileRefId, from, to })` from `@cosmicdrift/kumiko-framework/files` moves a file that is already bound (for example to an upload record or an inbound mail) onto another record's file field, for server code where a record takes over that file; pending uploads keep using `bindPendingFileRef`. It finds only files of the caller's tenant (\"not-found\" otherwise), answers \"moved\" when the file no longer sits at `from`, \"rebound\" when it was moved or already sits at `to`, and \"version-conflict\" when a parallel bind committed first, because the update is checked against the stream version. The target must be a registered file field whose accept and maxSize the file fits. A caller other than the framework system user must be able to read the file and must be able to write both the source record and field (not locked; an entity without update handler leaves the move to the system user) and the target record and field; the source row stays locked until the transaction commits, so a lock set in between is either seen or waits; a system job (`{ db, registry, user: ctx.systemUser }`) skips these checks, but the target record must exist. Rebind first, then save the id into the target field; clearing or deleting the source record afterwards leaves the file alone. An entity `readGate` takes `allLinks` as an alternative to `anyLink`: a row with links is visible only when the viewer can read every live link, and the boot validator rejects a gate that declares both. `createDocumentsFeature({ linkReadMode: \"allLinks\" })` switches the documents gate to it; the default stays `anyLink`, and the file-owner part is unchanged. `documentsTab()` now references `documents:filed-document`; before, a projection screen using it failed boot after the entity rename. Linking a document to a target entity without an update handler is now allowed for the roles in that entity's `access.write` (plus its row-level write rule); a target with neither stays unlinkable. `documents:write:link` and `documents:write:unlink` have title and field-label translations (de, en), and the documents write handlers carry an explicit `agent.risk` (link, unlink, create, update \"mid\"; import \"high\"). `createDocumentsFeature({ categoryLabels })` takes a de/en label per category (an unlabelled one shows its raw value); a key that is not in `categories` throws."
+  },
+  {
+    "version": "0.401.0",
+    "type": "breaking",
+    "title": "Boot rejects a user reference with personal: false and file accept entries that never match",
+    "detail": "`createReferenceField({ entity, personal?, reason?, required? })` builds a foreign key; a target ending in `:user` defaults to `personal: \"ref\"` and throws on `personal: false`. The boot validator now rejects a reference field to the user entity that carries `personal: false`, and a file, files, image or images field (also inside embedded schemas) whose `accept` has an entry that is not a bare lower-case extension, because the upload check compares the file's extension only. The new boot option `requireFieldValueTranslations: true` (also readable from the schema CLI input) lists every missing translation of select/multiSelect options and embedded cell labels shown by entityList/entityEdit screens in one error. `defineEntityWriteHandler` and the create/update/delete/restore wrappers return a type whose `reserveBeforeTransaction`, `beforeTransaction` and `beforeTransactionWhenNested` are `undefined`, so a handler spread into `defineWriteHandler` can add its own. user-data-rights has the export-job status option labels (de, en, es, fr, it); managed-pages branding accepts `png, jpg, jpeg, webp` instead of MIME types.",
+    "migration": "Replace `personal: false` on a reference to the user entity with `createReferenceField({ entity: \"user:user\" })` or `personal: \"ref\"`. Write `accept` entries as bare extensions (`\"pdf\"`, not `\".pdf\"` or `\"application/pdf\"`)."
+  },
   {
     "version": "0.400.0",
     "type": "improvement",