@cosmicdrift/kumiko-framework 0.406.0 → 0.409.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (209) hide show
  1. package/agents/api/framework-db.md +1 -0
  2. package/agents/api/framework-engine.md +15 -2
  3. package/agents/api/framework-ui-types.md +15 -0
  4. package/agents/api/renderer-web.md +156 -2
  5. package/agents/api/types.md +113 -71
  6. package/agents/api.md +4 -4
  7. package/agents/boot-rules.md +743 -0
  8. package/agents/examples/contact.md +167 -0
  9. package/agents/examples/delivery-notifications.md +34 -1
  10. package/agents/examples/record-detail-layout.md +13 -2
  11. package/agents/examples/search.md +65 -3
  12. package/agents/examples/secrets-demo.md +96 -2
  13. package/agents/examples/tenant-inactivity.md +138 -0
  14. package/agents/examples.md +2 -0
  15. package/agents/features-index.md +4 -0
  16. package/agents/features.md +24 -1
  17. package/agents/widgets.md +12 -1
  18. package/dist/api/export/export-rows.js +1 -0
  19. package/dist/compliance/index.d.ts +1 -1
  20. package/dist/db/event-store-executor-read-where.js +15 -5
  21. package/dist/db/index.d.ts +1 -1
  22. package/dist/db/index.js +1 -1
  23. package/dist/db/migrate-generator.js +3 -1
  24. package/dist/db/queries/event-consumer.js +11 -7
  25. package/dist/db/queries/event-store.d.ts +2 -1
  26. package/dist/db/queries/event-store.js +25 -6
  27. package/dist/db/queries/rls-boot-catalog.js +3 -1
  28. package/dist/db/queries/session-advisory-lock.d.ts +7 -0
  29. package/dist/db/queries/session-advisory-lock.js +23 -0
  30. package/dist/db/query.js +7 -10
  31. package/dist/db/row-level-security-connection.js +4 -2
  32. package/dist/engine/active-membership.js +1 -0
  33. package/dist/engine/boot-validator/access-declarations.js +57 -33
  34. package/dist/engine/boot-validator/action-wiring.js +8 -6
  35. package/dist/engine/boot-validator/agent-effect-rules.d.ts +12 -0
  36. package/dist/engine/boot-validator/agent-effect-rules.js +12 -0
  37. package/dist/engine/boot-validator/agent-effect.d.ts +2 -0
  38. package/dist/engine/boot-validator/agent-effect.js +20 -0
  39. package/dist/engine/boot-validator/boot-context.js +5 -1
  40. package/dist/engine/boot-validator/boot-environment-rules.d.ts +12 -0
  41. package/dist/engine/boot-validator/boot-environment-rules.js +12 -0
  42. package/dist/engine/boot-validator/boot-phases-app.js +5 -1
  43. package/dist/engine/boot-validator/boot-phases.js +3 -1
  44. package/dist/engine/boot-validator/boot-rules.d.ts +2619 -0
  45. package/dist/engine/boot-validator/boot-rules.js +58 -0
  46. package/dist/engine/boot-validator/bundled-lists-table.js +23 -9
  47. package/dist/engine/boot-validator/config-deps.js +71 -23
  48. package/dist/engine/boot-validator/config-edit-action-rules.d.ts +17 -0
  49. package/dist/engine/boot-validator/config-edit-action-rules.js +17 -0
  50. package/dist/engine/boot-validator/config-key-rules.d.ts +117 -0
  51. package/dist/engine/boot-validator/config-key-rules.js +117 -0
  52. package/dist/engine/boot-validator/custom-screen-write-qns.js +6 -2
  53. package/dist/engine/boot-validator/derived-sql-fields-rules.d.ts +77 -0
  54. package/dist/engine/boot-validator/derived-sql-fields-rules.js +77 -0
  55. package/dist/engine/boot-validator/derived-sql-fields.js +53 -17
  56. package/dist/engine/boot-validator/detail-screens.js +10 -4
  57. package/dist/engine/boot-validator/entity-declaration-rules.d.ts +92 -0
  58. package/dist/engine/boot-validator/entity-declaration-rules.js +92 -0
  59. package/dist/engine/boot-validator/entity-handler-access-rules.d.ts +102 -0
  60. package/dist/engine/boot-validator/entity-handler-access-rules.js +102 -0
  61. package/dist/engine/boot-validator/entity-handler.d.ts +0 -7
  62. package/dist/engine/boot-validator/entity-handler.js +259 -355
  63. package/dist/engine/boot-validator/entity-image-variants.d.ts +2 -0
  64. package/dist/engine/boot-validator/entity-image-variants.js +91 -0
  65. package/dist/engine/boot-validator/entity-list-aggregate-options.js +8 -2
  66. package/dist/engine/boot-validator/entity-reference-embedded-rules.d.ts +117 -0
  67. package/dist/engine/boot-validator/entity-reference-embedded-rules.js +117 -0
  68. package/dist/engine/boot-validator/entity-select-image-rules.d.ts +122 -0
  69. package/dist/engine/boot-validator/entity-select-image-rules.js +122 -0
  70. package/dist/engine/boot-validator/entity-select.d.ts +8 -0
  71. package/dist/engine/boot-validator/entity-select.js +197 -0
  72. package/dist/engine/boot-validator/entity-structure-rules.d.ts +107 -0
  73. package/dist/engine/boot-validator/entity-structure-rules.js +107 -0
  74. package/dist/engine/boot-validator/field-conditions-rules.d.ts +92 -0
  75. package/dist/engine/boot-validator/field-conditions-rules.js +92 -0
  76. package/dist/engine/boot-validator/field-conditions.js +67 -22
  77. package/dist/engine/boot-validator/form-derivations-rules.d.ts +77 -0
  78. package/dist/engine/boot-validator/form-derivations-rules.js +77 -0
  79. package/dist/engine/boot-validator/form-derivations.js +52 -18
  80. package/dist/engine/boot-validator/global-tenancy.js +13 -7
  81. package/dist/engine/boot-validator/handler-declaration-rules.d.ts +72 -0
  82. package/dist/engine/boot-validator/handler-declaration-rules.js +72 -0
  83. package/dist/engine/boot-validator/handler-field-references-rules.d.ts +22 -0
  84. package/dist/engine/boot-validator/handler-field-references-rules.js +22 -0
  85. package/dist/engine/boot-validator/handler-field-references.js +14 -6
  86. package/dist/engine/boot-validator/list-bulk-actions-rules.d.ts +42 -0
  87. package/dist/engine/boot-validator/list-bulk-actions-rules.js +42 -0
  88. package/dist/engine/boot-validator/list-bulk-actions.js +29 -11
  89. package/dist/engine/boot-validator/list-column-layout.js +22 -10
  90. package/dist/engine/boot-validator/list-query-rules.d.ts +107 -0
  91. package/dist/engine/boot-validator/list-query-rules.js +107 -0
  92. package/dist/engine/boot-validator/list-table-aggregate-options.js +43 -15
  93. package/dist/engine/boot-validator/list-table-aggregate-query.js +7 -3
  94. package/dist/engine/boot-validator/list-table-aggregate-rules.d.ts +82 -0
  95. package/dist/engine/boot-validator/list-table-aggregate-rules.js +82 -0
  96. package/dist/engine/boot-validator/list-table-export-options.js +19 -7
  97. package/dist/engine/boot-validator/list-table-options.js +33 -13
  98. package/dist/engine/boot-validator/list-table-reject-unknown-keys.js +6 -2
  99. package/dist/engine/boot-validator/list-table-rules.d.ts +132 -0
  100. package/dist/engine/boot-validator/list-table-rules.js +132 -0
  101. package/dist/engine/boot-validator/nav-rules.d.ts +42 -0
  102. package/dist/engine/boot-validator/nav-rules.js +42 -0
  103. package/dist/engine/boot-validator/nav.js +29 -15
  104. package/dist/engine/boot-validator/ownership-rules.d.ts +27 -0
  105. package/dist/engine/boot-validator/ownership-rules.js +27 -0
  106. package/dist/engine/boot-validator/ownership.js +28 -12
  107. package/dist/engine/boot-validator/parent-ref.js +32 -20
  108. package/dist/engine/boot-validator/projection-list-screens.js +76 -35
  109. package/dist/engine/boot-validator/query-output-columns.js +9 -3
  110. package/dist/engine/boot-validator/query-refs.js +20 -10
  111. package/dist/engine/boot-validator/query-rules.d.ts +37 -0
  112. package/dist/engine/boot-validator/query-rules.js +37 -0
  113. package/dist/engine/boot-validator/read-gate.js +14 -10
  114. package/dist/engine/boot-validator/record-owned.js +5 -1
  115. package/dist/engine/boot-validator/related-list-table-rules.js +17 -7
  116. package/dist/engine/boot-validator/screens-actions-rules.d.ts +185 -0
  117. package/dist/engine/boot-validator/screens-actions-rules.js +185 -0
  118. package/dist/engine/boot-validator/screens-actions.js +169 -93
  119. package/dist/engine/boot-validator/screens-dashboard-chart-rules.d.ts +87 -0
  120. package/dist/engine/boot-validator/screens-dashboard-chart-rules.js +87 -0
  121. package/dist/engine/boot-validator/screens-dashboard-rules.d.ts +227 -0
  122. package/dist/engine/boot-validator/screens-dashboard-rules.js +227 -0
  123. package/dist/engine/boot-validator/screens-dashboard.js +222 -85
  124. package/dist/engine/boot-validator/screens-forms-layout-rules.d.ts +122 -0
  125. package/dist/engine/boot-validator/screens-forms-layout-rules.js +122 -0
  126. package/dist/engine/boot-validator/screens-forms-rules.d.ts +152 -0
  127. package/dist/engine/boot-validator/screens-forms-rules.js +152 -0
  128. package/dist/engine/boot-validator/screens-forms.js +240 -112
  129. package/dist/engine/boot-validator/screens-kind-config-edit.js +72 -16
  130. package/dist/engine/boot-validator/screens-kind-entity-edit.js +15 -7
  131. package/dist/engine/boot-validator/screens-kind-entity-list.js +57 -32
  132. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +92 -0
  133. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +92 -0
  134. package/dist/engine/boot-validator/screens-kind-projection-detail.js +85 -47
  135. package/dist/engine/boot-validator/screens-kind-rules.d.ts +137 -0
  136. package/dist/engine/boot-validator/screens-kind-rules.js +137 -0
  137. package/dist/engine/boot-validator/screens-kind-secret-mint.js +18 -8
  138. package/dist/engine/boot-validator/screens-kind-shared.js +40 -22
  139. package/dist/engine/boot-validator/screens-lists-rules.d.ts +82 -0
  140. package/dist/engine/boot-validator/screens-lists-rules.js +82 -0
  141. package/dist/engine/boot-validator/screens-lists.js +90 -45
  142. package/dist/engine/boot-validator/screens-rules.d.ts +57 -0
  143. package/dist/engine/boot-validator/screens-rules.js +57 -0
  144. package/dist/engine/boot-validator/screens.js +17 -12
  145. package/dist/engine/boot-validator/transaction-phases.js +12 -4
  146. package/dist/engine/boot-validator/transfer-graph.js +17 -11
  147. package/dist/engine/boot-validator/url-prefill-fields.js +9 -5
  148. package/dist/engine/boot-validator/workspaces.js +11 -5
  149. package/dist/engine/boot-validator/zod-shape.js +6 -2
  150. package/dist/engine/entity-handlers.d.ts +1 -0
  151. package/dist/engine/entity-handlers.js +3 -0
  152. package/dist/engine/entity-list-runtime-options.js +23 -29
  153. package/dist/engine/extensions/tenant-data.d.ts +3 -0
  154. package/dist/engine/factories.d.ts +1 -1
  155. package/dist/engine/factories.js +4 -3
  156. package/dist/engine/index.d.ts +4 -2
  157. package/dist/engine/index.js +2 -0
  158. package/dist/engine/project-app-schema-for-roles.js +29 -14
  159. package/dist/engine/registry-facade.js +7 -8
  160. package/dist/engine/registry-validate.js +5 -1
  161. package/dist/engine/soft-delete-cleanup.d.ts +1 -0
  162. package/dist/engine/soft-delete-cleanup.js +5 -0
  163. package/dist/engine/steps/describe-workflow-step-error.js +1 -0
  164. package/dist/es-ops/operations-schema.d.ts +1 -1
  165. package/dist/event-store/ensure-dead-letter-table.d.ts +2 -0
  166. package/dist/event-store/ensure-dead-letter-table.js +10 -0
  167. package/dist/event-store/rebuild-dead-letter.js +2 -8
  168. package/dist/event-store/upcaster-dead-letter.js +2 -8
  169. package/dist/files/copy-pending-file-refs-to-tenant.d.ts +28 -0
  170. package/dist/files/copy-pending-file-refs-to-tenant.js +87 -0
  171. package/dist/files/file-routes.d.ts +1 -1
  172. package/dist/files/file-routes.js +21 -6
  173. package/dist/files/index.d.ts +2 -0
  174. package/dist/files/index.js +1 -0
  175. package/dist/i18n/required-surface-keys.js +1 -0
  176. package/dist/jobs/job-runner-helpers.js +1 -0
  177. package/dist/jobs/job-runner.js +7 -12
  178. package/dist/logging/utils.js +30 -60
  179. package/dist/observability/metrics-handle.js +10 -21
  180. package/dist/pipeline/cascade-handler.js +7 -6
  181. package/dist/pipeline/dispatch-query.js +18 -5
  182. package/dist/pipeline/dispatch-shared.d.ts +1 -0
  183. package/dist/pipeline/dispatch-shared.js +3 -1
  184. package/dist/pipeline/dispatch-write.js +10 -12
  185. package/dist/pipeline/dispatcher.js +12 -14
  186. package/dist/pipeline/event-dispatcher-admin.js +9 -8
  187. package/dist/pipeline/event-dispatcher-delivery.d.ts +19 -1
  188. package/dist/pipeline/event-dispatcher-delivery.js +121 -29
  189. package/dist/pipeline/event-dispatcher.d.ts +5 -1
  190. package/dist/pipeline/event-dispatcher.js +28 -21
  191. package/dist/pipeline/handler-context-phase-denials.js +2 -0
  192. package/dist/pipeline/multi-stream-apply-context.js +12 -20
  193. package/dist/pipeline/system-hooks.d.ts +4 -1
  194. package/dist/pipeline/system-hooks.js +79 -6
  195. package/dist/pipeline/system-identity-switch.js +10 -7
  196. package/dist/search/build-search-snippet.d.ts +9 -0
  197. package/dist/search/build-search-snippet.js +40 -0
  198. package/dist/search/index.d.ts +1 -0
  199. package/dist/search/index.js +1 -0
  200. package/dist/search/meilisearch-adapter.d.ts +32 -0
  201. package/dist/search/meilisearch-adapter.js +153 -56
  202. package/dist/search/meilisearch-chunking.d.ts +21 -0
  203. package/dist/search/meilisearch-chunking.js +96 -0
  204. package/dist/search/reindex-entity.d.ts +1 -0
  205. package/dist/search/reindex-entity.js +97 -52
  206. package/dist/ui-types/index.d.ts +1 -1
  207. package/dist/upgrade-cli.js +3 -14
  208. package/package.json +3 -3
  209. package/src/changes.json +73 -0
@@ -1,6 +1,8 @@
1
1
  import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
2
2
  import { join, relative } from "node:path";
3
3
  import { extractDispatcherWriteQnsFromSource, validateDispatcherWriteQn, } from "../write-handler-qn-extract.js";
4
+ import { bootRuleError } from "./boot-rule.js";
5
+ import { SCREEN_RULES } from "./screens-rules.js";
4
6
  const SKIP_SEGMENTS = new Set(["node_modules", ".kumiko", "dist", "dist-server", "__tests__"]);
5
7
  function collectAppSourceFiles(dir, out) {
6
8
  let entries;
@@ -70,6 +72,8 @@ export function validateAppCustomScreenWriteQns(appRoot, knownQns) {
70
72
  if (violations.length === 0)
71
73
  return;
72
74
  const lines = violations.map((v) => ` - ${v.file}: "${v.qn}" — ${v.reason}`);
73
- throw new Error(`[kumiko:boot] ${violations.length} invalid dispatcher.write QN(s) in app source:\n${lines.join("\n")}\n` +
74
- ` Check spelling against registered write handlers (expected "<feature>:write:<handler>").`);
75
+ throw bootRuleError(SCREEN_RULES.customWriteQnUnregistered, {
76
+ message: `[kumiko:boot] ${violations.length} invalid dispatcher.write QN(s) in app source:\n${lines.join("\n")}\n` +
77
+ ` Check spelling against registered write handlers (expected "<feature>:write:<handler>").`,
78
+ });
75
79
  }
@@ -0,0 +1,77 @@
1
+ export declare const DERIVED_SQL_FIELD_RULES: {
2
+ readonly unknownField: {
3
+ readonly id: "derived-field/unknown-field";
4
+ readonly summary: "Every field a SQL derived field reads is a field of the entity.";
5
+ readonly fix: "Name an existing field of the entity (or of the related entity).";
6
+ };
7
+ readonly unsupportedFieldType: {
8
+ readonly id: "derived-field/unsupported-field-type";
9
+ readonly summary: "A SQL derived field reads only scalar field types.";
10
+ readonly fix: "Read a text, number, decimal, boolean, date or timestamp field; money only as the measure of a related first.";
11
+ };
12
+ readonly encryptedField: {
13
+ readonly id: "derived-field/encrypted-field";
14
+ readonly summary: "A SQL derived field does not read encrypted or secret fields.";
15
+ readonly fix: "Read a field that is neither encrypted nor secret.";
16
+ };
17
+ readonly valueTypeMismatch: {
18
+ readonly id: "derived-field/value-type-mismatch";
19
+ readonly summary: "The derived field's valueType matches the type of the value it computes.";
20
+ readonly fix: "Set valueType to the expected value type.";
21
+ };
22
+ readonly labelNeedsReference: {
23
+ readonly id: "derived-field/label-needs-reference";
24
+ readonly summary: "A measure with label: true reads a reference field (with a labelField).";
25
+ readonly fix: "Measure a reference field that declares a labelField, or drop label: true.";
26
+ };
27
+ readonly activeOnNotDate: {
28
+ readonly id: "derived-field/active-on-not-date";
29
+ readonly summary: "The activeOn from/to fields are date fields.";
30
+ readonly fix: "Use date fields for activeOn.from and activeOn.to.";
31
+ };
32
+ readonly inOperatorList: {
33
+ readonly id: "derived-field/in-operator-list";
34
+ readonly summary: 'A where condition with op "in" takes a list, and only "in" does.';
35
+ readonly fix: 'Use a list value exactly with op "in".';
36
+ };
37
+ readonly nullOperator: {
38
+ readonly id: "derived-field/null-operator";
39
+ readonly summary: "A where condition with a null value uses op eq or ne.";
40
+ readonly fix: "Use op eq or ne for null, or give a value.";
41
+ };
42
+ readonly relativeDateFieldType: {
43
+ readonly id: "derived-field/relative-date-field-type";
44
+ readonly summary: "A where condition with today needs a date field and with now a timestamp field.";
45
+ readonly fix: "Compare today with a date field and now with a timestamp field.";
46
+ };
47
+ readonly sortableNeedsJoinIndex: {
48
+ readonly id: "derived-field/sortable-needs-join-index";
49
+ readonly summary: "A sortable related derived field has an index on the related table's join column.";
50
+ readonly fix: 'Declare indexes: [{ columns: ["<field>"] }] on the related entity.';
51
+ };
52
+ readonly unknownRelatedEntity: {
53
+ readonly id: "derived-field/unknown-related-entity";
54
+ readonly summary: "The related entity of a derived field is registered.";
55
+ readonly fix: "Register the entity or fix the entity name.";
56
+ };
57
+ readonly coalesceEmpty: {
58
+ readonly id: "derived-field/coalesce-empty";
59
+ readonly summary: "A coalesce derived field lists at least one field.";
60
+ readonly fix: "Add fields to coalesce.";
61
+ };
62
+ readonly coalesceMixedTypes: {
63
+ readonly id: "derived-field/coalesce-mixed-types";
64
+ readonly summary: "All coalesce fields have the same type.";
65
+ readonly fix: "Coalesce fields of one type.";
66
+ };
67
+ readonly moneyNeedsSql: {
68
+ readonly id: "derived-field/money-needs-sql";
69
+ readonly summary: 'A derived field with valueType "money" is a sql derived field.';
70
+ readonly fix: "Use a sql related first measure on a money field.";
71
+ };
72
+ readonly sortableNeedsSql: {
73
+ readonly id: "derived-field/sortable-needs-sql";
74
+ readonly summary: "Only sql derived fields are sortable.";
75
+ readonly fix: "Make the field a sql derived field or drop sortable.";
76
+ };
77
+ };
@@ -0,0 +1,77 @@
1
+ export const DERIVED_SQL_FIELD_RULES = {
2
+ unknownField: {
3
+ id: "derived-field/unknown-field",
4
+ summary: "Every field a SQL derived field reads is a field of the entity.",
5
+ fix: "Name an existing field of the entity (or of the related entity).",
6
+ },
7
+ unsupportedFieldType: {
8
+ id: "derived-field/unsupported-field-type",
9
+ summary: "A SQL derived field reads only scalar field types.",
10
+ fix: "Read a text, number, decimal, boolean, date or timestamp field; money only as the measure of a related first.",
11
+ },
12
+ encryptedField: {
13
+ id: "derived-field/encrypted-field",
14
+ summary: "A SQL derived field does not read encrypted or secret fields.",
15
+ fix: "Read a field that is neither encrypted nor secret.",
16
+ },
17
+ valueTypeMismatch: {
18
+ id: "derived-field/value-type-mismatch",
19
+ summary: "The derived field's valueType matches the type of the value it computes.",
20
+ fix: "Set valueType to the expected value type.",
21
+ },
22
+ labelNeedsReference: {
23
+ id: "derived-field/label-needs-reference",
24
+ summary: "A measure with label: true reads a reference field (with a labelField).",
25
+ fix: "Measure a reference field that declares a labelField, or drop label: true.",
26
+ },
27
+ activeOnNotDate: {
28
+ id: "derived-field/active-on-not-date",
29
+ summary: "The activeOn from/to fields are date fields.",
30
+ fix: "Use date fields for activeOn.from and activeOn.to.",
31
+ },
32
+ inOperatorList: {
33
+ id: "derived-field/in-operator-list",
34
+ summary: 'A where condition with op "in" takes a list, and only "in" does.',
35
+ fix: 'Use a list value exactly with op "in".',
36
+ },
37
+ nullOperator: {
38
+ id: "derived-field/null-operator",
39
+ summary: "A where condition with a null value uses op eq or ne.",
40
+ fix: "Use op eq or ne for null, or give a value.",
41
+ },
42
+ relativeDateFieldType: {
43
+ id: "derived-field/relative-date-field-type",
44
+ summary: "A where condition with today needs a date field and with now a timestamp field.",
45
+ fix: "Compare today with a date field and now with a timestamp field.",
46
+ },
47
+ sortableNeedsJoinIndex: {
48
+ id: "derived-field/sortable-needs-join-index",
49
+ summary: "A sortable related derived field has an index on the related table's join column.",
50
+ fix: 'Declare indexes: [{ columns: ["<field>"] }] on the related entity.',
51
+ },
52
+ unknownRelatedEntity: {
53
+ id: "derived-field/unknown-related-entity",
54
+ summary: "The related entity of a derived field is registered.",
55
+ fix: "Register the entity or fix the entity name.",
56
+ },
57
+ coalesceEmpty: {
58
+ id: "derived-field/coalesce-empty",
59
+ summary: "A coalesce derived field lists at least one field.",
60
+ fix: "Add fields to coalesce.",
61
+ },
62
+ coalesceMixedTypes: {
63
+ id: "derived-field/coalesce-mixed-types",
64
+ summary: "All coalesce fields have the same type.",
65
+ fix: "Coalesce fields of one type.",
66
+ },
67
+ moneyNeedsSql: {
68
+ id: "derived-field/money-needs-sql",
69
+ summary: 'A derived field with valueType "money" is a sql derived field.',
70
+ fix: "Use a sql related first measure on a money field.",
71
+ },
72
+ sortableNeedsSql: {
73
+ id: "derived-field/sortable-needs-sql",
74
+ summary: "Only sql derived fields are sortable.",
75
+ fix: "Make the field a sql derived field or drop sortable.",
76
+ },
77
+ };
@@ -1,6 +1,8 @@
1
1
  import { isSqlDerivedField, } from "@cosmicdrift/kumiko-types/fields";
2
2
  import { holdsCiphertextOrSecret } from "../../db/entity-field-encryption.js";
3
3
  import { parseRefTargetEntityName } from "../parse-ref-target.js";
4
+ import { bootRuleError } from "./boot-rule.js";
5
+ import { DERIVED_SQL_FIELD_RULES } from "./derived-sql-fields-rules.js";
4
6
  export function isSortableSqlDerivedField(entity, name) {
5
7
  const def = entity.derivedFields?.[name];
6
8
  return def !== undefined && isSqlDerivedField(def) && def.sortable === true;
@@ -26,26 +28,38 @@ function valueTypeOfField(entity, field) {
26
28
  }
27
29
  function requireUsableField(site, entity, field, role) {
28
30
  if (field !== "id" && entity.fields[field] === undefined) {
29
- throw new Error(`${site.where}: ${role} "${field}" is not a field of the entity.`);
31
+ throw bootRuleError(DERIVED_SQL_FIELD_RULES.unknownField, {
32
+ message: `${site.where}: ${role} "${field}" is not a field of the entity.`,
33
+ });
30
34
  }
31
35
  if (valueTypeOfField(entity, field) === undefined) {
32
- throw new Error(`${site.where}: ${role} "${field}" has type "${entity.fields[field]?.type}", which a SQL derived field cannot read (compound types are not supported; money only as the measure of a related first).`);
36
+ throw bootRuleError(DERIVED_SQL_FIELD_RULES.unsupportedFieldType, {
37
+ message: `${site.where}: ${role} "${field}" has type "${entity.fields[field]?.type}", which a SQL derived field cannot read (compound types are not supported; money only as the measure of a related first).`,
38
+ });
33
39
  }
34
40
  if (holdsCiphertextOrSecret(entity, field)) {
35
- throw new Error(`${site.where}: ${role} "${field}" is encrypted or secret; a SQL derived field would expose or order by it.`);
41
+ throw bootRuleError(DERIVED_SQL_FIELD_RULES.encryptedField, {
42
+ message: `${site.where}: ${role} "${field}" is encrypted or secret; a SQL derived field would expose or order by it.`,
43
+ });
36
44
  }
37
45
  }
38
46
  function requireValueType(site, def, expected) {
39
47
  if (def.valueType !== expected) {
40
- throw new Error(`${site.where}: valueType must be "${expected}", got "${def.valueType}".`);
48
+ throw bootRuleError(DERIVED_SQL_FIELD_RULES.valueTypeMismatch, {
49
+ message: `${site.where}: valueType must be "${expected}", got "${def.valueType}".`,
50
+ });
41
51
  }
42
52
  }
43
53
  function requireMoneyMeasure(site, def, related, measure) {
44
54
  if (measure.label === true) {
45
- throw new Error(`${site.where}: label: true needs a reference field, not money.`);
55
+ throw bootRuleError(DERIVED_SQL_FIELD_RULES.labelNeedsReference, {
56
+ message: `${site.where}: label: true needs a reference field, not money.`,
57
+ });
46
58
  }
47
59
  if (holdsCiphertextOrSecret(related, measure.field)) {
48
- throw new Error(`${site.where}: measure field "${measure.field}" is encrypted or secret; a SQL derived field would expose or order by it.`);
60
+ throw bootRuleError(DERIVED_SQL_FIELD_RULES.encryptedField, {
61
+ message: `${site.where}: measure field "${measure.field}" is encrypted or secret; a SQL derived field would expose or order by it.`,
62
+ });
49
63
  }
50
64
  requireUsableField(site, related, measure.orderBy, "measure orderBy");
51
65
  requireValueType(site, def, "money");
@@ -55,7 +69,9 @@ function validateCondition(site, related, condition) {
55
69
  for (const field of [condition.activeOn.from, condition.activeOn.to]) {
56
70
  requireUsableField(site, related, field, "activeOn field");
57
71
  if (valueTypeOfField(related, field) !== "date") {
58
- throw new Error(`${site.where}: activeOn field "${field}" must be a date field.`);
72
+ throw bootRuleError(DERIVED_SQL_FIELD_RULES.activeOnNotDate, {
73
+ message: `${site.where}: activeOn field "${field}" must be a date field.`,
74
+ });
59
75
  }
60
76
  }
61
77
  // skip: activeOn carries no op/value to check
@@ -65,15 +81,21 @@ function validateCondition(site, related, condition) {
65
81
  const { value, op } = condition;
66
82
  const isList = Array.isArray(value);
67
83
  if ((op === "in") !== isList) {
68
- throw new Error(`${site.where}: where "${condition.field}": op "in" takes a list, and only "in" does.`);
84
+ throw bootRuleError(DERIVED_SQL_FIELD_RULES.inOperatorList, {
85
+ message: `${site.where}: where "${condition.field}": op "in" takes a list, and only "in" does.`,
86
+ });
69
87
  }
70
88
  if (value === null && op !== "eq" && op !== "ne") {
71
- throw new Error(`${site.where}: where "${condition.field}": null is only valid with eq/ne.`);
89
+ throw bootRuleError(DERIVED_SQL_FIELD_RULES.nullOperator, {
90
+ message: `${site.where}: where "${condition.field}": null is only valid with eq/ne.`,
91
+ });
72
92
  }
73
93
  if (typeof value === "object" && value !== null && !isList) {
74
94
  const expected = "today" in value ? "date" : "timestamp";
75
95
  if (valueTypeOfField(related, condition.field) !== expected) {
76
- throw new Error(`${site.where}: where "${condition.field}": ${expected === "date" ? "today" : "now"} needs a ${expected} field.`);
96
+ throw bootRuleError(DERIVED_SQL_FIELD_RULES.relativeDateFieldType, {
97
+ message: `${site.where}: where "${condition.field}": ${expected === "date" ? "today" : "now"} needs a ${expected} field.`,
98
+ });
77
99
  }
78
100
  }
79
101
  }
@@ -88,14 +110,18 @@ function requireJoinIndex(site, related, field, relations) {
88
110
  return first === field || (first === "tenantId" && second === field);
89
111
  });
90
112
  if (!indexed) {
91
- throw new Error(`${site.where}: sortable needs an index on the related table's "${field}"; declare indexes: [{ columns: ["${field}"] }] (or ["tenantId", "${field}"]) on that entity.`);
113
+ throw bootRuleError(DERIVED_SQL_FIELD_RULES.sortableNeedsJoinIndex, {
114
+ message: `${site.where}: sortable needs an index on the related table's "${field}"; declare indexes: [{ columns: ["${field}"] }] (or ["tenantId", "${field}"]) on that entity.`,
115
+ });
92
116
  }
93
117
  }
94
118
  function validateRelated(site, own, def, spec, allEntities, relations) {
95
119
  const relatedName = parseRefTargetEntityName(spec.entity);
96
120
  const related = allEntities.get(relatedName);
97
121
  if (related === undefined) {
98
- throw new Error(`${site.where}: related entity "${spec.entity}" is not registered.`);
122
+ throw bootRuleError(DERIVED_SQL_FIELD_RULES.unknownRelatedEntity, {
123
+ message: `${site.where}: related entity "${spec.entity}" is not registered.`,
124
+ });
99
125
  }
100
126
  requireUsableField(site, related, spec.on.field, "on.field");
101
127
  if (def.sortable === true) {
@@ -127,7 +153,9 @@ function requireMeasureValueType(site, def, measure, related) {
127
153
  if (measure.label === true) {
128
154
  const measured = related.fields[measure.field];
129
155
  if (measured?.type !== "reference" || measured.labelField === undefined) {
130
- throw new Error(`${site.where}: label: true needs a reference field with a labelField.`);
156
+ throw bootRuleError(DERIVED_SQL_FIELD_RULES.labelNeedsReference, {
157
+ message: `${site.where}: label: true needs a reference field with a labelField.`,
158
+ });
131
159
  }
132
160
  requireValueType(site, def, "text");
133
161
  // skip: a label is always text, the measured field's own type does not apply
@@ -139,14 +167,18 @@ function requireMeasureValueType(site, def, measure, related) {
139
167
  }
140
168
  function validateCoalesce(site, own, def, fields) {
141
169
  if (fields.length === 0)
142
- throw new Error(`${site.where}: coalesce needs at least one field.`);
170
+ throw bootRuleError(DERIVED_SQL_FIELD_RULES.coalesceEmpty, {
171
+ message: `${site.where}: coalesce needs at least one field.`,
172
+ });
143
173
  const types = new Set();
144
174
  for (const field of fields) {
145
175
  requireUsableField(site, own, field, "coalesce field");
146
176
  types.add(valueTypeOfField(own, field));
147
177
  }
148
178
  if (types.size !== 1) {
149
- throw new Error(`${site.where}: coalesce fields must all have the same type.`);
179
+ throw bootRuleError(DERIVED_SQL_FIELD_RULES.coalesceMixedTypes, {
180
+ message: `${site.where}: coalesce fields must all have the same type.`,
181
+ });
150
182
  }
151
183
  const [only] = types;
152
184
  if (only !== undefined)
@@ -168,10 +200,14 @@ export function validateSqlDerivedFields(features) {
168
200
  const site = { where: `Entity "${entityName}" derived field "${key}"` };
169
201
  if (!isSqlDerivedField(def)) {
170
202
  if (def.valueType === "money") {
171
- throw new Error(`${site.where}: valueType "money" needs a sql derived field (related first on a money field); a JS derive has no currency column.`);
203
+ throw bootRuleError(DERIVED_SQL_FIELD_RULES.moneyNeedsSql, {
204
+ message: `${site.where}: valueType "money" needs a sql derived field (related first on a money field); a JS derive has no currency column.`,
205
+ });
172
206
  }
173
207
  if ("sortable" in def) {
174
- throw new Error(`${site.where}: sortable needs a sql derived field; a JS derive cannot order in SQL.`);
208
+ throw bootRuleError(DERIVED_SQL_FIELD_RULES.sortableNeedsSql, {
209
+ message: `${site.where}: sortable needs a sql derived field; a JS derive cannot order in SQL.`,
210
+ });
175
211
  }
176
212
  continue;
177
213
  }
@@ -1,5 +1,7 @@
1
1
  import { qualifyEntityName } from "../qualified-name.js";
2
+ import { bootRuleError } from "./boot-rule.js";
2
3
  import { findEntityFeature } from "./screens-kind-shared.js";
4
+ import { SCREEN_RULES } from "./screens-rules.js";
3
5
  // Entity name → the one screen that declares detailFor: "<entity>". Built
4
6
  // once, up front (before the per-feature validateScreens loop) so both this
5
7
  // module's own uniqueness check AND rowAction entity-targets (in screens-actions.ts)
@@ -16,13 +18,17 @@ export function collectDetailForScreens(features, featureMap) {
16
18
  const qualified = qualifyEntityName(feature.name, "screen", screenId);
17
19
  const existingQn = screenQnByEntity.get(detailFor);
18
20
  if (existingQn !== undefined) {
19
- throw new Error(`[detailFor] Screens "${existingQn}" and "${qualified}" both declare ` +
20
- `detailFor: "${detailFor}" — only one screen may be the detail view for an entity.`);
21
+ throw bootRuleError(SCREEN_RULES.detailForDuplicate, {
22
+ message: `[detailFor] Screens "${existingQn}" and "${qualified}" both declare ` +
23
+ `detailFor: "${detailFor}" — only one screen may be the detail view for an entity.`,
24
+ });
21
25
  }
22
26
  screenQnByEntity.set(detailFor, qualified);
23
27
  if (findEntityFeature(detailFor, featureMap) === undefined) {
24
- throw new Error(`[detailFor] Screen "${qualified}" declares detailFor: "${detailFor}", ` +
25
- `but no feature registers an entity with that name. Set detailFor to a registered entity name or remove it.`);
28
+ throw bootRuleError(SCREEN_RULES.detailForUnknownEntity, {
29
+ message: `[detailFor] Screen "${qualified}" declares detailFor: "${detailFor}", ` +
30
+ `but no feature registers an entity with that name. Set detailFor to a registered entity name or remove it.`,
31
+ });
26
32
  }
27
33
  result.set(detailFor, { featureName: feature.name, screen });
28
34
  }
@@ -0,0 +1,92 @@
1
+ export declare const ENTITY_DECLARATION_RULES: {
2
+ readonly parentRefTypeFieldUnknown: {
3
+ readonly id: "parent-ref/entity-type-field-unknown";
4
+ readonly summary: "parentRef.entityTypeField names a declared field of the entity.";
5
+ readonly fix: "Point entityTypeField at a real field on the entity.";
6
+ };
7
+ readonly parentRefIdFieldUnknown: {
8
+ readonly id: "parent-ref/entity-id-field-unknown";
9
+ readonly summary: "parentRef.entityIdField names a declared field of the entity.";
10
+ readonly fix: "Point entityIdField at a real field on the entity.";
11
+ };
12
+ readonly parentRefAllowedTypeUnregistered: {
13
+ readonly id: "parent-ref/allowed-type-unregistered";
14
+ readonly summary: "parentRef.allowedTypes names only registered entities.";
15
+ readonly fix: "Remove the name from allowedTypes, or register the entity.";
16
+ };
17
+ readonly parentRefAllowedTypeHasParentRef: {
18
+ readonly id: "parent-ref/allowed-type-has-parent-ref";
19
+ readonly summary: "A parentRef host entity does not itself declare a parentRef (no recursive gating).";
20
+ readonly fix: "Remove the host from allowedTypes, or drop its own parentRef.";
21
+ };
22
+ readonly parentRefHandWrittenQuery: {
23
+ readonly id: "parent-ref/hand-written-query-handler";
24
+ readonly summary: "Query handlers on an entity with parentRef carry the entity-convention brand, so the parent-ref read-gate applies.";
25
+ readonly fix: "Register the handler via defineEntityListHandler/defineEntityDetailHandler, or pass parentVisibility to the executor.";
26
+ };
27
+ readonly readGateWithParentRef: {
28
+ readonly id: "read-gate/with-parent-ref";
29
+ readonly summary: "An entity with readGate does not also declare parentRef.";
30
+ readonly fix: "Drop readGate or parentRef.";
31
+ };
32
+ readonly readGateAnyAndAllLinks: {
33
+ readonly id: "read-gate/any-and-all-links";
34
+ readonly summary: "A readGate declares anyLink or allLinks, not both.";
35
+ readonly fix: "Pick one of anyLink and allLinks.";
36
+ };
37
+ readonly readGateLinkEntityUnregistered: {
38
+ readonly id: "read-gate/link-entity-unregistered";
39
+ readonly summary: "A readGate link names a registered entity.";
40
+ readonly fix: "Register the entity or fix the readGate link entity name.";
41
+ };
42
+ readonly readGateLinkWithoutParentRef: {
43
+ readonly id: "read-gate/link-entity-without-parent-ref";
44
+ readonly summary: "A readGate link entity declares a parentRef, because its host visibility is what the gate checks.";
45
+ readonly fix: "Declare a parentRef on the link entity or use another entity.";
46
+ };
47
+ readonly readGateLinkFieldUnknown: {
48
+ readonly id: "read-gate/link-field-unknown";
49
+ readonly summary: "A readGate link field is a field of the link entity.";
50
+ readonly fix: "Point the link field at a real field of the link entity.";
51
+ };
52
+ readonly readGateFileOwnerFieldType: {
53
+ readonly id: "read-gate/file-owner-field-type";
54
+ readonly summary: "readGate.fileOwner.field is a single file or image field.";
55
+ readonly fix: "Point fileOwner.field at a single file or image field.";
56
+ };
57
+ readonly readGateFileOwnerNeedsFiles: {
58
+ readonly id: "read-gate/file-owner-needs-files-feature";
59
+ readonly summary: "readGate.fileOwner requires the files feature to be mounted.";
60
+ readonly fix: "Mount the files feature.";
61
+ };
62
+ readonly readGateHandWrittenReader: {
63
+ readonly id: "read-gate/hand-written-reader";
64
+ readonly summary: "A gated entity's list and detail query handlers are entity-convention handlers, so they cannot bypass the readGate.";
65
+ readonly fix: "Register them via defineEntityListHandler/defineEntityDetailHandler.";
66
+ };
67
+ readonly transferMultipleReference: {
68
+ readonly id: "transfer/multiple-reference-field";
69
+ readonly summary: "A transferable entity declares no multiple reference field to another transferable entity, since the transfer graph cannot match jsonb array rows.";
70
+ readonly fix: "Model the link as a single reference on the owning side, or drop transferable from the entity.";
71
+ };
72
+ readonly transferGraphTooDeep: {
73
+ readonly id: "transfer/graph-too-deep";
74
+ readonly summary: "The tenant-handover transfer graph is not deeper than the maximum depth.";
75
+ readonly fix: 'Flatten the chain, or mark a reference field that should not move with its host `handover: "stay"`.';
76
+ };
77
+ readonly globalWithoutSystemStream: {
78
+ readonly id: "entity/global-without-system-stream";
79
+ readonly summary: 'An entity with tenancy "global" also declares systemStream: true.';
80
+ readonly fix: "Declare systemStream: true on the entity.";
81
+ };
82
+ readonly globalWithoutSystemScope: {
83
+ readonly id: "entity/global-without-system-scope";
84
+ readonly summary: 'A feature that owns an entity with tenancy "global" declares r.systemScope().';
85
+ readonly fix: "Declare r.systemScope() in the owning feature.";
86
+ };
87
+ readonly recordOwnedSerialId: {
88
+ readonly id: "pii/record-owned-serial-id";
89
+ readonly summary: 'A recordOwned (or whenAbsent: "self") field lives only on entities with idType "uuid", because forgetSubject validates the record id as a UUID.';
90
+ readonly fix: 'Set idType: "uuid" on the entity, or give the field a different personal stance.';
91
+ };
92
+ };
@@ -0,0 +1,92 @@
1
+ export const ENTITY_DECLARATION_RULES = {
2
+ parentRefTypeFieldUnknown: {
3
+ id: "parent-ref/entity-type-field-unknown",
4
+ summary: "parentRef.entityTypeField names a declared field of the entity.",
5
+ fix: "Point entityTypeField at a real field on the entity.",
6
+ },
7
+ parentRefIdFieldUnknown: {
8
+ id: "parent-ref/entity-id-field-unknown",
9
+ summary: "parentRef.entityIdField names a declared field of the entity.",
10
+ fix: "Point entityIdField at a real field on the entity.",
11
+ },
12
+ parentRefAllowedTypeUnregistered: {
13
+ id: "parent-ref/allowed-type-unregistered",
14
+ summary: "parentRef.allowedTypes names only registered entities.",
15
+ fix: "Remove the name from allowedTypes, or register the entity.",
16
+ },
17
+ parentRefAllowedTypeHasParentRef: {
18
+ id: "parent-ref/allowed-type-has-parent-ref",
19
+ summary: "A parentRef host entity does not itself declare a parentRef (no recursive gating).",
20
+ fix: "Remove the host from allowedTypes, or drop its own parentRef.",
21
+ },
22
+ parentRefHandWrittenQuery: {
23
+ id: "parent-ref/hand-written-query-handler",
24
+ summary: "Query handlers on an entity with parentRef carry the entity-convention brand, so the parent-ref read-gate applies.",
25
+ fix: "Register the handler via defineEntityListHandler/defineEntityDetailHandler, or pass parentVisibility to the executor.",
26
+ },
27
+ readGateWithParentRef: {
28
+ id: "read-gate/with-parent-ref",
29
+ summary: "An entity with readGate does not also declare parentRef.",
30
+ fix: "Drop readGate or parentRef.",
31
+ },
32
+ readGateAnyAndAllLinks: {
33
+ id: "read-gate/any-and-all-links",
34
+ summary: "A readGate declares anyLink or allLinks, not both.",
35
+ fix: "Pick one of anyLink and allLinks.",
36
+ },
37
+ readGateLinkEntityUnregistered: {
38
+ id: "read-gate/link-entity-unregistered",
39
+ summary: "A readGate link names a registered entity.",
40
+ fix: "Register the entity or fix the readGate link entity name.",
41
+ },
42
+ readGateLinkWithoutParentRef: {
43
+ id: "read-gate/link-entity-without-parent-ref",
44
+ summary: "A readGate link entity declares a parentRef, because its host visibility is what the gate checks.",
45
+ fix: "Declare a parentRef on the link entity or use another entity.",
46
+ },
47
+ readGateLinkFieldUnknown: {
48
+ id: "read-gate/link-field-unknown",
49
+ summary: "A readGate link field is a field of the link entity.",
50
+ fix: "Point the link field at a real field of the link entity.",
51
+ },
52
+ readGateFileOwnerFieldType: {
53
+ id: "read-gate/file-owner-field-type",
54
+ summary: "readGate.fileOwner.field is a single file or image field.",
55
+ fix: "Point fileOwner.field at a single file or image field.",
56
+ },
57
+ readGateFileOwnerNeedsFiles: {
58
+ id: "read-gate/file-owner-needs-files-feature",
59
+ summary: "readGate.fileOwner requires the files feature to be mounted.",
60
+ fix: "Mount the files feature.",
61
+ },
62
+ readGateHandWrittenReader: {
63
+ id: "read-gate/hand-written-reader",
64
+ summary: "A gated entity's list and detail query handlers are entity-convention handlers, so they cannot bypass the readGate.",
65
+ fix: "Register them via defineEntityListHandler/defineEntityDetailHandler.",
66
+ },
67
+ transferMultipleReference: {
68
+ id: "transfer/multiple-reference-field",
69
+ summary: "A transferable entity declares no multiple reference field to another transferable entity, since the transfer graph cannot match jsonb array rows.",
70
+ fix: "Model the link as a single reference on the owning side, or drop transferable from the entity.",
71
+ },
72
+ transferGraphTooDeep: {
73
+ id: "transfer/graph-too-deep",
74
+ summary: "The tenant-handover transfer graph is not deeper than the maximum depth.",
75
+ fix: 'Flatten the chain, or mark a reference field that should not move with its host `handover: "stay"`.',
76
+ },
77
+ globalWithoutSystemStream: {
78
+ id: "entity/global-without-system-stream",
79
+ summary: 'An entity with tenancy "global" also declares systemStream: true.',
80
+ fix: "Declare systemStream: true on the entity.",
81
+ },
82
+ globalWithoutSystemScope: {
83
+ id: "entity/global-without-system-scope",
84
+ summary: 'A feature that owns an entity with tenancy "global" declares r.systemScope().',
85
+ fix: "Declare r.systemScope() in the owning feature.",
86
+ },
87
+ recordOwnedSerialId: {
88
+ id: "pii/record-owned-serial-id",
89
+ summary: 'A recordOwned (or whenAbsent: "self") field lives only on entities with idType "uuid", because forgetSubject validates the record id as a UUID.',
90
+ fix: 'Set idType: "uuid" on the entity, or give the field a different personal stance.',
91
+ },
92
+ };