@cosmicdrift/kumiko-framework 0.401.0 → 0.403.0

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

@@ -1,7 +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.
@@ -46,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
@@ -57,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.`,
+            });
         }
     }
 }
@@ -89,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 ---
@@ -125,13 +142,13 @@ 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,
@@ -146,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,
@@ -158,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;
@@ -170,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) {
@@ -179,7 +197,9 @@ 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) {
@@ -190,7 +210,9 @@ function rejectPlaintextUserReference(input) {
     // 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" }.`);
+    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
@@ -200,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
@@ -212,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
@@ -223,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) {
@@ -236,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);
@@ -247,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
@@ -255,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
@@ -327,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)) {
@@ -344,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/projection-list-screens.js

@@ -1,8 +1,10 @@
 import { isListQueryWithoutSearchableFields, resolveEntityBehindListQuery, } from "../entity-list-searchability.js";
 import { QnTypes, qualifyEntityName } from "../qualified-name.js";
 import { isEditLayoutScreen } from "../screen-helpers.js";
+import { bootRuleError } from "./boot-rule.js";
 import { SEARCHABLE_FALSE_WHITELIST } from "./entity-list-screens.js";
 import { validateListTableAggregateQuery } from "./list-table-aggregate-query.js";
+import { NAMED_FILTER_RULES } from "./named-filter-rules.js";
 import { findEntity } from "./parent-ref.js";
 import { getZodObjectShape } from "./zod-shape.js";
 // Sibling to entity-list-screens.ts rather than an extension of it:
@@ -66,6 +68,7 @@ function validateOneProjectionListScreen(feature, screen, queryHandlers, feature
     }
     validateProjectionListFilterSchemaAcceptance(prefix, screen, schema);
     validateProjectionListFacetsSchemaAcceptance(prefix, screen, schema);
+    validateProjectionListNamedFilterSchemaAcceptance(prefix, screen, schema);
     validateListTableAggregateQuery({ prefix, ...screen, handler, featureMap });
 }
 // filter sends `payload.filter` — same 422 footgun as facets below
@@ -78,6 +81,16 @@ function validateProjectionListFilterSchemaAcceptance(prefix, screen, schema) {
         `schema — add filter: z.object({ field: z.string(), op: z.enum(["eq","ne","lt","gt","lte","gte","in"]), ` +
         `value: z.unknown() }).optional() (or reuse entityListSchema's shape) to the handler's schema.`);
 }
+// namedFilters send `payload.namedFilter` — same 422 footgun as filter/facets.
+function validateProjectionListNamedFilterSchemaAcceptance(prefix, screen, schema) {
+    // skip: no named filters declared, or the schema already accepts the key — nothing to reject.
+    if (screen.namedFilters === undefined || schemaAccepts(schema, "namedFilter"))
+        return;
+    throw bootRuleError(NAMED_FILTER_RULES.projectionQueryAcceptsNamedFilter, {
+        message: `${prefix}: declares namedFilters but query "${screen.query}" has no "namedFilter" parameter in its ` +
+            `Zod schema — add namedFilter: z.string().optional() to the handler's schema and resolve it with resolveNamedListFilters.`,
+    });
+}
 // facets send `payload.filters` — same failure mode as search/sort:
 // definePagedQueryHandler doesn't auto-merge params into the
 // handler's own Zod schema, so a declared facet would 422 on every query

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

@@ -45,6 +45,7 @@ export declare const entityListSchema: z.ZodObject<{
         }>;
         value: z.ZodUnknown;
     }, z.core.$strip>>>;
+    namedFilter: z.ZodOptional<z.ZodString>;
     aggregate: z.ZodOptional<z.ZodObject<{
         groupBy: z.ZodOptional<z.ZodString>;
         measures: z.ZodDefault<z.ZodArray<z.ZodObject<{

package/dist/engine/entity-handlers.js

@@ -15,6 +15,7 @@ import { entityListRuntime, parentVisibilityFor } from "./entity-list-runtime-op
 import { assertReason } from "./escape-hatch-reason.js";
 import { dropEmptyWriteOnlyValues } from "./field-access.js";
 import { instructionFieldNames } from "./instruction-fields.js";
+import { resolveNamedListFilters } from "./resolve-named-list-filters.js";
 import { buildInsertSchema, buildUpdateSchema } from "./schema-builder.js";
 import { parseTenantId } from "./types/identifiers.js";
 // Convention-based handler factories for event-sourced aggregates.
@@ -109,6 +110,8 @@ export const entityListSchema = z.object({
         value: z.unknown(),
     }))
         .optional(),
+    // Entity-defined work-queue rule (EntityDefinition.namedFilters); its conditions are appended to `filters`.
+    namedFilter: z.string().min(1).max(100).optional(),
     aggregate: listAggregatePayloadSchema.optional(),
 });
 function parseHandlerName(name, validVerbs) {
@@ -398,7 +401,16 @@ export function defineEntityQueryHandler(name, entity, options) {
                 // against Meilisearch/InMem at runtime (remote combobox search). The
                 // executor is built at definition time and cannot know the adapter, so the
                 // runtime override supplies it.
-                const listPayload = query.payload; // @cast-boundary engine-payload
+                const requestPayload = query.payload; // @cast-boundary engine-payload
+                const listPayload = requestPayload.namedFilter === undefined
+                    ? requestPayload
+                    : {
+                        ...requestPayload,
+                        filters: [
+                            ...(requestPayload.filters ?? []),
+                            ...(await resolveNamedListFilters(ctx, query.user, entityName, requestPayload.namedFilter)),
+                        ],
+                    };
                 const db = dbFor(ctx);
                 const { runtimeOptions, eagerLoadViewer, resolveEntity } = entityListRuntime(ctx, entityName, query.user);
                 if (listPayload.aggregate !== undefined) {

package/dist/engine/factories.d.ts

@@ -208,6 +208,8 @@ export declare function createEntity<const F, const T extends EntityTenancy = "t
     readonly readGate?: EntityDefinition["readGate"];
     readonly retention?: RetentionDef;
     readonly derivedFields?: EntityDefinition["derivedFields"];
+    /** See EntityDefinition.namedFilters. */
+    readonly namedFilters?: EntityDefinition["namedFilters"];
     readonly tenancy?: T;
     /** See EntityDefinition.transferable. */
     readonly transferable?: boolean;

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";
@@ -78,6 +80,7 @@ export { defineApply, defineMspApply, setFields } from "./projection-helpers.ts"
 export { isValidQn, parseQn, QnTypes, qn, toKebab } from "./qualified-name.ts";
 export { readClaim } from "./read-claim.ts";
 export { createRegistry } from "./registry.ts";
+export { resolveNamedListFilters } from "./resolve-named-list-filters.ts";
 export type { AssignableAppRoles } from "./role-assignment.ts";
 export { assignableAppRolesFromUsages, assignableAppRolesOf, BUILT_IN_MEMBERSHIP_ROLES, canActorAssignRole, findForbiddenRoleAssignment, isAssignableByRole, mergeAssignedRoles, } from "./role-assignment.ts";
 export { runPipeline, runStepList } from "./run-pipeline.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";
@@ -62,6 +64,7 @@ export { defineApply, defineMspApply, setFields } from "./projection-helpers.js"
 export { isValidQn, parseQn, QnTypes, qn, toKebab } from "./qualified-name.js";
 export { readClaim } from "./read-claim.js";
 export { createRegistry } from "./registry.js";
+export { resolveNamedListFilters } from "./resolve-named-list-filters.js";
 export { assignableAppRolesFromUsages, assignableAppRolesOf, BUILT_IN_MEMBERSHIP_ROLES, canActorAssignRole, findForbiddenRoleAssignment, isAssignableByRole, mergeAssignedRoles, } from "./role-assignment.js";
 export { runPipeline, runStepList } from "./run-pipeline.js";
 export { buildInsertSchema, buildUpdateSchema, fieldToZod, SYSTEM_ONLY_JSON_SCHEMA_KEY, } from "./schema-builder.js";

package/dist/engine/resolve-named-list-filters.d.ts

@@ -0,0 +1,3 @@
+import type { NamedListFilterCondition } from "@cosmicdrift/kumiko-types/named-list-filters";
+import type { HandlerContext, SessionUser } from "./types/index.ts";
+export declare function resolveNamedListFilters(ctx: HandlerContext, user: SessionUser, entityName: string, name: string): Promise<readonly NamedListFilterCondition[]>;

package/dist/engine/resolve-named-list-filters.js

@@ -0,0 +1,30 @@
+import { AccessDeniedError, ValidationError } from "../errors/index.js";
+import { hasAccess } from "./access.js";
+export async function resolveNamedListFilters(ctx, user, entityName, name) {
+    const registered = ctx.registry.getEntity(entityName)?.namedFilters ?? {};
+    const def = Object.hasOwn(registered, name) ? registered[name] : undefined;
+    if (def === undefined) {
+        throw new ValidationError({
+            fields: [
+                {
+                    path: "namedFilter",
+                    code: "unknown_named_filter",
+                    i18nKey: "errors.validation.invalid_value",
+                    params: { entity: entityName, namedFilter: name },
+                },
+            ],
+        });
+    }
+    if (def.access !== undefined && !hasAccess(user, def.access)) {
+        throw new AccessDeniedError();
+    }
+    const conditions = await def.filters({ ctx, user, now: ctx.tz.now() });
+    const entityFields = ctx.registry.getEntity(entityName)?.fields ?? {};
+    for (const condition of conditions) {
+        // Fail closed: a condition on a non-column is dropped by the list filter and would widen the queue.
+        if (condition.field !== "id" && !Object.hasOwn(entityFields, condition.field)) {
+            throw new Error(`Named filter "${name}" of entity "${entityName}" filters on unknown field "${condition.field}".`);
+        }
+    }
+    return conditions;
+}

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

@@ -480,6 +480,9 @@ export function requiredKeysFromFeature(feature) {
         for (const key of requiredKeysFromNav(nav))
             out.add(key);
     }
+    for (const collection of Object.values(feature.contentCollections ?? {})) {
+        pushKey(out, collection.nav.entryLabel);
+    }
     for (const ws of Object.values(feature.workspaces)) {
         for (const key of requiredKeysFromWorkspace(ws))
             out.add(key);

package/dist/schema-cli/validate-command.js

@@ -4,7 +4,7 @@ import { assertRowLevelSecurityTableState, createDbConnection, generateMigration
 import { isLiveFrameworkTable } from "../db/known-table-names.js";
 import { readMigrationSqlTexts } from "../db/migrate-runner.js";
 import { diffReplayAgainstSnapshot, replayMigrationsDir } from "../db/replay-migration-sql.js";
-import { BootValidationError } from "../engine/boot-validator/boot-rule.js";
+import { BootValidationError, bootRuleDocLink, } from "../engine/boot-validator/boot-rule.js";
 import { validateBoot } from "../engine/boot-validator.js";
 import { describeThrown, loadPreviousSnapshot, loadSchemaModOrReport, nextSequenceNumber, SNAPSHOT_FILENAME, } from "./shared.js";
 import { featureDefinitionsOf, parseValidateBootOptions, withFileStoragePresence, } from "./validate-boot-input.js";
@@ -44,6 +44,9 @@ function reportBootViolations(out, violations) {
         out.err(`  ✗ boot [${v.ruleId}] ${v.message}`);
         if (v.fix !== undefined)
             out.err(`    Fix: ${v.fix}`);
+        const docLink = bootRuleDocLink(v.ruleId);
+        if (docLink !== undefined)
+            out.err(`    Rule: ${docLink}`);
     }
 }
 // 2. Boot validity — needs the composed feature set.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.401.0",
+  "version": "0.403.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.401.0",
+    "@cosmicdrift/kumiko-types": "0.403.0",
     "bullmq": "^5.76.7",
     "hono": "^4.13.14",
     "i18next": "^26.1.0",
@@ -225,7 +225,7 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-testing": "0.401.0",
+    "@cosmicdrift/kumiko-testing": "0.403.0",
     "bun-types": "^1.4.4",
     "fflate": "^0.8.3",
     "meilisearch": "^0.58.0",

package/src/changes.json

@@ -1,4 +1,22 @@
 [
+  {
+    "version": "0.403.0",
+    "type": "improvement",
+    "title": "Entities define named list filters",
+    "detail": "createEntity takes namedFilters, a record of { access?, filters(scope) } where filters returns ListFilter conditions (sync or async). The default list query accepts namedFilter and appends the resolved conditions to filters, on the row path and the aggregate path. An unknown name is a validation error on namedFilter, a failed access rule is access_denied. resolveNamedListFilters is exported from the engine entry. The definition is function-valued and never reaches the client schema."
+  },
+  {
+    "version": "0.402.0",
+    "type": "improvement",
+    "title": "Boot violations carry rule ids with a fix and a doc link",
+    "detail": "43 boot rules have an id such as `pii/subject-key-sortable` or `entity-list/default-sort-required`. A violation in `BootValidationError.violations` and in `kumiko-schema validate` (text and `--json`) carries that id instead of `unclassified/<check>`, plus a `Fix:` line and `Rule: agents/boot-rules.md#<id>`. PII field rules, entityList screen rules, missing i18n keys, API and extension usages and user-data-rights hooks now report all violations in one run. Message texts are unchanged. `@cosmicdrift/kumiko-framework/engine` exports `bootRuleError`, `BootRuleViolation`, `BootValidationError`, `collectBootRuleViolations` and the types `BootRule`, `BootRuleTable`, `BootViolation`, so a feature's `r.bootCheck` can throw a classified rule."
+  },
+  {
+    "version": "0.402.0",
+    "type": "fix",
+    "title": "Migration replay keeps tables whose name ends in \"as\"",
+    "detail": "`CREATE TABLE IF NOT EXISTS \"read_themas\" (...)` was parsed as `CREATE TABLE read_them AS ...`, so `kumiko-schema validate` reported content drift for `read_them` and `read_themas`. `AS` now needs a column list or whitespace before it."
+  },
   {
     "version": "0.401.0",
     "type": "improvement",