@cosmicdrift/kumiko-framework 0.405.0 → 0.409.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 (214) hide show
  1. package/agents/api/framework-db.md +1 -0
  2. package/agents/api/framework-engine.md +18 -2
  3. package/agents/api/framework-ui-types.md +15 -0
  4. package/agents/api/renderer-web.md +156 -2
  5. package/agents/api/types.md +113 -71
  6. package/agents/api.md +4 -4
  7. package/agents/boot-rules.md +743 -0
  8. package/agents/examples/contact.md +167 -0
  9. package/agents/examples/delivery-notifications.md +34 -1
  10. package/agents/examples/lane-routing.md +13 -0
  11. package/agents/examples/record-detail-layout.md +13 -2
  12. package/agents/examples/search.md +65 -3
  13. package/agents/examples/secrets-demo.md +96 -2
  14. package/agents/examples/tenant-inactivity.md +138 -0
  15. package/agents/examples.md +2 -0
  16. package/agents/features-index.md +4 -0
  17. package/agents/features.md +24 -1
  18. package/agents/widgets.md +12 -1
  19. package/dist/api/export/export-rows.js +1 -0
  20. package/dist/compliance/index.d.ts +1 -1
  21. package/dist/db/event-store-executor-read-where.js +15 -5
  22. package/dist/db/index.d.ts +1 -1
  23. package/dist/db/index.js +1 -1
  24. package/dist/db/migrate-generator.js +3 -1
  25. package/dist/db/queries/event-consumer.js +11 -7
  26. package/dist/db/queries/event-store.d.ts +2 -1
  27. package/dist/db/queries/event-store.js +25 -6
  28. package/dist/db/queries/rls-boot-catalog.js +3 -1
  29. package/dist/db/queries/session-advisory-lock.d.ts +7 -0
  30. package/dist/db/queries/session-advisory-lock.js +23 -0
  31. package/dist/db/query.js +7 -10
  32. package/dist/db/row-level-security-connection.js +4 -2
  33. package/dist/engine/active-membership.js +1 -0
  34. package/dist/engine/boot-validator/access-declarations.js +57 -33
  35. package/dist/engine/boot-validator/action-wiring.js +8 -6
  36. package/dist/engine/boot-validator/agent-effect-rules.d.ts +12 -0
  37. package/dist/engine/boot-validator/agent-effect-rules.js +12 -0
  38. package/dist/engine/boot-validator/agent-effect.d.ts +2 -0
  39. package/dist/engine/boot-validator/agent-effect.js +20 -0
  40. package/dist/engine/boot-validator/boot-context.js +5 -1
  41. package/dist/engine/boot-validator/boot-environment-rules.d.ts +12 -0
  42. package/dist/engine/boot-validator/boot-environment-rules.js +12 -0
  43. package/dist/engine/boot-validator/boot-phases-app.js +5 -1
  44. package/dist/engine/boot-validator/boot-phases.js +3 -1
  45. package/dist/engine/boot-validator/boot-rules.d.ts +2619 -0
  46. package/dist/engine/boot-validator/boot-rules.js +58 -0
  47. package/dist/engine/boot-validator/bundled-lists-table.js +23 -9
  48. package/dist/engine/boot-validator/config-deps.js +71 -23
  49. package/dist/engine/boot-validator/config-edit-action-rules.d.ts +17 -0
  50. package/dist/engine/boot-validator/config-edit-action-rules.js +17 -0
  51. package/dist/engine/boot-validator/config-key-rules.d.ts +117 -0
  52. package/dist/engine/boot-validator/config-key-rules.js +117 -0
  53. package/dist/engine/boot-validator/custom-screen-write-qns.js +6 -2
  54. package/dist/engine/boot-validator/derived-sql-fields-rules.d.ts +77 -0
  55. package/dist/engine/boot-validator/derived-sql-fields-rules.js +77 -0
  56. package/dist/engine/boot-validator/derived-sql-fields.js +53 -17
  57. package/dist/engine/boot-validator/detail-screens.js +10 -4
  58. package/dist/engine/boot-validator/entity-declaration-rules.d.ts +92 -0
  59. package/dist/engine/boot-validator/entity-declaration-rules.js +92 -0
  60. package/dist/engine/boot-validator/entity-handler-access-rules.d.ts +102 -0
  61. package/dist/engine/boot-validator/entity-handler-access-rules.js +102 -0
  62. package/dist/engine/boot-validator/entity-handler.d.ts +0 -7
  63. package/dist/engine/boot-validator/entity-handler.js +259 -355
  64. package/dist/engine/boot-validator/entity-image-variants.d.ts +2 -0
  65. package/dist/engine/boot-validator/entity-image-variants.js +91 -0
  66. package/dist/engine/boot-validator/entity-list-aggregate-options.js +8 -2
  67. package/dist/engine/boot-validator/entity-reference-embedded-rules.d.ts +117 -0
  68. package/dist/engine/boot-validator/entity-reference-embedded-rules.js +117 -0
  69. package/dist/engine/boot-validator/entity-select-image-rules.d.ts +122 -0
  70. package/dist/engine/boot-validator/entity-select-image-rules.js +122 -0
  71. package/dist/engine/boot-validator/entity-select.d.ts +8 -0
  72. package/dist/engine/boot-validator/entity-select.js +197 -0
  73. package/dist/engine/boot-validator/entity-structure-rules.d.ts +107 -0
  74. package/dist/engine/boot-validator/entity-structure-rules.js +107 -0
  75. package/dist/engine/boot-validator/field-conditions-rules.d.ts +92 -0
  76. package/dist/engine/boot-validator/field-conditions-rules.js +92 -0
  77. package/dist/engine/boot-validator/field-conditions.js +67 -22
  78. package/dist/engine/boot-validator/form-derivations-rules.d.ts +77 -0
  79. package/dist/engine/boot-validator/form-derivations-rules.js +77 -0
  80. package/dist/engine/boot-validator/form-derivations.js +52 -18
  81. package/dist/engine/boot-validator/global-tenancy.js +13 -7
  82. package/dist/engine/boot-validator/handler-declaration-rules.d.ts +72 -0
  83. package/dist/engine/boot-validator/handler-declaration-rules.js +72 -0
  84. package/dist/engine/boot-validator/handler-field-references-rules.d.ts +22 -0
  85. package/dist/engine/boot-validator/handler-field-references-rules.js +22 -0
  86. package/dist/engine/boot-validator/handler-field-references.js +14 -6
  87. package/dist/engine/boot-validator/list-bulk-actions-rules.d.ts +42 -0
  88. package/dist/engine/boot-validator/list-bulk-actions-rules.js +42 -0
  89. package/dist/engine/boot-validator/list-bulk-actions.js +29 -11
  90. package/dist/engine/boot-validator/list-column-layout.js +22 -10
  91. package/dist/engine/boot-validator/list-query-rules.d.ts +107 -0
  92. package/dist/engine/boot-validator/list-query-rules.js +107 -0
  93. package/dist/engine/boot-validator/list-table-aggregate-options.js +43 -15
  94. package/dist/engine/boot-validator/list-table-aggregate-query.js +7 -3
  95. package/dist/engine/boot-validator/list-table-aggregate-rules.d.ts +82 -0
  96. package/dist/engine/boot-validator/list-table-aggregate-rules.js +82 -0
  97. package/dist/engine/boot-validator/list-table-export-options.js +19 -7
  98. package/dist/engine/boot-validator/list-table-options.js +33 -13
  99. package/dist/engine/boot-validator/list-table-reject-unknown-keys.js +6 -2
  100. package/dist/engine/boot-validator/list-table-rules.d.ts +132 -0
  101. package/dist/engine/boot-validator/list-table-rules.js +132 -0
  102. package/dist/engine/boot-validator/nav-rules.d.ts +42 -0
  103. package/dist/engine/boot-validator/nav-rules.js +42 -0
  104. package/dist/engine/boot-validator/nav.js +29 -15
  105. package/dist/engine/boot-validator/ownership-rules.d.ts +27 -0
  106. package/dist/engine/boot-validator/ownership-rules.js +27 -0
  107. package/dist/engine/boot-validator/ownership.js +28 -12
  108. package/dist/engine/boot-validator/parent-ref.js +32 -20
  109. package/dist/engine/boot-validator/projection-list-screens.js +76 -35
  110. package/dist/engine/boot-validator/query-output-columns.js +9 -3
  111. package/dist/engine/boot-validator/query-refs.js +20 -10
  112. package/dist/engine/boot-validator/query-rules.d.ts +37 -0
  113. package/dist/engine/boot-validator/query-rules.js +37 -0
  114. package/dist/engine/boot-validator/read-gate.js +14 -10
  115. package/dist/engine/boot-validator/record-owned.js +5 -1
  116. package/dist/engine/boot-validator/related-list-table-rules.js +17 -7
  117. package/dist/engine/boot-validator/screens-actions-rules.d.ts +185 -0
  118. package/dist/engine/boot-validator/screens-actions-rules.js +185 -0
  119. package/dist/engine/boot-validator/screens-actions.js +169 -93
  120. package/dist/engine/boot-validator/screens-dashboard-chart-rules.d.ts +87 -0
  121. package/dist/engine/boot-validator/screens-dashboard-chart-rules.js +87 -0
  122. package/dist/engine/boot-validator/screens-dashboard-rules.d.ts +227 -0
  123. package/dist/engine/boot-validator/screens-dashboard-rules.js +227 -0
  124. package/dist/engine/boot-validator/screens-dashboard.js +222 -85
  125. package/dist/engine/boot-validator/screens-forms-layout-rules.d.ts +122 -0
  126. package/dist/engine/boot-validator/screens-forms-layout-rules.js +122 -0
  127. package/dist/engine/boot-validator/screens-forms-rules.d.ts +152 -0
  128. package/dist/engine/boot-validator/screens-forms-rules.js +152 -0
  129. package/dist/engine/boot-validator/screens-forms.js +240 -112
  130. package/dist/engine/boot-validator/screens-kind-config-edit.js +72 -16
  131. package/dist/engine/boot-validator/screens-kind-entity-edit.js +15 -7
  132. package/dist/engine/boot-validator/screens-kind-entity-list.js +57 -32
  133. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +92 -0
  134. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +92 -0
  135. package/dist/engine/boot-validator/screens-kind-projection-detail.js +85 -47
  136. package/dist/engine/boot-validator/screens-kind-rules.d.ts +137 -0
  137. package/dist/engine/boot-validator/screens-kind-rules.js +137 -0
  138. package/dist/engine/boot-validator/screens-kind-secret-mint.js +18 -8
  139. package/dist/engine/boot-validator/screens-kind-shared.js +40 -22
  140. package/dist/engine/boot-validator/screens-lists-rules.d.ts +82 -0
  141. package/dist/engine/boot-validator/screens-lists-rules.js +82 -0
  142. package/dist/engine/boot-validator/screens-lists.js +90 -45
  143. package/dist/engine/boot-validator/screens-rules.d.ts +57 -0
  144. package/dist/engine/boot-validator/screens-rules.js +57 -0
  145. package/dist/engine/boot-validator/screens.js +17 -12
  146. package/dist/engine/boot-validator/transaction-phases.js +12 -4
  147. package/dist/engine/boot-validator/transfer-graph.js +17 -11
  148. package/dist/engine/boot-validator/url-prefill-fields.js +9 -5
  149. package/dist/engine/boot-validator/workspaces.js +11 -5
  150. package/dist/engine/boot-validator/zod-shape.js +6 -2
  151. package/dist/engine/entity-handlers.d.ts +1 -0
  152. package/dist/engine/entity-handlers.js +3 -0
  153. package/dist/engine/entity-list-runtime-options.js +23 -29
  154. package/dist/engine/extensions/tenant-data.d.ts +3 -0
  155. package/dist/engine/extensions/tenant-resource.d.ts +1 -0
  156. package/dist/engine/factories.d.ts +1 -1
  157. package/dist/engine/factories.js +4 -3
  158. package/dist/engine/feature-config-events-jobs.js +7 -0
  159. package/dist/engine/index.d.ts +4 -2
  160. package/dist/engine/index.js +2 -0
  161. package/dist/engine/project-app-schema-for-roles.js +29 -14
  162. package/dist/engine/registry-facade.js +7 -8
  163. package/dist/engine/registry-validate.js +5 -1
  164. package/dist/engine/soft-delete-cleanup.d.ts +1 -0
  165. package/dist/engine/soft-delete-cleanup.js +5 -0
  166. package/dist/engine/steps/describe-workflow-step-error.js +1 -0
  167. package/dist/es-ops/operations-schema.d.ts +1 -1
  168. package/dist/event-store/ensure-dead-letter-table.d.ts +2 -0
  169. package/dist/event-store/ensure-dead-letter-table.js +10 -0
  170. package/dist/event-store/rebuild-dead-letter.js +2 -8
  171. package/dist/event-store/upcaster-dead-letter.js +2 -8
  172. package/dist/files/copy-pending-file-refs-to-tenant.d.ts +28 -0
  173. package/dist/files/copy-pending-file-refs-to-tenant.js +87 -0
  174. package/dist/files/file-routes.d.ts +1 -1
  175. package/dist/files/file-routes.js +21 -6
  176. package/dist/files/index.d.ts +2 -0
  177. package/dist/files/index.js +1 -0
  178. package/dist/i18n/required-surface-keys.js +1 -0
  179. package/dist/jobs/job-runner-helpers.js +1 -0
  180. package/dist/jobs/job-runner-schedulers.d.ts +2 -2
  181. package/dist/jobs/job-runner-schedulers.js +8 -4
  182. package/dist/jobs/job-runner.js +14 -16
  183. package/dist/logging/utils.js +30 -60
  184. package/dist/observability/metrics-handle.js +10 -21
  185. package/dist/pipeline/cascade-handler.js +7 -6
  186. package/dist/pipeline/dispatch-query.js +18 -5
  187. package/dist/pipeline/dispatch-shared.d.ts +1 -0
  188. package/dist/pipeline/dispatch-shared.js +3 -1
  189. package/dist/pipeline/dispatch-write.js +10 -12
  190. package/dist/pipeline/dispatcher.js +12 -14
  191. package/dist/pipeline/event-dispatcher-admin.js +9 -8
  192. package/dist/pipeline/event-dispatcher-delivery.d.ts +19 -1
  193. package/dist/pipeline/event-dispatcher-delivery.js +121 -29
  194. package/dist/pipeline/event-dispatcher.d.ts +5 -1
  195. package/dist/pipeline/event-dispatcher.js +28 -21
  196. package/dist/pipeline/handler-context-phase-denials.js +2 -0
  197. package/dist/pipeline/multi-stream-apply-context.js +12 -20
  198. package/dist/pipeline/system-hooks.d.ts +4 -1
  199. package/dist/pipeline/system-hooks.js +79 -6
  200. package/dist/pipeline/system-identity-switch.js +10 -7
  201. package/dist/search/build-search-snippet.d.ts +9 -0
  202. package/dist/search/build-search-snippet.js +40 -0
  203. package/dist/search/index.d.ts +1 -0
  204. package/dist/search/index.js +1 -0
  205. package/dist/search/meilisearch-adapter.d.ts +32 -0
  206. package/dist/search/meilisearch-adapter.js +153 -56
  207. package/dist/search/meilisearch-chunking.d.ts +21 -0
  208. package/dist/search/meilisearch-chunking.js +96 -0
  209. package/dist/search/reindex-entity.d.ts +1 -0
  210. package/dist/search/reindex-entity.js +97 -52
  211. package/dist/ui-types/index.d.ts +1 -1
  212. package/dist/upgrade-cli.js +3 -14
  213. package/package.json +3 -3
  214. package/src/changes.json +85 -0
@@ -4,6 +4,7 @@ import { QnTypes, qualifyEntityName } from "../qualified-name.js";
4
4
  import { isEditLayoutScreen } from "../screen-helpers.js";
5
5
  import { bootRuleError } from "./boot-rule.js";
6
6
  import { SEARCHABLE_FALSE_WHITELIST } from "./entity-list-screens.js";
7
+ import { LIST_QUERY_RULES } from "./list-query-rules.js";
7
8
  import { validateListTableAggregateQuery } from "./list-table-aggregate-query.js";
8
9
  import { NAMED_FILTER_RULES } from "./named-filter-rules.js";
9
10
  import { getZodObjectShape } from "./zod-shape.js";
@@ -36,10 +37,14 @@ function schemaAccepts(schema, key) {
36
37
  // silently overwritten with no signal to the author. Reject outright.
37
38
  function rejectHandAuthoredDerivedFlags(prefix, screen) {
38
39
  if (screen.sortable !== undefined) {
39
- throw new Error(`${prefix}: sortable is derived from the query's Zod schema, don't set it`);
40
+ throw bootRuleError(LIST_QUERY_RULES.derivedFlagHandAuthored, {
41
+ message: `${prefix}: sortable is derived from the query's Zod schema, don't set it`,
42
+ });
40
43
  }
41
44
  if (screen.paginated !== undefined) {
42
- throw new Error(`${prefix}: paginated is derived from the query's Zod schema, don't set it`);
45
+ throw bootRuleError(LIST_QUERY_RULES.derivedFlagHandAuthored, {
46
+ message: `${prefix}: paginated is derived from the query's Zod schema, don't set it`,
47
+ });
43
48
  }
44
49
  }
45
50
  function validateOneProjectionListScreen(feature, screen, queryHandlers, featureMap) {
@@ -49,22 +54,30 @@ function validateOneProjectionListScreen(feature, screen, queryHandlers, feature
49
54
  // buildAppSchema derives searchable: false for these, so no whitelist entry is needed.
50
55
  const searchDerivedOff = isListQueryWithoutSearchableFields(screen.query, handler, (name) => findEntity(featureMap, name));
51
56
  if (screen.searchable === true && !schemaAccepts(schema, "search")) {
52
- throw new Error(`${prefix}: searchable: true but query "${screen.query}" has no "search" parameter in its Zod schema. Add a "search" field to the query schema or remove searchable: true.`);
57
+ throw bootRuleError(LIST_QUERY_RULES.searchableWithoutSearchParam, {
58
+ message: `${prefix}: searchable: true but query "${screen.query}" has no "search" parameter in its Zod schema. Add a "search" field to the query schema or remove searchable: true.`,
59
+ });
53
60
  }
54
61
  if (screen.searchable === true && searchDerivedOff) {
55
- throw new Error(`${prefix}: searchable: true but query "${screen.query}" lists an entity with no searchable field, so a search would never match. Mark a field searchable: true on the entity or remove searchable: true.`);
62
+ throw bootRuleError(LIST_QUERY_RULES.searchableWithoutSearchableField, {
63
+ message: `${prefix}: searchable: true but query "${screen.query}" lists an entity with no searchable field, so a search would never match. Mark a field searchable: true on the entity or remove searchable: true.`,
64
+ });
56
65
  }
57
66
  if (screen.searchable === false &&
58
67
  schemaAccepts(schema, "search") &&
59
68
  !searchDerivedOff &&
60
69
  !SEARCHABLE_FALSE_WHITELIST.has(screen.id)) {
61
- throw new Error(`${prefix}: query "${screen.query}" accepts "search" but searchable: false disables it — remove searchable: false or add "${screen.id}" to SEARCHABLE_FALSE_WHITELIST`);
70
+ throw bootRuleError(LIST_QUERY_RULES.searchableFalseDisablesSearch, {
71
+ message: `${prefix}: query "${screen.query}" accepts "search" but searchable: false disables it — remove searchable: false or add "${screen.id}" to SEARCHABLE_FALSE_WHITELIST`,
72
+ });
62
73
  }
63
74
  rejectHandAuthoredDerivedFlags(prefix, screen);
64
75
  const searchActive = screen.searchable !== false && !searchDerivedOff && schemaAccepts(schema, "search");
65
76
  const sortActive = schemaAccepts(schema, "sort");
66
77
  if ((searchActive || sortActive) && screen.defaultSort === undefined) {
67
- throw new Error(`${prefix}: defaultSort required when search or sort is active. Set defaultSort: { field, direction }.`);
78
+ throw bootRuleError(LIST_QUERY_RULES.defaultSortRequired, {
79
+ message: `${prefix}: defaultSort required when search or sort is active. Set defaultSort: { field, direction }.`,
80
+ });
68
81
  }
69
82
  validateProjectionListFilterSchemaAcceptance(prefix, screen, schema);
70
83
  validateProjectionListFacetsSchemaAcceptance(prefix, screen, schema);
@@ -77,9 +90,11 @@ function validateProjectionListFilterSchemaAcceptance(prefix, screen, schema) {
77
90
  // skip: no filter declared, or the schema already accepts it — nothing to reject.
78
91
  if (screen.filter === undefined || schemaAccepts(schema, "filter"))
79
92
  return;
80
- throw new Error(`${prefix}: declares filter but query "${screen.query}" has no "filter" parameter in its Zod ` +
81
- `schema — add filter: z.object({ field: z.string(), op: z.enum(["eq","ne","lt","gt","lte","gte","in"]), ` +
82
- `value: z.unknown() }).optional() (or reuse entityListSchema's shape) to the handler's schema.`);
93
+ throw bootRuleError(LIST_QUERY_RULES.filterParamMissing, {
94
+ message: `${prefix}: declares filter but query "${screen.query}" has no "filter" parameter in its Zod ` +
95
+ `schema — add filter: z.object({ field: z.string(), op: z.enum(["eq","ne","lt","gt","lte","gte","in"]), ` +
96
+ `value: z.unknown() }).optional() (or reuse entityListSchema's shape) to the handler's schema.`,
97
+ });
83
98
  }
84
99
  // namedFilters send `payload.namedFilter` — same 422 footgun as filter/facets.
85
100
  function validateProjectionListNamedFilterSchemaAcceptance(prefix, screen, schema) {
@@ -120,25 +135,33 @@ function validateProjectionListDateRangeFacets(prefix, screen, schema) {
120
135
  if (facet.type !== "dateRange")
121
136
  continue;
122
137
  if (facet.params.from === facet.params.to) {
123
- throw new Error(`${prefix}: dateRange facet on "${facet.field}" names the same param ` +
124
- `"${facet.params.from}" for both bounds. Use two different param names for from and to.`);
138
+ throw bootRuleError(LIST_QUERY_RULES.dateRangeSameParam, {
139
+ message: `${prefix}: dateRange facet on "${facet.field}" names the same param ` +
140
+ `"${facet.params.from}" for both bounds. Use two different param names for from and to.`,
141
+ });
125
142
  }
126
143
  for (const param of [facet.params.from, facet.params.to]) {
127
144
  if (RESERVED_LIST_PAYLOAD_KEYS.has(param)) {
128
- throw new Error(`${prefix}: dateRange facet on "${facet.field}" names "${param}" as a bound, ` +
129
- `which is a reserved list-payload key — pick the query's own time-bound param names.`);
145
+ throw bootRuleError(LIST_QUERY_RULES.dateRangeReservedParam, {
146
+ message: `${prefix}: dateRange facet on "${facet.field}" names "${param}" as a bound, ` +
147
+ `which is a reserved list-payload key — pick the query's own time-bound param names.`,
148
+ });
130
149
  }
131
150
  if (usedParams.has(param)) {
132
- throw new Error(`${prefix}: dateRange facet on "${facet.field}" names "${param}" which another dateRange ` +
133
- `facet on this screen already uses — the facets would overwrite each other's bound. Give each dateRange facet its own param names.`);
151
+ throw bootRuleError(LIST_QUERY_RULES.dateRangeParamReused, {
152
+ message: `${prefix}: dateRange facet on "${facet.field}" names "${param}" which another dateRange ` +
153
+ `facet on this screen already uses — the facets would overwrite each other's bound. Give each dateRange facet its own param names.`,
154
+ });
134
155
  }
135
156
  usedParams.add(param);
136
157
  if (schemaAccepts(schema, param))
137
158
  continue;
138
- throw new Error(`${prefix}: dateRange facet on "${facet.field}" sends "${param}" but query ` +
139
- `"${screen.query}" has no "${param}" parameter in its Zod schema — add ` +
140
- `${param}: z.iso.datetime().optional() to the handler's schema, or point ` +
141
- `params at the keys it already accepts.`);
159
+ throw bootRuleError(LIST_QUERY_RULES.dateRangeParamMissing, {
160
+ message: `${prefix}: dateRange facet on "${facet.field}" sends "${param}" but query ` +
161
+ `"${screen.query}" has no "${param}" parameter in its Zod schema — add ` +
162
+ `${param}: z.iso.datetime().optional() to the handler's schema, or point ` +
163
+ `params at the keys it already accepts.`,
164
+ });
142
165
  }
143
166
  }
144
167
  }
@@ -150,9 +173,11 @@ function validateProjectionListFacetsSchemaAcceptance(prefix, screen, schema) {
150
173
  // skip: the schema already accepts filters — nothing to reject.
151
174
  if (schemaAccepts(schema, "filters"))
152
175
  return;
153
- throw new Error(`${prefix}: declares facets but query "${screen.query}" has no "filters" parameter in its ` +
154
- `Zod schema — add filters: z.array(z.object({ field: z.string(), op: z.literal("in"), ` +
155
- `value: z.unknown() })).optional() (or reuse entityListSchema's shape) to the handler's schema.`);
176
+ throw bootRuleError(LIST_QUERY_RULES.facetsWithoutFiltersParam, {
177
+ message: `${prefix}: declares facets but query "${screen.query}" has no "filters" parameter in its ` +
178
+ `Zod schema — add filters: z.array(z.object({ field: z.string(), op: z.literal("in"), ` +
179
+ `value: z.unknown() })).optional() (or reuse entityListSchema's shape) to the handler's schema.`,
180
+ });
156
181
  }
157
182
  export function validateProjectionListScreens(features) {
158
183
  const queryHandlers = buildQueryHandlerMap(features);
@@ -169,7 +194,9 @@ function validateRelatedListSearchable(prefix, section, schema) {
169
194
  // skip: not searchable, or the schema already accepts search — nothing to reject.
170
195
  if (section.searchable !== true || schemaAccepts(schema, "search"))
171
196
  return;
172
- throw new Error(`${prefix}: searchable: true but query "${section.query}" has no "search" parameter in its Zod schema. Add a "search" field to the query schema or remove searchable: true.`);
197
+ throw bootRuleError(LIST_QUERY_RULES.searchableWithoutSearchParam, {
198
+ message: `${prefix}: searchable: true but query "${section.query}" has no "search" parameter in its Zod schema. Add a "search" field to the query schema or remove searchable: true.`,
199
+ });
173
200
  }
174
201
  function validateRelatedListFacets(prefix, section, schema) {
175
202
  // skip: no facets declared — nothing to reject.
@@ -178,22 +205,30 @@ function validateRelatedListFacets(prefix, section, schema) {
178
205
  // skip: the schema already accepts filters — nothing to reject.
179
206
  if (schemaAccepts(schema, "filters"))
180
207
  return;
181
- throw new Error(`${prefix}: declares facets but query "${section.query}" has no "filters" parameter in its Zod schema — add filters: z.array(z.object({ field: z.string(), op: z.literal("in"), value: z.unknown() })).optional() (or reuse entityListSchema's shape) to the handler's schema.`);
208
+ throw bootRuleError(LIST_QUERY_RULES.facetsWithoutFiltersParam, {
209
+ message: `${prefix}: declares facets but query "${section.query}" has no "filters" parameter in its Zod schema — add filters: z.array(z.object({ field: z.string(), op: z.literal("in"), value: z.unknown() })).optional() (or reuse entityListSchema's shape) to the handler's schema.`,
210
+ });
182
211
  }
183
212
  function validateRelatedListCount(prefix, section, layoutMode, schema) {
184
213
  // skip: no count badge declared — nothing to reject.
185
214
  if (section.count !== true)
186
215
  return;
187
216
  if (layoutMode !== "tabs") {
188
- throw new Error(`${prefix}: count: true only renders in a layout with mode "tabs".`);
217
+ throw bootRuleError(LIST_QUERY_RULES.countNeedsTabsLayout, {
218
+ message: `${prefix}: count: true only renders in a layout with mode "tabs".`,
219
+ });
189
220
  }
190
221
  if (section.countField !== undefined) {
191
- throw new Error(`${prefix}: declares both count and countField — pick one badge source.`);
222
+ throw bootRuleError(LIST_QUERY_RULES.countAndCountField, {
223
+ message: `${prefix}: declares both count and countField — pick one badge source.`,
224
+ });
192
225
  }
193
226
  for (const key of ["totalCount", "limit"]) {
194
227
  if (schemaAccepts(schema, key))
195
228
  continue;
196
- throw new Error(`${prefix}: count: true needs query "${section.query}" to accept "${key}" in its Zod schema (the badge asks for limit: 1, totalCount: true).`);
229
+ throw bootRuleError(LIST_QUERY_RULES.countParamMissing, {
230
+ message: `${prefix}: count: true needs query "${section.query}" to accept "${key}" in its Zod schema (the badge asks for limit: 1, totalCount: true).`,
231
+ });
197
232
  }
198
233
  }
199
234
  // parentFilter lets a relatedList reuse the
@@ -205,19 +240,25 @@ function validateRelatedListParentFilter(prefix, section, schema, handler, featu
205
240
  if (section.parentFilter === undefined)
206
241
  return;
207
242
  if (section.parentParam !== undefined) {
208
- throw new Error(`${prefix}: declares both parentFilter and parentParam — parentFilter replaces the implicit ` +
209
- `{ [parentParam]: parentId } payload key with a server-side "filter" clause, so the two can't ` +
210
- `be combined. Remove parentParam or drop parentFilter.`);
243
+ throw bootRuleError(LIST_QUERY_RULES.parentFilterAndParentParam, {
244
+ message: `${prefix}: declares both parentFilter and parentParam — parentFilter replaces the implicit ` +
245
+ `{ [parentParam]: parentId } payload key with a server-side "filter" clause, so the two can't ` +
246
+ `be combined. Remove parentParam or drop parentFilter.`,
247
+ });
211
248
  }
212
249
  if (!schemaAccepts(schema, "filter")) {
213
- throw new Error(`${prefix}: declares parentFilter but query "${section.query}" has no "filter" parameter in its ` +
214
- `Zod schema — add filter: z.object({ field: z.string(), op: z.enum(["eq","ne","lt","gt","lte","gte","in"]), ` +
215
- `value: z.unknown() }).optional() (or reuse entityListSchema's shape) to the handler's schema.`);
250
+ throw bootRuleError(LIST_QUERY_RULES.parentFilterParamMissing, {
251
+ message: `${prefix}: declares parentFilter but query "${section.query}" has no "filter" parameter in its ` +
252
+ `Zod schema — add filter: z.object({ field: z.string(), op: z.enum(["eq","ne","lt","gt","lte","gte","in"]), ` +
253
+ `value: z.unknown() }).optional() (or reuse entityListSchema's shape) to the handler's schema.`,
254
+ });
216
255
  }
217
256
  const entity = resolveEntityBehindListQuery(section.query, handler, (name) => findEntity(featureMap, name));
218
257
  if (entity !== undefined && entity.fields[section.parentFilter.field] === undefined) {
219
- throw new Error(`${prefix}: parentFilter.field "${section.parentFilter.field}" is not a declared field on the ` +
220
- `entity behind query "${section.query}". Known fields: ${Object.keys(entity.fields).sort().join(", ")}.`);
258
+ throw bootRuleError(LIST_QUERY_RULES.parentFilterFieldUnknown, {
259
+ message: `${prefix}: parentFilter.field "${section.parentFilter.field}" is not a declared field on the ` +
260
+ `entity behind query "${section.query}". Known fields: ${Object.keys(entity.fields).sort().join(", ")}.`,
261
+ });
221
262
  }
222
263
  }
223
264
  // relatedList sections declare search/facets the same way a projectionList
@@ -1,13 +1,15 @@
1
1
  import { isPagedQueryHandler } from "../define-handler.js";
2
2
  import { normalizeListColumn, sectionFieldSpecs } from "../screen-helpers.js";
3
+ import { bootRuleError } from "./boot-rule.js";
3
4
  import { buildQueryHandlerMap } from "./projection-list-screens.js";
5
+ import { QUERY_RULES } from "./query-rules.js";
4
6
  import { validateActionFieldRefs } from "./screens.js";
5
7
  import { getZodObjectShape, getZodRowShape } from "./zod-shape.js";
6
8
  function checkFieldExists(shape, field, buildMessage) {
7
9
  // skip: capability absent (no introspectable shape) or field already present — nothing to validate
8
10
  if (shape === undefined || field in shape)
9
11
  return;
10
- throw new Error(buildMessage());
12
+ throw bootRuleError(QUERY_RULES.outputFieldMissing, { message: buildMessage() });
11
13
  }
12
14
  // Unlike entity-list-screens.ts, `label` does not exempt a column here: query
13
15
  // screens label nearly every column, so that exemption would leave the check
@@ -33,7 +35,9 @@ function checkPagedHandlerOutputSchemaShape(queryHandlers) {
33
35
  const shape = getZodObjectShape(handler.outputSchema);
34
36
  if (shape === undefined || "rows" in shape)
35
37
  continue;
36
- throw new Error(`Query handler "${qn}" is a paged handler (definePagedQueryHandler) but its outputSchema does not describe the paged envelope { rows: [...], nextCursor, total? } — it has no "rows" field. Did you pass the row schema instead of wrapping it in the envelope?`);
38
+ throw bootRuleError(QUERY_RULES.pagedOutputWithoutRows, {
39
+ message: `Query handler "${qn}" is a paged handler (definePagedQueryHandler) but its outputSchema does not describe the paged envelope { rows: [...], nextCursor, total? } — it has no "rows" field. Did you pass the row schema instead of wrapping it in the envelope?`,
40
+ });
37
41
  }
38
42
  }
39
43
  // Usage-site twin of checkPagedHandlerOutputSchemaShape: a plain
@@ -49,7 +53,9 @@ function resolveListRowShape(queryHandlers, queryQn, usage) {
49
53
  // skip: no introspectable object schema (absent / union) — capability absent per module policy
50
54
  if (envelopeShape === undefined || "rows" in envelopeShape)
51
55
  return undefined;
52
- throw new Error(`${usage} uses query "${queryQn}" as a list source, but its outputSchema does not describe the paged envelope { rows: [...], nextCursor, total? } — it has no "rows" field. Did you pass the row schema instead of wrapping it in the envelope?`);
56
+ throw bootRuleError(QUERY_RULES.listSourceOutputWithoutRows, {
57
+ message: `${usage} uses query "${queryQn}" as a list source, but its outputSchema does not describe the paged envelope { rows: [...], nextCursor, total? } — it has no "rows" field. Did you pass the row schema instead of wrapping it in the envelope?`,
58
+ });
53
59
  }
54
60
  function checkProjectionListOutputColumns(queryHandlers, featureName, screenId, screen) {
55
61
  const rowShape = resolveListRowShape(queryHandlers, screen.query, `[Feature ${featureName}] Screen "${screenId}" (projectionList)`);
@@ -1,5 +1,7 @@
1
1
  import { isFieldsEditSection, normalizeEditField, sectionFieldSpecs } from "../screen-helpers.js";
2
+ import { bootRuleError } from "./boot-rule.js";
2
3
  import { buildQueryHandlerMap } from "./projection-list-screens.js";
4
+ import { QUERY_RULES } from "./query-rules.js";
3
5
  const NOT_REGISTERED_SUFFIX = "is not a registered query-handler. Check the QN spelling (expected " +
4
6
  '"<feature>:query:<short>") and that the handler is declared via r.queryHandler(...).';
5
7
  function isNonEmptyQueryString(value) {
@@ -10,7 +12,9 @@ export function checkQueryRef(queryHandlers, query, buildPrefix) {
10
12
  // a registered query has nothing left to check.
11
13
  if (!isNonEmptyQueryString(query) || queryHandlers.has(query))
12
14
  return;
13
- throw new Error(`${buildPrefix()} query "${query}" ${NOT_REGISTERED_SUFFIX}`);
15
+ throw bootRuleError(QUERY_RULES.notRegistered, {
16
+ message: `${buildPrefix()} query "${query}" ${NOT_REGISTERED_SUFFIX}`,
17
+ });
14
18
  }
15
19
  const PROBE_ROUTE_ID = "00000000-0000-4000-8000-000000000000";
16
20
  // Panel gates run with an empty payload; a screen gate with `idParam` runs with the route id
@@ -26,11 +30,13 @@ function checkVisibleWhenQueryRef(queryHandlers, query, buildPrefix, idParam) {
26
30
  // skip: the query parses what the gate sends
27
31
  if (handler.schema.safeParse(probe).success)
28
32
  return;
29
- throw new Error(idParam === undefined
30
- ? `${buildPrefix()} query "${query}" requires input; visibleWhen queries run with an empty payload. ` +
31
- "Make the query's input fields optional, use a query without required input, or (projectionDetail only) set visibleWhen.idParam to receive the route id."
32
- : `${buildPrefix()} query "${query}" requires input beyond idParam "${idParam}"; visibleWhen queries run with only the route id under that key. ` +
33
- `Make the other input fields optional or fix idParam "${idParam}".`);
33
+ throw bootRuleError(QUERY_RULES.visibleWhenRequiresInput, {
34
+ message: idParam === undefined
35
+ ? `${buildPrefix()} query "${query}" requires input; visibleWhen queries run with an empty payload. ` +
36
+ "Make the query's input fields optional, use a query without required input, or (projectionDetail only) set visibleWhen.idParam to receive the route id."
37
+ : `${buildPrefix()} query "${query}" requires input beyond idParam "${idParam}"; visibleWhen queries run with only the route id under that key. ` +
38
+ `Make the other input fields optional or fix idParam "${idParam}".`,
39
+ });
34
40
  }
35
41
  // relatedList is currently only reachable on projectionDetail — screens.ts
36
42
  // rejects it outright on entityEdit/actionForm/configEdit. Walking
@@ -99,8 +105,10 @@ function checkEditFormScreenQueryRefs(queryHandlers, featureName, screenId, scre
99
105
  if (screen.load.singleton === true &&
100
106
  loadHandler !== undefined &&
101
107
  !loadHandler.schema.safeParse({}).success) {
102
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (actionForm) load.singleton query "${screen.load.query}" ` +
103
- "requires input; a singleton load runs with an empty payload. Make the query's input fields optional.");
108
+ throw bootRuleError(QUERY_RULES.singletonLoadRequiresInput, {
109
+ message: `[Feature ${featureName}] Screen "${screenId}" (actionForm) load.singleton query "${screen.load.query}" ` +
110
+ "requires input; a singleton load runs with an empty payload. Make the query's input fields optional.",
111
+ });
104
112
  }
105
113
  }
106
114
  if (screen.type !== "entityEdit") {
@@ -121,8 +129,10 @@ function checkScreenQueryRefs(queryHandlers, featureName, screenId, screen) {
121
129
  if (screen.visibleWhen !== undefined) {
122
130
  const { idParam } = screen.visibleWhen;
123
131
  if (idParam !== undefined && screen.type !== "projectionDetail") {
124
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screen.type}) visibleWhen.idParam is only supported on projectionDetail, ` +
125
- "where the route always carries a record id. Remove idParam or use a projectionDetail screen.");
132
+ throw bootRuleError(QUERY_RULES.visibleWhenIdParamUnsupported, {
133
+ message: `[Feature ${featureName}] Screen "${screenId}" (${screen.type}) visibleWhen.idParam is only supported on projectionDetail, ` +
134
+ "where the route always carries a record id. Remove idParam or use a projectionDetail screen.",
135
+ });
126
136
  }
127
137
  checkVisibleWhenQueryRef(queryHandlers, screen.visibleWhen.query, () => `[Feature ${featureName}] Screen "${screenId}" (${screen.type}) visibleWhen`, idParam);
128
138
  }
@@ -0,0 +1,37 @@
1
+ export declare const QUERY_RULES: {
2
+ readonly notRegistered: {
3
+ readonly id: "query/not-registered";
4
+ readonly summary: "A query reference on a screen names a registered query handler.";
5
+ readonly fix: 'Check the QN spelling ("<feature>:query:<short>") and declare the handler via r.queryHandler(...).';
6
+ };
7
+ readonly visibleWhenRequiresInput: {
8
+ readonly id: "query/visible-when-requires-input";
9
+ readonly summary: "A visibleWhen query parses the payload the gate sends.";
10
+ readonly fix: "Make the query's input fields optional, use a query without required input, or for projectionDetail set visibleWhen.idParam.";
11
+ };
12
+ readonly visibleWhenIdParamUnsupported: {
13
+ readonly id: "query/visible-when-id-param-unsupported";
14
+ readonly summary: "visibleWhen.idParam is used only on projectionDetail screens.";
15
+ readonly fix: "Remove idParam or use a projectionDetail screen.";
16
+ };
17
+ readonly singletonLoadRequiresInput: {
18
+ readonly id: "query/singleton-load-requires-input";
19
+ readonly summary: "An actionForm singleton load binds a query that parses an empty payload.";
20
+ readonly fix: "Make the query's input fields optional.";
21
+ };
22
+ readonly outputFieldMissing: {
23
+ readonly id: "query/output-field-missing";
24
+ readonly summary: "A field a screen reads from a query result exists in the query's outputSchema.";
25
+ readonly fix: "Check the field name for a typo or add the field to the outputSchema.";
26
+ };
27
+ readonly pagedOutputWithoutRows: {
28
+ readonly id: "query/paged-output-without-rows";
29
+ readonly summary: "A paged query handler's outputSchema describes the paged envelope with a rows field.";
30
+ readonly fix: "Wrap the row schema in the { rows, nextCursor, total? } envelope.";
31
+ };
32
+ readonly listSourceOutputWithoutRows: {
33
+ readonly id: "query/list-source-output-without-rows";
34
+ readonly summary: "A query used as a list source has an outputSchema describing the paged envelope with a rows field.";
35
+ readonly fix: "Wrap the row schema in the { rows, nextCursor, total? } envelope.";
36
+ };
37
+ };
@@ -0,0 +1,37 @@
1
+ export const QUERY_RULES = {
2
+ notRegistered: {
3
+ id: "query/not-registered",
4
+ summary: "A query reference on a screen names a registered query handler.",
5
+ fix: 'Check the QN spelling ("<feature>:query:<short>") and declare the handler via r.queryHandler(...).',
6
+ },
7
+ visibleWhenRequiresInput: {
8
+ id: "query/visible-when-requires-input",
9
+ summary: "A visibleWhen query parses the payload the gate sends.",
10
+ fix: "Make the query's input fields optional, use a query without required input, or for projectionDetail set visibleWhen.idParam.",
11
+ },
12
+ visibleWhenIdParamUnsupported: {
13
+ id: "query/visible-when-id-param-unsupported",
14
+ summary: "visibleWhen.idParam is used only on projectionDetail screens.",
15
+ fix: "Remove idParam or use a projectionDetail screen.",
16
+ },
17
+ singletonLoadRequiresInput: {
18
+ id: "query/singleton-load-requires-input",
19
+ summary: "An actionForm singleton load binds a query that parses an empty payload.",
20
+ fix: "Make the query's input fields optional.",
21
+ },
22
+ outputFieldMissing: {
23
+ id: "query/output-field-missing",
24
+ summary: "A field a screen reads from a query result exists in the query's outputSchema.",
25
+ fix: "Check the field name for a typo or add the field to the outputSchema.",
26
+ },
27
+ pagedOutputWithoutRows: {
28
+ id: "query/paged-output-without-rows",
29
+ summary: "A paged query handler's outputSchema describes the paged envelope with a rows field.",
30
+ fix: "Wrap the row schema in the { rows, nextCursor, total? } envelope.",
31
+ },
32
+ listSourceOutputWithoutRows: {
33
+ id: "query/list-source-output-without-rows",
34
+ summary: "A query used as a list source has an outputSchema describing the paged envelope with a rows field.",
35
+ fix: "Wrap the row schema in the { rows, nextCursor, total? } envelope.",
36
+ },
37
+ };
@@ -1,28 +1,32 @@
1
1
  import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handlers";
2
2
  import { FILE_REF_ENTITY_NAME } from "../../files/types.js";
3
3
  import { findEntity } from "../find-entity.js";
4
- function fail(check, message) {
5
- throw new Error(`[Kumiko ReadGate] entity "${check.entityName}" (feature: "${check.feature.name}"): ${message}`);
4
+ import { bootRuleError } from "./boot-rule.js";
5
+ import { ENTITY_DECLARATION_RULES } from "./entity-declaration-rules.js";
6
+ function fail(check, rule, message) {
7
+ throw bootRuleError(rule, {
8
+ message: `[Kumiko ReadGate] entity "${check.entityName}" (feature: "${check.feature.name}"): ${message}`,
9
+ });
6
10
  }
7
11
  function validateLink(check, key, gateLink) {
8
12
  const link = findEntity(check.featureMap, gateLink.entity);
9
13
  if (link === undefined) {
10
- fail(check, `readGate.${key}.entity "${gateLink.entity}" is not registered.`);
14
+ fail(check, ENTITY_DECLARATION_RULES.readGateLinkEntityUnregistered, `readGate.${key}.entity "${gateLink.entity}" is not registered.`);
11
15
  }
12
16
  if (link.parentRef === undefined) {
13
- fail(check, `readGate.${key}.entity "${gateLink.entity}" must declare a parentRef; its host visibility is what the gate checks.`);
17
+ fail(check, ENTITY_DECLARATION_RULES.readGateLinkWithoutParentRef, `readGate.${key}.entity "${gateLink.entity}" must declare a parentRef; its host visibility is what the gate checks.`);
14
18
  }
15
19
  if (link.fields[gateLink.field] === undefined) {
16
- fail(check, `readGate.${key}.field "${gateLink.field}" is not a field of "${gateLink.entity}".`);
20
+ fail(check, ENTITY_DECLARATION_RULES.readGateLinkFieldUnknown, `readGate.${key}.field "${gateLink.field}" is not a field of "${gateLink.entity}".`);
17
21
  }
18
22
  }
19
23
  function validateFileOwner(check, fileOwner) {
20
24
  const fileField = check.entity.fields[fileOwner.field];
21
25
  if (fileField?.type !== "file" && fileField?.type !== "image") {
22
- fail(check, `readGate.fileOwner.field "${fileOwner.field}" must be a single file or image field.`);
26
+ fail(check, ENTITY_DECLARATION_RULES.readGateFileOwnerFieldType, `readGate.fileOwner.field "${fileOwner.field}" must be a single file or image field.`);
23
27
  }
24
28
  if (findEntity(check.featureMap, FILE_REF_ENTITY_NAME) === undefined) {
25
- fail(check, `readGate.fileOwner needs the files feature (entity "${FILE_REF_ENTITY_NAME}").`);
29
+ fail(check, ENTITY_DECLARATION_RULES.readGateFileOwnerNeedsFiles, `readGate.fileOwner needs the files feature (entity "${FILE_REF_ENTITY_NAME}").`);
26
30
  }
27
31
  }
28
32
  function validateNoHandWrittenReaders(check) {
@@ -31,7 +35,7 @@ function validateNoHandWrittenReaders(check) {
31
35
  for (const f of check.featureMap.values()) {
32
36
  const handler = f.queryHandlers[handlerName];
33
37
  if (handler !== undefined && handler[ENTITY_CONVENTION_QUERY_BRAND] !== true) {
34
- fail(check, `query handler "${handlerName}" is hand-written and would bypass the readGate. Fix: register it via defineEntityListHandler/defineEntityDetailHandler.`);
38
+ fail(check, ENTITY_DECLARATION_RULES.readGateHandWrittenReader, `query handler "${handlerName}" is hand-written and would bypass the readGate. Fix: register it via defineEntityListHandler/defineEntityDetailHandler.`);
35
39
  }
36
40
  }
37
41
  }
@@ -43,10 +47,10 @@ export function validateReadGates(feature, featureMap) {
43
47
  continue;
44
48
  const check = { feature, featureMap, entityName, entity };
45
49
  if (entity.parentRef !== undefined) {
46
- fail(check, "readGate and parentRef cannot be combined; a gated entity cannot be a join row.");
50
+ fail(check, ENTITY_DECLARATION_RULES.readGateWithParentRef, "readGate and parentRef cannot be combined; a gated entity cannot be a join row.");
47
51
  }
48
52
  if (gate.anyLink !== undefined && gate.allLinks !== undefined) {
49
- fail(check, "readGate declares both anyLink and allLinks; pick one.");
53
+ fail(check, ENTITY_DECLARATION_RULES.readGateAnyAndAllLinks, "readGate declares both anyLink and allLinks; pick one.");
50
54
  }
51
55
  if (gate.anyLink !== undefined)
52
56
  validateLink(check, "anyLink", gate.anyLink);
@@ -1,3 +1,5 @@
1
+ import { bootRuleError } from "./boot-rule.js";
2
+ import { ENTITY_DECLARATION_RULES } from "./entity-declaration-rules.js";
1
3
  // A recordOwned field (or one with whenAbsent: "self") is encrypted under `record:<entity>:<id>` (kms-adapter-types.ts)
2
4
  // and forgetSubject's subjectIdSchema (crypto/kms-adapter.ts) requires that id
3
5
  // to be a UUID — an entity with idType: "serial" would encrypt the field but
@@ -10,7 +12,9 @@ export function validateRecordOwnedSubjects(feature) {
10
12
  const annot = field; // @cast-boundary schema-walk
11
13
  if (annot.recordOwned !== true && annot.userOwned?.whenAbsent !== "self")
12
14
  continue;
13
- throw new Error(`[Feature ${feature.name}] entity "${entityName}" field "${fieldName}" is recordOwned (or whenAbsent: "self") but the entity declares idType: "serial" — the record subject key is "record:${entityName}:<id>" and forgetSubject validates that id as a UUID, so this field would be encrypted but could never be shredded. Set idType: "uuid" on entity "${entityName}", or give field "${fieldName}" a different personal stance (personal: "self" / "tenant" / { of: "<field>" }).`);
15
+ throw bootRuleError(ENTITY_DECLARATION_RULES.recordOwnedSerialId, {
16
+ message: `[Feature ${feature.name}] entity "${entityName}" field "${fieldName}" is recordOwned (or whenAbsent: "self") but the entity declares idType: "serial" — the record subject key is "record:${entityName}:<id>" and forgetSubject validates that id as a UUID, so this field would be encrypted but could never be shredded. Set idType: "uuid" on entity "${entityName}", or give field "${fieldName}" a different personal stance (personal: "self" / "tenant" / { of: "<field>" }).`,
17
+ });
14
18
  }
15
19
  }
16
20
  }
@@ -1,12 +1,16 @@
1
1
  import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
2
+ import { bootRuleError } from "./boot-rule.js";
3
+ import { LIST_QUERY_RULES } from "./list-query-rules.js";
2
4
  const EXPANDABLE_ROW_TABLE_KEYS = new Set(["grouping"]);
3
5
  const EXPANDABLE_ROW_REJECTED_GROUPING_KEYS = ["userChoice", "fields"];
4
6
  // `groupBy` grouped the loaded page on the client; it is gone, and a screen
5
7
  // still carrying it fails at boot instead of silently losing its groups.
6
8
  function rejectRemovedGroupBy(prefix, section) {
7
9
  if (Object.hasOwn(section, "groupBy")) {
8
- throw new Error(`${prefix} uses groupBy, which was removed. Use table.grouping: { field, label?, labels?, collapsedWhen? }; ` +
9
- `groups and counts come from the server, so the bound query must accept aggregate.`);
10
+ throw bootRuleError(LIST_QUERY_RULES.groupByRemoved, {
11
+ message: `${prefix} uses groupBy, which was removed. Use table.grouping: { field, label?, labels?, collapsedWhen? }; ` +
12
+ `groups and counts come from the server, so the bound query must accept aggregate.`,
13
+ });
10
14
  }
11
15
  }
12
16
  function rejectExpandableRowTableOptions(prefix, table) {
@@ -18,8 +22,10 @@ function rejectExpandableRowTableOptions(prefix, table) {
18
22
  function rejectUnsupportedTableKeys(prefix, table) {
19
23
  const unsupported = Object.keys(table).filter((key) => !EXPANDABLE_ROW_TABLE_KEYS.has(key));
20
24
  if (unsupported.length > 0) {
21
- throw new Error(`${prefix} supports only table.grouping, not table.${unsupported.join(", table.")}. ` +
22
- `Put the other table options on the entityList screen itself.`);
25
+ throw bootRuleError(LIST_QUERY_RULES.expandableRowTableKeys, {
26
+ message: `${prefix} supports only table.grouping, not table.${unsupported.join(", table.")}. ` +
27
+ `Put the other table options on the entityList screen itself.`,
28
+ });
23
29
  }
24
30
  }
25
31
  function rejectGroupingChoice(prefix, grouping) {
@@ -27,15 +33,19 @@ function rejectGroupingChoice(prefix, grouping) {
27
33
  ? EXPANDABLE_ROW_REJECTED_GROUPING_KEYS.find((key) => Object.hasOwn(grouping, key))
28
34
  : undefined;
29
35
  if (choiceKey !== undefined) {
30
- throw new Error(`${prefix} does not support table.grouping.${choiceKey}: an expanded row has no view menu. ` +
31
- `Set a fixed table.grouping.field.`);
36
+ throw bootRuleError(LIST_QUERY_RULES.expandableRowGroupingChoice, {
37
+ message: `${prefix} does not support table.grouping.${choiceKey}: an expanded row has no view menu. ` +
38
+ `Set a fixed table.grouping.field.`,
39
+ });
32
40
  }
33
41
  }
34
42
  /** Grouping rules of a relatedList section or entityList.expandableRow, before the shared table checks. */
35
43
  export function validateRelatedListGroupingRules(prefix, section, isExpandableRow) {
36
44
  rejectRemovedGroupBy(prefix, section);
37
45
  if (isExpandableRow && Object.hasOwn(section, "bulkActions")) {
38
- throw new Error(`${prefix} does not support bulkActions. Put bulkActions on the entityList screen itself.`);
46
+ throw bootRuleError(LIST_QUERY_RULES.expandableRowBulkActions, {
47
+ message: `${prefix} does not support bulkActions. Put bulkActions on the entityList screen itself.`,
48
+ });
39
49
  }
40
50
  if (isExpandableRow)
41
51
  rejectExpandableRowTableOptions(prefix, section.table);