@cosmicdrift/kumiko-framework 0.414.0 → 0.415.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. package/agents/api/framework-engine.md +9 -3
  2. package/agents/api/framework-errors.md +1 -1
  3. package/agents/api/framework-ui-types.md +10 -1
  4. package/agents/api/renderer-web.md +20 -3
  5. package/agents/api/types.md +47 -14
  6. package/agents/api.md +2 -2
  7. package/agents/boot-rules.md +7 -5
  8. package/agents/examples/crypto-shredding-hr.md +63 -1
  9. package/agents/examples/record-detail-layout.md +113 -7
  10. package/agents/widgets.md +7 -0
  11. package/dist/api/request-context-internals.d.ts +2 -0
  12. package/dist/api/request-context-scopes.js +9 -2
  13. package/dist/api/request-context.js +1 -1
  14. package/dist/api/routes.js +4 -4
  15. package/dist/api/server-event-dispatcher.js +3 -0
  16. package/dist/db/parent-ref-clause.js +31 -3
  17. package/dist/db/parent-ref-global-hosts.d.ts +4 -1
  18. package/dist/db/parent-ref-global-hosts.js +50 -12
  19. package/dist/db/queries/rls-boot-catalog.js +5 -6
  20. package/dist/db/queries/rls-shape.d.ts +1 -0
  21. package/dist/db/queries/rls-shape.js +21 -6
  22. package/dist/engine/boot-validator/boot-rules.d.ts +16 -6
  23. package/dist/engine/boot-validator/card-meta-overflow-rules.d.ts +2 -2
  24. package/dist/engine/boot-validator/card-meta-overflow-rules.js +2 -2
  25. package/dist/engine/boot-validator/card-meta-overflow.js +7 -5
  26. package/dist/engine/boot-validator/entity-list-screens.js +2 -7
  27. package/dist/engine/boot-validator/list-row-guidance-rules.d.ts +2 -2
  28. package/dist/engine/boot-validator/list-row-guidance-rules.js +2 -2
  29. package/dist/engine/boot-validator/list-row-guidance.js +15 -1
  30. package/dist/engine/boot-validator/list-sort-summary-rules.d.ts +2 -2
  31. package/dist/engine/boot-validator/list-sort-summary-rules.js +2 -2
  32. package/dist/engine/boot-validator/list-sort-summary.js +31 -20
  33. package/dist/engine/boot-validator/list-toolbar-options.js +3 -4
  34. package/dist/engine/boot-validator/named-filter-rules.d.ts +10 -0
  35. package/dist/engine/boot-validator/named-filter-rules.js +10 -0
  36. package/dist/engine/boot-validator/projection-list-screens.js +5 -4
  37. package/dist/engine/boot-validator/query-output-guidance.js +1 -0
  38. package/dist/engine/boot-validator/query-refs.js +10 -0
  39. package/dist/engine/boot-validator/screens-actions.js +1 -1
  40. package/dist/engine/named-filter-roles.js +6 -14
  41. package/dist/engine/schema-builder.js +3 -1
  42. package/dist/engine/soft-delete-cleanup.js +2 -0
  43. package/dist/errors/reasons.d.ts +1 -0
  44. package/dist/errors/reasons.js +4 -0
  45. package/dist/i18n/required-surface-keys.js +2 -1
  46. package/dist/jobs/job-runner-execution.js +3 -0
  47. package/dist/jobs/job-runner-types.d.ts +1 -0
  48. package/dist/jobs/job-runner.js +8 -0
  49. package/dist/pipeline/context-services.d.ts +1 -1
  50. package/dist/pipeline/context-services.js +1 -1
  51. package/dist/pipeline/event-dispatcher-delivery.js +3 -0
  52. package/dist/pipeline/event-dispatcher.d.ts +2 -0
  53. package/dist/pipeline/handler-context-phase-denials.js +1 -1
  54. package/dist/pipeline/irreversible-operation-gate.js +36 -10
  55. package/dist/search/meilisearch-adapter-internals.d.ts +2 -0
  56. package/dist/search/meilisearch-adapter-internals.js +5 -0
  57. package/dist/search/meilisearch-adapter.d.ts +1 -0
  58. package/dist/search/meilisearch-adapter.js +3 -2
  59. package/dist/ui-types/card-column-roles.d.ts +2 -0
  60. package/dist/ui-types/card-column-roles.js +15 -0
  61. package/dist/ui-types/index.d.ts +2 -2
  62. package/dist/ui-types/index.js +1 -1
  63. package/package.json +3 -3
  64. package/presets/biome-plugins/no-date-api.grit +3 -1
  65. package/presets/biome-plugins/no-direct-fetch.grit +1 -1
  66. package/presets/biome-plugins/unsafe-json-parse.grit +7 -1
  67. package/presets/biome-rules.json +12 -10
  68. package/src/changes.json +57 -0
@@ -17,12 +17,7 @@ function commandOf(code) {
17
17
  throw new Error(`unknown pg_policy.polcmd code "${code}"`);
18
18
  return command;
19
19
  }
20
- export async function readRowLevelSecurityShape(db, tableName) {
21
- const rows = await asRawClient(db).unsafe(`SELECT c.relrowsecurity, c.relforcerowsecurity, p.polname, p.polpermissive, p.polcmd::text AS polcmd, (p.polroles = '{0}'::oid[]) AS polpublic
22
- FROM pg_class c
23
- JOIN pg_namespace n ON n.oid = c.relnamespace
24
- LEFT JOIN pg_policy p ON p.polrelid = c.oid
25
- WHERE n.nspname = 'public' AND c.relname = $1`, [tableName]);
20
+ function shapeOfRows(rows) {
26
21
  const first = rows[0];
27
22
  if (first === undefined)
28
23
  return undefined;
@@ -41,6 +36,26 @@ export async function readRowLevelSecurityShape(db, tableName) {
41
36
  });
42
37
  return { enabled: first.relrowsecurity, forced: first.relforcerowsecurity, policies };
43
38
  }
39
+ export async function readRowLevelSecurityShapes(db, tableNames) {
40
+ const shapes = new Map();
41
+ if (tableNames.length === 0)
42
+ return shapes;
43
+ const rows = await asRawClient(db).unsafe(`SELECT c.relname, c.relrowsecurity, c.relforcerowsecurity, p.polname, p.polpermissive, p.polcmd::text AS polcmd, (p.polroles = '{0}'::oid[]) AS polpublic
44
+ FROM pg_class c
45
+ JOIN pg_namespace n ON n.oid = c.relnamespace
46
+ LEFT JOIN pg_policy p ON p.polrelid = c.oid
47
+ WHERE n.nspname = 'public' AND c.relname = ANY($1::text[])`, [tableNames]);
48
+ const rowsByTable = Map.groupBy(rows, (row) => row.relname);
49
+ for (const [tableName, tableRows] of rowsByTable) {
50
+ const shape = shapeOfRows(tableRows);
51
+ if (shape !== undefined)
52
+ shapes.set(tableName, shape);
53
+ }
54
+ return shapes;
55
+ }
56
+ export async function readRowLevelSecurityShape(db, tableName) {
57
+ return (await readRowLevelSecurityShapes(db, [tableName])).get(tableName);
58
+ }
44
59
  // Shared by the rebuild guard and the boot check, so both judge a hand-edited policy alike.
45
60
  export function isFrameworkIsolationIntact(shape) {
46
61
  const isolation = shape.policies.find((policy) => policy.name === TENANT_ISOLATION_POLICY);
@@ -177,6 +177,16 @@ export declare const FRAMEWORK_BOOT_RULE_TABLES: readonly [{
177
177
  readonly summary: "A named filter's emptyState.title is a non-empty i18n key.";
178
178
  readonly fix: "Name the title key or remove emptyState from the filter.";
179
179
  };
180
+ readonly emptyStateParamsQueryEmpty: {
181
+ readonly id: "list/named-filter-empty-state-params-query-empty";
182
+ readonly summary: "A named filter's emptyState.paramsQuery is a non-empty query QN.";
183
+ readonly fix: "Name the query or remove paramsQuery from the emptyState.";
184
+ };
185
+ readonly emptyStateParamsQueryWithoutDescription: {
186
+ readonly id: "list/named-filter-empty-state-params-query-without-description";
187
+ readonly summary: "A named filter's emptyState.paramsQuery feeds the description, so it needs one.";
188
+ readonly fix: "Set emptyState.description (an i18n key with {params}) or remove paramsQuery.";
189
+ };
180
190
  readonly statNavigateTarget: {
181
191
  readonly id: "named-filter/stat-navigate-target";
182
192
  readonly summary: "A stat navigate.screen resolves to an entityList, projectionList or custom screen.";
@@ -231,8 +241,8 @@ export declare const FRAMEWORK_BOOT_RULE_TABLES: readonly [{
231
241
  }, {
232
242
  readonly overflow: {
233
243
  readonly id: "list/card-meta-overflow";
234
- readonly summary: "A card list shows at most the maximum number of meta columns.";
235
- readonly fix: "Reduce each list to the maximum number of meta columns or mark the others hideOnNarrow: true.";
244
+ readonly summary: "A card list shows at most the maximum number of meta lines.";
245
+ readonly fix: "Reduce each list to the maximum number of meta lines or mark the other columns hideOnNarrow: true.";
236
246
  };
237
247
  }, {
238
248
  readonly actionIcon: {
@@ -1165,7 +1175,7 @@ export declare const FRAMEWORK_BOOT_RULE_TABLES: readonly [{
1165
1175
  };
1166
1176
  readonly hintColumnLink: {
1167
1177
  readonly id: "list/hint-column-link";
1168
- readonly summary: "A hint column owns its cell rendering and sets no linkScreenField, linkParamsField, refEntity or badgeToneField.";
1178
+ readonly summary: "A hint column owns its cell rendering and sets no linkScreenField, linkParamsField, refEntity, badgeToneField or badgeDot.";
1169
1179
  readonly fix: "Remove the link or badge option, or move the hint to its own column.";
1170
1180
  };
1171
1181
  readonly hintColumnEmptyPlaceholder: {
@@ -1216,7 +1226,7 @@ export declare const FRAMEWORK_BOOT_RULE_TABLES: readonly [{
1216
1226
  readonly rowDecorationIdsMissing: {
1217
1227
  readonly id: "list/row-decoration-ids-missing";
1218
1228
  readonly summary: "The rowDecoration query's input schema declares `ids`, the row ids the list sends with every call.";
1219
- readonly fix: "Add `ids: z.array(z.string())` to the decoration query's schema.";
1229
+ readonly fix: "Add `ids: z.array(z.string())` to the decoration query's schema; `.max(...)` must cover at least the list page size; the list asks in batches of the first page size.";
1220
1230
  };
1221
1231
  }, {
1222
1232
  readonly listScreenIdUnresolved: {
@@ -2671,7 +2681,7 @@ export declare const FRAMEWORK_BOOT_RULE_TABLES: readonly [{
2671
2681
  }, {
2672
2682
  readonly sortOptionNotSortable: {
2673
2683
  readonly id: "list/sort-option-not-sortable";
2674
- readonly summary: "Every sortOptions field is a listed, sortable column (entityList); a projectionList's query takes sort and sortDirection and, when sort is an enum, lists every option field.";
2684
+ readonly summary: "Every sortOptions field is a listed, sortable column (entityList); a projectionList's query takes sort and sortDirection and, when they are enums, lists every option field and dir.";
2675
2685
  readonly fix: "Mark the field sortable and list it as a column, or give the projectionList's query sort and sortDirection parameters that accept the option fields.";
2676
2686
  };
2677
2687
  readonly sortOptionsInvalid: {
@@ -2696,7 +2706,7 @@ export declare const FRAMEWORK_BOOT_RULE_TABLES: readonly [{
2696
2706
  };
2697
2707
  readonly summaryRowQueryAcceptsListKeys: {
2698
2708
  readonly id: "list/summary-row-query-accepts-list-keys";
2699
- readonly summary: "The summaryRow query's Zod schema accepts every list key the screen sends (search, namedFilter, filters).";
2709
+ readonly summary: "The summaryRow query's Zod schema accepts every list key the screen sends (search, namedFilter, filters) and every summaryRow.params key.";
2700
2710
  readonly fix: "Add the missing keys to the query schema (or reuse the list query's filter shape) and apply them, or drop the feature on the screen.";
2701
2711
  };
2702
2712
  readonly summaryRowWithTotals: {
@@ -1,7 +1,7 @@
1
1
  export declare const CARD_META_OVERFLOW_RULES: {
2
2
  readonly overflow: {
3
3
  readonly id: "list/card-meta-overflow";
4
- readonly summary: "A card list shows at most the maximum number of meta columns.";
5
- readonly fix: "Reduce each list to the maximum number of meta columns or mark the others hideOnNarrow: true.";
4
+ readonly summary: "A card list shows at most the maximum number of meta lines.";
5
+ readonly fix: "Reduce each list to the maximum number of meta lines or mark the other columns hideOnNarrow: true.";
6
6
  };
7
7
  };
@@ -1,7 +1,7 @@
1
1
  export const CARD_META_OVERFLOW_RULES = {
2
2
  overflow: {
3
3
  id: "list/card-meta-overflow",
4
- summary: "A card list shows at most the maximum number of meta columns.",
5
- fix: "Reduce each list to the maximum number of meta columns or mark the others hideOnNarrow: true.",
4
+ summary: "A card list shows at most the maximum number of meta lines.",
5
+ fix: "Reduce each list to the maximum number of meta lines or mark the other columns hideOnNarrow: true.",
6
6
  },
7
7
  };
@@ -1,4 +1,4 @@
1
- import { CARD_META_MAX, cardColumnRoles, cardFileDisplayKind, } from "../../ui-types/card-column-roles.js";
1
+ import { CARD_META_MAX, cardColumnRoles, cardFileDisplayKind, cardMetaLines, } from "../../ui-types/card-column-roles.js";
2
2
  import { LIST_ROW_META_COLUMNS } from "../../ui-types/list-row-meta.js";
3
3
  import { parseRefTarget } from "../parse-ref-target.js";
4
4
  import { normalizeListColumn } from "../screen-helpers.js";
@@ -28,18 +28,20 @@ function countOverflow(feature, screen, location, columns, storedTypeOf, entity)
28
28
  type,
29
29
  renderer: col.renderer,
30
30
  hideOnNarrow: col.hideOnNarrow,
31
+ narrowInline: col.narrowInline,
31
32
  hint: col.hint,
32
33
  ...(fileKind !== undefined && { fileDisplay: { kind: fileKind } }),
33
34
  };
34
35
  });
35
36
  const { meta } = cardColumnRoles(cardColumns);
36
- if (meta.length <= CARD_META_MAX)
37
+ const lineCount = cardMetaLines(meta).length;
38
+ if (lineCount <= CARD_META_MAX)
37
39
  return undefined;
38
40
  return {
39
41
  feature: feature.name,
40
42
  screen,
41
43
  ...(location !== undefined && { location }),
42
- count: meta.length,
44
+ count: lineCount,
43
45
  fields: meta.map((col) => col.field),
44
46
  };
45
47
  }
@@ -96,8 +98,8 @@ export function validateCardMetaOverflow(features) {
96
98
  // skip: nothing overflows, so there is nothing to report
97
99
  if (overflows.length === 0)
98
100
  return;
99
- const lines = overflows.map((o) => ` - Feature "${o.feature}" screen "${o.screen}"${o.location !== undefined ? ` ${o.location}` : ""}: ${o.count} meta columns (${o.fields.join(", ")})`);
101
+ const lines = overflows.map((o) => ` - Feature "${o.feature}" screen "${o.screen}"${o.location !== undefined ? ` ${o.location}` : ""}: ${o.count} meta lines from the columns ${o.fields.join(", ")}`);
100
102
  throw bootRuleError(CARD_META_OVERFLOW_RULES.overflow, {
101
- message: `List cards show at most ${CARD_META_MAX} meta columns (all columns except title, status select and hideOnNarrow ones); more would be cut off on narrow screens:\n${lines.join("\n")}\nReduce each to ${CARD_META_MAX} columns or mark the others hideOnNarrow: true.`,
103
+ message: `List cards show at most ${CARD_META_MAX} meta lines (all columns except title, status select and hideOnNarrow ones, consecutive narrowInline columns sharing one line); more would be cut off on narrow screens:\n${lines.join("\n")}\nReduce each to ${CARD_META_MAX} lines or mark the other columns hideOnNarrow: true.`,
102
104
  });
103
105
  }
@@ -1,3 +1,4 @@
1
+ import { entityHasFilterableFields, } from "@cosmicdrift/kumiko-types/screen";
1
2
  import { LIST_ROW_META_COLUMNS } from "../../ui-types/list-row-meta.js";
2
3
  import { normalizeListColumn } from "../screen-helpers.js";
3
4
  import { collectBootRuleViolations } from "./boot-report.js";
@@ -15,13 +16,7 @@ export const SEARCHABLE_FALSE_WHITELIST = new Set(["download-attempt-list", "cap
15
16
  // because the renderer's LIST_ROW_META_COLUMNS doesn't know them.
16
17
  export const LIST_ROW_META_COLUMN_NAMES = new Set(Object.keys(LIST_ROW_META_COLUMNS));
17
18
  export function hasFilterableFields(feature, entityName) {
18
- const entities = feature.entities;
19
- if (!entities)
20
- return false;
21
- const entity = entities[entityName];
22
- if (!entity)
23
- return false;
24
- return Object.values(entity.fields).some((raw) => "filterable" in raw && raw.filterable === true);
19
+ return entityHasFilterableFields(feature.entities?.[entityName]);
25
20
  }
26
21
  function hasEntityEditDetail(feature, entityName) {
27
22
  return Object.values(feature.screens).some((s) => s.type === "entityEdit" && s.entity === entityName);
@@ -11,7 +11,7 @@ export declare const LIST_ROW_GUIDANCE_RULES: {
11
11
  };
12
12
  readonly hintColumnLink: {
13
13
  readonly id: "list/hint-column-link";
14
- readonly summary: "A hint column owns its cell rendering and sets no linkScreenField, linkParamsField, refEntity or badgeToneField.";
14
+ readonly summary: "A hint column owns its cell rendering and sets no linkScreenField, linkParamsField, refEntity, badgeToneField or badgeDot.";
15
15
  readonly fix: "Remove the link or badge option, or move the hint to its own column.";
16
16
  };
17
17
  readonly hintColumnEmptyPlaceholder: {
@@ -62,6 +62,6 @@ export declare const LIST_ROW_GUIDANCE_RULES: {
62
62
  readonly rowDecorationIdsMissing: {
63
63
  readonly id: "list/row-decoration-ids-missing";
64
64
  readonly summary: "The rowDecoration query's input schema declares `ids`, the row ids the list sends with every call.";
65
- readonly fix: "Add `ids: z.array(z.string())` to the decoration query's schema.";
65
+ readonly fix: "Add `ids: z.array(z.string())` to the decoration query's schema; `.max(...)` must cover at least the list page size; the list asks in batches of the first page size.";
66
66
  };
67
67
  };
@@ -11,7 +11,7 @@ export const LIST_ROW_GUIDANCE_RULES = {
11
11
  },
12
12
  hintColumnLink: {
13
13
  id: "list/hint-column-link",
14
- summary: "A hint column owns its cell rendering and sets no linkScreenField, linkParamsField, refEntity or badgeToneField.",
14
+ summary: "A hint column owns its cell rendering and sets no linkScreenField, linkParamsField, refEntity, badgeToneField or badgeDot.",
15
15
  fix: "Remove the link or badge option, or move the hint to its own column.",
16
16
  },
17
17
  hintColumnEmptyPlaceholder: {
@@ -62,6 +62,6 @@ export const LIST_ROW_GUIDANCE_RULES = {
62
62
  rowDecorationIdsMissing: {
63
63
  id: "list/row-decoration-ids-missing",
64
64
  summary: "The rowDecoration query's input schema declares `ids`, the row ids the list sends with every call.",
65
- fix: "Add `ids: z.array(z.string())` to the decoration query's schema.",
65
+ fix: "Add `ids: z.array(z.string())` to the decoration query's schema; `.max(...)` must cover at least the list page size; the list asks in batches of the first page size.",
66
66
  },
67
67
  };
@@ -14,6 +14,7 @@ const HINT_CONFLICTS = [
14
14
  { option: "linkParamsField", rule: LIST_ROW_GUIDANCE_RULES.hintColumnLink },
15
15
  { option: "refEntity", rule: LIST_ROW_GUIDANCE_RULES.hintColumnLink },
16
16
  { option: "badgeToneField", rule: LIST_ROW_GUIDANCE_RULES.hintColumnLink },
17
+ { option: "badgeDot", rule: LIST_ROW_GUIDANCE_RULES.hintColumnLink },
17
18
  { option: "emptyPlaceholder", rule: LIST_ROW_GUIDANCE_RULES.hintColumnEmptyPlaceholder },
18
19
  ];
19
20
  function validateHintColumn(where, column) {
@@ -81,11 +82,24 @@ function validateNamedFilterOptions(where, screen) {
81
82
  });
82
83
  }
83
84
  for (const ref of screen.namedFilters ?? []) {
84
- if (ref.emptyState !== undefined && ref.emptyState.title.trim().length === 0) {
85
+ const { emptyState } = ref;
86
+ if (emptyState === undefined)
87
+ continue;
88
+ if (emptyState.title.trim().length === 0) {
85
89
  throw bootRuleError(NAMED_FILTER_RULES.emptyStateTitleEmpty, {
86
90
  message: `${where} namedFilters "${ref.id}" sets emptyState with an empty title. Name the i18n key or remove emptyState.`,
87
91
  });
88
92
  }
93
+ if (emptyState.paramsQuery !== undefined && emptyState.paramsQuery.trim().length === 0) {
94
+ throw bootRuleError(NAMED_FILTER_RULES.emptyStateParamsQueryEmpty, {
95
+ message: `${where} namedFilters "${ref.id}" sets emptyState.paramsQuery to an empty string. Name the query or remove paramsQuery.`,
96
+ });
97
+ }
98
+ if (emptyState.paramsQuery !== undefined && emptyState.description === undefined) {
99
+ throw bootRuleError(NAMED_FILTER_RULES.emptyStateParamsQueryWithoutDescription, {
100
+ message: `${where} namedFilters "${ref.id}" sets emptyState.paramsQuery without a description — the params only feed the description. Set description or remove paramsQuery.`,
101
+ });
102
+ }
89
103
  }
90
104
  }
91
105
  function guidanceLocation(featureName, screenId, kind, partLabel) {
@@ -1,7 +1,7 @@
1
1
  export declare const LIST_SORT_SUMMARY_RULES: {
2
2
  readonly sortOptionNotSortable: {
3
3
  readonly id: "list/sort-option-not-sortable";
4
- readonly summary: "Every sortOptions field is a listed, sortable column (entityList); a projectionList's query takes sort and sortDirection and, when sort is an enum, lists every option field.";
4
+ readonly summary: "Every sortOptions field is a listed, sortable column (entityList); a projectionList's query takes sort and sortDirection and, when they are enums, lists every option field and dir.";
5
5
  readonly fix: "Mark the field sortable and list it as a column, or give the projectionList's query sort and sortDirection parameters that accept the option fields.";
6
6
  };
7
7
  readonly sortOptionsInvalid: {
@@ -26,7 +26,7 @@ export declare const LIST_SORT_SUMMARY_RULES: {
26
26
  };
27
27
  readonly summaryRowQueryAcceptsListKeys: {
28
28
  readonly id: "list/summary-row-query-accepts-list-keys";
29
- readonly summary: "The summaryRow query's Zod schema accepts every list key the screen sends (search, namedFilter, filters).";
29
+ readonly summary: "The summaryRow query's Zod schema accepts every list key the screen sends (search, namedFilter, filters) and every summaryRow.params key.";
30
30
  readonly fix: "Add the missing keys to the query schema (or reuse the list query's filter shape) and apply them, or drop the feature on the screen.";
31
31
  };
32
32
  readonly summaryRowWithTotals: {
@@ -1,7 +1,7 @@
1
1
  export const LIST_SORT_SUMMARY_RULES = {
2
2
  sortOptionNotSortable: {
3
3
  id: "list/sort-option-not-sortable",
4
- summary: "Every sortOptions field is a listed, sortable column (entityList); a projectionList's query takes sort and sortDirection and, when sort is an enum, lists every option field.",
4
+ summary: "Every sortOptions field is a listed, sortable column (entityList); a projectionList's query takes sort and sortDirection and, when they are enums, lists every option field and dir.",
5
5
  fix: "Mark the field sortable and list it as a column, or give the projectionList's query sort and sortDirection parameters that accept the option fields.",
6
6
  },
7
7
  sortOptionsInvalid: {
@@ -26,7 +26,7 @@ export const LIST_SORT_SUMMARY_RULES = {
26
26
  },
27
27
  summaryRowQueryAcceptsListKeys: {
28
28
  id: "list/summary-row-query-accepts-list-keys",
29
- summary: "The summaryRow query's Zod schema accepts every list key the screen sends (search, namedFilter, filters).",
29
+ summary: "The summaryRow query's Zod schema accepts every list key the screen sends (search, namedFilter, filters) and every summaryRow.params key.",
30
30
  fix: "Add the missing keys to the query schema (or reuse the list query's filter shape) and apply them, or drop the feature on the screen.",
31
31
  },
32
32
  summaryRowWithTotals: {
@@ -1,7 +1,7 @@
1
+ import { entityListDeclaresFilters, entityListDeclaresSearch, listPayloadKeysSent, } from "@cosmicdrift/kumiko-types/screen";
1
2
  import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
2
3
  import { LIST_TABLE_SUMMARY_ROW_KEYS } from "../types/screen.js";
3
4
  import { bootRuleError } from "./boot-rule.js";
4
- import { hasFilterableFields } from "./entity-list-screens.js";
5
5
  import { LIST_SORT_SUMMARY_RULES } from "./list-sort-summary-rules.js";
6
6
  import { rejectUnknownKeys } from "./list-table-reject-unknown-keys.js";
7
7
  import { buildQueryHandlerMap, schemaAccepts } from "./projection-list-screens.js";
@@ -32,32 +32,31 @@ export function rejectSummaryRowOnRelatedList(where, table) {
32
32
  });
33
33
  }
34
34
  }
35
- function entityListKeysSent(feature, screen) {
35
+ function entityListCapabilities(feature, screen) {
36
36
  const entity = feature.entities?.[screen.entity];
37
- const searchable = screen.searchable ??
38
- Object.values(entity?.fields ?? {}).some((f) => "searchable" in f && f.searchable === true);
39
- const hasRangeFacet = Object.values(screen.facets ?? {}).some((facet) => facet !== false && facet.display === "range");
40
- const filters = hasFilterableFields(feature, screen.entity) ||
41
- screen.defaultFilters !== undefined ||
42
- hasRangeFacet;
43
- return [...(searchable ? ["search"] : []), ...(filters ? ["filters"] : [])];
37
+ return {
38
+ searchable: entityListDeclaresSearch(screen, entity),
39
+ filters: entityListDeclaresFilters(screen, entity),
40
+ };
44
41
  }
45
- function projectionListKeysSent(screen, queryHandlers) {
42
+ function projectionListCapabilities(screen, queryHandlers) {
46
43
  const listSchema = queryHandlers.get(screen.query)?.schema;
47
- const searchable = screen.searchable !== false && schemaAccepts(listSchema, "search");
48
- return [...(searchable ? ["search"] : []), ...(screen.facets !== undefined ? ["filters"] : [])];
44
+ return {
45
+ searchable: screen.searchable !== false && schemaAccepts(listSchema, "search"),
46
+ filters: screen.facets !== undefined,
47
+ };
49
48
  }
50
49
  // The keys the list sends for what the screen declares (mirrors the renderer); the summary query
51
50
  // gets the same ones so its numbers follow the narrowing the user sees.
52
51
  function listKeysSentBy(feature, screen, queryHandlers) {
53
- const own = [
54
- ...(screen.namedFilters !== undefined ? ["namedFilter"] : []),
55
- ...(screen.filter !== undefined ? ["filter"] : []),
56
- ];
57
52
  const derived = screen.type === "entityList"
58
- ? entityListKeysSent(feature, screen)
59
- : projectionListKeysSent(screen, queryHandlers);
60
- return [...derived, ...own];
53
+ ? entityListCapabilities(feature, screen)
54
+ : projectionListCapabilities(screen, queryHandlers);
55
+ return listPayloadKeysSent({
56
+ ...derived,
57
+ namedFilters: screen.namedFilters !== undefined,
58
+ screenFilter: screen.filter !== undefined,
59
+ });
61
60
  }
62
61
  function validateSummaryRowQuery(prefix, feature, screen, summaryRow, queryHandlers) {
63
62
  const handler = queryHandlers.get(summaryRow.query);
@@ -67,7 +66,8 @@ function validateSummaryRowQuery(prefix, feature, screen, summaryRow, queryHandl
67
66
  });
68
67
  }
69
68
  const shape = getZodObjectShape(handler.schema);
70
- const missing = listKeysSentBy(feature, screen, queryHandlers).filter((key) => shape === undefined || !(key in shape));
69
+ const paramKeys = Object.keys(summaryRow.params ?? {});
70
+ const missing = [...listKeysSentBy(feature, screen, queryHandlers), ...paramKeys].filter((key) => shape === undefined || !(key in shape));
71
71
  if (missing.length === 0)
72
72
  return;
73
73
  throw bootRuleError(LIST_SORT_SUMMARY_RULES.summaryRowQueryAcceptsListKeys, {
@@ -101,6 +101,17 @@ function validateProjectionSortOptions(prefix, screen, queryHandlers) {
101
101
  `accepts for "sort" (${accepted.join(", ")}) - every pick would fail with a 422.`,
102
102
  });
103
103
  }
104
+ const acceptedDirections = getZodStringLiterals(shape["sortDirection"]);
105
+ // skip: "sortDirection" is an open string
106
+ if (acceptedDirections === undefined)
107
+ return;
108
+ const rejectedDirection = options.find((option) => !acceptedDirections.includes(option.dir));
109
+ if (rejectedDirection !== undefined) {
110
+ throw bootRuleError(LIST_SORT_SUMMARY_RULES.sortOptionNotSortable, {
111
+ message: `${prefix}: sortOptions dir "${rejectedDirection.dir}" is not one of the values query "${screen.query}" ` +
112
+ `accepts for "sortDirection" (${acceptedDirections.join(", ")}) - every pick would fail with a 422.`,
113
+ });
114
+ }
104
115
  }
105
116
  function validateSortOptionsList(prefix, screen) {
106
117
  const options = screen.sortOptions;
@@ -1,8 +1,7 @@
1
- import { LIST_NARROW_FACETS } from "@cosmicdrift/kumiko-types/screen";
1
+ import { LIST_NARROW_FACETS, LIST_TOOLBAR_ACTIONS_PLACEMENTS, } from "@cosmicdrift/kumiko-types/screen";
2
2
  import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
3
3
  import { bootRuleError } from "./boot-rule.js";
4
4
  import { SCREEN_KIND_RULES } from "./screens-kind-rules.js";
5
- const TOOLBAR_ACTIONS_PLACEMENTS = ["header", "toolbar"];
6
5
  /** Toolbar options shared by entityList and projectionList. */
7
6
  export function validateListToolbarOptions(where, screen) {
8
7
  if (screen.toolbarSort === true && (screen.sortOptions ?? []).length === 0) {
@@ -18,9 +17,9 @@ export function validateListToolbarOptions(where, screen) {
18
17
  const placement = screen.toolbarActionsPlacement;
19
18
  if (placement === undefined)
20
19
  return;
21
- if (!isOneOf(TOOLBAR_ACTIONS_PLACEMENTS, placement)) {
20
+ if (!isOneOf(LIST_TOOLBAR_ACTIONS_PLACEMENTS, placement)) {
22
21
  throw bootRuleError(SCREEN_KIND_RULES.toolbarActionsPlacementInvalid, {
23
- message: `${where} sets toolbarActionsPlacement ${JSON.stringify(placement)} — must be "header" or "toolbar".`,
22
+ message: `${where} sets toolbarActionsPlacement ${JSON.stringify(placement)} — must be ${LIST_TOOLBAR_ACTIONS_PLACEMENTS.map((p) => `"${p}"`).join(" or ")}.`,
24
23
  });
25
24
  }
26
25
  if (placement === "toolbar" && (screen.toolbarActions ?? []).length === 0) {
@@ -34,6 +34,16 @@ export declare const NAMED_FILTER_RULES: {
34
34
  readonly summary: "A named filter's emptyState.title is a non-empty i18n key.";
35
35
  readonly fix: "Name the title key or remove emptyState from the filter.";
36
36
  };
37
+ readonly emptyStateParamsQueryEmpty: {
38
+ readonly id: "list/named-filter-empty-state-params-query-empty";
39
+ readonly summary: "A named filter's emptyState.paramsQuery is a non-empty query QN.";
40
+ readonly fix: "Name the query or remove paramsQuery from the emptyState.";
41
+ };
42
+ readonly emptyStateParamsQueryWithoutDescription: {
43
+ readonly id: "list/named-filter-empty-state-params-query-without-description";
44
+ readonly summary: "A named filter's emptyState.paramsQuery feeds the description, so it needs one.";
45
+ readonly fix: "Set emptyState.description (an i18n key with {params}) or remove paramsQuery.";
46
+ };
37
47
  readonly statNavigateTarget: {
38
48
  readonly id: "named-filter/stat-navigate-target";
39
49
  readonly summary: "A stat navigate.screen resolves to an entityList, projectionList or custom screen.";
@@ -34,6 +34,16 @@ export const NAMED_FILTER_RULES = {
34
34
  summary: "A named filter's emptyState.title is a non-empty i18n key.",
35
35
  fix: "Name the title key or remove emptyState from the filter.",
36
36
  },
37
+ emptyStateParamsQueryEmpty: {
38
+ id: "list/named-filter-empty-state-params-query-empty",
39
+ summary: "A named filter's emptyState.paramsQuery is a non-empty query QN.",
40
+ fix: "Name the query or remove paramsQuery from the emptyState.",
41
+ },
42
+ emptyStateParamsQueryWithoutDescription: {
43
+ id: "list/named-filter-empty-state-params-query-without-description",
44
+ summary: "A named filter's emptyState.paramsQuery feeds the description, so it needs one.",
45
+ fix: "Set emptyState.description (an i18n key with {params}) or remove paramsQuery.",
46
+ },
37
47
  statNavigateTarget: {
38
48
  id: "named-filter/stat-navigate-target",
39
49
  summary: "A stat navigate.screen resolves to an entityList, projectionList or custom screen.",
@@ -108,17 +108,18 @@ function validateProjectionListNamedFilterSchemaAcceptance(prefix, screen, schem
108
108
  `Zod schema — add namedFilter: z.string().optional() to the handler's schema and resolve it with resolveNamedListFilters.`,
109
109
  });
110
110
  }
111
- // showCounts asks the query once per filter with { limit: 1, totalCount: true, namedFilter }; a schema
111
+ // showCounts and hideEmpty ask the query once per filter with { limit: 1, totalCount: true, namedFilter }; a schema
112
112
  // without those keys 422s every count request.
113
113
  function validateProjectionListNamedFilterCountAcceptance(prefix, screen, schema) {
114
- if (screen.namedFilterFacet?.showCounts !== true)
114
+ if (screen.namedFilterFacet?.showCounts !== true && screen.namedFilterFacet?.hideEmpty !== true) {
115
115
  return;
116
+ }
116
117
  const missing = ["limit", "totalCount"].filter((key) => !schemaAccepts(schema, key));
117
118
  if (missing.length === 0)
118
119
  return;
119
120
  throw bootRuleError(NAMED_FILTER_RULES.projectionQueryAcceptsCount, {
120
- message: `${prefix}: namedFilterFacet.showCounts needs query "${screen.query}" to accept ${missing.map((key) => `"${key}"`).join(" and ")} in its Zod schema ` +
121
- `- add them or drop showCounts.`,
121
+ message: `${prefix}: namedFilterFacet.${screen.namedFilterFacet.showCounts === true ? "showCounts" : "hideEmpty"} needs query "${screen.query}" to accept ${missing.map((key) => `"${key}"`).join(" and ")} in its Zod schema ` +
122
+ `- add them or drop showCounts and hideEmpty.`,
122
123
  });
123
124
  }
124
125
  // A filter's own sort travels as `payload.sort`/`sortDirection`; without them in the schema it 422s
@@ -29,6 +29,7 @@ export function listGuidanceFieldRefs(screen) {
29
29
  { option: "linkParamsField", field: column.linkParamsField },
30
30
  { option: "hint.detailField", field: hint?.detailField },
31
31
  { option: "hint.narrowDetailField", field: hint?.narrowDetailField },
32
+ { option: "hint.narrowField", field: hint?.narrowField },
32
33
  { option: "hint.toneField", field: hint?.toneField },
33
34
  { option: "hint.reasonField", field: hint?.reasonField },
34
35
  { option: "hint.reasonOpenField", field: hint?.reasonOpenField },
@@ -139,6 +139,14 @@ function checkRowDecorationQueryRef(queryHandlers, featureName, screenId, screen
139
139
  message: `${prefix} query "${decoration.query}" does not declare "ids" in its input schema. The list sends the loaded row ids as "ids"; add ids: z.array(z.string()).`,
140
140
  });
141
141
  }
142
+ function checkEmptyStateParamsQueryRefs(queryHandlers, featureName, screenId, screen) {
143
+ for (const ref of screen.namedFilters ?? []) {
144
+ const query = ref.emptyState?.paramsQuery;
145
+ if (query === undefined)
146
+ continue;
147
+ checkQueryRef(queryHandlers, query, () => `[Feature ${featureName}] Screen "${screenId}" (${screen.type}) namedFilters "${ref.id}" emptyState.paramsQuery`);
148
+ }
149
+ }
142
150
  function checkToolbarVisibleWhenQueryRefs(queryHandlers, featureName, screenId, screen) {
143
151
  for (const action of screen.toolbarActions ?? []) {
144
152
  if (action.visibleWhen === undefined)
@@ -161,10 +169,12 @@ function checkScreenQueryRefs(queryHandlers, featureName, screenId, screen) {
161
169
  checkQueryRef(queryHandlers, screen.query, () => `[Feature ${featureName}] Screen "${screenId}" (projectionList)`);
162
170
  checkToolbarVisibleWhenQueryRefs(queryHandlers, featureName, screenId, screen);
163
171
  checkRowDecorationQueryRef(queryHandlers, featureName, screenId, screen);
172
+ checkEmptyStateParamsQueryRefs(queryHandlers, featureName, screenId, screen);
164
173
  }
165
174
  else if (screen.type === "entityList") {
166
175
  checkToolbarVisibleWhenQueryRefs(queryHandlers, featureName, screenId, screen);
167
176
  checkRowDecorationQueryRef(queryHandlers, featureName, screenId, screen);
177
+ checkEmptyStateParamsQueryRefs(queryHandlers, featureName, screenId, screen);
168
178
  if (screen.expandableRow !== undefined) {
169
179
  checkQueryRef(queryHandlers, screen.expandableRow.query, () => `[Feature ${featureName}] Screen "${screenId}" (entityList) expandableRow "${screen.expandableRow?.title}"`);
170
180
  }
@@ -116,7 +116,7 @@ export function validateRowActionNavigateParams(featureName, screenId, screenTyp
116
116
  //
117
117
  // Registration check (not just "resolved is not undefined"): action.icon is
118
118
  // typed IconKey, a closed union — but that only protects call sites this
119
- // repo's own `tsc --build` actually covers (samples and external consumers
119
+ // repo's own typecheck actually covers (samples and external consumers
120
120
  // aren't in that project graph). The renderer's actionIconFor
121
121
  // (renderer/src/web/primitives/index.tsx) already falls back to "no icon"
122
122
  // for an unregistered key instead of crashing — this check makes the same
@@ -1,23 +1,15 @@
1
- // Only a plain role rule is serializable; openToAll, anySignedIn and no rule restrict nobody.
2
- function rolesRestrictingNamedFilter(access) {
3
- if (access === undefined || "openToAll" in access || access.anySignedIn === true) {
4
- return undefined;
5
- }
6
- return access.roles;
7
- }
8
- // `roles` on a ref is framework-owned: an authored value is dropped so a screen cannot widen the
9
- // entity's access rule on the client.
10
- function refWithEntityRoles(ref, defs) {
11
- const { roles: _authored, ...plain } = ref;
1
+ // `access` on a ref is framework-owned: an authored value is dropped so a screen cannot widen the
2
+ // entity filter's access rule on the client. A rule is plain data (roles, openToAll), safe to serialize.
3
+ function refWithEntityAccess(ref, defs) {
4
+ const { access: _authored, ...plain } = ref;
12
5
  const def = Object.hasOwn(defs, ref.id) ? defs[ref.id] : undefined;
13
- const roles = rolesRestrictingNamedFilter(def?.access);
14
- return roles === undefined ? plain : { ...plain, roles };
6
+ return def?.access === undefined ? plain : { ...plain, access: def.access };
15
7
  }
16
8
  export function projectNamedFilterRoles(screen, defs) {
17
9
  if (screen.namedFilters === undefined)
18
10
  return screen;
19
11
  return {
20
12
  ...screen,
21
- namedFilters: screen.namedFilters.map((ref) => refWithEntityRoles(ref, defs ?? {})),
13
+ namedFilters: screen.namedFilters.map((ref) => refWithEntityAccess(ref, defs ?? {})),
22
14
  };
23
15
  }
@@ -347,7 +347,9 @@ export function fieldToZod(field, currencies, opts = {}) {
347
347
  // validator's; checking it here would require a database round trip during
348
348
  // parsing.
349
349
  // Multi-mode accepts an array of UUIDs.
350
- return field.multiple === true ? z.array(z.uuid()) : z.uuid();
350
+ return field.multiple === true
351
+ ? z.array(z.uuid().meta({ references: field.entity }))
352
+ : z.uuid().meta({ references: field.entity });
351
353
  default:
352
354
  assertUnreachable(field, "field type");
353
355
  }
@@ -167,6 +167,7 @@ export function buildSoftDeleteCleanupJob() {
167
167
  includeSystemTenant: true,
168
168
  concurrency: "skip",
169
169
  runIn: "worker",
170
+ irreversibleWithoutEntryHandler: "high-risk-or-cron-pipeline",
170
171
  };
171
172
  }
172
173
  export function buildSoftDeleteCleanupSystemJob() {
@@ -176,6 +177,7 @@ export function buildSoftDeleteCleanupSystemJob() {
176
177
  trigger: { maintenance: true },
177
178
  concurrency: "skip",
178
179
  runIn: "worker",
180
+ irreversibleWithoutEntryHandler: "high-risk-or-cron-pipeline",
179
181
  escapeHatch: {
180
182
  reason: "hard-deletes expired soft-deleted rows of global entities (e.g. user) once, system-wide",
181
183
  grants: ["unsafeRaw"],
@@ -14,6 +14,7 @@ export declare const FrameworkReasons: {
14
14
  readonly publicIntakeRequired: "public_intake_required";
15
15
  readonly irreversibleOperationRequiresHighRisk: "irreversible_operation_requires_high_risk";
16
16
  readonly instructionFieldWriteRequiresHighRisk: "instruction_field_write_requires_high_risk";
17
+ readonly irreversibleOperationWithoutEntryHandler: "irreversible_operation_without_entry_handler";
17
18
  readonly subjectErased: "subject_erased";
18
19
  readonly fileRejected: "file_rejected";
19
20
  readonly fileViolatesBindTarget: "file_violates_bind_target";
@@ -65,6 +65,10 @@ export const FrameworkReasons = {
65
65
  // delegation via ctx.dispatch.write/writeAs from a lower-risk handler does not
66
66
  // inherit the gate.
67
67
  instructionFieldWriteRequiresHighRisk: "instruction_field_write_requires_high_risk",
68
+ // AccessDeniedError: a job or consumer without a directly dispatched entry handler performs an
69
+ // irreversible operation but declared no irreversibleWithoutEntryHandler exception.
70
+ // details.handler names the job or consumer, details.gate the gate that refused.
71
+ irreversibleOperationWithoutEntryHandler: "irreversible_operation_without_entry_handler",
68
72
  // ConflictError: a write touched a personal-data field of a data subject whose
69
73
  // key was erased (crypto-shredding); the subject can no longer receive data.
70
74
  subjectErased: "subject_erased",
@@ -541,7 +541,8 @@ export function buildEffectiveTranslationKeys(features) {
541
541
  function hasLocaleValue(value) {
542
542
  if (value === undefined)
543
543
  return false;
544
- return typeof value === "string" ? value !== "" : true;
544
+ const forms = typeof value === "string" ? [value] : Object.values(value);
545
+ return forms.every((form) => form.trim() !== "");
545
546
  }
546
547
  /**
547
548
  * Per feature, every translation key must carry every locale that any key of the
@@ -41,6 +41,9 @@ async function runJobHandler(scope, run, correlation) {
41
41
  handler: run.jobName,
42
42
  feature: scope.registry.getJobFeature(run.jobName) ?? qnScope(run.jobName),
43
43
  writeOrigin: run.writeOrigin,
44
+ ...(run.jobDef.irreversibleWithoutEntryHandler && {
45
+ irreversibleWithoutEntryHandler: run.jobDef.irreversibleWithoutEntryHandler,
46
+ }),
44
47
  tenantId: run.tenantId,
45
48
  ...(run.triggeredById !== null && { userId: run.triggeredById }),
46
49
  }, async () => run.jobDef.handler(run.payload, {