@cosmicdrift/kumiko-framework 0.406.0 → 0.410.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 (212) hide show
  1. package/AGENTS.md +4 -2
  2. package/agents/api/framework-db.md +1 -0
  3. package/agents/api/framework-engine.md +17 -2
  4. package/agents/api/framework-ui-types.md +15 -0
  5. package/agents/api/renderer-web.md +156 -2
  6. package/agents/api/types.md +113 -71
  7. package/agents/api.md +4 -4
  8. package/agents/boot-rules.md +744 -0
  9. package/agents/examples/anonymous-access.md +23 -1
  10. package/agents/examples/contact.md +173 -0
  11. package/agents/examples/delivery-notifications.md +34 -1
  12. package/agents/examples/record-detail-layout.md +13 -2
  13. package/agents/examples/search.md +65 -3
  14. package/agents/examples/secrets-demo.md +96 -2
  15. package/agents/examples/tenant-inactivity.md +138 -0
  16. package/agents/examples.md +2 -0
  17. package/agents/features-index.md +4 -0
  18. package/agents/features.md +25 -1
  19. package/agents/widgets.md +12 -1
  20. package/dist/api/export/export-rows.js +1 -0
  21. package/dist/compliance/index.d.ts +1 -1
  22. package/dist/db/event-store-executor-read-where.js +15 -5
  23. package/dist/db/index.d.ts +1 -1
  24. package/dist/db/index.js +1 -1
  25. package/dist/db/migrate-generator.js +3 -1
  26. package/dist/db/queries/event-consumer.js +11 -7
  27. package/dist/db/queries/event-store.d.ts +2 -1
  28. package/dist/db/queries/event-store.js +25 -6
  29. package/dist/db/queries/rls-boot-catalog.js +3 -1
  30. package/dist/db/queries/session-advisory-lock.d.ts +7 -0
  31. package/dist/db/queries/session-advisory-lock.js +23 -0
  32. package/dist/db/query.js +7 -10
  33. package/dist/db/row-level-security-connection.js +4 -2
  34. package/dist/engine/access.js +5 -1
  35. package/dist/engine/active-membership.js +1 -0
  36. package/dist/engine/boot-validator/access-declarations.js +76 -33
  37. package/dist/engine/boot-validator/action-wiring.js +8 -6
  38. package/dist/engine/boot-validator/agent-effect-rules.d.ts +12 -0
  39. package/dist/engine/boot-validator/agent-effect-rules.js +12 -0
  40. package/dist/engine/boot-validator/agent-effect.d.ts +2 -0
  41. package/dist/engine/boot-validator/agent-effect.js +20 -0
  42. package/dist/engine/boot-validator/boot-context.js +5 -1
  43. package/dist/engine/boot-validator/boot-environment-rules.d.ts +12 -0
  44. package/dist/engine/boot-validator/boot-environment-rules.js +12 -0
  45. package/dist/engine/boot-validator/boot-phases-app.js +5 -1
  46. package/dist/engine/boot-validator/boot-phases.js +3 -1
  47. package/dist/engine/boot-validator/boot-rules.d.ts +2624 -0
  48. package/dist/engine/boot-validator/boot-rules.js +58 -0
  49. package/dist/engine/boot-validator/bundled-lists-table.js +23 -9
  50. package/dist/engine/boot-validator/config-deps.js +71 -23
  51. package/dist/engine/boot-validator/config-edit-action-rules.d.ts +17 -0
  52. package/dist/engine/boot-validator/config-edit-action-rules.js +17 -0
  53. package/dist/engine/boot-validator/config-key-rules.d.ts +117 -0
  54. package/dist/engine/boot-validator/config-key-rules.js +117 -0
  55. package/dist/engine/boot-validator/custom-screen-write-qns.js +6 -2
  56. package/dist/engine/boot-validator/derived-sql-fields-rules.d.ts +77 -0
  57. package/dist/engine/boot-validator/derived-sql-fields-rules.js +77 -0
  58. package/dist/engine/boot-validator/derived-sql-fields.js +53 -17
  59. package/dist/engine/boot-validator/detail-screens.js +10 -4
  60. package/dist/engine/boot-validator/entity-declaration-rules.d.ts +92 -0
  61. package/dist/engine/boot-validator/entity-declaration-rules.js +92 -0
  62. package/dist/engine/boot-validator/entity-handler-access-rules.d.ts +102 -0
  63. package/dist/engine/boot-validator/entity-handler-access-rules.js +102 -0
  64. package/dist/engine/boot-validator/entity-handler.d.ts +0 -7
  65. package/dist/engine/boot-validator/entity-handler.js +259 -355
  66. package/dist/engine/boot-validator/entity-image-variants.d.ts +2 -0
  67. package/dist/engine/boot-validator/entity-image-variants.js +91 -0
  68. package/dist/engine/boot-validator/entity-list-aggregate-options.js +8 -2
  69. package/dist/engine/boot-validator/entity-reference-embedded-rules.d.ts +117 -0
  70. package/dist/engine/boot-validator/entity-reference-embedded-rules.js +117 -0
  71. package/dist/engine/boot-validator/entity-select-image-rules.d.ts +122 -0
  72. package/dist/engine/boot-validator/entity-select-image-rules.js +122 -0
  73. package/dist/engine/boot-validator/entity-select.d.ts +8 -0
  74. package/dist/engine/boot-validator/entity-select.js +197 -0
  75. package/dist/engine/boot-validator/entity-structure-rules.d.ts +107 -0
  76. package/dist/engine/boot-validator/entity-structure-rules.js +107 -0
  77. package/dist/engine/boot-validator/field-conditions-rules.d.ts +92 -0
  78. package/dist/engine/boot-validator/field-conditions-rules.js +92 -0
  79. package/dist/engine/boot-validator/field-conditions.js +67 -22
  80. package/dist/engine/boot-validator/form-derivations-rules.d.ts +77 -0
  81. package/dist/engine/boot-validator/form-derivations-rules.js +77 -0
  82. package/dist/engine/boot-validator/form-derivations.js +52 -18
  83. package/dist/engine/boot-validator/global-tenancy.js +13 -7
  84. package/dist/engine/boot-validator/handler-declaration-rules.d.ts +77 -0
  85. package/dist/engine/boot-validator/handler-declaration-rules.js +77 -0
  86. package/dist/engine/boot-validator/handler-field-references-rules.d.ts +22 -0
  87. package/dist/engine/boot-validator/handler-field-references-rules.js +22 -0
  88. package/dist/engine/boot-validator/handler-field-references.js +14 -6
  89. package/dist/engine/boot-validator/list-bulk-actions-rules.d.ts +42 -0
  90. package/dist/engine/boot-validator/list-bulk-actions-rules.js +42 -0
  91. package/dist/engine/boot-validator/list-bulk-actions.js +29 -11
  92. package/dist/engine/boot-validator/list-column-layout.js +22 -10
  93. package/dist/engine/boot-validator/list-query-rules.d.ts +107 -0
  94. package/dist/engine/boot-validator/list-query-rules.js +107 -0
  95. package/dist/engine/boot-validator/list-table-aggregate-options.js +43 -15
  96. package/dist/engine/boot-validator/list-table-aggregate-query.js +7 -3
  97. package/dist/engine/boot-validator/list-table-aggregate-rules.d.ts +82 -0
  98. package/dist/engine/boot-validator/list-table-aggregate-rules.js +82 -0
  99. package/dist/engine/boot-validator/list-table-export-options.js +19 -7
  100. package/dist/engine/boot-validator/list-table-options.js +33 -13
  101. package/dist/engine/boot-validator/list-table-reject-unknown-keys.js +6 -2
  102. package/dist/engine/boot-validator/list-table-rules.d.ts +132 -0
  103. package/dist/engine/boot-validator/list-table-rules.js +132 -0
  104. package/dist/engine/boot-validator/nav-rules.d.ts +42 -0
  105. package/dist/engine/boot-validator/nav-rules.js +42 -0
  106. package/dist/engine/boot-validator/nav.js +33 -17
  107. package/dist/engine/boot-validator/ownership-rules.d.ts +27 -0
  108. package/dist/engine/boot-validator/ownership-rules.js +27 -0
  109. package/dist/engine/boot-validator/ownership.js +28 -12
  110. package/dist/engine/boot-validator/parent-ref.js +32 -20
  111. package/dist/engine/boot-validator/projection-list-screens.js +76 -35
  112. package/dist/engine/boot-validator/query-output-columns.js +9 -3
  113. package/dist/engine/boot-validator/query-refs.js +20 -10
  114. package/dist/engine/boot-validator/query-rules.d.ts +37 -0
  115. package/dist/engine/boot-validator/query-rules.js +37 -0
  116. package/dist/engine/boot-validator/read-gate.js +14 -10
  117. package/dist/engine/boot-validator/record-owned.js +5 -1
  118. package/dist/engine/boot-validator/related-list-table-rules.js +17 -7
  119. package/dist/engine/boot-validator/screens-actions-rules.d.ts +185 -0
  120. package/dist/engine/boot-validator/screens-actions-rules.js +185 -0
  121. package/dist/engine/boot-validator/screens-actions.js +169 -93
  122. package/dist/engine/boot-validator/screens-dashboard-chart-rules.d.ts +87 -0
  123. package/dist/engine/boot-validator/screens-dashboard-chart-rules.js +87 -0
  124. package/dist/engine/boot-validator/screens-dashboard-rules.d.ts +227 -0
  125. package/dist/engine/boot-validator/screens-dashboard-rules.js +227 -0
  126. package/dist/engine/boot-validator/screens-dashboard.js +222 -85
  127. package/dist/engine/boot-validator/screens-forms-layout-rules.d.ts +122 -0
  128. package/dist/engine/boot-validator/screens-forms-layout-rules.js +122 -0
  129. package/dist/engine/boot-validator/screens-forms-rules.d.ts +152 -0
  130. package/dist/engine/boot-validator/screens-forms-rules.js +152 -0
  131. package/dist/engine/boot-validator/screens-forms.js +240 -112
  132. package/dist/engine/boot-validator/screens-kind-config-edit.js +72 -16
  133. package/dist/engine/boot-validator/screens-kind-entity-edit.js +15 -7
  134. package/dist/engine/boot-validator/screens-kind-entity-list.js +57 -32
  135. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +92 -0
  136. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +92 -0
  137. package/dist/engine/boot-validator/screens-kind-projection-detail.js +85 -47
  138. package/dist/engine/boot-validator/screens-kind-rules.d.ts +137 -0
  139. package/dist/engine/boot-validator/screens-kind-rules.js +137 -0
  140. package/dist/engine/boot-validator/screens-kind-secret-mint.js +18 -8
  141. package/dist/engine/boot-validator/screens-kind-shared.js +40 -22
  142. package/dist/engine/boot-validator/screens-lists-rules.d.ts +82 -0
  143. package/dist/engine/boot-validator/screens-lists-rules.js +82 -0
  144. package/dist/engine/boot-validator/screens-lists.js +90 -45
  145. package/dist/engine/boot-validator/screens-rules.d.ts +57 -0
  146. package/dist/engine/boot-validator/screens-rules.js +57 -0
  147. package/dist/engine/boot-validator/screens.js +17 -12
  148. package/dist/engine/boot-validator/transaction-phases.js +12 -4
  149. package/dist/engine/boot-validator/transfer-graph.js +17 -11
  150. package/dist/engine/boot-validator/url-prefill-fields.js +9 -5
  151. package/dist/engine/boot-validator/workspaces.js +11 -5
  152. package/dist/engine/boot-validator/zod-shape.js +6 -2
  153. package/dist/engine/entity-handlers.d.ts +1 -0
  154. package/dist/engine/entity-handlers.js +3 -0
  155. package/dist/engine/entity-list-runtime-options.js +23 -29
  156. package/dist/engine/extensions/tenant-data.d.ts +3 -0
  157. package/dist/engine/factories.d.ts +1 -1
  158. package/dist/engine/factories.js +4 -3
  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.js +7 -12
  181. package/dist/logging/utils.js +30 -60
  182. package/dist/observability/metrics-handle.js +10 -21
  183. package/dist/pipeline/cascade-handler.js +7 -6
  184. package/dist/pipeline/dispatch-query.js +18 -5
  185. package/dist/pipeline/dispatch-shared.d.ts +1 -0
  186. package/dist/pipeline/dispatch-shared.js +3 -1
  187. package/dist/pipeline/dispatch-write.js +10 -12
  188. package/dist/pipeline/dispatcher.js +12 -14
  189. package/dist/pipeline/event-dispatcher-admin.js +9 -8
  190. package/dist/pipeline/event-dispatcher-delivery.d.ts +19 -1
  191. package/dist/pipeline/event-dispatcher-delivery.js +121 -29
  192. package/dist/pipeline/event-dispatcher.d.ts +5 -1
  193. package/dist/pipeline/event-dispatcher.js +28 -21
  194. package/dist/pipeline/handler-context-phase-denials.js +2 -0
  195. package/dist/pipeline/multi-stream-apply-context.js +12 -20
  196. package/dist/pipeline/system-hooks.d.ts +4 -1
  197. package/dist/pipeline/system-hooks.js +79 -6
  198. package/dist/pipeline/system-identity-switch.js +10 -7
  199. package/dist/search/build-search-snippet.d.ts +9 -0
  200. package/dist/search/build-search-snippet.js +40 -0
  201. package/dist/search/index.d.ts +1 -0
  202. package/dist/search/index.js +1 -0
  203. package/dist/search/meilisearch-adapter.d.ts +32 -0
  204. package/dist/search/meilisearch-adapter.js +153 -56
  205. package/dist/search/meilisearch-chunking.d.ts +21 -0
  206. package/dist/search/meilisearch-chunking.js +96 -0
  207. package/dist/search/reindex-entity.d.ts +1 -0
  208. package/dist/search/reindex-entity.js +97 -52
  209. package/dist/ui-types/index.d.ts +1 -1
  210. package/dist/upgrade-cli.js +3 -14
  211. package/package.json +3 -3
  212. package/src/changes.json +79 -0
@@ -1,19 +1,26 @@
1
1
  import { DASHBOARD_MIN_REFRESH_SECONDS } from "@cosmicdrift/kumiko-types/screen";
2
2
  import { normalizeListColumn } from "../screen-helpers.js";
3
+ import { bootRuleError } from "./boot-rule.js";
3
4
  import { assertWriteHandlerRegistered, isRowClickAction, resolveRowActionNavigateTarget, resolveScreenTargetQn, validateActionHasIcon, validateClientActionName, validateRowActionNavigateParams, } from "./screens-actions.js";
5
+ import { DASHBOARD_CHART_RULES } from "./screens-dashboard-chart-rules.js";
6
+ import { DASHBOARD_RULES } from "./screens-dashboard-rules.js";
4
7
  import { assertRefTargetRegistered, validateColumnRendererForm } from "./screens-lists.js";
5
8
  // Panel-driven, no entity — structural checks (unique panel ids, non-empty
6
9
  // queries/columns/valueField); the query contracts (stat record, points
7
10
  // envelope, paged rows) are resolved at render time.
8
11
  export function validateDashboardScreen(featureName, screenId, screen, featureMap) {
9
12
  if (screen.panels.length === 0) {
10
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) has an empty panels list — ` +
11
- `declare at least one panel.`);
13
+ throw bootRuleError(DASHBOARD_RULES.emptyPanels, {
14
+ message: `[Feature ${featureName}] Screen "${screenId}" (dashboard) has an empty panels list — ` +
15
+ `declare at least one panel.`,
16
+ });
12
17
  }
13
18
  const panelIds = new Set();
14
19
  const addPanelId = (id, context) => {
15
20
  if (panelIds.has(id)) {
16
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) has duplicate panel id "${id}" (${context}). Give each panel a unique id.`);
21
+ throw bootRuleError(DASHBOARD_RULES.duplicatePanelId, {
22
+ message: `[Feature ${featureName}] Screen "${screenId}" (dashboard) has duplicate panel id "${id}" (${context}). Give each panel a unique id.`,
23
+ });
17
24
  }
18
25
  panelIds.add(id);
19
26
  };
@@ -50,11 +57,15 @@ export function validateDashboardActions(featureName, screenId, screen, allWrite
50
57
  const where = `[Feature ${featureName}] Screen "${screenId}" (dashboard) action "${action.id}"`;
51
58
  validateActionHasIcon(featureName, screenId, "dashboard", "action", action);
52
59
  if (isRowClickAction(action)) {
53
- throw new Error(`${where} sets rowClick: true — a dashboard has no row to click. Remove rowClick.`);
60
+ throw bootRuleError(DASHBOARD_RULES.actionRowClick, {
61
+ message: `${where} sets rowClick: true — a dashboard has no row to click. Remove rowClick.`,
62
+ });
54
63
  }
55
64
  if (action.kind === "drawer") {
56
- throw new Error(`${where} is a drawer action — a dashboard has no drawer host. Use a navigate, ` +
57
- `writeHandler or clientAction action.`);
65
+ throw bootRuleError(DASHBOARD_RULES.actionDrawer, {
66
+ message: `${where} is a drawer action — a dashboard has no drawer host. Use a navigate, ` +
67
+ `writeHandler or clientAction action.`,
68
+ });
58
69
  }
59
70
  if (action.kind === "navigate") {
60
71
  const target = resolveRowActionNavigateTarget(featureName, screenId, "dashboard", "action", action, allScreenQns, navTargetShortIds, screensByShortId, detailForScreens);
@@ -65,8 +76,10 @@ export function validateDashboardActions(featureName, screenId, screen, allWrite
65
76
  }
66
77
  else {
67
78
  if (action.redirect !== undefined) {
68
- throw new Error(`${where} sets redirect — a dashboard action stays on the dashboard and refetches ` +
69
- `after success. Remove redirect.`);
79
+ throw bootRuleError(DASHBOARD_RULES.actionRedirect, {
80
+ message: `${where} sets redirect — a dashboard action stays on the dashboard and refetches ` +
81
+ `after success. Remove redirect.`,
82
+ });
70
83
  }
71
84
  assertWriteHandlerRegistered(featureName, `Screen "${screenId}" (dashboard) action "${action.id}"`, action.handler, allWriteHandlerQns);
72
85
  }
@@ -80,8 +93,10 @@ export function validateDashboardRecordBinding(featureName, screenId, screen) {
80
93
  const { record, refresh } = screen;
81
94
  if (record === undefined) {
82
95
  if (screen.actions !== undefined) {
83
- throw new Error(`${where} declares actions without a record — the actions run on the bound record. ` +
84
- `Add record: { param } or remove actions.`);
96
+ throw bootRuleError(DASHBOARD_RULES.actionsWithoutRecord, {
97
+ message: `${where} declares actions without a record — the actions run on the bound record. ` +
98
+ `Add record: { param } or remove actions.`,
99
+ });
85
100
  }
86
101
  }
87
102
  else {
@@ -94,23 +109,33 @@ export function validateDashboardRecordBinding(featureName, screenId, screen) {
94
109
  }
95
110
  function validateDashboardRecordShape(where, record, otherUrlParamIds) {
96
111
  if (typeof record.param !== "string" || record.param.length === 0) {
97
- throw new Error(`${where} record.param is empty. Name the URL search param carrying the id.`);
112
+ throw bootRuleError(DASHBOARD_RULES.recordParamEmpty, {
113
+ message: `${where} record.param is empty. Name the URL search param carrying the id.`,
114
+ });
98
115
  }
99
116
  if (record.payloadKey !== undefined && record.payloadKey.length === 0) {
100
- throw new Error(`${where} record.payloadKey is empty. Omit it to reuse record.param as the payload key.`);
117
+ throw bootRuleError(DASHBOARD_RULES.recordPayloadKeyEmpty, {
118
+ message: `${where} record.payloadKey is empty. Omit it to reuse record.param as the payload key.`,
119
+ });
101
120
  }
102
121
  if (record.query !== undefined && record.query.length === 0) {
103
- throw new Error(`${where} record.query is empty. Set a registered query name or omit it.`);
122
+ throw bootRuleError(DASHBOARD_RULES.recordQueryEmpty, {
123
+ message: `${where} record.query is empty. Set a registered query name or omit it.`,
124
+ });
104
125
  }
105
126
  if (record.titleField !== undefined && isTitleFieldUnusable(record)) {
106
- throw new Error(`${where} record.titleField needs record.query and a field name — the title is read ` +
107
- `from the record row.`);
127
+ throw bootRuleError(DASHBOARD_RULES.recordTitleFieldUnusable, {
128
+ message: `${where} record.titleField needs record.query and a field name — the title is read ` +
129
+ `from the record row.`,
130
+ });
108
131
  }
109
132
  const payloadKey = record.payloadKey ?? record.param;
110
133
  for (const other of otherUrlParamIds) {
111
134
  if (other !== undefined && (other === record.param || other === payloadKey)) {
112
- throw new Error(`${where} record.param/payloadKey "${other}" collides with the filter or timeRange id — ` +
113
- `all of them live in the URL search params and panel payloads. Use a different name.`);
135
+ throw bootRuleError(DASHBOARD_RULES.recordParamCollision, {
136
+ message: `${where} record.param/payloadKey "${other}" collides with the filter or timeRange id — ` +
137
+ `all of them live in the URL search params and panel payloads. Use a different name.`,
138
+ });
114
139
  }
115
140
  }
116
141
  }
@@ -119,22 +144,30 @@ function isTitleFieldUnusable(record) {
119
144
  }
120
145
  function validateDashboardRefresh(where, refresh, record) {
121
146
  if ("seconds" in refresh && "field" in refresh) {
122
- throw new Error(`${where} refresh sets both seconds and field — set exactly one.`);
147
+ throw bootRuleError(DASHBOARD_RULES.refreshSecondsAndField, {
148
+ message: `${where} refresh sets both seconds and field — set exactly one.`,
149
+ });
123
150
  }
124
151
  if ("seconds" in refresh) {
125
152
  if (!isRefreshSecondsAllowed(refresh.seconds)) {
126
- throw new Error(`${where} refresh.seconds "${String(refresh.seconds)}" must be a number of at least ` +
127
- `${DASHBOARD_MIN_REFRESH_SECONDS} — shorter intervals would hammer every panel query.`);
153
+ throw bootRuleError(DASHBOARD_RULES.refreshSecondsTooShort, {
154
+ message: `${where} refresh.seconds "${String(refresh.seconds)}" must be a number of at least ` +
155
+ `${DASHBOARD_MIN_REFRESH_SECONDS} — shorter intervals would hammer every panel query.`,
156
+ });
128
157
  }
129
158
  // skip: seconds validated, field rules below do not apply
130
159
  return;
131
160
  }
132
161
  if (refresh.field.length === 0) {
133
- throw new Error(`${where} refresh.field is empty. Name the record field holding the seconds.`);
162
+ throw bootRuleError(DASHBOARD_RULES.refreshFieldEmpty, {
163
+ message: `${where} refresh.field is empty. Name the record field holding the seconds.`,
164
+ });
134
165
  }
135
166
  if (record?.query === undefined) {
136
- throw new Error(`${where} refresh.field "${refresh.field}" needs record.query to read the seconds from. ` +
137
- `Add record: { param, query } or use refresh: { seconds }.`);
167
+ throw bootRuleError(DASHBOARD_RULES.refreshFieldWithoutRecordQuery, {
168
+ message: `${where} refresh.field "${refresh.field}" needs record.query to read the seconds from. ` +
169
+ `Add record: { param, query } or use refresh: { seconds }.`,
170
+ });
138
171
  }
139
172
  }
140
173
  function isRefreshSecondsAllowed(seconds) {
@@ -143,25 +176,37 @@ function isRefreshSecondsAllowed(seconds) {
143
176
  function validateDashboardTimeRange(featureName, screenId, timeRange, filterId) {
144
177
  const prefix = `[Feature ${featureName}] Screen "${screenId}" (dashboard) timeRange`;
145
178
  if (timeRange.id.length === 0)
146
- throw new Error(`${prefix} has an empty id. Set a non-empty id.`);
179
+ throw bootRuleError(DASHBOARD_RULES.timeRangeIdEmpty, {
180
+ message: `${prefix} has an empty id. Set a non-empty id.`,
181
+ });
147
182
  if (timeRange.id === filterId) {
148
- throw new Error(`${prefix} id "${timeRange.id}" collides with the filter id — both live in the URL search params. Use an id different from the filter id.`);
183
+ throw bootRuleError(DASHBOARD_RULES.timeRangeIdCollidesFilter, {
184
+ message: `${prefix} id "${timeRange.id}" collides with the filter id — both live in the URL search params. Use an id different from the filter id.`,
185
+ });
149
186
  }
150
187
  if (timeRange.options.length === 0) {
151
- throw new Error(`${prefix}.options is empty — declare at least one option.`);
188
+ throw bootRuleError(DASHBOARD_RULES.timeRangeOptionsEmpty, {
189
+ message: `${prefix}.options is empty — declare at least one option.`,
190
+ });
152
191
  }
153
192
  const values = new Set();
154
193
  for (const option of timeRange.options) {
155
194
  if (option.value.length === 0 || option.label.length === 0) {
156
- throw new Error(`${prefix} option needs a non-empty value and label. Give every option both.`);
195
+ throw bootRuleError(DASHBOARD_RULES.timeRangeOptionIncomplete, {
196
+ message: `${prefix} option needs a non-empty value and label. Give every option both.`,
197
+ });
157
198
  }
158
199
  if (values.has(option.value)) {
159
- throw new Error(`${prefix}.options has duplicate value "${option.value}". Use each option value once.`);
200
+ throw bootRuleError(DASHBOARD_RULES.timeRangeOptionDuplicate, {
201
+ message: `${prefix}.options has duplicate value "${option.value}". Use each option value once.`,
202
+ });
160
203
  }
161
204
  values.add(option.value);
162
205
  }
163
206
  if (!values.has(timeRange.default)) {
164
- throw new Error(`${prefix}.default "${timeRange.default}" is not among the options (${[...values].join(", ")}). Set default to one of the options.`);
207
+ throw bootRuleError(DASHBOARD_RULES.timeRangeDefaultUnknown, {
208
+ message: `${prefix}.default "${timeRange.default}" is not among the options (${[...values].join(", ")}). Set default to one of the options.`,
209
+ });
165
210
  }
166
211
  }
167
212
  const EMBEDDABLE_SCREEN_TYPES = new Set([
@@ -177,27 +222,35 @@ function validateEmbeddableScreenRef(context, prop, ref, featureName, featureMap
177
222
  const [targetFeatureName = "", , targetShortId = ""] = targetQn.split(":");
178
223
  const target = featureMap.get(targetFeatureName)?.screens[targetShortId];
179
224
  if (target === undefined) {
180
- throw new Error(`${context} ${prop} "${ref}" does not resolve to a registered screen (checked "${targetQn}"). ` +
181
- `Use a same-feature short id or a cross-feature QN "<feature>:screen:<id>".`);
225
+ throw bootRuleError(DASHBOARD_RULES.embeddedScreenUnresolved, {
226
+ message: `${context} ${prop} "${ref}" does not resolve to a registered screen (checked "${targetQn}"). ` +
227
+ `Use a same-feature short id or a cross-feature QN "<feature>:screen:<id>".`,
228
+ });
182
229
  }
183
230
  if (!EMBEDDABLE_SCREEN_TYPES.has(target.type)) {
184
- throw new Error(`${context} embeds "${targetQn}" of type "${target.type}", which can't be embedded — allowed: ` +
185
- `${[...EMBEDDABLE_SCREEN_TYPES].join(", ")}. Use a custom panel for app components.`);
231
+ throw bootRuleError(DASHBOARD_RULES.embeddedScreenType, {
232
+ message: `${context} embeds "${targetQn}" of type "${target.type}", which can't be embedded — allowed: ` +
233
+ `${[...EMBEDDABLE_SCREEN_TYPES].join(", ")}. Use a custom panel for app components.`,
234
+ });
186
235
  }
187
236
  // The tile hands the dashboard's bound record id to the detail screen; without a binding it has no id.
188
237
  // undefined = host unknown (extension-selector panels), checked nowhere else.
189
238
  if (target.type === "projectionDetail" && hostHasRecord === false) {
190
- throw new Error(`${context} embeds "${targetQn}", a projectionDetail, but the host dashboard has no record binding ` +
191
- `to take its id from. Add record: { param } to the dashboard or embed another screen type.`);
239
+ throw bootRuleError(DASHBOARD_RULES.embeddedDetailWithoutRecord, {
240
+ message: `${context} embeds "${targetQn}", a projectionDetail, but the host dashboard has no record binding ` +
241
+ `to take its id from. Add record: { param } to the dashboard or embed another screen type.`,
242
+ });
192
243
  }
193
244
  // ActionFormBody/SecretMintBody navigate via nav.navigate after submit or
194
245
  // cancel even when embedded, which would pull the user off the dashboard.
195
246
  if ((target.type === "actionForm" || target.type === "secretMint") &&
196
247
  (target.redirect !== undefined ||
197
248
  (target.cancelTarget !== undefined && target.cancelTarget !== false))) {
198
- throw new Error(`${context} embeds "${targetQn}", which sets redirect/cancelTarget — an embedded form would ` +
199
- `navigate away from the dashboard on submit or cancel. Embed a screen without redirect and ` +
200
- `with cancelTarget: false (or omitted).`);
249
+ throw bootRuleError(DASHBOARD_RULES.embeddedFormNavigates, {
250
+ message: `${context} embeds "${targetQn}", which sets redirect/cancelTarget — an embedded form would ` +
251
+ `navigate away from the dashboard on submit or cancel. Embed a screen without redirect and ` +
252
+ `with cancelTarget: false (or omitted).`,
253
+ });
201
254
  }
202
255
  return target;
203
256
  }
@@ -209,24 +262,32 @@ export function validateDashboardScreenPanel(featureName, screenId, panel, featu
209
262
  if (panel.fallback === undefined)
210
263
  return;
211
264
  if (panel.visibleWhen === undefined) {
212
- throw new Error(`${context} declares fallback without visibleWhen. Add visibleWhen or remove fallback.`);
265
+ throw bootRuleError(DASHBOARD_RULES.panelFallbackWithoutVisibleWhen, {
266
+ message: `${context} declares fallback without visibleWhen. Add visibleWhen or remove fallback.`,
267
+ });
213
268
  }
214
269
  const target = validateEmbeddableScreenRef(context, "fallback", panel.fallback, featureName, featureMap, hostHasRecord);
215
270
  // A gated fallback could hide in turn; the tile would show nothing where it promised a stand-in.
216
271
  if (target.visibleWhen !== undefined) {
217
- throw new Error(`${context} fallback "${panel.fallback}" has its own visibleWhen; a fallback must always render.`);
272
+ throw bootRuleError(DASHBOARD_RULES.panelFallbackGated, {
273
+ message: `${context} fallback "${panel.fallback}" has its own visibleWhen; a fallback must always render.`,
274
+ });
218
275
  }
219
276
  }
220
277
  function validateDashboardTextPanel(featureName, screenId, panel, featureMap) {
221
278
  const context = `[Feature ${featureName}] Screen "${screenId}" (dashboard) text-panel "${panel.id}"`;
222
279
  if (panel.blocks.length === 0) {
223
- throw new Error(`${context} has an empty blocks list. Add at least one block.`);
280
+ throw bootRuleError(DASHBOARD_RULES.textPanelEmpty, {
281
+ message: `${context} has an empty blocks list. Add at least one block.`,
282
+ });
224
283
  }
225
284
  validateDashboardPanelSpan(featureName, screenId, panel);
226
285
  validateDashboardPanelVisibleWhen(context, panel.visibleWhen);
227
286
  for (const block of panel.blocks) {
228
287
  if (block.kind === "list" && block.items.length === 0) {
229
- throw new Error(`${context} has a list block without items. Add items or remove the block.`);
288
+ throw bootRuleError(DASHBOARD_RULES.textListBlockEmpty, {
289
+ message: `${context} has a list block without items. Add items or remove the block.`,
290
+ });
230
291
  }
231
292
  if (block.kind === "link")
232
293
  validateDashboardTextLinkBlock(context, block, featureName, featureMap);
@@ -236,62 +297,88 @@ function validateDashboardTextLinkBlock(context, block, featureName, featureMap)
236
297
  const targetQn = resolveScreenTargetQn(featureName, block.screen);
237
298
  const [targetFeatureName = "", , targetShortId = ""] = targetQn.split(":");
238
299
  if (featureMap.get(targetFeatureName)?.screens[targetShortId] === undefined) {
239
- throw new Error(`${context} link block screen "${block.screen}" does not resolve to a registered screen ` +
240
- `(checked "${targetQn}"). Use a same-feature short id or a cross-feature QN "<feature>:screen:<id>".`);
300
+ throw bootRuleError(DASHBOARD_RULES.textLinkUnresolved, {
301
+ message: `${context} link block screen "${block.screen}" does not resolve to a registered screen ` +
302
+ `(checked "${targetQn}"). Use a same-feature short id or a cross-feature QN "<feature>:screen:<id>".`,
303
+ });
241
304
  }
242
305
  if (block.roles?.length === 0) {
243
- throw new Error(`${context} link block "${block.screen}" has an empty roles list, which would hide it from everyone. ` +
244
- `List the roles or omit roles.`);
306
+ throw bootRuleError(DASHBOARD_RULES.textLinkRolesEmpty, {
307
+ message: `${context} link block "${block.screen}" has an empty roles list, which would hide it from everyone. ` +
308
+ `List the roles or omit roles.`,
309
+ });
245
310
  }
246
311
  }
247
312
  export function validateDashboardPanelVisibleWhen(context, visibleWhen) {
248
313
  if (visibleWhen !== undefined && (visibleWhen.query === "" || visibleWhen.field === "")) {
249
- throw new Error(`${context} visibleWhen needs a non-empty query and field. Set both visibleWhen.query and visibleWhen.field.`);
314
+ throw bootRuleError(DASHBOARD_RULES.panelVisibleWhenIncomplete, {
315
+ message: `${context} visibleWhen needs a non-empty query and field. Set both visibleWhen.query and visibleWhen.field.`,
316
+ });
250
317
  }
251
318
  }
252
319
  function validateDashboardPanelSpan(featureName, screenId, panel) {
253
320
  if (panel.span !== undefined && panel.span !== "half" && panel.span !== "full") {
254
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) panel "${panel.id}" has span "${String(panel.span)}" — expected "half" or "full".`);
321
+ throw bootRuleError(DASHBOARD_RULES.panelSpanInvalid, {
322
+ message: `[Feature ${featureName}] Screen "${screenId}" (dashboard) panel "${panel.id}" has span "${String(panel.span)}" — expected "half" or "full".`,
323
+ });
255
324
  }
256
325
  }
257
326
  function validateDashboardStatGroupPanel(featureName, screenId, panel, addPanelId) {
258
327
  const context = `[Feature ${featureName}] Screen "${screenId}" (dashboard) stat-group "${panel.id}"`;
259
328
  if (panel.stats.length === 0) {
260
- throw new Error(`${context} has an empty stats list. Add at least one stat.`);
329
+ throw bootRuleError(DASHBOARD_RULES.statGroupEmpty, {
330
+ message: `${context} has an empty stats list. Add at least one stat.`,
331
+ });
261
332
  }
262
333
  if (panel.subtitle !== undefined && panel.label === undefined) {
263
- throw new Error(`${context} sets subtitle without label — an unlabeled group renders as a KPI strip without a header. Set a label or remove subtitle.`);
334
+ throw bootRuleError(DASHBOARD_RULES.statGroupSubtitleWithoutLabel, {
335
+ message: `${context} sets subtitle without label — an unlabeled group renders as a KPI strip without a header. Set a label or remove subtitle.`,
336
+ });
264
337
  }
265
338
  validateDashboardPanelSpan(featureName, screenId, panel);
266
339
  validateDashboardPanelVisibleWhen(context, panel.visibleWhen);
267
340
  for (const stat of panel.stats) {
268
341
  addPanelId(stat.id, "stat-group child");
269
342
  if (stat.visibleWhen !== undefined) {
270
- throw new Error(`${context} child "${stat.id}" sets visibleWhen — gate the whole group instead; a hidden cell would leave a gap in the strip.`);
343
+ throw bootRuleError(DASHBOARD_RULES.statGroupChildVisibleWhen, {
344
+ message: `${context} child "${stat.id}" sets visibleWhen — gate the whole group instead; a hidden cell would leave a gap in the strip.`,
345
+ });
271
346
  }
272
347
  if (!stat.query || typeof stat.query !== "string") {
273
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) stat-group "${panel.id}" child "${stat.id}" has empty or non-string query. Set query to a registered query name.`);
348
+ throw bootRuleError(DASHBOARD_RULES.panelQueryEmpty, {
349
+ message: `[Feature ${featureName}] Screen "${screenId}" (dashboard) stat-group "${panel.id}" child "${stat.id}" has empty or non-string query. Set query to a registered query name.`,
350
+ });
274
351
  }
275
352
  if (stat.valueField.length === 0) {
276
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) stat-group "${panel.id}" child "${stat.id}" has empty valueField. Set valueField to a field of the query result.`);
353
+ throw bootRuleError(DASHBOARD_RULES.statValueFieldEmpty, {
354
+ message: `[Feature ${featureName}] Screen "${screenId}" (dashboard) stat-group "${panel.id}" child "${stat.id}" has empty valueField. Set valueField to a field of the query result.`,
355
+ });
277
356
  }
278
357
  validateDashboardValueFormat(featureName, screenId, stat.id, stat.valueFormat, STAT_VALUE_FORMATS);
279
358
  }
280
359
  }
281
360
  function validateFromTodayWindowReach(where, panel) {
282
361
  if (panel.initialWindow === "from-today" && panel.ranges === undefined && panel.brush !== true) {
283
- throw new Error(`${where}.initialWindow "from-today" needs ranges or brush, otherwise data before today is unreachable.`);
362
+ throw bootRuleError(DASHBOARD_CHART_RULES.chartFromTodayUnreachable, {
363
+ message: `${where}.initialWindow "from-today" needs ranges or brush, otherwise data before today is unreachable.`,
364
+ });
284
365
  }
285
366
  }
286
367
  function validateChartScrollableAndUnit(where, panel) {
287
368
  if (panel.scrollable !== undefined && typeof panel.scrollable !== "boolean") {
288
- throw new Error(`${where} has a non-boolean scrollable. Use true or false.`);
369
+ throw bootRuleError(DASHBOARD_CHART_RULES.chartFlagNonBoolean, {
370
+ message: `${where} has a non-boolean scrollable. Use true or false.`,
371
+ });
289
372
  }
290
373
  if (panel.scrollable === true && panel.chart !== "stacked-area") {
291
- throw new Error(`${where} sets scrollable on chart "${panel.chart}" — only "stacked-area" supports it. Remove scrollable or use chart "stacked-area".`);
374
+ throw bootRuleError(DASHBOARD_CHART_RULES.chartStackedAreaOnly, {
375
+ message: `${where} sets scrollable on chart "${panel.chart}" — only "stacked-area" supports it. Remove scrollable or use chart "stacked-area".`,
376
+ });
292
377
  }
293
378
  if (panel.unit !== undefined && panel.chart !== "timeseries") {
294
- throw new Error(`${where} sets unit on chart "${panel.chart}" — only "timeseries" supports it. Remove unit or use chart "timeseries".`);
379
+ throw bootRuleError(DASHBOARD_CHART_RULES.chartUnitTimeseriesOnly, {
380
+ message: `${where} sets unit on chart "${panel.chart}" — only "timeseries" supports it. Remove unit or use chart "timeseries".`,
381
+ });
295
382
  }
296
383
  }
297
384
  function validateDashboardChartDisplay(featureName, screenId, panel) {
@@ -307,12 +394,16 @@ function validateDashboardChartDisplay(featureName, screenId, panel) {
307
394
  validateStackedAreaEnumProp(where, "markerLegend", panel.markerLegend, ["list", "legend"]);
308
395
  const nonBooleanProp = ["brush", "legendTotals", "markerLabels"].find((prop) => panel[prop] !== undefined && typeof panel[prop] !== "boolean");
309
396
  if (nonBooleanProp !== undefined) {
310
- throw new Error(`${where} has a non-boolean ${nonBooleanProp}. Use true or false.`);
397
+ throw bootRuleError(DASHBOARD_CHART_RULES.chartFlagNonBoolean, {
398
+ message: `${where} has a non-boolean ${nonBooleanProp}. Use true or false.`,
399
+ });
311
400
  }
312
401
  validateFromTodayWindowReach(where, panel);
313
402
  for (const [key, color] of Object.entries(panel.seriesColors ?? {})) {
314
403
  if (typeof color !== "string" || color.trim() === "") {
315
- throw new Error(`${where} seriesColors["${key}"] must be a non-empty CSS color.`);
404
+ throw bootRuleError(DASHBOARD_CHART_RULES.chartColorInvalid, {
405
+ message: `${where} seriesColors["${key}"] must be a non-empty CSS color.`,
406
+ });
316
407
  }
317
408
  }
318
409
  for (const [kind, look] of Object.entries(panel.markerKinds ?? {})) {
@@ -326,7 +417,9 @@ function validateStackedAreaEnumProp(where, prop, value, allowed) {
326
417
  if (value === undefined)
327
418
  return;
328
419
  if (!allowed.includes(value)) {
329
- throw new Error(`${where}.${prop} "${String(value)}" must be one of ${allowed.join(", ")}.`);
420
+ throw bootRuleError(DASHBOARD_CHART_RULES.chartEnumPropInvalid, {
421
+ message: `${where}.${prop} "${String(value)}" must be one of ${allowed.join(", ")}.`,
422
+ });
330
423
  }
331
424
  }
332
425
  function validateStackedAreaOnlyProps(where, panel) {
@@ -344,7 +437,9 @@ function validateStackedAreaOnlyProps(where, panel) {
344
437
  "markerLabels",
345
438
  ].filter((prop) => panel[prop] !== undefined);
346
439
  if (stackedAreaOnly.length > 0) {
347
- throw new Error(`${where} sets ${stackedAreaOnly.join(", ")} on chart "${panel.chart}" — only "stacked-area" supports it. Remove these props or use chart "stacked-area".`);
440
+ throw bootRuleError(DASHBOARD_CHART_RULES.chartStackedAreaOnly, {
441
+ message: `${where} sets ${stackedAreaOnly.join(", ")} on chart "${panel.chart}" — only "stacked-area" supports it. Remove these props or use chart "stacked-area".`,
442
+ });
348
443
  }
349
444
  }
350
445
  const DASHBOARD_CHART_TONES = new Set([
@@ -355,37 +450,55 @@ const DASHBOARD_CHART_TONES = new Set([
355
450
  ]);
356
451
  function validateDashboardChartMarkerKind(where, look) {
357
452
  if (look.tone === undefined && look.color === undefined) {
358
- throw new Error(`${where} needs a tone or a color. Set tone or color.`);
453
+ throw bootRuleError(DASHBOARD_CHART_RULES.chartMarkerLookMissing, {
454
+ message: `${where} needs a tone or a color. Set tone or color.`,
455
+ });
359
456
  }
360
457
  if (look.tone !== undefined && !DASHBOARD_CHART_TONES.has(look.tone)) {
361
- throw new Error(`${where}.tone "${String(look.tone)}" is not one of ${[...DASHBOARD_CHART_TONES].join(", ")}.`);
458
+ throw bootRuleError(DASHBOARD_CHART_RULES.chartMarkerToneInvalid, {
459
+ message: `${where}.tone "${String(look.tone)}" is not one of ${[...DASHBOARD_CHART_TONES].join(", ")}.`,
460
+ });
362
461
  }
363
462
  if (look.color !== undefined && (typeof look.color !== "string" || look.color.trim() === "")) {
364
- throw new Error(`${where}.color must be a non-empty CSS color.`);
463
+ throw bootRuleError(DASHBOARD_CHART_RULES.chartColorInvalid, {
464
+ message: `${where}.color must be a non-empty CSS color.`,
465
+ });
365
466
  }
366
467
  if (look.label !== undefined && (typeof look.label !== "string" || look.label.trim() === "")) {
367
- throw new Error(`${where}.label must be a non-empty i18n key.`);
468
+ throw bootRuleError(DASHBOARD_CHART_RULES.chartMarkerLabelInvalid, {
469
+ message: `${where}.label must be a non-empty i18n key.`,
470
+ });
368
471
  }
369
472
  }
370
473
  function validateDashboardChartRanges(where, ranges) {
371
474
  if (ranges.options.length === 0) {
372
- throw new Error(`${where}.options is empty — declare at least one option.`);
475
+ throw bootRuleError(DASHBOARD_CHART_RULES.chartRangesOptionsEmpty, {
476
+ message: `${where}.options is empty — declare at least one option.`,
477
+ });
373
478
  }
374
479
  const values = new Set();
375
480
  for (const option of ranges.options) {
376
481
  if (option.value.length === 0 || option.label.length === 0) {
377
- throw new Error(`${where} option needs a non-empty value and label. Give every option both.`);
482
+ throw bootRuleError(DASHBOARD_CHART_RULES.chartRangesOptionIncomplete, {
483
+ message: `${where} option needs a non-empty value and label. Give every option both.`,
484
+ });
378
485
  }
379
486
  if (values.has(option.value)) {
380
- throw new Error(`${where}.options has duplicate value "${option.value}". Use each option value once.`);
487
+ throw bootRuleError(DASHBOARD_CHART_RULES.chartRangesOptionDuplicate, {
488
+ message: `${where}.options has duplicate value "${option.value}". Use each option value once.`,
489
+ });
381
490
  }
382
491
  if (option.months !== undefined && (!Number.isInteger(option.months) || option.months <= 0)) {
383
- throw new Error(`${where} option "${option.value}" months "${String(option.months)}" must be a positive integer.`);
492
+ throw bootRuleError(DASHBOARD_CHART_RULES.chartRangesMonthsInvalid, {
493
+ message: `${where} option "${option.value}" months "${String(option.months)}" must be a positive integer.`,
494
+ });
384
495
  }
385
496
  values.add(option.value);
386
497
  }
387
498
  if (!values.has(ranges.default)) {
388
- throw new Error(`${where}.default "${ranges.default}" is not among the options (${[...values].join(", ")}). Set default to one of the options.`);
499
+ throw bootRuleError(DASHBOARD_CHART_RULES.chartRangesDefaultUnknown, {
500
+ message: `${where}.default "${ranges.default}" is not among the options (${[...values].join(", ")}). Set default to one of the options.`,
501
+ });
389
502
  }
390
503
  }
391
504
  const CURRENCY_CODE_RE = /^[A-Z]{3}$/;
@@ -401,34 +514,46 @@ function validateDashboardValueFormat(featureName, screenId, panelId, valueForma
401
514
  return;
402
515
  const where = `[Feature ${featureName}] Screen "${screenId}" (dashboard) panel "${panelId}" valueFormat`;
403
516
  if (!allowedKinds.includes(valueFormat.kind)) {
404
- throw new Error(`${where}.kind "${String(valueFormat.kind)}" must be ${allowedKinds.map((kind) => `"${kind}"`).join(" or ")}.`);
517
+ throw bootRuleError(DASHBOARD_CHART_RULES.valueFormatKind, {
518
+ message: `${where}.kind "${String(valueFormat.kind)}" must be ${allowedKinds.map((kind) => `"${kind}"`).join(" or ")}.`,
519
+ });
405
520
  }
406
521
  // skip: relativeTime carries no options
407
522
  if (valueFormat.kind === "relativeTime")
408
523
  return;
409
524
  if (!CURRENCY_CODE_RE.test(valueFormat.currency)) {
410
- throw new Error(`${where}.currency "${String(valueFormat.currency)}" must be a 3-letter uppercase ISO currency code.`);
525
+ throw bootRuleError(DASHBOARD_CHART_RULES.valueFormatCurrency, {
526
+ message: `${where}.currency "${String(valueFormat.currency)}" must be a 3-letter uppercase ISO currency code.`,
527
+ });
411
528
  }
412
529
  const digits = valueFormat.fractionDigits;
413
530
  if (digits !== undefined &&
414
531
  (!Number.isInteger(digits) || digits < 0 || digits > MAX_VALUE_FORMAT_FRACTION_DIGITS)) {
415
- throw new Error(`${where}.fractionDigits "${String(digits)}" must be an integer from 0 to ${MAX_VALUE_FORMAT_FRACTION_DIGITS}.`);
532
+ throw bootRuleError(DASHBOARD_CHART_RULES.valueFormatFractionDigits, {
533
+ message: `${where}.fractionDigits "${String(digits)}" must be an integer from 0 to ${MAX_VALUE_FORMAT_FRACTION_DIGITS}.`,
534
+ });
416
535
  }
417
536
  }
418
537
  export function validateDashboardCustomPanel(featureName, screenId, panel) {
419
538
  if (panel.component.react === undefined && panel.component.native === undefined) {
420
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) custom-panel "${panel.id}" has no component — ` +
421
- `declare a react/native component marker.`);
539
+ throw bootRuleError(DASHBOARD_RULES.customPanelNoComponent, {
540
+ message: `[Feature ${featureName}] Screen "${screenId}" (dashboard) custom-panel "${panel.id}" has no component — ` +
541
+ `declare a react/native component marker.`,
542
+ });
422
543
  }
423
544
  }
424
545
  function validateDashboardQueryPanel(featureName, screenId, panel, featureMap) {
425
546
  if (!panel.query || typeof panel.query !== "string") {
426
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) panel "${panel.id}" has empty or non-string query. Set query to a registered query name.`);
547
+ throw bootRuleError(DASHBOARD_RULES.panelQueryEmpty, {
548
+ message: `[Feature ${featureName}] Screen "${screenId}" (dashboard) panel "${panel.id}" has empty or non-string query. Set query to a registered query name.`,
549
+ });
427
550
  }
428
551
  validateDashboardPanelSpan(featureName, screenId, panel);
429
552
  if (panel.kind === "stat") {
430
553
  if (panel.valueField.length === 0) {
431
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) stat-panel "${panel.id}" has empty valueField. Set valueField to a field of the query result.`);
554
+ throw bootRuleError(DASHBOARD_RULES.statValueFieldEmpty, {
555
+ message: `[Feature ${featureName}] Screen "${screenId}" (dashboard) stat-panel "${panel.id}" has empty valueField. Set valueField to a field of the query result.`,
556
+ });
432
557
  }
433
558
  validateDashboardValueFormat(featureName, screenId, panel.id, panel.valueFormat, STAT_VALUE_FORMATS);
434
559
  }
@@ -437,7 +562,9 @@ function validateDashboardQueryPanel(featureName, screenId, panel, featureMap) {
437
562
  validateDashboardChartDisplay(featureName, screenId, panel);
438
563
  if (panel.kind === "list") {
439
564
  if (panel.columns.length === 0) {
440
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) list-panel "${panel.id}" has an empty columns list. Add at least one column.`);
565
+ throw bootRuleError(DASHBOARD_RULES.listPanelColumnsEmpty, {
566
+ message: `[Feature ${featureName}] Screen "${screenId}" (dashboard) list-panel "${panel.id}" has an empty columns list. Add at least one column.`,
567
+ });
441
568
  }
442
569
  for (const col of panel.columns) {
443
570
  const normalized = normalizeListColumn(col);
@@ -450,22 +577,32 @@ function validateDashboardQueryPanel(featureName, screenId, panel, featureMap) {
450
577
  }
451
578
  function validateDashboardFilterDefinition(featureName, screenId, filter) {
452
579
  if (filter.id.length === 0) {
453
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) filter has an empty id. Set a non-empty id.`);
580
+ throw bootRuleError(DASHBOARD_RULES.filterIdEmpty, {
581
+ message: `[Feature ${featureName}] Screen "${screenId}" (dashboard) filter has an empty id. Set a non-empty id.`,
582
+ });
454
583
  }
455
584
  if (filter.label.length === 0) {
456
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) filter has an empty label. Set a non-empty label.`);
585
+ throw bootRuleError(DASHBOARD_RULES.filterLabelEmpty, {
586
+ message: `[Feature ${featureName}] Screen "${screenId}" (dashboard) filter has an empty label. Set a non-empty label.`,
587
+ });
457
588
  }
458
589
  const hasOptions = filter.options !== undefined;
459
590
  const hasOptionsQuery = filter.optionsQuery !== undefined;
460
591
  if (hasOptions === hasOptionsQuery) {
461
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) filter must set exactly one of ` +
462
- `options/optionsQuery.`);
592
+ throw bootRuleError(DASHBOARD_RULES.filterOptionsXor, {
593
+ message: `[Feature ${featureName}] Screen "${screenId}" (dashboard) filter must set exactly one of ` +
594
+ `options/optionsQuery.`,
595
+ });
463
596
  }
464
597
  if (hasOptions && (filter.options?.length ?? 0) === 0) {
465
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) filter.options is empty — ` +
466
- `declare at least one option or use optionsQuery instead.`);
598
+ throw bootRuleError(DASHBOARD_RULES.filterOptionsEmpty, {
599
+ message: `[Feature ${featureName}] Screen "${screenId}" (dashboard) filter.options is empty — ` +
600
+ `declare at least one option or use optionsQuery instead.`,
601
+ });
467
602
  }
468
603
  if (hasOptionsQuery && filter.optionsQuery?.length === 0) {
469
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) filter.optionsQuery is empty. Set optionsQuery to a query name or remove it.`);
604
+ throw bootRuleError(DASHBOARD_RULES.filterOptionsQueryEmpty, {
605
+ message: `[Feature ${featureName}] Screen "${screenId}" (dashboard) filter.optionsQuery is empty. Set optionsQuery to a query name or remove it.`,
606
+ });
470
607
  }
471
608
  }