@cosmicdrift/kumiko-framework 0.400.0 → 0.402.0

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

@@ -1,6 +1,10 @@
 import { holdsFileRefs } from "../../files/file-field-slots.js";
 import { createFallbackLogger } from "../../logging/utils.js";
+import { isUserEntityReference } from "../user-entity-reference.js";
+import { collectBootRuleViolations } from "./boot-report.js";
+import { bootRuleError } from "./boot-rule.js";
 import { PII_DIRECT_NAME_HINTS, PII_USER_OWNED_NAME_HINTS, PII_USER_REFERENCE_NAME_HINTS, } from "./entity-handler.js";
+import { PII_RULES } from "./pii-retention-rules.js";
 const log = createFallbackLogger("kumiko:boot");
 // Framework-managed timestamp fields may be used as retention.reference
 // even when they are not declared in entity.fields.
@@ -45,7 +49,9 @@ function validateWriteOnlyField(input) {
         for (const [subName, subField] of Object.entries(field.schema)) {
             if ("writeOnly" in subField && subField.writeOnly === true) {
                 // @cast-boundary schema-walk
-                throw new Error(`${where} declares writeOnly on embedded sub-field "${subName}" — writeOnly is only supported on top-level text fields. Remove writeOnly from the sub-field or declare it on a top-level text field.`);
+                throw bootRuleError(PII_RULES.writeOnlyEmbeddedSubField, {
+                    message: `${where} declares writeOnly on embedded sub-field "${subName}" — writeOnly is only supported on top-level text fields. Remove writeOnly from the sub-field or declare it on a top-level text field.`,
+                });
             }
         }
         // skip: embedded fields carry no writeOnly of their own; sub-fields are checked above
@@ -56,15 +62,21 @@ function validateWriteOnlyField(input) {
     if (flags.writeOnly !== true)
         return;
     if (field.type !== "text") {
-        throw new Error(`${where} declares { writeOnly: true } but has type "${field.type}" — writeOnly only applies to text fields. Use a text field or remove writeOnly.`);
+        throw bootRuleError(PII_RULES.writeOnlyNonText, {
+            message: `${where} declares { writeOnly: true } but has type "${field.type}" — writeOnly only applies to text fields. Use a text field or remove writeOnly.`,
+        });
     }
     if (field.sensitive !== true) {
-        throw new Error(`${where} declares { writeOnly: true } without { sensitive: true } — add find: "secret" (ciphertext at rest, stripped from event echoes).`);
+        throw bootRuleError(PII_RULES.writeOnlyWithoutSensitive, {
+            message: `${where} declares { writeOnly: true } without { sensitive: true } — add find: "secret" (ciphertext at rest, stripped from event echoes).`,
+        });
     }
     for (const flag of WRITE_ONLY_FORBIDDEN_FLAGS) {
         const value = flags[flag];
         if (value !== undefined && value !== false) {
-            throw new Error(`${where} combines { writeOnly: true } with { ${flag} } — a value that is never returned cannot be defaulted, searched, sorted, filtered or looked up. Remove either writeOnly or the conflicting flag.`);
+            throw bootRuleError(PII_RULES.writeOnlyConflictingFlag, {
+                message: `${where} combines { writeOnly: true } with { ${flag} } — a value that is never returned cannot be defaulted, searched, sorted, filtered or looked up. Remove either writeOnly or the conflicting flag.`,
+            });
         }
     }
 }
@@ -88,15 +100,21 @@ function validatePersonalJsonbField(input) {
     const flags = field; // @cast-boundary schema-walk
     for (const flag of JSONB_PERSONAL_FORBIDDEN_FLAGS) {
         if (flags[flag] !== undefined && flags[flag] !== false) {
-            throw new Error(`${where} combines a personal annotation on a jsonb field with { ${flag} } — ${reason}. Remove the ${flag} flag or the personal annotation.`);
+            throw bootRuleError(PII_RULES.personalJsonbFlag, {
+                message: `${where} combines a personal annotation on a jsonb field with { ${flag} } — ${reason}. Remove the ${flag} flag or the personal annotation.`,
+            });
         }
     }
     const index = entity.indexes?.find((def) => def.columns.includes(fieldName));
     if (index) {
-        throw new Error(`${where} is a personal jsonb field used in an entity index — ${reason}. Drop the index or the personal annotation.`);
+        throw bootRuleError(PII_RULES.personalJsonbIndex, {
+            message: `${where} is a personal jsonb field used in an entity index — ${reason}. Drop the index or the personal annotation.`,
+        });
     }
     if (fieldName === CUSTOM_FIELDS_COLUMN) {
-        throw new Error(`${where} is the custom-fields jsonb column — its values are merged and searched per key, which ciphertext cannot support. Drop the personal annotation.`);
+        throw bootRuleError(PII_RULES.personalJsonbCustomFields, {
+            message: `${where} is the custom-fields jsonb column — its values are merged and searched per key, which ciphertext cannot support. Drop the personal annotation.`,
+        });
     }
 }
 // --- PII / Subject-Key Annotations + Retention validation ---
@@ -124,16 +142,17 @@ function validatePersonalJsonbField(input) {
 // Encryption and decryption are handled elsewhere; this validation runs early
 // so schema drift is detected during boot.
 export function validatePiiAndRetention(feature) {
-    for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
-        validateFieldAnnotations(feature.name, entityName, entity);
-        validateEntityRetention(feature.name, entityName, entity);
-    }
+    collectBootRuleViolations(Object.entries(feature.entities ?? {}), ([entityName, entity]) => {
+        const entityChecks = [validateFieldAnnotations, validateEntityRetention];
+        collectBootRuleViolations(entityChecks, (check) => check(feature.name, entityName, entity));
+    });
 }
-// Order matters: the first failing rule decides the boot error, and warnings
-// are emitted in this order.
+// Every rule runs on every field; order only decides the order of the reported
+// violations and warnings.
 const FIELD_RULES = [
     rejectMultipleSubjectAnnotations,
     rejectTextWithoutPersonalStance,
+    rejectPlaintextUserReference,
     rejectInvalidLookupable,
     rejectSensitiveWithoutCiphertextAtRest,
     validateWriteOnlyField,
@@ -144,7 +163,7 @@ const FIELD_RULES = [
 ];
 function validateFieldAnnotations(featureName, entityName, entity) {
     const personalOfOwnerFieldNames = ownerFieldNamesReferencedByPersonalOf(entity.fields);
-    for (const [fieldName, field] of Object.entries(entity.fields)) {
+    collectBootRuleViolations(Object.entries(entity.fields), ([fieldName, field]) => {
         const flags = field; // @cast-boundary schema-walk
         const input = {
             featureName,
@@ -156,9 +175,8 @@ function validateFieldAnnotations(featureName, entityName, entity) {
             subjectAnnotationCount: countSubjectAnnotations(flags),
             personalOfOwnerFieldNames,
         };
-        for (const rule of FIELD_RULES)
-            rule(input);
-    }
+        collectBootRuleViolations(FIELD_RULES, (rule) => rule(input));
+    });
 }
 function countSubjectAnnotations(flags) {
     return [flags.pii, flags.userOwned, flags.tenantOwned, flags.recordOwned].filter(Boolean).length;
@@ -168,7 +186,9 @@ function fieldLocation(input) {
 }
 function rejectMultipleSubjectAnnotations(input) {
     if (input.subjectAnnotationCount > 1) {
-        throw new Error(`${fieldLocation(input)} has multiple subject-key annotations (personal: "self" / "tenant" / { of: "<field>" }). Pick one — each field belongs to exactly one subject.`);
+        throw bootRuleError(PII_RULES.multipleSubjectAnnotations, {
+            message: `${fieldLocation(input)} has multiple subject-key annotations (personal: "self" / "tenant" / { of: "<field>" }). Pick one — each field belongs to exactly one subject.`,
+        });
     }
 }
 function rejectTextWithoutPersonalStance(input) {
@@ -177,9 +197,23 @@ function rejectTextWithoutPersonalStance(input) {
         input.subjectAnnotationCount === 0 &&
         !flags.allowPlaintext &&
         !flags.subjectRef) {
-        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.`);
+        throw bootRuleError(PII_RULES.textWithoutPersonalStance, {
+            message: `${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 bootRuleError(PII_RULES.plaintextUserReference, {
+        message: `${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.
@@ -188,10 +222,14 @@ function rejectInvalidLookupable(input) {
     if (input.flags.lookupable !== true)
         return;
     if (input.field.type !== "text") {
-        throw new Error(`${fieldLocation(input)} declares find: "exact" (or "fuzzy") but has type "${input.field.type}" — blind-index equality lookups only apply to text fields. Use a text field or set find: "none".`);
+        throw bootRuleError(PII_RULES.lookupableNonText, {
+            message: `${fieldLocation(input)} declares find: "exact" (or "fuzzy") but has type "${input.field.type}" — blind-index equality lookups only apply to text fields. Use a text field or set find: "none".`,
+        });
     }
     if (input.subjectAnnotationCount === 0) {
-        throw new Error(`${fieldLocation(input)} declares find: "exact" (or "fuzzy") without a subject annotation (personal: "self" / "tenant" / { of: "<field>" }). Plaintext fields don't need a blind index — add personal or set find: "none".`);
+        throw bootRuleError(PII_RULES.lookupableWithoutSubject, {
+            message: `${fieldLocation(input)} declares find: "exact" (or "fuzzy") without a subject annotation (personal: "self" / "tenant" / { of: "<field>" }). Plaintext fields don't need a blind index — add personal or set find: "none".`,
+        });
     }
 }
 // Sensitive fields are stored as table ciphertext in the event log; without
@@ -200,7 +238,9 @@ function rejectInvalidLookupable(input) {
 function rejectSensitiveWithoutCiphertextAtRest(input) {
     const { flags } = input;
     if (flags.sensitive === true && input.subjectAnnotationCount === 0 && flags.encrypted !== true) {
-        throw new Error(`${fieldLocation(input)} declares { sensitive: true } without ciphertext-at-rest. Since #967 the event log stores sensitive fields as table ciphertext — add a subject annotation (personal: "self" / "tenant" / { of: "<field>" }) or { encrypted: true }.`);
+        throw bootRuleError(PII_RULES.sensitiveWithoutCiphertext, {
+            message: `${fieldLocation(input)} declares { sensitive: true } without ciphertext-at-rest. Since #967 the event log stores sensitive fields as table ciphertext — add a subject annotation (personal: "self" / "tenant" / { of: "<field>" }) or { encrypted: true }.`,
+        });
     }
 }
 // Sorting reads the projection column — that stays ciphertext, so
@@ -211,10 +251,14 @@ function rejectSensitiveWithoutCiphertextAtRest(input) {
 function rejectCiphertextSortOrSensitiveSearch(input) {
     const { flags } = input;
     if (input.subjectAnnotationCount > 0 && flags.sortable === true) {
-        throw new Error(`${fieldLocation(input)} combines a subject-key annotation with { sortable: true } — sorting reads the projection column, which is ciphertext at rest. For equality lookups use find: "exact"; drop sortable or keep the field plaintext (personal: false).`);
+        throw bootRuleError(PII_RULES.subjectKeySortable, {
+            message: `${fieldLocation(input)} combines a subject-key annotation with { sortable: true } — sorting reads the projection column, which is ciphertext at rest. For equality lookups use find: "exact"; drop sortable or keep the field plaintext (personal: false).`,
+        });
     }
     if (flags.sensitive === true && flags.searchable === true) {
-        throw new Error(`${fieldLocation(input)} combines { sensitive: true } with { searchable: true } — sensitive means ciphertext at rest, never searchable, stripped from event echoes — authorized readers can still read it back (passwords, tokens, tax IDs). Subject-annotated identity fields may be searchable (#1610); sensitive fields may not. To never return the value at all, add { writeOnly: true }.`);
+        throw bootRuleError(PII_RULES.sensitiveSearchable, {
+            message: `${fieldLocation(input)} combines { sensitive: true } with { searchable: true } — sensitive means ciphertext at rest, never searchable, stripped from event echoes — authorized readers can still read it back (passwords, tokens, tax IDs). Subject-annotated identity fields may be searchable (#1610); sensitive fields may not. To never return the value at all, add { writeOnly: true }.`,
+        });
     }
 }
 function validatePersonalOfOwner(input) {
@@ -224,7 +268,9 @@ function validatePersonalOfOwner(input) {
         return;
     const ownerName = personalOf.ownerField;
     if (!ownerName || typeof ownerName !== "string") {
-        throw new Error(`${fieldLocation(input)} has personal: { of: ... } without an owner field name. Pass the name of the owner field: personal: { of: "<ownerField>" }.`);
+        throw bootRuleError(PII_RULES.personalOfMissingOwnerName, {
+            message: `${fieldLocation(input)} has personal: { of: ... } without an owner field name. Pass the name of the owner field: personal: { of: "<ownerField>" }.`,
+        });
     }
     const ownerField = requireOwnerField(input, ownerName);
     rejectOwnerWithoutRowFallback(input, ownerName, ownerField, personalOf);
@@ -235,7 +281,9 @@ function requireOwnerField(input, ownerName) {
     const ownerField = fieldsByName[ownerName];
     if (!ownerField) {
         const known = Object.keys(fieldsByName).sort().join(", ");
-        throw new Error(`${fieldLocation(input)} references personal.of "${ownerName}" but no such field exists. Known fields: ${known}`);
+        throw bootRuleError(PII_RULES.personalOfUnknownOwner, {
+            message: `${fieldLocation(input)} references personal.of "${ownerName}" but no such field exists. Known fields: ${known}`,
+        });
     }
     // Text is accepted alongside reference: the ES-framework carries
     // user ids as plain text columns throughout the bundled features
@@ -243,17 +291,23 @@ function requireOwnerField(input, ownerName) {
     // relational FK to point a reference at. Self-referencing
     // ownerField (the field's own value IS the owner id) rides on this.
     if (ownerField.type !== "reference" && ownerField.type !== "text") {
-        throw new Error(`[Feature ${input.featureName}] personal.of "${ownerName}" on entity "${input.entityName}" must be a reference or text (userId) field, got type "${ownerField.type}"`);
+        throw bootRuleError(PII_RULES.personalOfOwnerType, {
+            message: `[Feature ${input.featureName}] personal.of "${ownerName}" on entity "${input.entityName}" must be a reference or text (userId) field, got type "${ownerField.type}"`,
+        });
     }
     return ownerField;
 }
 function rejectOwnerWithoutRowFallback(input, ownerName, ownerField, personalOf) {
     const { whenAbsent } = personalOf;
     if (whenAbsent !== undefined && whenAbsent !== "tenant" && whenAbsent !== "self") {
-        throw new Error(`${fieldLocation(input)} declares personal.whenAbsent "${String(whenAbsent)}" — entity fields only support whenAbsent: "tenant" or "self" (no plaintext fallback for stored PII). Remove whenAbsent or set it to "tenant" (tenant key) or "self" (the row's own record key).`);
+        throw bootRuleError(PII_RULES.personalOfInvalidWhenAbsent, {
+            message: `${fieldLocation(input)} declares personal.whenAbsent "${String(whenAbsent)}" — entity fields only support whenAbsent: "tenant" or "self" (no plaintext fallback for stored PII). Remove whenAbsent or set it to "tenant" (tenant key) or "self" (the row's own record key).`,
+        });
     }
     if (ownerField.required !== true && whenAbsent === undefined) {
-        throw new Error(`${fieldLocation(input)} is personal: { of: "${ownerName}" }, but "${ownerName}" is not required — rows without an owner would fail to encrypt (SubjectResolutionError, HTTP 500) on update, delete and forget. Declare { personal: { of: "${ownerName}", whenAbsent: "tenant" } } to encrypt those rows under the tenant key, whenAbsent: "self" to encrypt them under the row's own record key (shreddable per record), or make "${ownerName}" required: true. Entity fields have no plaintext fallback (fw#3654).`);
+        throw bootRuleError(PII_RULES.personalOfOptionalOwner, {
+            message: `${fieldLocation(input)} is personal: { of: "${ownerName}" }, but "${ownerName}" is not required — rows without an owner would fail to encrypt (SubjectResolutionError, HTTP 500) on update, delete and forget. Declare { personal: { of: "${ownerName}", whenAbsent: "tenant" } } to encrypt those rows under the tenant key, whenAbsent: "self" to encrypt them under the row's own record key (shreddable per record), or make "${ownerName}" required: true. Entity fields have no plaintext fallback (fw#3654).`,
+        });
     }
 }
 // Custom subject entities (such as HR employees or patients) are allowed but
@@ -263,8 +317,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.`);
     }
 }
@@ -316,8 +369,7 @@ function validateEntityRetention(featureName, entityName, entity) {
         fieldsByName: entity.fields,
         retention,
     };
-    for (const rule of RETENTION_RULES)
-        rule(input);
+    collectBootRuleViolations(RETENTION_RULES, (rule) => rule(input));
 }
 function warnOnInvalidKeepFor({ featureName, entityName, retention }) {
     if (!KEEP_FOR_PATTERN.test(retention.keepFor)) {
@@ -333,7 +385,9 @@ function rejectUnknownRetentionReference(input) {
     if (!fieldsByName[refName] && !FRAMEWORK_TIMESTAMP_FIELDS.has(refName)) {
         const known = Object.keys(fieldsByName).sort().join(", ");
         const framework = [...FRAMEWORK_TIMESTAMP_FIELDS].sort().join(", ");
-        throw new Error(`[Feature ${featureName}] Entity "${entityName}" retention.reference "${refName}" does not exist. Known fields: ${known} — framework-managed timestamps also accepted: ${framework}`);
+        throw bootRuleError(PII_RULES.retentionUnknownReference, {
+            message: `[Feature ${featureName}] Entity "${entityName}" retention.reference "${refName}" does not exist. Known fields: ${known} — framework-managed timestamps also accepted: ${framework}`,
+        });
     }
 }
 // blockDelete with no field that can carry `anonymize` is fine;

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/boot-validator/screens-actions-rules.d.ts

@@ -0,0 +1,7 @@
+export declare const SCREEN_ACTION_RULES: {
+    readonly actionIcon: {
+        readonly id: "screen/action-icon";
+        readonly summary: "Every screen action resolves to a registered icon.";
+        readonly fix: "Set icon to a registered NAV_ICONS key or use an action id that resolves one via the default icon map.";
+    };
+};

package/dist/engine/boot-validator/screens-actions-rules.js

@@ -0,0 +1,7 @@
+export const SCREEN_ACTION_RULES = {
+    actionIcon: {
+        id: "screen/action-icon",
+        summary: "Every screen action resolves to a registered icon.",
+        fix: "Set icon to a registered NAV_ICONS key or use an action id that resolves one via the default icon map.",
+    },
+};

package/dist/engine/boot-validator/screens-actions.js

@@ -4,6 +4,8 @@ import { fallbackTargets, SCREEN_FALLBACK_REASONS, } from "@cosmicdrift/kumiko-t
 import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { isKebabSegment, isValidQn, qualifyEntityName } from "../qualified-name.js";
 import { isFieldsEditSection, normalizeEditField, sectionFieldSpecs } from "../screen-helpers.js";
+import { bootRuleError } from "./boot-rule.js";
+import { SCREEN_ACTION_RULES } from "./screens-actions-rules.js";
 export function isRowClickAction(action) {
     return (action.kind === "navigate" || action.kind === "drawer") && action.rowClick === true;
 }
@@ -117,9 +119,11 @@ function isRegisteredIcon(icon) {
 export function validateActionHasIcon(featureName, screenId, screenType, context, action) {
     const resolved = resolveActionIcon(action.id, action.icon);
     if (resolved === undefined || !isRegisteredIcon(resolved)) {
-        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${context} "${action.id}" has no ` +
-            `resolvable icon — set icon to a key registered in NAV_ICONS, or use an id that resolves one of ` +
-            `its kebab segments via the default icon map (resolveActionIcon).`);
+        throw bootRuleError(SCREEN_ACTION_RULES.actionIcon, {
+            message: `[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${context} "${action.id}" has no ` +
+                `resolvable icon — set icon to a key registered in NAV_ICONS, or use an id that resolves one of ` +
+                `its kebab segments via the default icon map (resolveActionIcon).`,
+        });
     }
 }
 // Pin an action's declarative field references against the entity

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

@@ -22,6 +22,8 @@ export { handlerFieldLabelKey, handlerTitleKey } from "../i18n/required-surface-
 export { attachOutsideTransaction } from "../pipeline/attach-outside-transaction.ts";
 export { hasAccess } from "./access.ts";
 export type { PrincipalProfile, PrincipalStatus, PrincipalStatusPlugin, TenantLifecycleStatusPlugin, } from "./active-membership.ts";
+export { collectBootRuleViolations } from "./boot-validator/boot-report.ts";
+export { type BootRule, type BootRuleTable, BootRuleViolation, BootValidationError, type BootViolation, bootRuleError, } from "./boot-validator/boot-rule.ts";
 export { validateBundledListsOptions } from "./boot-validator/bundled-lists-table.ts";
 export { PII_DIRECT_NAME_HINTS, PII_USER_OWNED_NAME_HINTS, PII_USER_REFERENCE_NAME_HINTS, } from "./boot-validator/entity-handler.ts";
 export { entityHasAnonymizableSubjectField } from "./boot-validator/pii-retention.ts";
@@ -57,7 +59,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

@@ -4,6 +4,8 @@ export { DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, HTTP_ERROR_CODE_PATTERN,
 export { handlerFieldLabelKey, handlerTitleKey } from "../i18n/required-surface-keys.js";
 export { attachOutsideTransaction } from "../pipeline/attach-outside-transaction.js";
 export { hasAccess } from "./access.js";
+export { collectBootRuleViolations } from "./boot-validator/boot-report.js";
+export { BootRuleViolation, BootValidationError, bootRuleError, } from "./boot-validator/boot-rule.js";
 export { validateBundledListsOptions } from "./boot-validator/bundled-lists-table.js";
 export { PII_DIRECT_NAME_HINTS, PII_USER_OWNED_NAME_HINTS, PII_USER_REFERENCE_NAME_HINTS, } from "./boot-validator/entity-handler.js";
 export { entityHasAnonymizableSubjectField } from "./boot-validator/pii-retention.js";
@@ -36,7 +38,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>;