@cosmicdrift/kumiko-framework 0.412.0 → 0.413.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 (52) hide show
  1. package/agents/boot-rules.md +343 -0
  2. package/agents/examples/api-docs.md +79 -71
  3. package/agents/examples/golden-path.md +11 -11
  4. package/agents/examples/{contact.md → helpdesk.md} +31 -31
  5. package/agents/examples.md +1 -1
  6. package/agents/features-index.md +2 -2
  7. package/agents/features.md +16 -16
  8. package/dist/engine/boot-validator/boot-report.d.ts +3 -0
  9. package/dist/engine/boot-validator/boot-report.js +2 -2
  10. package/dist/engine/boot-validator/boot-rules.d.ts +570 -0
  11. package/dist/engine/boot-validator/boot-rules.js +20 -0
  12. package/dist/engine/boot-validator/definition-config-events-jobs-rules.d.ts +77 -0
  13. package/dist/engine/boot-validator/definition-config-events-jobs-rules.js +77 -0
  14. package/dist/engine/boot-validator/definition-events-rules.d.ts +42 -0
  15. package/dist/engine/boot-validator/definition-events-rules.js +42 -0
  16. package/dist/engine/boot-validator/definition-feature-rules.d.ts +42 -0
  17. package/dist/engine/boot-validator/definition-feature-rules.js +42 -0
  18. package/dist/engine/boot-validator/definition-field-factories-rules.d.ts +17 -0
  19. package/dist/engine/boot-validator/definition-field-factories-rules.js +17 -0
  20. package/dist/engine/boot-validator/definition-handlers-rules.d.ts +72 -0
  21. package/dist/engine/boot-validator/definition-handlers-rules.js +72 -0
  22. package/dist/engine/boot-validator/definition-ownership-from-rules.d.ts +27 -0
  23. package/dist/engine/boot-validator/definition-ownership-from-rules.js +27 -0
  24. package/dist/engine/boot-validator/definition-probes-rules.d.ts +47 -0
  25. package/dist/engine/boot-validator/definition-probes-rules.js +47 -0
  26. package/dist/engine/boot-validator/definition-role-assignment-rules.d.ts +27 -0
  27. package/dist/engine/boot-validator/definition-role-assignment-rules.js +27 -0
  28. package/dist/engine/boot-validator/definition-ui-extensions-rules.d.ts +197 -0
  29. package/dist/engine/boot-validator/definition-ui-extensions-rules.js +197 -0
  30. package/dist/engine/boot-validator/definition-webhook-events-rules.d.ts +32 -0
  31. package/dist/engine/boot-validator/definition-webhook-events-rules.js +32 -0
  32. package/dist/engine/define-feature.js +26 -9
  33. package/dist/engine/define-handler.js +8 -4
  34. package/dist/engine/definition-violations.d.ts +14 -0
  35. package/dist/engine/definition-violations.js +71 -0
  36. package/dist/engine/entity-handlers.js +39 -13
  37. package/dist/engine/event-def.js +32 -12
  38. package/dist/engine/factories.js +16 -5
  39. package/dist/engine/feature-config-events-jobs.js +63 -27
  40. package/dist/engine/feature-entity-handlers.js +15 -6
  41. package/dist/engine/feature-probes.js +29 -9
  42. package/dist/engine/feature-ui-extensions.js +178 -92
  43. package/dist/engine/object-form.js +8 -2
  44. package/dist/engine/ownership.js +17 -5
  45. package/dist/engine/role-assignment.js +17 -5
  46. package/dist/engine/webhook-events.js +20 -6
  47. package/dist/files/file-routes.js +1 -1
  48. package/dist/schema-cli/shared.d.ts +11 -0
  49. package/dist/schema-cli/shared.js +37 -3
  50. package/dist/schema-cli/validate-command.js +10 -3
  51. package/package.json +3 -3
  52. package/src/changes.json +12 -0
@@ -1,33 +1,51 @@
1
+ import { bootRuleError } from "./boot-validator/boot-rule.js";
2
+ import { DEFINITION_PROBE_RULES } from "./boot-validator/definition-probes-rules.js";
1
3
  import { isKebabSegment, QnTypes, qn, toKebab } from "./qualified-name.js";
2
4
  const PROBE_SCOPES = ["tenant", "system"];
3
5
  const PROBE_COSTS = ["free", "paid"];
4
6
  function assertValidProbe(featureName, options) {
5
7
  const prefix = `[Feature ${featureName}] r.probe()`;
6
8
  if (typeof options.name !== "string" || options.name.length === 0) {
7
- throw new Error(`${prefix}: name must be a non-empty string`);
9
+ throw bootRuleError(DEFINITION_PROBE_RULES.nameEmpty, {
10
+ message: `${prefix}: name must be a non-empty string`,
11
+ });
8
12
  }
9
13
  if (!isKebabSegment(options.name)) {
10
- throw new Error(`${prefix}: name "${options.name}" must be kebab-case`);
14
+ throw bootRuleError(DEFINITION_PROBE_RULES.nameNotKebab, {
15
+ message: `${prefix}: name "${options.name}" must be kebab-case`,
16
+ });
11
17
  }
12
18
  if (!PROBE_SCOPES.includes(options.scope)) {
13
- throw new Error(`${prefix} "${options.name}": scope must be one of ${PROBE_SCOPES.join(", ")}`);
19
+ throw bootRuleError(DEFINITION_PROBE_RULES.scopeInvalid, {
20
+ message: `${prefix} "${options.name}": scope must be one of ${PROBE_SCOPES.join(", ")}`,
21
+ });
14
22
  }
15
23
  if (!PROBE_COSTS.includes(options.cost)) {
16
- throw new Error(`${prefix} "${options.name}": cost must be one of ${PROBE_COSTS.join(", ")}`);
24
+ throw bootRuleError(DEFINITION_PROBE_RULES.costInvalid, {
25
+ message: `${prefix} "${options.name}": cost must be one of ${PROBE_COSTS.join(", ")}`,
26
+ });
17
27
  }
18
28
  for (const field of ["area", "label"]) {
19
29
  if (typeof options[field] !== "string" || options[field].length === 0) {
20
- throw new Error(`${prefix} "${options.name}": ${field} must be a non-empty i18n key`);
30
+ throw bootRuleError(DEFINITION_PROBE_RULES.i18nKeyEmpty, {
31
+ message: `${prefix} "${options.name}": ${field} must be a non-empty i18n key`,
32
+ });
21
33
  }
22
34
  }
23
35
  if (options.timeoutMs !== undefined && !(options.timeoutMs > 0)) {
24
- throw new Error(`${prefix} "${options.name}": timeoutMs must be > 0`);
36
+ throw bootRuleError(DEFINITION_PROBE_RULES.timeoutInvalid, {
37
+ message: `${prefix} "${options.name}": timeoutMs must be > 0`,
38
+ });
25
39
  }
26
40
  if (typeof options.run !== "function") {
27
- throw new Error(`${prefix} "${options.name}": run must be a function`);
41
+ throw bootRuleError(DEFINITION_PROBE_RULES.runNotFunction, {
42
+ message: `${prefix} "${options.name}": run must be a function`,
43
+ });
28
44
  }
29
45
  if (options.targets !== undefined && typeof options.targets !== "function") {
30
- throw new Error(`${prefix} "${options.name}": targets must be a function`);
46
+ throw bootRuleError(DEFINITION_PROBE_RULES.targetsNotFunction, {
47
+ message: `${prefix} "${options.name}": targets must be a function`,
48
+ });
31
49
  }
32
50
  }
33
51
  export function buildProbeMethods(state, featureName) {
@@ -35,7 +53,9 @@ export function buildProbeMethods(state, featureName) {
35
53
  probe(options) {
36
54
  assertValidProbe(featureName, options);
37
55
  if (state.probes[options.name]) {
38
- throw new Error(`[Feature ${featureName}] Probe "${options.name}" already registered. Probe names must be unique per feature.`);
56
+ throw bootRuleError(DEFINITION_PROBE_RULES.duplicate, {
57
+ message: `[Feature ${featureName}] Probe "${options.name}" already registered. Probe names must be unique per feature.`,
58
+ });
39
59
  }
40
60
  state.probes[options.name] = {
41
61
  ...options,
@@ -3,6 +3,8 @@ import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
3
3
  import { WEBSOCKET_MAX_CONNECTIONS_PER_USER_LIMIT, WEBSOCKET_MAX_PAYLOAD_BYTES, WEBSOCKET_ROUTE_PATH_PREFIX, } from "@cosmicdrift/kumiko-types/websocket-route";
4
4
  import { markExecutorManagedTable } from "../db/executor-managed-tables.js";
5
5
  import { bindHookEscapeHatchGrant } from "../pipeline/system-identity-switch.js";
6
+ import { bootRuleError } from "./boot-validator/boot-rule.js";
7
+ import { DEFINITION_UI_EXTENSION_RULES } from "./boot-validator/definition-ui-extensions-rules.js";
6
8
  import { LifecycleHookTypes } from "./constants.js";
7
9
  import { reasonProblem } from "./escape-hatch-reason.js";
8
10
  import { resolveName } from "./handler-helpers.js";
@@ -17,8 +19,10 @@ function assertSelectorPanelIds(featureName, extensionName, panels) {
17
19
  const seen = new Set();
18
20
  for (const { id } of panels) {
19
21
  if (id === "" || id === RESERVED_SELECTION_PANEL_ID || seen.has(id)) {
20
- throw new Error(`[Feature ${featureName}] extensionSelector("${extensionName}") panel id "${id}" must be unique, ` +
21
- `non-empty and not "${RESERVED_SELECTION_PANEL_ID}" (reserved for the selector panel).`);
22
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.extensionSelectorPanelIdInvalid, {
23
+ message: `[Feature ${featureName}] extensionSelector("${extensionName}") panel id "${id}" must be unique, ` +
24
+ `non-empty and not "${RESERVED_SELECTION_PANEL_ID}" (reserved for the selector panel).`,
25
+ });
22
26
  }
23
27
  seen.add(id);
24
28
  }
@@ -30,8 +34,10 @@ function qualifySelectorPanel(featureName, panel) {
30
34
  return panel;
31
35
  if (panel.kind === "screen") {
32
36
  if ("label" in panel) {
33
- throw new Error(`[Feature ${featureName}] extensionSelector screen panel "${panel.id}" must not set a label — ` +
34
- `the settings dashboard has no i18n namespace for it; the embedded screen carries its own title.`);
37
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.extensionSelectorScreenPanelLabel, {
38
+ message: `[Feature ${featureName}] extensionSelector screen panel "${panel.id}" must not set a label — ` +
39
+ `the settings dashboard has no i18n namespace for it; the embedded screen carries its own title.`,
40
+ });
35
41
  }
36
42
  const qualify = (ref) => ref === "" || isValidQn(ref) ? ref : qualifyEntityName(featureName, "screen", ref);
37
43
  const screen = qualify(panel.screen);
@@ -40,8 +46,10 @@ function qualifySelectorPanel(featureName, panel) {
40
46
  return panel;
41
47
  return { ...panel, screen, ...(fallback !== undefined && { fallback }) };
42
48
  }
43
- throw new Error(`[Feature ${featureName}] extensionSelector panel ${JSON.stringify(panel)} has an unsupported kind — ` +
44
- `only "custom" and "screen" panels are allowed.`);
49
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.extensionSelectorPanelKindUnsupported, {
50
+ message: `[Feature ${featureName}] extensionSelector panel ${JSON.stringify(panel)} has an unsupported kind — ` +
51
+ `only "custom" and "screen" panels are allowed.`,
52
+ });
45
53
  }
46
54
  function isEntityWideHookType(type) {
47
55
  return (type === LifecycleHookTypes.postSave ||
@@ -98,14 +106,18 @@ export function buildUiExtensionsMethods(state, name) {
98
106
  // instead of only the standalone r.nav() one.
99
107
  function registerNav(navDefinition) {
100
108
  if (!isKebabSegment(navDefinition.id)) {
101
- throw new Error(`[Feature ${name}] Nav id "${navDefinition.id}" must be kebab-case ` +
102
- `(lowercase letters, digits, dashes; start with a letter). ` +
103
- `Got "${navDefinition.id}" — try "${toKebab(navDefinition.id).replace(/_/g, "-")}".`);
109
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.navIdNotKebab, {
110
+ message: `[Feature ${name}] Nav id "${navDefinition.id}" must be kebab-case ` +
111
+ `(lowercase letters, digits, dashes; start with a letter). ` +
112
+ `Got "${navDefinition.id}" — try "${toKebab(navDefinition.id).replace(/_/g, "-")}".`,
113
+ });
104
114
  }
105
115
  if (state.navs[navDefinition.id]) {
106
- throw new Error(`[Feature ${name}] Nav entry "${navDefinition.id}" already registered. ` +
107
- `Nav ids must be unique per feature — remove the standalone ` +
108
- `r.nav("${navDefinition.id}", ...) call or the screen's inline nav.`);
116
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.navIdDuplicate, {
117
+ message: `[Feature ${name}] Nav entry "${navDefinition.id}" already registered. ` +
118
+ `Nav ids must be unique per feature — remove the standalone ` +
119
+ `r.nav("${navDefinition.id}", ...) call or the screen's inline nav.`,
120
+ });
109
121
  }
110
122
  // Explicit `undefined` values (e.g. `icon: cond ? "x" : undefined`) would trip
111
123
  // buildAppSchema's JSON-safety check, so strip them for every nav path.
@@ -123,19 +135,25 @@ export function buildUiExtensionsMethods(state, name) {
123
135
  };
124
136
  if (type === "validation") {
125
137
  if (options?.escapeHatch !== undefined) {
126
- throw new Error(`[Feature ${name}] r.hook({ type: "validation", … }) does not accept escapeHatch — ` +
127
- "validation hooks receive no context to switch identity with.");
138
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.hookValidationEscapeHatch, {
139
+ message: `[Feature ${name}] r.hook({ type: "validation", … }) does not accept escapeHatch — ` +
140
+ "validation hooks receive no context to switch identity with.",
141
+ });
128
142
  }
129
143
  }
130
144
  else if (options?.escapeHatch !== undefined) {
131
145
  const hookReasonProblem = reasonProblem(options.escapeHatch.reason);
132
146
  if (hookReasonProblem !== undefined) {
133
- throw new Error(`[Feature ${name}] r.hook({ type: "${type}", … }) declares an invalid escapeHatch — ${hookReasonProblem}`);
147
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.hookEscapeHatchInvalid, {
148
+ message: `[Feature ${name}] r.hook({ type: "${type}", … }) declares an invalid escapeHatch — ${hookReasonProblem}`,
149
+ });
134
150
  }
135
151
  }
136
152
  const hookGrantsProblem = options?.escapeHatch && escapeHatchGrantsProblem(options.escapeHatch);
137
153
  if (hookGrantsProblem) {
138
- throw new Error(`[Feature ${name}] r.hook({ type: "${type}", … }) declares an invalid escapeHatch — ${hookGrantsProblem}`);
154
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.hookEscapeHatchInvalid, {
155
+ message: `[Feature ${name}] r.hook({ type: "${type}", … }) declares an invalid escapeHatch — ${hookGrantsProblem}`,
156
+ });
139
157
  }
140
158
  // Wrapped once for both branches below; validation hooks stay unwrapped (no context).
141
159
  const hookLabel = `${type} hook of feature "${name}"`;
@@ -149,8 +167,10 @@ export function buildUiExtensionsMethods(state, name) {
149
167
  !Array.isArray(target) &&
150
168
  "allOf" in target) {
151
169
  if (!isEntityWideHookType(type)) {
152
- throw new Error(`[Feature ${name}] r.hook({ type: "${type}", target: { allOf }, … }) only supports ` +
153
- `postSave/preDelete/postDelete/postQuery, not "${type}".`);
170
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.hookAllOfUnsupportedType, {
171
+ message: `[Feature ${name}] r.hook({ type: "${type}", target: { allOf }, … }) only supports ` +
172
+ `postSave/preDelete/postDelete/postQuery, not "${type}".`,
173
+ });
154
174
  }
155
175
  registerEntityWideHook(state, name, type, resolveName(target.allOf), wrapped, // @cast-boundary engine-bridge
156
176
  options);
@@ -183,8 +203,10 @@ export function buildUiExtensionsMethods(state, name) {
183
203
  return;
184
204
  }
185
205
  if (!(type in state.phasedLifecycleHooks)) {
186
- throw new Error(`[Feature ${name}] r.hook({ type: "${type}", … }) is not a known hook type ` +
187
- "(preQuery hooks were never invoked and have been removed).");
206
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.hookTypeUnknown, {
207
+ message: `[Feature ${name}] r.hook({ type: "${type}", … }) is not a known hook type ` +
208
+ "(preQuery hooks were never invoked and have been removed).",
209
+ });
188
210
  }
189
211
  // Phased storage. preDelete has no phase option (always inTransaction);
190
212
  // postSave/postDelete default to afterCommit.
@@ -233,16 +255,22 @@ export function buildUiExtensionsMethods(state, name) {
233
255
  const escapeHatchObject = isPlainObject(escapeHatch) ? escapeHatch : undefined;
234
256
  const reason = escapeHatchObject?.["reason"];
235
257
  if (escapeHatchObject === undefined || typeof reason !== "string") {
236
- throw new Error(`[Feature ${name}] r.useExtension("${extensionName}", "${resolvedEntityName}", ...) declares an invalid { escapeHatch } — ` +
237
- `must be { reason: "<explanation>" } explaining why this usage needs unfiltered db access.`);
258
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.useExtensionEscapeHatchInvalid, {
259
+ message: `[Feature ${name}] r.useExtension("${extensionName}", "${resolvedEntityName}", ...) declares an invalid { escapeHatch } — ` +
260
+ `must be { reason: "<explanation>" } explaining why this usage needs unfiltered db access.`,
261
+ });
238
262
  }
239
263
  const extReasonProblem = reasonProblem(reason);
240
264
  if (extReasonProblem !== undefined) {
241
- throw new Error(`[Feature ${name}] r.useExtension("${extensionName}", "${resolvedEntityName}", ...) declares an invalid { escapeHatch } — ${extReasonProblem}`);
265
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.useExtensionEscapeHatchInvalid, {
266
+ message: `[Feature ${name}] r.useExtension("${extensionName}", "${resolvedEntityName}", ...) declares an invalid { escapeHatch } — ${extReasonProblem}`,
267
+ });
242
268
  }
243
269
  const extGrantsProblem = escapeHatchGrantsProblem(escapeHatchObject);
244
270
  if (extGrantsProblem) {
245
- throw new Error(`[Feature ${name}] r.useExtension("${extensionName}", "${resolvedEntityName}", ...) declares an invalid { escapeHatch } — ${extGrantsProblem}`);
271
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.useExtensionEscapeHatchInvalid, {
272
+ message: `[Feature ${name}] r.useExtension("${extensionName}", "${resolvedEntityName}", ...) declares an invalid { escapeHatch } — ${extGrantsProblem}`,
273
+ });
246
274
  }
247
275
  }
248
276
  state.extensionUsages.push({
@@ -253,8 +281,10 @@ export function buildUiExtensionsMethods(state, name) {
253
281
  },
254
282
  extensionSelector(extensionName, key, options) {
255
283
  if (state.extensionSelectors.some((s) => s.extensionName === extensionName)) {
256
- throw new Error(`[Feature ${name}] extensionSelector("${extensionName}") declared twice — ` +
257
- `one selector key per extension point.`);
284
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.extensionSelectorDuplicate, {
285
+ message: `[Feature ${name}] extensionSelector("${extensionName}") declared twice — ` +
286
+ `one selector key per extension point.`,
287
+ });
258
288
  }
259
289
  const qualifiedKey = typeof key === "string" ? key : key.name;
260
290
  const panels = options?.panels?.map((panel) => qualifySelectorPanel(name, panel));
@@ -284,7 +314,9 @@ export function buildUiExtensionsMethods(state, name) {
284
314
  */
285
315
  exposesApi(apiName) {
286
316
  if (state.exposedApis.has(apiName)) {
287
- throw new Error(`[Feature ${name}] r.exposesApi("${apiName}") called twice — API names must be unique within a feature.`);
317
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.exposesApiTwice, {
318
+ message: `[Feature ${name}] r.exposesApi("${apiName}") called twice — API names must be unique within a feature.`,
319
+ });
288
320
  }
289
321
  state.exposedApis.add(apiName);
290
322
  },
@@ -304,13 +336,17 @@ export function buildUiExtensionsMethods(state, name) {
304
336
  // Catch it at the registration site so the stack trace points at the
305
337
  // feature file, not at framework internals.
306
338
  if (!isKebabSegment(definition.name)) {
307
- throw new Error(`[Feature ${name}] Projection name "${definition.name}" must be kebab-case ` +
308
- `(lowercase letters, digits, dashes; start with a letter). ` +
309
- `Got "${definition.name}" — try "${toKebab(definition.name).replace(/_/g, "-")}".`);
339
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.projectionNameNotKebab, {
340
+ message: `[Feature ${name}] Projection name "${definition.name}" must be kebab-case ` +
341
+ `(lowercase letters, digits, dashes; start with a letter). ` +
342
+ `Got "${definition.name}" — try "${toKebab(definition.name).replace(/_/g, "-")}".`,
343
+ });
310
344
  }
311
345
  if (state.projections[definition.name]) {
312
- throw new Error(`[Feature ${name}] Projection "${definition.name}" already registered. ` +
313
- `Projection names must be unique per feature.`);
346
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.projectionNameDuplicate, {
347
+ message: `[Feature ${name}] Projection "${definition.name}" already registered. ` +
348
+ `Projection names must be unique per feature.`,
349
+ });
314
350
  }
315
351
  if (typeof definition.table === "object" && definition.table !== null) {
316
352
  markExecutorManagedTable(definition.table);
@@ -319,24 +355,32 @@ export function buildUiExtensionsMethods(state, name) {
319
355
  },
320
356
  multiStreamProjection(definition) {
321
357
  if (!isKebabSegment(definition.name)) {
322
- throw new Error(`[Feature ${name}] MultiStreamProjection name "${definition.name}" must be kebab-case ` +
323
- `(lowercase letters, digits, dashes; start with a letter). ` +
324
- `Got "${definition.name}" — try "${toKebab(definition.name).replace(/_/g, "-")}".`);
358
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.multiStreamProjectionNameNotKebab, {
359
+ message: `[Feature ${name}] MultiStreamProjection name "${definition.name}" must be kebab-case ` +
360
+ `(lowercase letters, digits, dashes; start with a letter). ` +
361
+ `Got "${definition.name}" — try "${toKebab(definition.name).replace(/_/g, "-")}".`,
362
+ });
325
363
  }
326
364
  if (state.multiStreamProjections[definition.name] || state.projections[definition.name]) {
327
- throw new Error(`[Feature ${name}] Projection name "${definition.name}" already registered. ` +
328
- `r.projection and r.multiStreamProjection share a namespace — pick a unique short name.`);
365
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.multiStreamProjectionNameDuplicate, {
366
+ message: `[Feature ${name}] Projection name "${definition.name}" already registered. ` +
367
+ `r.projection and r.multiStreamProjection share a namespace — pick a unique short name.`,
368
+ });
329
369
  }
330
370
  if (Object.keys(definition.apply).length === 0) {
331
- throw new Error(`[Feature ${name}] MultiStreamProjection "${definition.name}" has no apply handlers. ` +
332
- `Declare at least one event type it reacts to, otherwise the dispatcher has nothing to route.`);
371
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.multiStreamProjectionWithoutApply, {
372
+ message: `[Feature ${name}] MultiStreamProjection "${definition.name}" has no apply handlers. ` +
373
+ `Declare at least one event type it reacts to, otherwise the dispatcher has nothing to route.`,
374
+ });
333
375
  }
334
376
  state.multiStreamProjections[definition.name] = definition;
335
377
  },
336
378
  extendEntityProjection(entityName, extension) {
337
379
  if (Object.keys(extension.apply).length === 0) {
338
- throw new Error(`[Feature ${name}] extendEntityProjection("${entityName}") has no apply handlers. ` +
339
- `Declare at least one event type, otherwise the rebuild replay has nothing to do.`);
380
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.extendEntityProjectionWithoutApply, {
381
+ message: `[Feature ${name}] extendEntityProjection("${entityName}") has no apply handlers. ` +
382
+ `Declare at least one event type, otherwise the rebuild replay has nothing to do.`,
383
+ });
340
384
  }
341
385
  // Entity existence + apply-key collisions are validated at registry
342
386
  // build — r.entity may legally be called after this in the same feature.
@@ -367,13 +411,17 @@ export function buildUiExtensionsMethods(state, name) {
367
411
  // the feature file, not at registry-boot. Same guard pattern as
368
412
  // r.projection / r.multiStreamProjection.
369
413
  if (!isKebabSegment(definition.id)) {
370
- throw new Error(`[Feature ${name}] Screen id "${definition.id}" must be kebab-case ` +
371
- `(lowercase letters, digits, dashes; start with a letter). ` +
372
- `Got "${definition.id}" — try "${toKebab(definition.id).replace(/_/g, "-")}".`);
414
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.screenIdNotKebab, {
415
+ message: `[Feature ${name}] Screen id "${definition.id}" must be kebab-case ` +
416
+ `(lowercase letters, digits, dashes; start with a letter). ` +
417
+ `Got "${definition.id}" — try "${toKebab(definition.id).replace(/_/g, "-")}".`,
418
+ });
373
419
  }
374
420
  if (state.screens[definition.id]) {
375
- throw new Error(`[Feature ${name}] Screen "${definition.id}" already registered. ` +
376
- `Screen ids must be unique per feature.`);
421
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.screenIdDuplicate, {
422
+ message: `[Feature ${name}] Screen "${definition.id}" already registered. ` +
423
+ `Screen ids must be unique per feature.`,
424
+ });
377
425
  }
378
426
  state.screens[definition.id] = definition;
379
427
  if (definition.nav) {
@@ -395,8 +443,10 @@ export function buildUiExtensionsMethods(state, name) {
395
443
  },
396
444
  contentCollection(definition) {
397
445
  if (state.contentCollections[definition.id]) {
398
- throw new Error(`[Feature ${name}] Content collection "${definition.id}" already registered. ` +
399
- `Collection ids must be unique per feature.`);
446
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.contentCollectionIdDuplicate, {
447
+ message: `[Feature ${name}] Content collection "${definition.id}" already registered. ` +
448
+ `Collection ids must be unique per feature.`,
449
+ });
400
450
  }
401
451
  // registerNav owns the kebab + collision checks, including collisions
402
452
  // with a plain r.nav() of the same id.
@@ -424,13 +474,17 @@ export function buildUiExtensionsMethods(state, name) {
424
474
  // Same kebab guard as r.screen / r.nav so authoring-time mistakes
425
475
  // surface at the feature file, not deep in registry boot.
426
476
  if (!isKebabSegment(definition.id)) {
427
- throw new Error(`[Feature ${name}] Workspace id "${definition.id}" must be kebab-case ` +
428
- `(lowercase letters, digits, dashes; start with a letter). ` +
429
- `Got "${definition.id}" — try "${toKebab(definition.id).replace(/_/g, "-")}".`);
477
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.workspaceIdNotKebab, {
478
+ message: `[Feature ${name}] Workspace id "${definition.id}" must be kebab-case ` +
479
+ `(lowercase letters, digits, dashes; start with a letter). ` +
480
+ `Got "${definition.id}" — try "${toKebab(definition.id).replace(/_/g, "-")}".`,
481
+ });
430
482
  }
431
483
  if (state.workspaces[definition.id]) {
432
- throw new Error(`[Feature ${name}] Workspace "${definition.id}" already registered. ` +
433
- `Workspace ids must be unique per feature.`);
484
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.workspaceIdDuplicate, {
485
+ message: `[Feature ${name}] Workspace "${definition.id}" already registered. ` +
486
+ `Workspace ids must be unique per feature.`,
487
+ });
434
488
  }
435
489
  state.workspaces[definition.id] = definition;
436
490
  },
@@ -439,17 +493,23 @@ export function buildUiExtensionsMethods(state, name) {
439
493
  // dispatcher. An HTTP route occupying /api/foo could bypass the auth
440
494
  // middleware without the author explicitly intending it, so block it.
441
495
  if (!definition.path.startsWith("/")) {
442
- throw new Error(`[Feature ${name}] httpRoute path "${definition.path}" must start with "/". ` +
443
- `Got "${definition.path}".`);
496
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.httpRoutePathNotAbsolute, {
497
+ message: `[Feature ${name}] httpRoute path "${definition.path}" must start with "/". ` +
498
+ `Got "${definition.path}".`,
499
+ });
444
500
  }
445
501
  if (definition.path === "/api" || definition.path.startsWith("/api/")) {
446
- throw new Error(`[Feature ${name}] httpRoute path "${definition.path}" is in the /api/* namespace ` +
447
- `which is reserved for the dispatcher (write/query/batch/auth/sse). ` +
448
- `Pick a different path or use r.queryHandler / r.writeHandler.`);
502
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.httpRoutePathReserved, {
503
+ message: `[Feature ${name}] httpRoute path "${definition.path}" is in the /api/* namespace ` +
504
+ `which is reserved for the dispatcher (write/query/batch/auth/sse). ` +
505
+ `Pick a different path or use r.queryHandler / r.writeHandler.`,
506
+ });
449
507
  }
450
508
  if (typeof definition.anonymous !== "boolean") {
451
- throw new Error(`[Feature ${name}] httpRoute "${definition.method} ${definition.path}" must declare ` +
452
- `anonymous: true | false — true mounts it public, false behind the session auth chain.`);
509
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.httpRouteAnonymousMissing, {
510
+ message: `[Feature ${name}] httpRoute "${definition.method} ${definition.path}" must declare ` +
511
+ `anonymous: true | false — true mounts it public, false behind the session auth chain.`,
512
+ });
453
513
  }
454
514
  const routeLimit = definition.rateLimit;
455
515
  if (routeLimit !== undefined &&
@@ -457,45 +517,59 @@ export function buildUiExtensionsMethods(state, name) {
457
517
  routeLimit.limit < 1 ||
458
518
  !Number.isInteger(routeLimit.windowSeconds) ||
459
519
  routeLimit.windowSeconds < 1)) {
460
- throw new Error(`[Feature ${name}] httpRoute "${definition.method} ${definition.path}" rateLimit needs ` +
461
- `positive integer limit and windowSeconds.`);
520
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.httpRouteRateLimitInvalid, {
521
+ message: `[Feature ${name}] httpRoute "${definition.method} ${definition.path}" rateLimit needs ` +
522
+ `positive integer limit and windowSeconds.`,
523
+ });
462
524
  }
463
525
  const key = `${definition.method} ${definition.path}`;
464
526
  if (state.httpRoutes[key]) {
465
- throw new Error(`[Feature ${name}] HTTP-Route "${key}" already registered. ` +
466
- `method + path must be unique per feature.`);
527
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.httpRouteDuplicate, {
528
+ message: `[Feature ${name}] HTTP-Route "${key}" already registered. ` +
529
+ `method + path must be unique per feature.`,
530
+ });
467
531
  }
468
532
  state.httpRoutes[key] = definition;
469
533
  },
470
534
  webSocketRoute(definition) {
471
535
  if (!definition.path.startsWith(WEBSOCKET_ROUTE_PATH_PREFIX)) {
472
- throw new Error(`[Feature ${name}] webSocketRoute path "${definition.path}" must start with ` +
473
- `"${WEBSOCKET_ROUTE_PATH_PREFIX}" — only that namespace rides the /api/* auth chain ` +
474
- "the upgrade relies on.");
536
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.webSocketRoutePathPrefix, {
537
+ message: `[Feature ${name}] webSocketRoute path "${definition.path}" must start with ` +
538
+ `"${WEBSOCKET_ROUTE_PATH_PREFIX}" — only that namespace rides the /api/* auth chain ` +
539
+ "the upgrade relies on.",
540
+ });
475
541
  }
476
542
  if (definition.path.includes("*")) {
477
- throw new Error(`[Feature ${name}] webSocketRoute path "${definition.path}" must not contain "*" — ` +
478
- "wildcards would let one route swallow unrelated /api/ws/* paths.");
543
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.webSocketRoutePathWildcard, {
544
+ message: `[Feature ${name}] webSocketRoute path "${definition.path}" must not contain "*" — ` +
545
+ "wildcards would let one route swallow unrelated /api/ws/* paths.",
546
+ });
479
547
  }
480
548
  const { maxMessageBytes } = definition;
481
549
  if (maxMessageBytes !== undefined &&
482
550
  (!Number.isInteger(maxMessageBytes) ||
483
551
  maxMessageBytes < 1 ||
484
552
  maxMessageBytes > WEBSOCKET_MAX_PAYLOAD_BYTES)) {
485
- throw new Error(`[Feature ${name}] webSocketRoute "${definition.path}" maxMessageBytes must be an ` +
486
- `integer between 1 and ${WEBSOCKET_MAX_PAYLOAD_BYTES}, got ${maxMessageBytes}.`);
553
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.webSocketRouteMaxMessageBytesInvalid, {
554
+ message: `[Feature ${name}] webSocketRoute "${definition.path}" maxMessageBytes must be an ` +
555
+ `integer between 1 and ${WEBSOCKET_MAX_PAYLOAD_BYTES}, got ${maxMessageBytes}.`,
556
+ });
487
557
  }
488
558
  const { maxConnectionsPerUser } = definition;
489
559
  if (maxConnectionsPerUser !== undefined &&
490
560
  (!Number.isInteger(maxConnectionsPerUser) ||
491
561
  maxConnectionsPerUser < 1 ||
492
562
  maxConnectionsPerUser > WEBSOCKET_MAX_CONNECTIONS_PER_USER_LIMIT)) {
493
- throw new Error(`[Feature ${name}] webSocketRoute "${definition.path}" maxConnectionsPerUser must be an ` +
494
- `integer between 1 and ${WEBSOCKET_MAX_CONNECTIONS_PER_USER_LIMIT}, got ${maxConnectionsPerUser}.`);
563
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.webSocketRouteMaxConnectionsInvalid, {
564
+ message: `[Feature ${name}] webSocketRoute "${definition.path}" maxConnectionsPerUser must be an ` +
565
+ `integer between 1 and ${WEBSOCKET_MAX_CONNECTIONS_PER_USER_LIMIT}, got ${maxConnectionsPerUser}.`,
566
+ });
495
567
  }
496
568
  if (state.webSocketRoutes[definition.path]) {
497
- throw new Error(`[Feature ${name}] WebSocket route "${definition.path}" already registered. ` +
498
- "path must be unique per feature.");
569
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.webSocketRouteDuplicate, {
570
+ message: `[Feature ${name}] WebSocket route "${definition.path}" already registered. ` +
571
+ "path must be unique per feature.",
572
+ });
499
573
  }
500
574
  state.webSocketRoutes[definition.path] = definition;
501
575
  },
@@ -506,39 +580,49 @@ export function buildUiExtensionsMethods(state, name) {
506
580
  if (!isKebabSegment(tableName.replace(/_/g, "-"))) {
507
581
  // EntityTableMeta uses snake_case for tableName (matches Postgres
508
582
  // convention); we just guard against truly broken input.
509
- throw new Error(`[Feature ${name}] Store-table name "${tableName}" must be a ` +
510
- `valid identifier (lowercase letters, digits, underscores; start with a letter).`);
583
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.storeTableNameInvalid, {
584
+ message: `[Feature ${name}] Store-table name "${tableName}" must be a ` +
585
+ `valid identifier (lowercase letters, digits, underscores; start with a letter).`,
586
+ });
511
587
  }
512
588
  if (state.storeTables[tableName]) {
513
- throw new Error(`[Feature ${name}] r.storeTable("${tableName}") already registered. ` +
514
- `Store-table names must be unique per feature.`);
589
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.storeTableDuplicate, {
590
+ message: `[Feature ${name}] r.storeTable("${tableName}") already registered. ` +
591
+ `Store-table names must be unique per feature.`,
592
+ });
515
593
  }
516
594
  // `read_` is reserved for r.entity()/r.projection() (managed,
517
595
  // event-sourced, rebuildable). storeTable is the unmanaged
518
596
  // direct-write escape hatch — the prefix must say so.
519
597
  if (tableName.startsWith("read_")) {
520
- throw new Error(`[Feature ${name}] r.storeTable("${tableName}"): the "read_" prefix is reserved ` +
521
- `for managed r.entity()/r.projection() tables. Pick an unprefixed name or a ` +
522
- `distinct prefix (e.g. "store_${tableName.slice("read_".length)}").`);
598
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.storeTableReadPrefixReserved, {
599
+ message: `[Feature ${name}] r.storeTable("${tableName}"): the "read_" prefix is reserved ` +
600
+ `for managed r.entity()/r.projection() tables. Pick an unprefixed name or a ` +
601
+ `distinct prefix (e.g. "store_${tableName.slice("read_".length)}").`,
602
+ });
523
603
  }
524
604
  // meta.source must agree with the r.storeTable() escape hatch, or the
525
605
  // migrate-generator treats schema drift on this table as safe to
526
606
  // DROP+rebuild-from-events — wiping direct-write data with no events
527
607
  // to replay it from.
528
608
  if (meta.source !== "unmanaged") {
529
- throw new Error(`[Feature ${name}] r.storeTable("${tableName}") was given an EntityTableMeta with ` +
530
- `source: "${meta.source}". r.storeTable() requires source: "unmanaged" (via ` +
531
- `defineUnmanagedTable(), or deriveEntityTableMeta(..., { source: "unmanaged" })) — ` +
532
- `otherwise the migration generator will treat schema drift on this table as safe ` +
533
- `to DROP+rebuild, wiping any direct-write data.`);
609
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.storeTableMetaNotUnmanaged, {
610
+ message: `[Feature ${name}] r.storeTable("${tableName}") was given an EntityTableMeta with ` +
611
+ `source: "${meta.source}". r.storeTable() requires source: "unmanaged" (via ` +
612
+ `defineUnmanagedTable(), or deriveEntityTableMeta(..., { source: "unmanaged" })) — ` +
613
+ `otherwise the migration generator will treat schema drift on this table as safe ` +
614
+ `to DROP+rebuild, wiping any direct-write data.`,
615
+ });
534
616
  }
535
617
  // The `reason` is the marker that justifies the bypass — empty
536
618
  // strings would defeat the audit trail. Reject early so the
537
619
  // failure points at the feature file.
538
620
  if (typeof options.reason !== "string" || options.reason.trim().length === 0) {
539
- throw new Error(`[Feature ${name}] r.storeTable("${tableName}"): options.reason must be a ` +
540
- `non-empty string. The reason justifies the audit-trail bypass — ` +
541
- `if you can't write one, declare data via r.entity() instead.`);
621
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.storeTableReasonMissing, {
622
+ message: `[Feature ${name}] r.storeTable("${tableName}"): options.reason must be a ` +
623
+ `non-empty string. The reason justifies the audit-trail bypass — ` +
624
+ `if you can't write one, declare data via r.entity() instead.`,
625
+ });
542
626
  }
543
627
  state.storeTables[tableName] = {
544
628
  name: tableName,
@@ -551,8 +635,10 @@ export function buildUiExtensionsMethods(state, name) {
551
635
  // Only-once guard: a second call is an authoring error that should surface in
552
636
  // the feature file (matching the behavior of r.toggleable).
553
637
  if (state.treeActions !== undefined) {
554
- throw new Error(`[Feature ${name}] r.treeActions() already called. ` +
555
- `Each feature may declare a single tree-actions schema.`);
638
+ throw bootRuleError(DEFINITION_UI_EXTENSION_RULES.treeActionsTwice, {
639
+ message: `[Feature ${name}] r.treeActions() already called. ` +
640
+ `Each feature may declare a single tree-actions schema.`,
641
+ });
556
642
  }
557
643
  state.treeActions = actions;
558
644
  // Return a typed handle for the setup export. Freeze it so callers cannot
@@ -1,3 +1,5 @@
1
+ import { bootRuleError } from "./boot-validator/boot-rule.js";
2
+ import { FEATURE_DEFINITION_RULES } from "./boot-validator/definition-feature-rules.js";
1
3
  // Shared helpers for registrar methods that take a single object argument
2
4
  // (`r.entity({ name: "item", ... })`).
3
5
  export function splitNamedDefinition(definition) {
@@ -8,7 +10,9 @@ export function splitNamedDefinition(definition) {
8
10
  // the implementation signature has to stay optional, so untyped callers are caught here.
9
11
  export function requireArgument(value, featureName, method, argument) {
10
12
  if (value === undefined) {
11
- throw new Error(`[Feature ${featureName}] r.${method}() needs its ${argument} argument`);
13
+ throw bootRuleError(FEATURE_DEFINITION_RULES.argumentMissing, {
14
+ message: `[Feature ${featureName}] r.${method}() needs its ${argument} argument`,
15
+ });
12
16
  }
13
17
  return value;
14
18
  }
@@ -29,5 +33,7 @@ export function isObjectArgument(value) {
29
33
  // Untyped JS callers bypass the types; without this check a positional call would
30
34
  // register a definition built from undefined fields instead of failing.
31
35
  export function throwObjectArgumentRequired(featureName, method) {
32
- throw new Error(`[Feature ${featureName}] r.${method}() takes one options object`);
36
+ throw bootRuleError(FEATURE_DEFINITION_RULES.optionsObjectRequired, {
37
+ message: `[Feature ${featureName}] r.${method}() takes one options object`,
38
+ });
33
39
  }