@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,21 +1,29 @@
1
1
  import { NO_WIDGET_FIELD_TYPES, optionsQueryFieldRefs } from "@cosmicdrift/kumiko-types/fields";
2
2
  import { isKebabSegment } from "../qualified-name.js";
3
3
  import { isExtensionEditSection, isWriteFormEditSection, normalizeEditField, sectionFieldSpecs, } from "../screen-helpers.js";
4
+ import { bootRuleError } from "./boot-rule.js";
4
5
  import { validateFormDerivations, validateFormDerivationsEnforced } from "./form-derivations.js";
5
6
  import { assertWriteHandlerRegistered, isSensitiveOrPasswordField, validateIdlessSuccessLink, validateRedirectTarget, validateScreenNavTarget, } from "./screens-actions.js";
7
+ import { SCREEN_ACTION_RULES } from "./screens-actions-rules.js";
8
+ import { FORM_LAYOUT_RULES } from "./screens-forms-layout-rules.js";
9
+ import { FORM_FIELD_RULES } from "./screens-forms-rules.js";
6
10
  function assertKnownSubFields(where, option, cells, schema) {
7
11
  for (const cell of cells ?? []) {
8
12
  if (schema[cell] === undefined) {
9
- throw new Error(`${where} embeddedList.${option} names "${cell}", which is not a sub-field ` +
10
- `(known: ${Object.keys(schema).sort().join(", ")}).`);
13
+ throw bootRuleError(FORM_FIELD_RULES.embeddedListUnknownSubField, {
14
+ message: `${where} embeddedList.${option} names "${cell}", which is not a sub-field ` +
15
+ `(known: ${Object.keys(schema).sort().join(", ")}).`,
16
+ });
11
17
  }
12
18
  }
13
19
  }
14
20
  function assertCardHiddenCellsReadOnly(where, cardHiddenCells, readOnlyCells) {
15
21
  for (const cell of cardHiddenCells ?? []) {
16
22
  if (readOnlyCells?.includes(cell) !== true) {
17
- throw new Error(`${where} embeddedList.cardHiddenCells names "${cell}", which is editable; ` +
18
- `only read-only cells (readOnlyCells) can be hidden on cards, otherwise phone users cannot fill it.`);
23
+ throw bootRuleError(FORM_FIELD_RULES.embeddedListCardHiddenEditable, {
24
+ message: `${where} embeddedList.cardHiddenCells names "${cell}", which is editable; ` +
25
+ `only read-only cells (readOnlyCells) can be hidden on cards, otherwise phone users cannot fill it.`,
26
+ });
19
27
  }
20
28
  }
21
29
  }
@@ -36,8 +44,10 @@ export function validateEditFieldExtras(featureName, screenId, entityDef, fieldS
36
44
  const listSpec = fieldSpec.embeddedList;
37
45
  if (listSpec !== undefined) {
38
46
  if (fieldDef.type !== "embedded" || fieldDef.multiple !== true) {
39
- throw new Error(`${where} sets embeddedList, which only applies to an embedded list ` +
40
- `(createEmbeddedListField); the field is type "${fieldDef.type}". Remove embeddedList or point it at an embedded list field.`);
47
+ throw bootRuleError(FORM_FIELD_RULES.embeddedListOnNonListField, {
48
+ message: `${where} sets embeddedList, which only applies to an embedded list ` +
49
+ `(createEmbeddedListField); the field is type "${fieldDef.type}". Remove embeddedList or point it at an embedded list field.`,
50
+ });
41
51
  }
42
52
  assertKnownSubFields(where, "readOnlyCells", listSpec.readOnlyCells, fieldDef.schema);
43
53
  assertKnownSubFields(where, "cardHiddenCells", listSpec.cardHiddenCells, fieldDef.schema);
@@ -49,15 +59,19 @@ export function validateEditFieldExtras(featureName, screenId, entityDef, fieldS
49
59
  return;
50
60
  if (prefill.kind === "today") {
51
61
  if (fieldDef.type !== "date") {
52
- throw new Error(`${where} prefill "today" needs a date field; the field is type "${fieldDef.type}". Use a date field or a different prefill.`);
62
+ throw bootRuleError(FORM_FIELD_RULES.prefillTodayNeedsDate, {
63
+ message: `${where} prefill "today" needs a date field; the field is type "${fieldDef.type}". Use a date field or a different prefill.`,
64
+ });
53
65
  }
54
66
  // skip: today carries no property, nothing further to check
55
67
  return;
56
68
  }
57
69
  const allowsUserId = fieldDef.type === "text" || fieldDef.type === "reference";
58
70
  if (prefill.property === "id" ? !allowsUserId : fieldDef.type !== "text") {
59
- throw new Error(`${where} prefill currentUser.${prefill.property} does not fit a field of type ` +
60
- `"${fieldDef.type}" (displayName and email need text; id needs text or a reference). Use a fitting field type or a different prefill property.`);
71
+ throw bootRuleError(FORM_FIELD_RULES.prefillCurrentUserFieldType, {
72
+ message: `${where} prefill currentUser.${prefill.property} does not fit a field of type ` +
73
+ `"${fieldDef.type}" (displayName and email need text; id needs text or a reference). Use a fitting field type or a different prefill property.`,
74
+ });
61
75
  }
62
76
  }
63
77
  // `{ field }` affixes and fillAction params read live form values, so every
@@ -72,7 +86,9 @@ export function validateFieldFormRefs(where, fieldSpec, formFieldNames) {
72
86
  if (affix === undefined || typeof affix === "string")
73
87
  continue;
74
88
  if (!formFieldNames.has(affix.field)) {
75
- throw new Error(`${where} ${prop} references unknown field "${affix.field}" — it must be another field of the same form.`);
89
+ throw bootRuleError(FORM_FIELD_RULES.affixUnknownField, {
90
+ message: `${where} ${prop} references unknown field "${affix.field}" — it must be another field of the same form.`,
91
+ });
76
92
  }
77
93
  }
78
94
  const params = fieldSpec.fillAction?.params;
@@ -82,7 +98,9 @@ export function validateFieldFormRefs(where, fieldSpec, formFieldNames) {
82
98
  const sourceFields = "pick" in params ? params.pick : Object.values(params.map);
83
99
  for (const sourceField of sourceFields) {
84
100
  if (!formFieldNames.has(sourceField)) {
85
- throw new Error(`${where} fillAction.params reads unknown field "${sourceField}" — it must be a field of the same form.`);
101
+ throw bootRuleError(FORM_FIELD_RULES.fillActionUnknownField, {
102
+ message: `${where} fillAction.params reads unknown field "${sourceField}" — it must be a field of the same form.`,
103
+ });
86
104
  }
87
105
  }
88
106
  }
@@ -94,12 +112,16 @@ export function validateFillActionTarget(where, fieldSpec, fieldDef) {
94
112
  if (fieldSpec.fillAction === undefined || fieldDef === undefined)
95
113
  return;
96
114
  if (!FILL_ACTION_FIELD_TYPES.includes(fieldDef.type)) {
97
- throw new Error(`${where} fillAction needs a ${FILL_ACTION_FIELD_TYPES.join(", ")} field, not "${fieldDef.type}". ` +
98
- `Remove fillAction or use a fitting field type.`);
115
+ throw bootRuleError(FORM_FIELD_RULES.fillActionFieldType, {
116
+ message: `${where} fillAction needs a ${FILL_ACTION_FIELD_TYPES.join(", ")} field, not "${fieldDef.type}". ` +
117
+ `Remove fillAction or use a fitting field type.`,
118
+ });
99
119
  }
100
120
  if (isSensitiveOrPasswordField(fieldDef)) {
101
- throw new Error(`${where} fillAction targets a sensitive, writeOnly or password field — a query result is ` +
102
- `never written into those. Remove fillAction.`);
121
+ throw bootRuleError(FORM_FIELD_RULES.fillActionSensitiveField, {
122
+ message: `${where} fillAction targets a sensitive, writeOnly or password field — a query result is ` +
123
+ `never written into those. Remove fillAction.`,
124
+ });
103
125
  }
104
126
  }
105
127
  export function validateNoWidgetRequiredField(featureName, screenId, entityDef, fieldSpec) {
@@ -121,36 +143,48 @@ export function validateNoWidgetRequiredField(featureName, screenId, entityDef,
121
143
  // skip: not required — a read-only widget-less field is fine to leave empty.
122
144
  if (!isStaticallyRequired)
123
145
  return;
124
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (entityEdit) field "${fieldSpec.field}" is ` +
125
- `type "${fieldDef.type}", which renders read-only on the auto-wired entityEdit path — a ` +
126
- `required field the user could never fill would block every save. Set required: false, ` +
127
- `move the field to a custom-component section, or drop the required constraint.`);
146
+ throw bootRuleError(FORM_FIELD_RULES.requiredFieldWithoutWidget, {
147
+ message: `[Feature ${featureName}] Screen "${screenId}" (entityEdit) field "${fieldSpec.field}" is ` +
148
+ `type "${fieldDef.type}", which renders read-only on the auto-wired entityEdit path — a ` +
149
+ `required field the user could never fill would block every save. Set required: false, ` +
150
+ `move the field to a custom-component section, or drop the required constraint.`,
151
+ });
128
152
  }
129
153
  // Shared by projectionDetail and entityEdit: a tab strip needs something to
130
154
  // label each tab with and a stable id per tab — the id anchors the ?tab=
131
155
  // param on projectionDetail and the jump-to-erroring-tab logic on entityEdit.
132
156
  export function validateTabSections(featureName, screenId, screenType, sections) {
133
157
  if (sections.length < 2) {
134
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) has mode: "tabs" but only ` +
135
- `${sections.length} section(s) — tabs need at least 2 sections.`);
158
+ throw bootRuleError(FORM_LAYOUT_RULES.tabsTooFewSections, {
159
+ message: `[Feature ${featureName}] Screen "${screenId}" (${screenType}) has mode: "tabs" but only ` +
160
+ `${sections.length} section(s) — tabs need at least 2 sections.`,
161
+ });
136
162
  }
137
163
  const tabIds = new Set();
138
164
  sections.forEach((section, index) => {
139
165
  if (section.title === undefined || section.title.trim().length === 0) {
140
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) has mode: "tabs" but ` +
141
- `sections[${index}] has no title — every tab needs a title.`);
166
+ throw bootRuleError(FORM_LAYOUT_RULES.tabTitleMissing, {
167
+ message: `[Feature ${featureName}] Screen "${screenId}" (${screenType}) has mode: "tabs" but ` +
168
+ `sections[${index}] has no title — every tab needs a title.`,
169
+ });
142
170
  }
143
171
  if (section.id === undefined || section.id.trim().length === 0) {
144
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) has mode: "tabs" but ` +
145
- `sections[${index}] ("${section.title}") has no id — every tab needs a stable id.`);
172
+ throw bootRuleError(FORM_LAYOUT_RULES.tabIdMissing, {
173
+ message: `[Feature ${featureName}] Screen "${screenId}" (${screenType}) has mode: "tabs" but ` +
174
+ `sections[${index}] ("${section.title}") has no id — every tab needs a stable id.`,
175
+ });
146
176
  }
147
177
  if (!isKebabSegment(section.id)) {
148
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) sections[${index}] ` +
149
- `("${section.title}") has id "${section.id}" — must be kebab-case.`);
178
+ throw bootRuleError(FORM_LAYOUT_RULES.tabIdNotKebab, {
179
+ message: `[Feature ${featureName}] Screen "${screenId}" (${screenType}) sections[${index}] ` +
180
+ `("${section.title}") has id "${section.id}" — must be kebab-case.`,
181
+ });
150
182
  }
151
183
  if (tabIds.has(section.id)) {
152
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) has duplicate tab id ` +
153
- `"${section.id}" (sections[${index}]). Give each tab section a unique id.`);
184
+ throw bootRuleError(FORM_LAYOUT_RULES.tabIdDuplicate, {
185
+ message: `[Feature ${featureName}] Screen "${screenId}" (${screenType}) has duplicate tab id ` +
186
+ `"${section.id}" (sections[${index}]). Give each tab section a unique id.`,
187
+ });
154
188
  }
155
189
  tabIds.add(section.id);
156
190
  });
@@ -166,8 +200,10 @@ export function validateWizardLayout(featureName, screenId, screenType, layout,
166
200
  // required field on a hidden tab would still block their submit silently.
167
201
  if (layout.mode === "tabs") {
168
202
  if (screenType !== "entityEdit") {
169
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) sets mode: "tabs" — tabs are only ` +
170
- `supported on projectionDetail and entityEdit. Use mode: "wizard" or "single" instead.`);
203
+ throw bootRuleError(FORM_LAYOUT_RULES.tabsUnsupportedScreenType, {
204
+ message: `[Feature ${featureName}] Screen "${screenId}" (${screenType}) sets mode: "tabs" — tabs are only ` +
205
+ `supported on projectionDetail and entityEdit. Use mode: "wizard" or "single" instead.`,
206
+ });
171
207
  }
172
208
  validateTabSections(featureName, screenId, screenType, layout.sections);
173
209
  }
@@ -176,28 +212,36 @@ export function validateWizardLayout(featureName, screenId, screenType, layout,
176
212
  // "user-data-rights" check in gdpr-storage.ts.
177
213
  if (layout.draft === true) {
178
214
  if (layout.mode !== "wizard") {
179
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) sets draft: true but ` +
180
- `mode is not "wizard" — draft persistence only applies to wizard layouts. Remove ` +
181
- `draft: true or set mode: "wizard".`);
215
+ throw bootRuleError(FORM_LAYOUT_RULES.draftWithoutWizard, {
216
+ message: `[Feature ${featureName}] Screen "${screenId}" (${screenType}) sets draft: true but ` +
217
+ `mode is not "wizard" — draft persistence only applies to wizard layouts. Remove ` +
218
+ `draft: true or set mode: "wizard".`,
219
+ });
182
220
  }
183
221
  if (!featureMap.has("form-draft")) {
184
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) sets draft: true but the ` +
185
- `bundled feature "form-draft" is not mounted — every resume would silently lose its ` +
186
- `values. Add createFormDraftFeature() from @cosmicdrift/kumiko-bundled-features to the app's ` +
187
- `feature list.`);
222
+ throw bootRuleError(FORM_LAYOUT_RULES.draftFeatureMissing, {
223
+ message: `[Feature ${featureName}] Screen "${screenId}" (${screenType}) sets draft: true but the ` +
224
+ `bundled feature "form-draft" is not mounted — every resume would silently lose its ` +
225
+ `values. Add createFormDraftFeature() from @cosmicdrift/kumiko-bundled-features to the app's ` +
226
+ `feature list.`,
227
+ });
188
228
  }
189
229
  }
190
230
  // skip: mode omitted/"single" — no wizard constraints apply.
191
231
  if (layout.mode !== "wizard")
192
232
  return;
193
233
  if (layout.sections.length < 2) {
194
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) has mode: "wizard" but only ` +
195
- `${layout.sections.length} section(s) — a wizard needs at least 2 sections (one per step).`);
234
+ throw bootRuleError(FORM_LAYOUT_RULES.wizardTooFewSections, {
235
+ message: `[Feature ${featureName}] Screen "${screenId}" (${screenType}) has mode: "wizard" but only ` +
236
+ `${layout.sections.length} section(s) — a wizard needs at least 2 sections (one per step).`,
237
+ });
196
238
  }
197
239
  layout.sections.forEach((section, index) => {
198
240
  if (section.title === undefined || section.title.trim().length === 0) {
199
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) has mode: "wizard" but ` +
200
- `sections[${index}] has no title — every wizard step needs a title.`);
241
+ throw bootRuleError(FORM_LAYOUT_RULES.wizardStepTitleMissing, {
242
+ message: `[Feature ${featureName}] Screen "${screenId}" (${screenType}) has mode: "wizard" but ` +
243
+ `sections[${index}] has no title — every wizard step needs a title.`,
244
+ });
201
245
  }
202
246
  });
203
247
  }
@@ -219,7 +263,9 @@ export function validateWizardLayout(featureName, screenId, screenType, layout,
219
263
  // same registration requirement.
220
264
  function validateWriteHandlerRegistered(featureName, screenId, context, handler, allWriteHandlerQns) {
221
265
  if (!handler || typeof handler !== "string") {
222
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${context}) has empty or non-string handler. Set handler to a non-empty handler name.`);
266
+ throw bootRuleError(FORM_FIELD_RULES.handlerEmpty, {
267
+ message: `[Feature ${featureName}] Screen "${screenId}" (${context}) has empty or non-string handler. Set handler to a non-empty handler name.`,
268
+ });
223
269
  }
224
270
  assertWriteHandlerRegistered(featureName, `Screen "${screenId}" (${context})`, handler, allWriteHandlerQns);
225
271
  }
@@ -240,15 +286,19 @@ function validateWriteHandlerRegistered(featureName, screenId, context, handler,
240
286
  function validateFormFieldsMap(featureName, screenId, context, fields, allowEmpty) {
241
287
  const fieldNames = new Set(Object.keys(fields));
242
288
  if (fieldNames.size === 0 && !allowEmpty) {
243
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${context}) has empty fields map — ` +
244
- `declare at least one field.`);
289
+ throw bootRuleError(FORM_FIELD_RULES.fieldsEmpty, {
290
+ message: `[Feature ${featureName}] Screen "${screenId}" (${context}) has empty fields map — ` +
291
+ `declare at least one field.`,
292
+ });
245
293
  }
246
294
  for (const [fname, fdef] of Object.entries(fields)) {
247
295
  // @cast-boundary schema-walk — feature-config inspection (Author may circumvent type-check)
248
296
  const ftype = fdef.type;
249
297
  if (typeof ftype !== "string" || ftype.length === 0) {
250
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${context}) field "${fname}" has no ` +
251
- `\`type\` set. Each field must declare a type (e.g. "text", "number", "select").`);
298
+ throw bootRuleError(FORM_FIELD_RULES.fieldTypeMissing, {
299
+ message: `[Feature ${featureName}] Screen "${screenId}" (${context}) field "${fname}" has no ` +
300
+ `\`type\` set. Each field must declare a type (e.g. "text", "number", "select").`,
301
+ });
252
302
  }
253
303
  if (ftype === "money") {
254
304
  validateFormMoneyCurrency(featureName, screenId, context, fname, fdef);
@@ -261,10 +311,14 @@ function validateFormFieldsMap(featureName, screenId, context, fields, allowEmpt
261
311
  function validateOptionsQueryFieldRefs(where, fieldName, payload, siblingFieldNames) {
262
312
  for (const ref of optionsQueryFieldRefs(payload)) {
263
313
  if (ref === fieldName) {
264
- throw new Error(`${where} optionsQueryPayload references itself ({ field: "${ref}" }). Reference a different field of the form.`);
314
+ throw bootRuleError(FORM_FIELD_RULES.optionsQueryPayloadSelfReference, {
315
+ message: `${where} optionsQueryPayload references itself ({ field: "${ref}" }). Reference a different field of the form.`,
316
+ });
265
317
  }
266
318
  if (!siblingFieldNames.has(ref)) {
267
- throw new Error(`${where} optionsQueryPayload references unknown field "${ref}" — it must be another field of the same form`);
319
+ throw bootRuleError(FORM_FIELD_RULES.optionsQueryPayloadUnknownField, {
320
+ message: `${where} optionsQueryPayload references unknown field "${ref}" — it must be another field of the same form`,
321
+ });
268
322
  }
269
323
  }
270
324
  }
@@ -272,31 +326,42 @@ export function isWriteOnlyField(fdef) {
272
326
  return fdef?.writeOnly === true; // @cast-boundary schema-walk
273
327
  }
274
328
  // A secret on a configEdit form keeps its value out of the client like an encrypted
275
- // config key does, and the secrets store only exists per tenant.
329
+ // config key does. The secrets store only exists per tenant and, for scope "system", platform-wide
330
+ // under the system tenant.
276
331
  export function validateConfigEditSecretField(featureName, screen, fieldName, secretQn, featureMap) {
277
332
  const where = `[Feature ${featureName}] Screen "${screen.id}" (configEdit) field "${fieldName}"`;
278
333
  if (screen.configKeys[fieldName] !== undefined) {
279
- throw new Error(`${where} is mapped in both configKeys and secretKeys — keep one.`);
334
+ throw bootRuleError(FORM_FIELD_RULES.configSecretAlsoConfigKey, {
335
+ message: `${where} is mapped in both configKeys and secretKeys — keep one.`,
336
+ });
280
337
  }
281
- if (screen.scope !== "tenant") {
282
- throw new Error(`${where} maps secret "${secretQn}" on a ${screen.scope}-scope screen — secrets are tenant-scoped.`);
338
+ if (screen.scope === "user") {
339
+ throw bootRuleError(FORM_FIELD_RULES.configSecretScope, {
340
+ message: `${where} maps secret "${secretQn}" on a user-scope screen — secrets exist per tenant or platform-wide (scope "system"), not per user.`,
341
+ });
283
342
  }
284
343
  const fdef = screen.fields[fieldName];
285
344
  if (fdef?.type !== "text" || !isWriteOnlyField(fdef)) {
286
- throw new Error(`${where} maps secret "${secretQn}" but is no writeOnly text field — a stored secret never goes back to the client.`);
345
+ throw bootRuleError(FORM_FIELD_RULES.configSecretFieldType, {
346
+ message: `${where} maps secret "${secretQn}" but is no writeOnly text field — a stored secret never goes back to the client.`,
347
+ });
287
348
  }
288
349
  const declared = [...featureMap.values()].some((feature) => Object.values(feature.secretKeys ?? {}).some((def) => def.qualifiedName === secretQn));
289
350
  if (!declared) {
290
- throw new Error(`${where} → secret "${secretQn}" is not declared via r.secret() in any feature.`);
351
+ throw bootRuleError(FORM_FIELD_RULES.configSecretUndeclared, {
352
+ message: `${where} → secret "${secretQn}" is not declared via r.secret() in any feature.`,
353
+ });
291
354
  }
292
355
  }
293
356
  // Inline forms have no stored value to hide or keep: writeOnly there would
294
357
  // render a "set / keep" affordance with nothing behind it.
295
358
  export function rejectWriteOnlyFormField(featureName, screenId, context, fieldName, fdef) {
296
359
  if (isWriteOnlyField(fdef)) {
297
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${context}) field "${fieldName}" declares writeOnly — ` +
298
- `writeOnly only applies to entity fields (nothing to hide on a form that stores no value). ` +
299
- `Use format: "password" for a masked input.`);
360
+ throw bootRuleError(FORM_FIELD_RULES.writeOnlyField, {
361
+ message: `[Feature ${featureName}] Screen "${screenId}" (${context}) field "${fieldName}" declares writeOnly — ` +
362
+ `writeOnly only applies to entity fields (nothing to hide on a form that stores no value). ` +
363
+ `Use format: "password" for a masked input.`,
364
+ });
300
365
  }
301
366
  }
302
367
  // Static options XOR optionsQuery on inline-form select fields, and `{ field }`
@@ -308,33 +373,47 @@ export function validateFormSelectOptions(featureName, screenId, context, fieldN
308
373
  if (fdef.type === "select") {
309
374
  const where = `[Feature ${featureName}] Screen "${screenId}" (${context}) select field "${fieldName}"`;
310
375
  if (fdef.conditionalOptions !== undefined) {
311
- throw new Error(`${where} declares conditionalOptions — ${CONDITIONAL_OPTIONS_ENTITY_ONLY}. Remove conditionalOptions from this field.`);
376
+ throw bootRuleError(FORM_FIELD_RULES.selectConditionalOptions, {
377
+ message: `${where} declares conditionalOptions — ${CONDITIONAL_OPTIONS_ENTITY_ONLY}. Remove conditionalOptions from this field.`,
378
+ });
312
379
  }
313
380
  if (fdef.optionsQuery !== undefined) {
314
381
  if (fdef.optionsQuery.length === 0) {
315
- throw new Error(`${where} has an empty optionsQuery. Set it to a query name or remove it.`);
382
+ throw bootRuleError(FORM_FIELD_RULES.selectOptionsQueryEmpty, {
383
+ message: `${where} has an empty optionsQuery. Set it to a query name or remove it.`,
384
+ });
316
385
  }
317
386
  if (fdef.options.length > 0) {
318
- throw new Error(`${where} declares both options and optionsQuery — pick one`);
387
+ throw bootRuleError(FORM_FIELD_RULES.selectOptionsAndQuery, {
388
+ message: `${where} declares both options and optionsQuery — pick one`,
389
+ });
319
390
  }
320
391
  if (fdef.optionsAvailabilityQuery !== undefined) {
321
- throw new Error(`${where} declares both optionsQuery and optionsAvailabilityQuery — availability only applies to static options`);
392
+ throw bootRuleError(FORM_FIELD_RULES.selectQueryAndAvailability, {
393
+ message: `${where} declares both optionsQuery and optionsAvailabilityQuery — availability only applies to static options`,
394
+ });
322
395
  }
323
396
  validateOptionsQueryFieldRefs(where, fieldName, fdef.optionsQueryPayload, siblingFieldNames);
324
397
  }
325
398
  else if (fdef.optionsAvailabilityQuery !== undefined) {
326
399
  if (fdef.optionsAvailabilityQuery.length === 0) {
327
- throw new Error(`${where} has an empty optionsAvailabilityQuery. Set it to a query name or remove it.`);
400
+ throw bootRuleError(FORM_FIELD_RULES.optionsAvailabilityQueryEmpty, {
401
+ message: `${where} has an empty optionsAvailabilityQuery. Set it to a query name or remove it.`,
402
+ });
328
403
  }
329
404
  validateOptionsQueryFieldRefs(where, fieldName, fdef.optionsQueryPayload, siblingFieldNames);
330
405
  }
331
406
  else if (fdef.optionsQueryPayload !== undefined) {
332
- throw new Error(`${where} has optionsQueryPayload without optionsQuery. Set optionsQuery or remove optionsQueryPayload.`);
407
+ throw bootRuleError(FORM_FIELD_RULES.optionsQueryPayloadWithoutQuery, {
408
+ message: `${where} has optionsQueryPayload without optionsQuery. Set optionsQuery or remove optionsQueryPayload.`,
409
+ });
333
410
  }
334
411
  }
335
412
  else if (fdef.type === "multiSelect" && fdef.optionsAvailabilityQuery !== undefined) {
336
413
  if (fdef.optionsAvailabilityQuery.length === 0) {
337
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${context}) multiSelect field "${fieldName}" has an empty optionsAvailabilityQuery. Set it to a query name or remove it.`);
414
+ throw bootRuleError(FORM_FIELD_RULES.optionsAvailabilityQueryEmpty, {
415
+ message: `[Feature ${featureName}] Screen "${screenId}" (${context}) multiSelect field "${fieldName}" has an empty optionsAvailabilityQuery. Set it to a query name or remove it.`,
416
+ });
338
417
  }
339
418
  }
340
419
  }
@@ -352,23 +431,31 @@ function validateFormMoneyCurrency(featureName, screenId, context, fieldName, fd
352
431
  // @cast-boundary schema-walk — feature-config inspection (Author may circumvent type-check)
353
432
  const currency = fdef.currency;
354
433
  if (currency === undefined) {
355
- throw new Error(`${where} must declare where its currency comes from — this screen has no entity whose ` +
356
- `\`defaultCurrency\` it could inherit, so the form would seed a bare \`0\` that the ` +
357
- `handler's schema rejects. ${validForms}`);
434
+ throw bootRuleError(FORM_FIELD_RULES.moneyCurrencyMissing, {
435
+ message: `${where} must declare where its currency comes from — this screen has no entity whose ` +
436
+ `\`defaultCurrency\` it could inherit, so the form would seed a bare \`0\` that the ` +
437
+ `handler's schema rejects. ${validForms}`,
438
+ });
358
439
  }
359
440
  if (typeof currency !== "object" || currency === null) {
360
- throw new Error(`${where} has a non-object \`currency\`. ${validForms}`);
441
+ throw bootRuleError(FORM_FIELD_RULES.moneyCurrencyNotObject, {
442
+ message: `${where} has a non-object \`currency\`. ${validForms}`,
443
+ });
361
444
  }
362
445
  const kind = currency.kind;
363
446
  if (kind === "literal") {
364
447
  const code = currency.code;
365
448
  if (typeof code !== "string" || code.trim() === "") {
366
- throw new Error(`${where} declares \`currency: { kind: "literal" }\` with an empty or non-string \`code\`. ` +
367
- `Pass the ISO code, e.g. { kind: "literal", code: "EUR" }.`);
449
+ throw bootRuleError(FORM_FIELD_RULES.moneyCurrencyLiteralCode, {
450
+ message: `${where} declares \`currency: { kind: "literal" }\` with an empty or non-string \`code\`. ` +
451
+ `Pass the ISO code, e.g. { kind: "literal", code: "EUR" }.`,
452
+ });
368
453
  }
369
454
  }
370
455
  else if (kind !== "tenant") {
371
- throw new Error(`${where} declares an unknown currency kind ${JSON.stringify(kind)}. ${validForms}`);
456
+ throw bootRuleError(FORM_FIELD_RULES.moneyCurrencyUnknownKind, {
457
+ message: `${where} declares an unknown currency kind ${JSON.stringify(kind)}. ${validForms}`,
458
+ });
372
459
  }
373
460
  }
374
461
  // `allowEmptySections` mirrors `validateFormFieldsMap`'s `allowEmpty` — the
@@ -380,12 +467,16 @@ function validateFormMoneyCurrency(featureName, screenId, context, fieldName, fd
380
467
  // every EditLayout-walking screen type instead of four hand-rolled copies.
381
468
  export function validateFieldsXorGroups(errorPrefix, section) {
382
469
  if (section.fields !== undefined && section.groups !== undefined) {
383
- throw new Error(`${errorPrefix} section "${section.title}" declares both fields and groups — remove ` +
384
- `\`fields: []\` when using groups.`);
470
+ throw bootRuleError(FORM_LAYOUT_RULES.sectionFieldsAndGroups, {
471
+ message: `${errorPrefix} section "${section.title}" declares both fields and groups — remove ` +
472
+ `\`fields: []\` when using groups.`,
473
+ });
385
474
  }
386
475
  if ((section.fields?.length ?? 0) === 0 && (section.groups?.length ?? 0) === 0) {
387
- throw new Error(`${errorPrefix} has a section "${section.title}" with zero fields — drop the section or add ` +
388
- `fields (or groups) to it.`);
476
+ throw bootRuleError(FORM_LAYOUT_RULES.sectionEmpty, {
477
+ message: `${errorPrefix} has a section "${section.title}" with zero fields — drop the section or add ` +
478
+ `fields (or groups) to it.`,
479
+ });
389
480
  }
390
481
  }
391
482
  function validateFormLayoutSections(featureName, screenId, context, layout, fieldNames, fieldDefs, allowEmptySections) {
@@ -393,32 +484,42 @@ function validateFormLayoutSections(featureName, screenId, context, layout, fiel
393
484
  // skip: an input-less secretMint declares fields: {} and sections: [] together — no sections to validate.
394
485
  if (allowEmptySections)
395
486
  return;
396
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${context}) has an empty sections list — ` +
397
- `declare at least one section.`);
487
+ throw bootRuleError(FORM_LAYOUT_RULES.sectionsEmpty, {
488
+ message: `[Feature ${featureName}] Screen "${screenId}" (${context}) has an empty sections list — ` +
489
+ `declare at least one section.`,
490
+ });
398
491
  }
399
492
  for (const section of layout.sections) {
400
493
  if (isExtensionEditSection(section)) {
401
494
  if (section.component?.react === undefined && section.component?.native === undefined) {
402
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${context}) extension section ` +
403
- `"${section.title}" has no component — declare a react/native component marker.`);
495
+ throw bootRuleError(FORM_LAYOUT_RULES.extensionSectionNoComponent, {
496
+ message: `[Feature ${featureName}] Screen "${screenId}" (${context}) extension section ` +
497
+ `"${section.title}" has no component — declare a react/native component marker.`,
498
+ });
404
499
  }
405
500
  continue;
406
501
  }
407
502
  if (section.kind === "relatedList") {
408
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${context}) relatedList section ` +
409
- `"${section.title}" is not supported — relatedList is a projectionDetail-only ` +
410
- `primitive (fw#2166). Move the section to a projectionDetail screen or remove it.`);
503
+ throw bootRuleError(FORM_LAYOUT_RULES.relatedListSectionUnsupported, {
504
+ message: `[Feature ${featureName}] Screen "${screenId}" (${context}) relatedList section ` +
505
+ `"${section.title}" is not supported — relatedList is a projectionDetail-only ` +
506
+ `primitive (fw#2166). Move the section to a projectionDetail screen or remove it.`,
507
+ });
411
508
  }
412
509
  if (isWriteFormEditSection(section)) {
413
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${context}) writeForm section ` +
414
- `"${section.title}" is not supported — writeForm is a projectionDetail-only primitive. Move the section to a projectionDetail screen or remove it.`);
510
+ throw bootRuleError(FORM_LAYOUT_RULES.writeFormSectionUnsupported, {
511
+ message: `[Feature ${featureName}] Screen "${screenId}" (${context}) writeForm section ` +
512
+ `"${section.title}" is not supported — writeForm is a projectionDetail-only primitive. Move the section to a projectionDetail screen or remove it.`,
513
+ });
415
514
  }
416
515
  validateFieldsXorGroups(`[Feature ${featureName}] Screen "${screenId}" (${context})`, section);
417
516
  for (const fieldSpec of sectionFieldSpecs(section)) {
418
517
  const normalized = normalizeEditField(fieldSpec);
419
518
  if (!fieldNames.has(normalized.field)) {
420
- throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${context}) layout references unknown field ` +
421
- `"${normalized.field}". Known fields: ${[...fieldNames].sort().join(", ")}`);
519
+ throw bootRuleError(FORM_LAYOUT_RULES.layoutUnknownField, {
520
+ message: `[Feature ${featureName}] Screen "${screenId}" (${context}) layout references unknown field ` +
521
+ `"${normalized.field}". Known fields: ${[...fieldNames].sort().join(", ")}`,
522
+ });
422
523
  }
423
524
  const fieldWhere = `[Feature ${featureName}] Screen "${screenId}" (${context}) field "${normalized.field}"`;
424
525
  validateFieldFormRefs(fieldWhere, normalized, fieldNames);
@@ -426,6 +527,14 @@ function validateFormLayoutSections(featureName, screenId, context, layout, fiel
426
527
  }
427
528
  }
428
529
  }
530
+ function validateSuccessLink(feature, screenId, kind, link, lookups, propertyPath) {
531
+ if (link.idFrom === undefined) {
532
+ validateIdlessSuccessLink(feature, screenId, "actionForm", link, lookups, propertyPath);
533
+ }
534
+ else {
535
+ validateRedirectTarget(feature, screenId, kind, { ...link, idFrom: link.idFrom }, lookups, propertyPath);
536
+ }
537
+ }
429
538
  function validateInlineFormNavTargets(feature, screenId, screen, kind, lookups) {
430
539
  const { allScreenQns } = lookups;
431
540
  if (screen.redirect !== undefined) {
@@ -434,24 +543,33 @@ function validateInlineFormNavTargets(feature, screenId, screen, kind, lookups)
434
543
  if (screen.type === "actionForm" &&
435
544
  screen.successFacts !== undefined &&
436
545
  screen.redirect !== undefined) {
437
- throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (actionForm) sets both redirect and successFacts — ` +
438
- `redirect leaves the screen, successFacts are shown on it. Use one of them.`);
546
+ throw bootRuleError(FORM_LAYOUT_RULES.successFactsWithRedirect, {
547
+ message: `[Feature ${feature.name}] Screen "${screenId}" (actionForm) sets both redirect and successFacts — ` +
548
+ `redirect leaves the screen, successFacts are shown on it. Use one of them.`,
549
+ });
439
550
  }
440
551
  if (screen.type === "actionForm" && screen.successLinks !== undefined) {
441
552
  if (screen.redirect !== undefined) {
442
- throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (actionForm) sets both redirect and successLinks — ` +
443
- `redirect leaves the screen, successLinks keep it open. Use one of them.`);
553
+ throw bootRuleError(FORM_LAYOUT_RULES.successLinksWithRedirect, {
554
+ message: `[Feature ${feature.name}] Screen "${screenId}" (actionForm) sets both redirect and successLinks — ` +
555
+ `redirect leaves the screen, successLinks keep it open. Use one of them.`,
556
+ });
444
557
  }
445
558
  screen.successLinks.forEach((link, index) => {
446
- const propertyPath = `successLinks[${index}]`;
447
- if (link.idFrom === undefined) {
448
- validateIdlessSuccessLink(feature, screenId, "actionForm", link, lookups, propertyPath);
449
- }
450
- else {
451
- validateRedirectTarget(feature, screenId, kind, { ...link, idFrom: link.idFrom }, lookups, propertyPath);
452
- }
559
+ validateSuccessLink(feature, screenId, kind, link, lookups, `successLinks[${index}]`);
453
560
  });
454
561
  }
562
+ if (screen.type === "actionForm" && screen.successItems !== undefined) {
563
+ if (screen.redirect !== undefined) {
564
+ throw bootRuleError(SCREEN_ACTION_RULES.actionFormSuccessItemsRedirect, {
565
+ message: `[Feature ${feature.name}] Screen "${screenId}" (actionForm) sets both redirect and successItems — ` +
566
+ `redirect leaves the screen, successItems are shown on it. Use one of them.`,
567
+ });
568
+ }
569
+ if (screen.successItems.link !== undefined) {
570
+ validateSuccessLink(feature, screenId, kind, screen.successItems.link, lookups, "successItems.link");
571
+ }
572
+ }
455
573
  if (typeof screen.cancelTarget === "string") {
456
574
  // Same rule as redirect — `false` (no Cancel button) needs no validation.
457
575
  validateScreenNavTarget(feature.name, screenId, kind, "cancelTarget", screen.cancelTarget, allScreenQns, feature.screens);
@@ -474,9 +592,11 @@ export function validateInlineFormScreen(feature, screenId, screen, kind, allWri
474
592
  if (screen.type === "actionForm" &&
475
593
  screen.load?.singleton === true &&
476
594
  screen.load.idParam !== undefined) {
477
- throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (actionForm) sets both load.singleton: true ` +
478
- `and load.idParam — singleton means the query picks the row from the caller's context, so ` +
479
- `there is no record id to send under idParam. Remove idParam.`);
595
+ throw bootRuleError(FORM_LAYOUT_RULES.loadSingletonWithIdParam, {
596
+ message: `[Feature ${feature.name}] Screen "${screenId}" (actionForm) sets both load.singleton: true ` +
597
+ `and load.idParam — singleton means the query picks the row from the caller's context, so ` +
598
+ `there is no record id to send under idParam. Remove idParam.`,
599
+ });
480
600
  }
481
601
  validateInlineFormNavTargets(feature, screenId, screen, kind, lookups);
482
602
  }
@@ -498,27 +618,35 @@ export function validateSecretMintConfirm(feature, screenId, screen, allWriteHan
498
618
  const fieldNames = validateFormFieldsMap(feature.name, screenId, context, confirm.fields, false);
499
619
  validateFormLayoutSections(feature.name, screenId, context, confirm.layout, fieldNames, confirm.fields, false);
500
620
  if (confirm.layout.mode !== undefined && confirm.layout.mode !== "single") {
501
- throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (${context}) sets layout.mode: ` +
502
- `"${confirm.layout.mode}" — a one-time reveal confirm step must stay a single-step form. ` +
503
- `Remove mode or set it to "single".`);
621
+ throw bootRuleError(FORM_LAYOUT_RULES.confirmLayoutMode, {
622
+ message: `[Feature ${feature.name}] Screen "${screenId}" (${context}) sets layout.mode: ` +
623
+ `"${confirm.layout.mode}" — a one-time reveal confirm step must stay a single-step form. ` +
624
+ `Remove mode or set it to "single".`,
625
+ });
504
626
  }
505
627
  if (confirm.layout.draft === true) {
506
- throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (${context}) sets layout.draft: true — ` +
507
- `persisting a draft of the reveal-confirm step would leak the one-time secret into storage, ` +
508
- `the exact leak fw#2548 closed. Remove draft: true.`);
628
+ throw bootRuleError(FORM_LAYOUT_RULES.confirmLayoutDraft, {
629
+ message: `[Feature ${feature.name}] Screen "${screenId}" (${context}) sets layout.draft: true — ` +
630
+ `persisting a draft of the reveal-confirm step would leak the one-time secret into storage, ` +
631
+ `the exact leak fw#2548 closed. Remove draft: true.`,
632
+ });
509
633
  }
510
634
  // skip: no carry list declared — no carried fields to cross-check against confirm.fields.
511
635
  if (confirm.carry === undefined)
512
636
  return;
513
637
  for (const carryField of confirm.carry) {
514
638
  if (typeof carryField !== "string" || carryField.trim() === "") {
515
- throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (${context}) has an empty or non-string ` +
516
- `entry in "carry". Use non-empty strings in carry.`);
639
+ throw bootRuleError(FORM_LAYOUT_RULES.confirmCarryEntryEmpty, {
640
+ message: `[Feature ${feature.name}] Screen "${screenId}" (${context}) has an empty or non-string ` +
641
+ `entry in "carry". Use non-empty strings in carry.`,
642
+ });
517
643
  }
518
644
  if (fieldNames.has(carryField)) {
519
- throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (${context}) carry field "${carryField}" ` +
520
- `also names a confirm.fields entry — a carried mint-payload value would silently ` +
521
- `overwrite the user-entered field of the same name. Rename one of them.`);
645
+ throw bootRuleError(FORM_LAYOUT_RULES.confirmCarryCollidesField, {
646
+ message: `[Feature ${feature.name}] Screen "${screenId}" (${context}) carry field "${carryField}" ` +
647
+ `also names a confirm.fields entry — a carried mint-payload value would silently ` +
648
+ `overwrite the user-entered field of the same name. Rename one of them.`,
649
+ });
522
650
  }
523
651
  }
524
652
  }