@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
@@ -15,8 +15,10 @@ export function isRowClickAction(action) {
15
15
  export function validateAtMostOneRowClick(featureName, screenId, screenType, rowActions) {
16
16
  const rowClickActions = rowActions.filter(isRowClickAction);
17
17
  if (rowClickActions.length > 1) {
18
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) has ${rowClickActions.length} ` +
19
- "rowActions marked rowClick:true — at most one may fire on a row-body click. Mark at most one rowAction with rowClick: true.");
18
+ throw bootRuleError(SCREEN_ACTION_RULES.rowClickAtMostOne, {
19
+ message: `[Feature ${featureName}] Screen "${screenId}" (${screenType}) has ${rowClickActions.length} ` +
20
+ "rowActions marked rowClick:true — at most one may fire on a row-body click. Mark at most one rowAction with rowClick: true.",
21
+ });
20
22
  }
21
23
  }
22
24
  export function rowFieldExtractorKeys(params) {
@@ -61,20 +63,24 @@ export function validateRowActionNavigateParams(featureName, screenId, screenTyp
61
63
  const { filter, record, timeRange } = target.screen;
62
64
  const readIds = [filter?.id, record?.param, timeRange?.id].filter((id) => id !== undefined);
63
65
  if (readIds.length === 0) {
64
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" sets ` +
65
- `params on navigate-target ${targetDescriptor} (dashboard) — target dashboard declares no ` +
66
- `filter, time range or record binding — params would be a no-op. Remove the params extractor, or add a \`filter\` (or a \`record\` binding) to the ` +
67
- `target dashboard so it has somewhere to read the value from.`);
66
+ throw bootRuleError(SCREEN_ACTION_RULES.navigateParamsDashboardNoReader, {
67
+ message: `[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" sets ` +
68
+ `params on navigate-target ${targetDescriptor} (dashboard) — target dashboard declares no ` +
69
+ `filter, time range or record binding — params would be a no-op. Remove the params extractor, or add a \`filter\` (or a \`record\` binding) to the ` +
70
+ `target dashboard so it has somewhere to read the value from.`,
71
+ });
68
72
  }
69
73
  const extractedKeys = rowFieldExtractorKeys(action.params);
70
74
  if (!readIds.some((id) => extractedKeys.includes(id))) {
71
75
  const readDescriptor = filter !== undefined && readIds.length === 1
72
76
  ? `filter id is "${filter.id}"`
73
77
  : `URL params are [${readIds.join(", ")}]`;
74
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" sets ` +
75
- `params [${extractedKeys.join(", ")}] on navigate-target ${targetDescriptor} (dashboard) whose ` +
76
- `${readDescriptor} — none of the extracted keys match, so the value would stay ` +
77
- `unset. Fix the params extractor to produce one of these keys, or remove it.`);
78
+ throw bootRuleError(SCREEN_ACTION_RULES.navigateParamsDashboardKeyMismatch, {
79
+ message: `[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" sets ` +
80
+ `params [${extractedKeys.join(", ")}] on navigate-target ${targetDescriptor} (dashboard) whose ` +
81
+ `${readDescriptor} — none of the extracted keys match, so the value would stay ` +
82
+ `unset. Fix the params extractor to produce one of these keys, or remove it.`,
83
+ });
78
84
  }
79
85
  // skip: a read id is present and the extractor's keys cover it — valid dashboard deep-link.
80
86
  return;
@@ -87,11 +93,13 @@ export function validateRowActionNavigateParams(featureName, screenId, screenTyp
87
93
  : `same entity "${screenEntity}" auto-fills row["id"]`})`
88
94
  : `screen type "${target.screen.type}"`;
89
95
  const targetDescriptor = action.screen !== undefined ? `"${action.screen}"` : `entity "${action.entity}"`;
90
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" ` +
91
- `sets params on navigate-target ${targetDescriptor} which ${reason} — only actionForm, ` +
92
- `secretMint and entityEdit-create targets read URL search params as initial values. Remove ` +
93
- `the params extractor or retarget to an actionForm / secretMint / cross-entity ` +
94
- `entityEdit-create screen.`);
96
+ throw bootRuleError(SCREEN_ACTION_RULES.navigateParamsTargetIgnoresParams, {
97
+ message: `[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" ` +
98
+ `sets params on navigate-target ${targetDescriptor} which ${reason} — only actionForm, ` +
99
+ `secretMint and entityEdit-create targets read URL search params as initial values. Remove ` +
100
+ `the params extractor or retarget to an actionForm / secretMint / cross-entity ` +
101
+ `entityEdit-create screen.`,
102
+ });
95
103
  }
96
104
  const formTarget = target.screen;
97
105
  if ((formTarget.type === "actionForm" || formTarget.type === "secretMint") &&
@@ -153,8 +161,10 @@ export function validateActionFieldRefs(featureName, screenId, actionKind, actio
153
161
  if (rowMeta.has(source))
154
162
  continue;
155
163
  if (!fieldNames.has(source)) {
156
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" ${actionKind} "${actionId}" ` +
157
- `${label} references unknown field "${source}". Known fields: ${known()}.`);
164
+ throw bootRuleError(SCREEN_ACTION_RULES.actionUnknownFieldRef, {
165
+ message: `[Feature ${featureName}] Screen "${screenId}" ${actionKind} "${actionId}" ` +
166
+ `${label} references unknown field "${source}". Known fields: ${known()}.`,
167
+ });
158
168
  }
159
169
  }
160
170
  };
@@ -164,12 +174,16 @@ export function validateActionFieldRefs(featureName, screenId, actionKind, actio
164
174
  typeof visible !== "boolean" &&
165
175
  !rowMeta.has(visible.field) &&
166
176
  !fieldNames.has(visible.field)) {
167
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" ${actionKind} "${actionId}" ` +
168
- `visible.field references unknown field "${visible.field}". Known fields: ${known()}.`);
177
+ throw bootRuleError(SCREEN_ACTION_RULES.actionVisibleUnknownField, {
178
+ message: `[Feature ${featureName}] Screen "${screenId}" ${actionKind} "${actionId}" ` +
179
+ `visible.field references unknown field "${visible.field}". Known fields: ${known()}.`,
180
+ });
169
181
  }
170
182
  if (entityId !== undefined && entityId !== "id" && !fieldNames.has(entityId)) {
171
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" ${actionKind} "${actionId}" ` +
172
- `entityId references unknown field "${entityId}". Known fields: ${known()}.`);
183
+ throw bootRuleError(SCREEN_ACTION_RULES.actionEntityIdUnknownField, {
184
+ message: `[Feature ${featureName}] Screen "${screenId}" ${actionKind} "${actionId}" ` +
185
+ `entityId references unknown field "${entityId}". Known fields: ${known()}.`,
186
+ });
173
187
  }
174
188
  }
175
189
  // Two features registering the same short screen-id is a silent routing
@@ -182,10 +196,12 @@ export function validateScreenShortIdCollisions(screensByShortId) {
182
196
  for (const [shortId, entries] of screensByShortId) {
183
197
  const featureNames = new Set(entries.map((e) => e.featureName));
184
198
  if (featureNames.size > 1) {
185
- throw new Error(`Screen short-id "${shortId}" is registered by ${featureNames.size} features ` +
186
- `(${[...featureNames].join(", ")}) — the runtime router resolves a bare navigate-target ` +
187
- `id by taking the first match, so all but one of these screens would be unreachable by ` +
188
- `that id. Give each screen a distinct id.`);
199
+ throw bootRuleError(SCREEN_ACTION_RULES.screenShortIdCollision, {
200
+ message: `Screen short-id "${shortId}" is registered by ${featureNames.size} features ` +
201
+ `(${[...featureNames].join(", ")}) — the runtime router resolves a bare navigate-target ` +
202
+ `id by taking the first match, so all but one of these screens would be unreachable by ` +
203
+ `that id. Give each screen a distinct id.`,
204
+ });
189
205
  }
190
206
  }
191
207
  }
@@ -200,9 +216,11 @@ export function resolveScreenTargetQn(featureName, target) {
200
216
  export function validateScreenNavTarget(featureName, screenId, screenKind, fieldName, value, allScreenQns, screens) {
201
217
  const candidateQn = resolveScreenTargetQn(featureName, value);
202
218
  if (!allScreenQns.has(candidateQn)) {
203
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenKind}) ${fieldName} "${value}" ` +
204
- `does not resolve to a registered screen (checked "${candidateQn}"). Known screens ` +
205
- `in this feature: ${[...Object.keys(screens)].sort().join(", ") || "(none)"}.`);
219
+ throw bootRuleError(SCREEN_ACTION_RULES.navTargetUnresolved, {
220
+ message: `[Feature ${featureName}] Screen "${screenId}" (${screenKind}) ${fieldName} "${value}" ` +
221
+ `does not resolve to a registered screen (checked "${candidateQn}"). Known screens ` +
222
+ `in this feature: ${[...Object.keys(screens)].sort().join(", ") || "(none)"}.`,
223
+ });
206
224
  }
207
225
  }
208
226
  // kind:"drawer" resolves same-feature only — unlike navigate/redirect,
@@ -216,19 +234,23 @@ export function validateScreenNavTarget(featureName, screenId, screenKind, field
216
234
  export function validateDrawerTargetAction(featureName, screenId, screenKind, actionLabel, action, screens) {
217
235
  const target = screens[action.screen];
218
236
  if (target === undefined) {
219
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenKind}) ${actionLabel} "${action.id}" ` +
220
- `drawer-target "${action.screen}" does not resolve to a registered screen in this feature. ` +
221
- `kind:"drawer" only resolves same-feature screens (unlike kind:"navigate", which can target ` +
222
- `screens in any feature) — the drawer mounts the target inline using this feature's schema. ` +
223
- `Known screens in this feature: ${[...Object.keys(screens)].sort().join(", ") || "(none)"}.`);
237
+ throw bootRuleError(SCREEN_ACTION_RULES.drawerTargetUnresolved, {
238
+ message: `[Feature ${featureName}] Screen "${screenId}" (${screenKind}) ${actionLabel} "${action.id}" ` +
239
+ `drawer-target "${action.screen}" does not resolve to a registered screen in this feature. ` +
240
+ `kind:"drawer" only resolves same-feature screens (unlike kind:"navigate", which can target ` +
241
+ `screens in any feature) — the drawer mounts the target inline using this feature's schema. ` +
242
+ `Known screens in this feature: ${[...Object.keys(screens)].sort().join(", ") || "(none)"}.`,
243
+ });
224
244
  }
225
245
  // secretMint is intentionally excluded — a one-time secret reveal belongs on
226
246
  // its own page, not layered in a Drawer above a list.
227
247
  if (target.type !== "actionForm") {
228
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenKind}) ${actionLabel} "${action.id}" ` +
229
- `drawer-target "${action.screen}" is a "${target.type}" screen, not an actionForm. ` +
230
- `kind:"drawer" mounts an actionForm inside a Drawer widget — point "screen" at an ` +
231
- `actionForm screen, or use kind:"navigate" for a full-page target.`);
248
+ throw bootRuleError(SCREEN_ACTION_RULES.drawerTargetNotActionForm, {
249
+ message: `[Feature ${featureName}] Screen "${screenId}" (${screenKind}) ${actionLabel} "${action.id}" ` +
250
+ `drawer-target "${action.screen}" is a "${target.type}" screen, not an actionForm. ` +
251
+ `kind:"drawer" mounts an actionForm inside a Drawer widget — point "screen" at an ` +
252
+ `actionForm screen, or use kind:"navigate" for a full-page target.`,
253
+ });
232
254
  }
233
255
  // The renderer (mergeSearchParamsIntoInitial) silently drops a prefill key
234
256
  // when the target doesn't declare the field, marks it sensitive/password,
@@ -262,17 +284,23 @@ export function validateDrawerPrefillKeys(where, targetLabel, targetScreenId, ta
262
284
  if (fieldName === "id" && target.type === "actionForm" && target.load !== undefined)
263
285
  continue;
264
286
  if (!Object.hasOwn(target.fields, fieldName)) {
265
- throw new Error(`${where} params prefills "${fieldName}", which ${targetLabel} "${targetScreenId}" does not declare as a ` +
266
- `field — the renderer would drop it and leave the form empty. Target fields: ` +
267
- `${Object.keys(target.fields).sort().join(", ") || "(none)"}.`);
287
+ throw bootRuleError(SCREEN_ACTION_RULES.prefillParamUnknownField, {
288
+ message: `${where} params prefills "${fieldName}", which ${targetLabel} "${targetScreenId}" does not declare as a ` +
289
+ `field — the renderer would drop it and leave the form empty. Target fields: ` +
290
+ `${Object.keys(target.fields).sort().join(", ") || "(none)"}.`,
291
+ });
268
292
  }
269
293
  if (isSensitiveOrPasswordField(target.fields[fieldName])) {
270
- throw new Error(`${where} params prefills "${fieldName}", which ${targetLabel} "${targetScreenId}" marks as ` +
271
- `sensitive or password — the renderer never prefills those fields and would leave the form empty. Remove that param or prefill a non-sensitive field.`);
294
+ throw bootRuleError(SCREEN_ACTION_RULES.prefillParamSensitiveField, {
295
+ message: `${where} params prefills "${fieldName}", which ${targetLabel} "${targetScreenId}" marks as ` +
296
+ `sensitive or password — the renderer never prefills those fields and would leave the form empty. Remove that param or prefill a non-sensitive field.`,
297
+ });
272
298
  }
273
299
  if (!renderedFieldNames.has(fieldName)) {
274
- throw new Error(`${where} params prefills "${fieldName}", which ${targetLabel} "${targetScreenId}" does not render in ` +
275
- `its layout — the renderer only prefills fields the layout shows and would drop it.`);
300
+ throw bootRuleError(SCREEN_ACTION_RULES.prefillParamNotRendered, {
301
+ message: `${where} params prefills "${fieldName}", which ${targetLabel} "${targetScreenId}" does not render in ` +
302
+ `its layout — the renderer only prefills fields the layout shows and would drop it.`,
303
+ });
276
304
  }
277
305
  }
278
306
  }
@@ -283,28 +311,36 @@ function validateRowActionNavigateTab(featureName, screenId, screenType, actionL
283
311
  if (action.tab === undefined)
284
312
  return;
285
313
  if (target === undefined) {
286
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" ` +
287
- `sets tab "${action.tab}", but its navigate-target could not be resolved to a screen. Point the navigate-target at a registered screen.`);
314
+ throw bootRuleError(SCREEN_ACTION_RULES.navigateTabTargetUnresolved, {
315
+ message: `[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" ` +
316
+ `sets tab "${action.tab}", but its navigate-target could not be resolved to a screen. Point the navigate-target at a registered screen.`,
317
+ });
288
318
  }
289
319
  if (target.screen.type !== "projectionDetail" || target.screen.layout.mode !== "tabs") {
290
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" ` +
291
- `sets tab "${action.tab}", but navigate-target screen "${target.screen.id}" is not a ` +
292
- `projectionDetail with layout.mode "tabs" — only those read the tab param. Remove the tab or navigate to a projectionDetail screen with layout.mode "tabs".`);
320
+ throw bootRuleError(SCREEN_ACTION_RULES.navigateTabTargetNotTabbed, {
321
+ message: `[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" ` +
322
+ `sets tab "${action.tab}", but navigate-target screen "${target.screen.id}" is not a ` +
323
+ `projectionDetail with layout.mode "tabs" — only those read the tab param. Remove the tab or navigate to a projectionDetail screen with layout.mode "tabs".`,
324
+ });
293
325
  }
294
326
  const sectionIds = target.screen.layout.sections
295
327
  .map((section) => section.id)
296
328
  .filter((id) => id !== undefined);
297
329
  if (!sectionIds.includes(action.tab)) {
298
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" ` +
299
- `navigates to tab "${action.tab}", which is not a section id on target screen ` +
300
- `"${target.screen.id}". Available: ${sectionIds.join(", ") || "(none)"}.`);
330
+ throw bootRuleError(SCREEN_ACTION_RULES.navigateTabUnknownSection, {
331
+ message: `[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" ` +
332
+ `navigates to tab "${action.tab}", which is not a section id on target screen ` +
333
+ `"${target.screen.id}". Available: ${sectionIds.join(", ") || "(none)"}.`,
334
+ });
301
335
  }
302
336
  }
303
337
  export function resolveRowActionNavigateTarget(featureName, screenId, screenType, actionLabel, action, allScreenQns, navTargetShortIds, screensByShortId, detailForScreens) {
304
338
  if (action.entity !== undefined) {
305
339
  if (action.screen !== undefined) {
306
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" ` +
307
- `sets both "screen" and "entity" — exactly one navigate-target form is allowed.`);
340
+ throw bootRuleError(SCREEN_ACTION_RULES.navigateTargetScreenAndEntity, {
341
+ message: `[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" ` +
342
+ `sets both "screen" and "entity" — exactly one navigate-target form is allowed.`,
343
+ });
308
344
  }
309
345
  if (screenType !== "entityList" && action.entityId === undefined) {
310
346
  // entityList rows are always a real entity record, so row["id"] is a
@@ -312,29 +348,41 @@ export function resolveRowActionNavigateTarget(featureName, screenId, screenType
312
348
  // an arbitrary query projection with no guaranteed "id" field — an
313
349
  // entity-target there needs an explicit entityId, or navigation silently
314
350
  // opens the detail screen with no entity context at runtime.
315
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" ` +
316
- `navigate-target entity "${action.entity}" needs an explicit "entityId" — ${screenType} rows ` +
317
- `come from a query projection with no guaranteed "id" field.`);
351
+ throw bootRuleError(SCREEN_ACTION_RULES.navigateEntityTargetNeedsEntityId, {
352
+ message: `[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" ` +
353
+ `navigate-target entity "${action.entity}" needs an explicit "entityId" — ${screenType} rows ` +
354
+ `come from a query projection with no guaranteed "id" field.`,
355
+ });
318
356
  }
319
357
  const detail = detailForScreens.get(action.entity);
320
358
  if (detail === undefined) {
321
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" ` +
322
- `navigate-target entity "${action.entity}" has no screen declaring ` +
323
- `detailFor: "${action.entity}". Add detailFor: "${action.entity}" to a screen or navigate to a screen directly.`);
359
+ throw bootRuleError(SCREEN_ACTION_RULES.navigateEntityTargetNoDetail, {
360
+ message: `[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" ` +
361
+ `navigate-target entity "${action.entity}" has no screen declaring ` +
362
+ `detailFor: "${action.entity}". Add detailFor: "${action.entity}" to a screen or navigate to a screen directly.`,
363
+ });
324
364
  }
325
365
  validateRowActionNavigateTab(featureName, screenId, screenType, actionLabel, action, detail);
326
366
  return detail;
327
367
  }
328
368
  if (action.screen === undefined) {
329
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" ` +
330
- `sets neither "screen" nor "entity" — exactly one navigate-target form is required.`);
369
+ throw bootRuleError(SCREEN_ACTION_RULES.navigateTargetNeitherScreenNorEntity, {
370
+ message: `[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" ` +
371
+ `sets neither "screen" nor "entity" — exactly one navigate-target form is required.`,
372
+ });
331
373
  }
332
- const candidateQn = qualifyEntityName(featureName, "screen", action.screen);
374
+ const candidateQn = resolveScreenTargetQn(featureName, action.screen);
333
375
  if (!allScreenQns.has(candidateQn) && !navTargetShortIds.has(action.screen)) {
334
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" ` +
335
- `navigate-target "${action.screen}" does not resolve to a registered screen in any feature. Use "<feature>:screen:<id>" of an existing screen.`);
376
+ throw bootRuleError(SCREEN_ACTION_RULES.navigateTargetUnresolved, {
377
+ message: `[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" ` +
378
+ `navigate-target "${action.screen}" does not resolve to a registered screen in any feature. Use "<feature>:screen:<id>" of an existing screen.`,
379
+ });
336
380
  }
337
- const target = screensByShortId.get(action.screen)?.[0];
381
+ const targetIsQn = isValidQn(action.screen);
382
+ const screensWithShortId = screensByShortId.get(targetIsQn ? action.screen.slice(action.screen.lastIndexOf(":") + 1) : action.screen);
383
+ const target = targetIsQn
384
+ ? screensWithShortId?.find((entry) => qualifyEntityName(entry.featureName, "screen", entry.screen.id) === candidateQn)
385
+ : screensWithShortId?.[0];
338
386
  validateRowActionNavigateTab(featureName, screenId, screenType, actionLabel, action, target);
339
387
  return target;
340
388
  }
@@ -352,15 +400,19 @@ propertyPath = "redirect") {
352
400
  const redirectTarget = typeof redirect === "string" ? redirect : redirect.screen;
353
401
  if (typeof redirect !== "string" &&
354
402
  (typeof redirect.idFrom !== "string" || redirect.idFrom.trim() === "")) {
355
- throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (${screenKind}) ${propertyPath}.idFrom is empty or not a string — ` +
356
- `name the success-payload field carrying the navigation id, or use the plain string ` +
357
- `redirect form to navigate with the handler's own "id".`);
403
+ throw bootRuleError(SCREEN_ACTION_RULES.redirectIdFromEmpty, {
404
+ message: `[Feature ${feature.name}] Screen "${screenId}" (${screenKind}) ${propertyPath}.idFrom is empty or not a string — ` +
405
+ `name the success-payload field carrying the navigation id, or use the plain string ` +
406
+ `redirect form to navigate with the handler's own "id".`,
407
+ });
358
408
  }
359
409
  // The renderer reads idFrom verbatim (Object.hasOwn), so stray whitespace
360
410
  // never matches and the navigation silently lands without an entityId.
361
411
  if (typeof redirect !== "string" && redirect.idFrom !== redirect.idFrom.trim()) {
362
- throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (${screenKind}) ${propertyPath}.idFrom "${redirect.idFrom}" ` +
363
- `has leading/trailing whitespace — it would never match a payload field. Remove the whitespace from idFrom.`);
412
+ throw bootRuleError(SCREEN_ACTION_RULES.redirectIdFromWhitespace, {
413
+ message: `[Feature ${feature.name}] Screen "${screenId}" (${screenKind}) ${propertyPath}.idFrom "${redirect.idFrom}" ` +
414
+ `has leading/trailing whitespace — it would never match a payload field. Remove the whitespace from idFrom.`,
415
+ });
364
416
  }
365
417
  validateScreenNavTarget(feature.name, screenId, screenKind, propertyPath, redirectTarget, allScreenQns, feature.screens);
366
418
  // idFrom only means something to a target that carries a record id; the
@@ -371,8 +423,10 @@ propertyPath = "redirect") {
371
423
  sameFeatureTarget !== undefined &&
372
424
  sameFeatureTarget.type !== "entityEdit" &&
373
425
  sameFeatureTarget.type !== "projectionDetail") {
374
- throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (${screenKind}) ${propertyPath}.idFrom is set but target screen ` +
375
- `"${redirectTarget}" (${sameFeatureTarget.type}) carries no id — use the plain string form.`);
426
+ throw bootRuleError(SCREEN_ACTION_RULES.redirectIdFromOnIdlessTarget, {
427
+ message: `[Feature ${feature.name}] Screen "${screenId}" (${screenKind}) ${propertyPath}.idFrom is set but target screen ` +
428
+ `"${redirectTarget}" (${sameFeatureTarget.type}) carries no id — use the plain string form.`,
429
+ });
376
430
  }
377
431
  if (typeof redirect !== "string" && redirect.tab !== undefined) {
378
432
  validateRowActionNavigateTab(feature.name, screenId, screenKind, propertyPath, { kind: "navigate", id: redirectTarget, label: redirectTarget, tab: redirect.tab }, findNavTargetEntry(feature, redirectTarget, lookups));
@@ -391,8 +445,10 @@ export function validateIdlessSuccessLink(feature, screenId, screenKind, link, l
391
445
  const target = findNavTargetEntry(feature, link.screen, lookups);
392
446
  const targetType = target?.screen.type;
393
447
  if (targetType === "entityEdit" || targetType === "projectionDetail") {
394
- throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (${screenKind}) ${propertyPath} targets "${link.screen}" ` +
395
- `(${targetType}), a record screen — set ${propertyPath}.idFrom to the success-payload field carrying the record id.`);
448
+ throw bootRuleError(SCREEN_ACTION_RULES.successLinkTargetsRecordScreen, {
449
+ message: `[Feature ${feature.name}] Screen "${screenId}" (${screenKind}) ${propertyPath} targets "${link.screen}" ` +
450
+ `(${targetType}), a record screen — set ${propertyPath}.idFrom to the success-payload field carrying the record id.`,
451
+ });
396
452
  }
397
453
  if (link.tab !== undefined) {
398
454
  validateRowActionNavigateTab(feature.name, screenId, screenKind, propertyPath, { kind: "navigate", id: link.screen, label: link.screen, tab: link.tab }, target);
@@ -412,9 +468,11 @@ export function validateClientActionName(featureName, screenId, screenKind, acti
412
468
  // skip: well-formed name, nothing to reject
413
469
  if (wellFormed)
414
470
  return;
415
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenKind}) ${actionLabel} "${action.id}" ` +
416
- `action "${action.action}" is not a client action name — expected "<feature>:<kebab-name>", ` +
417
- `e.g. "auth-email-password:request-password-reset".`);
471
+ throw bootRuleError(SCREEN_ACTION_RULES.clientActionName, {
472
+ message: `[Feature ${featureName}] Screen "${screenId}" (${screenKind}) ${actionLabel} "${action.id}" ` +
473
+ `action "${action.action}" is not a client action name — expected "<feature>:<kebab-name>", ` +
474
+ `e.g. "auth-email-password:request-password-reset".`,
475
+ });
418
476
  }
419
477
  // redirect is only honored on record actions; on list/related-list row
420
478
  // actions it would be silently dropped, so the author would believe it works.
@@ -423,9 +481,11 @@ export function rejectRedirectOnListRowAction(featureName, screenId, screenKind,
423
481
  action.kind !== "drawer" &&
424
482
  action.kind !== "clientAction" &&
425
483
  action.redirect !== undefined) {
426
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenKind}) rowAction "${action.id}" sets redirect — ` +
427
- `redirect is only honored on record actions (projectionDetail/entityEdit header and section ` +
428
- `actions) and is ignored on list row actions. Remove it.`);
484
+ throw bootRuleError(SCREEN_ACTION_RULES.redirectOnListRowAction, {
485
+ message: `[Feature ${featureName}] Screen "${screenId}" (${screenKind}) rowAction "${action.id}" sets redirect — ` +
486
+ `redirect is only honored on record actions (projectionDetail/entityEdit header and section ` +
487
+ `actions) and is ignored on list row actions. Remove it.`,
488
+ });
429
489
  }
430
490
  }
431
491
  // A writeHandler record action's redirect (projectionDetail/entityEdit
@@ -452,19 +512,25 @@ export function validatePrimaryActionTarget(featureName, screenId, screen) {
452
512
  for (const [option, id] of targets) {
453
513
  if (declaredIds.includes(id) || (editIsAvailable && id === "edit"))
454
514
  continue;
455
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail) ${option} "${id}" ` +
456
- `matches no action — use one of the declared action ids (${declaredIds.join(", ") || "none declared"})` +
457
- `${editIsAvailable ? ' or "edit"' : ' ("edit" needs detailFor on this screen)'}.`);
515
+ throw bootRuleError(SCREEN_ACTION_RULES.primaryActionUnknown, {
516
+ message: `[Feature ${featureName}] Screen "${screenId}" (projectionDetail) ${option} "${id}" ` +
517
+ `matches no action — use one of the declared action ids (${declaredIds.join(", ") || "none declared"})` +
518
+ `${editIsAvailable ? ' or "edit"' : ' ("edit" needs detailFor on this screen)'}.`,
519
+ });
458
520
  }
459
521
  }
460
522
  export function validateScreenVisibleWhen(feature, screenId, screen, allScreenQns, featureMap) {
461
523
  const { visibleWhen, fallback } = screen;
462
524
  const context = `[Feature ${feature.name}] Screen "${screenId}" (${screen.type})`;
463
525
  if (visibleWhen === undefined && fallback !== undefined) {
464
- throw new Error(`${context} declares fallback without visibleWhen. Add visibleWhen or remove fallback.`);
526
+ throw bootRuleError(SCREEN_ACTION_RULES.fallbackWithoutVisibleWhen, {
527
+ message: `${context} declares fallback without visibleWhen. Add visibleWhen or remove fallback.`,
528
+ });
465
529
  }
466
530
  if (visibleWhen !== undefined && (visibleWhen.query === "" || visibleWhen.field === "")) {
467
- throw new Error(`${context} visibleWhen needs a non-empty query and field. Set both visibleWhen.query and visibleWhen.field.`);
531
+ throw bootRuleError(SCREEN_ACTION_RULES.visibleWhenEmpty, {
532
+ message: `${context} visibleWhen needs a non-empty query and field. Set both visibleWhen.query and visibleWhen.field.`,
533
+ });
468
534
  }
469
535
  if (fallback !== undefined) {
470
536
  validateScreenFallback(feature, screenId, screen.type, fallback, allScreenQns, featureMap);
@@ -473,11 +539,15 @@ export function validateScreenVisibleWhen(feature, screenId, screen, allScreenQn
473
539
  function assertFallbackMapShape(context, fallback) {
474
540
  const reasons = Object.keys(fallback);
475
541
  if (reasons.length === 0) {
476
- throw new Error(`${context} fallback map is empty. Set at least one of ${SCREEN_FALLBACK_REASONS.join(", ")} or use a screen id string.`);
542
+ throw bootRuleError(SCREEN_ACTION_RULES.fallbackMapEmpty, {
543
+ message: `${context} fallback map is empty. Set at least one of ${SCREEN_FALLBACK_REASONS.join(", ")} or use a screen id string.`,
544
+ });
477
545
  }
478
546
  const unknownReason = reasons.find((reason) => !isOneOf(SCREEN_FALLBACK_REASONS, reason));
479
547
  if (unknownReason !== undefined) {
480
- throw new Error(`${context} fallback has unknown reason "${unknownReason}". Use ${SCREEN_FALLBACK_REASONS.join(", ")}.`);
548
+ throw bootRuleError(SCREEN_ACTION_RULES.fallbackUnknownReason, {
549
+ message: `${context} fallback has unknown reason "${unknownReason}". Use ${SCREEN_FALLBACK_REASONS.join(", ")}.`,
550
+ });
481
551
  }
482
552
  }
483
553
  function validateScreenFallback(feature, screenId, screenType, fallback, allScreenQns, featureMap) {
@@ -493,13 +563,17 @@ function validateFallbackTarget(feature, screenId, screenType, fallback, allScre
493
563
  validateScreenNavTarget(feature.name, screenId, screenType, "fallback", fallback, allScreenQns, feature.screens);
494
564
  const fallbackQn = resolveScreenTargetQn(feature.name, fallback);
495
565
  if (fallbackQn === qualifyEntityName(feature.name, "screen", screenId)) {
496
- throw new Error(`${context} fallback points at the screen itself. Point fallback at a different screen.`);
566
+ throw bootRuleError(SCREEN_ACTION_RULES.fallbackSelf, {
567
+ message: `${context} fallback points at the screen itself. Point fallback at a different screen.`,
568
+ });
497
569
  }
498
570
  // A gated fallback could hide in turn and chain or cycle (A→B→A); one hop keeps the
499
571
  // runtime gate trivially terminating.
500
572
  const [fallbackFeatureName = "", , fallbackShortId = ""] = fallbackQn.split(":");
501
573
  if (featureMap.get(fallbackFeatureName)?.screens[fallbackShortId]?.visibleWhen !== undefined) {
502
- throw new Error(`${context} fallback "${fallback}" has its own visibleWhen; a fallback must always render.`);
574
+ throw bootRuleError(SCREEN_ACTION_RULES.fallbackHasVisibleWhen, {
575
+ message: `${context} fallback "${fallback}" has its own visibleWhen; a fallback must always render.`,
576
+ });
503
577
  }
504
578
  }
505
579
  // Only a navigate action that sets `tab` needs the target resolved (to check
@@ -513,8 +587,10 @@ export function validateNavigateActionTab(featureName, screenId, screenType, act
513
587
  }
514
588
  export function assertWriteHandlerRegistered(featureName, subject, handler, allWriteHandlerQns) {
515
589
  if (!allWriteHandlerQns.has(handler)) {
516
- throw new Error(`[Feature ${featureName}] ${subject} handler "${handler}" ` +
517
- `is not a registered write-handler. Check the QN spelling (expected ` +
518
- `"<feature>:write:<short>") and that the handler is declared via r.writeHandler(...).`);
590
+ throw bootRuleError(SCREEN_ACTION_RULES.writeHandlerUnregistered, {
591
+ message: `[Feature ${featureName}] ${subject} handler "${handler}" ` +
592
+ `is not a registered write-handler. Check the QN spelling (expected ` +
593
+ `"<feature>:write:<short>") and that the handler is declared via r.writeHandler(...).`,
594
+ });
519
595
  }
520
596
  }
@@ -0,0 +1,87 @@
1
+ export declare const DASHBOARD_CHART_RULES: {
2
+ readonly chartFromTodayUnreachable: {
3
+ readonly id: "dashboard/chart-from-today-unreachable";
4
+ readonly summary: 'A chart with initialWindow "from-today" has ranges or brush.';
5
+ readonly fix: "Add ranges or brush, or change initialWindow.";
6
+ };
7
+ readonly chartFlagNonBoolean: {
8
+ readonly id: "dashboard/chart-flag-non-boolean";
9
+ readonly summary: "Chart flags (scrollable, brush, legendTotals, markerLabels) are booleans.";
10
+ readonly fix: "Use true or false.";
11
+ };
12
+ readonly chartStackedAreaOnly: {
13
+ readonly id: "dashboard/chart-stacked-area-only";
14
+ readonly summary: 'Stacked-area chart props are only set on a "stacked-area" chart.';
15
+ readonly fix: 'Remove the props or use chart "stacked-area".';
16
+ };
17
+ readonly chartUnitTimeseriesOnly: {
18
+ readonly id: "dashboard/chart-unit-timeseries-only";
19
+ readonly summary: 'A chart unit is only set on a "timeseries" chart.';
20
+ readonly fix: 'Remove unit or use chart "timeseries".';
21
+ };
22
+ readonly chartColorInvalid: {
23
+ readonly id: "dashboard/chart-color-invalid";
24
+ readonly summary: "Chart series and marker colors are non-empty CSS colors.";
25
+ readonly fix: "Set a non-empty CSS color.";
26
+ };
27
+ readonly chartEnumPropInvalid: {
28
+ readonly id: "dashboard/chart-enum-prop-invalid";
29
+ readonly summary: "Stacked-area dateFormat, initialWindow and markerLegend use an allowed value.";
30
+ readonly fix: "Set the prop to one of the allowed values.";
31
+ };
32
+ readonly chartMarkerLookMissing: {
33
+ readonly id: "dashboard/chart-marker-look-missing";
34
+ readonly summary: "A chart marker kind sets a tone or a color.";
35
+ readonly fix: "Set tone or color.";
36
+ };
37
+ readonly chartMarkerToneInvalid: {
38
+ readonly id: "dashboard/chart-marker-tone-invalid";
39
+ readonly summary: "A chart marker tone is a known dashboard tone.";
40
+ readonly fix: "Use positive, negative, active or neutral.";
41
+ };
42
+ readonly chartMarkerLabelInvalid: {
43
+ readonly id: "dashboard/chart-marker-label-invalid";
44
+ readonly summary: "A chart marker label is a non-empty i18n key.";
45
+ readonly fix: "Set a non-empty i18n key or remove label.";
46
+ };
47
+ readonly chartRangesOptionsEmpty: {
48
+ readonly id: "dashboard/chart-ranges-options-empty";
49
+ readonly summary: "Chart ranges declare at least one option.";
50
+ readonly fix: "Add an option to ranges.options.";
51
+ };
52
+ readonly chartRangesOptionIncomplete: {
53
+ readonly id: "dashboard/chart-ranges-option-incomplete";
54
+ readonly summary: "Every chart range option has a non-empty value and label.";
55
+ readonly fix: "Give every option a value and a label.";
56
+ };
57
+ readonly chartRangesOptionDuplicate: {
58
+ readonly id: "dashboard/chart-ranges-option-duplicate";
59
+ readonly summary: "Chart range option values are unique.";
60
+ readonly fix: "Use each option value once.";
61
+ };
62
+ readonly chartRangesMonthsInvalid: {
63
+ readonly id: "dashboard/chart-ranges-months-invalid";
64
+ readonly summary: "A chart range option's months is a positive integer.";
65
+ readonly fix: "Set months to a positive integer or remove it.";
66
+ };
67
+ readonly chartRangesDefaultUnknown: {
68
+ readonly id: "dashboard/chart-ranges-default-unknown";
69
+ readonly summary: "ranges.default is one of the option values.";
70
+ readonly fix: "Set default to one of the options.";
71
+ };
72
+ readonly valueFormatKind: {
73
+ readonly id: "dashboard/value-format-kind";
74
+ readonly summary: "A valueFormat kind is allowed for the panel type.";
75
+ readonly fix: "Use an allowed kind for this panel type.";
76
+ };
77
+ readonly valueFormatCurrency: {
78
+ readonly id: "dashboard/value-format-currency";
79
+ readonly summary: "A currency valueFormat uses a 3-letter uppercase ISO currency code.";
80
+ readonly fix: 'Set currency to an ISO 4217 code such as "EUR".';
81
+ };
82
+ readonly valueFormatFractionDigits: {
83
+ readonly id: "dashboard/value-format-fraction-digits";
84
+ readonly summary: "valueFormat.fractionDigits is an integer from 0 to the maximum.";
85
+ readonly fix: "Set fractionDigits to an integer within range.";
86
+ };
87
+ };