@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
@@ -20,6 +20,7 @@ export function isTenantLifecycleStatusPlugin(v) {
20
20
  export const TENANT_TEARDOWN_STATUSES = new Set([
21
21
  "destroyRequested",
22
22
  "destroying",
23
+ "destroyHeld",
23
24
  "destroyFailed",
24
25
  "destroyed",
25
26
  ]);
@@ -2,6 +2,8 @@ import { escapeHatchGrantsProblem, isRateLimitDisabled } from "@cosmicdrift/kumi
2
2
  import { reasonProblem } from "../escape-hatch-reason.js";
3
3
  import { accessAllowsAnonymous, declaredPersonalData, personalFieldNames, } from "../personal-data-fields.js";
4
4
  import { ANONYMOUS_ROLE } from "../system-user.js";
5
+ import { bootRuleError } from "./boot-rule.js";
6
+ import { HANDLER_DECLARATION_RULES } from "./handler-declaration-rules.js";
5
7
  import { collectZodObjectKeys } from "./zod-shape.js";
6
8
  // escapeHatch and r.systemScope() can write around the entity's write map
7
9
  // (db.global(), systemDb, SYSTEM identity), so the map no longer vouches for the row.
@@ -50,19 +52,25 @@ function validateOpenToAllReason(feature, kind, handlerName, access) {
50
52
  // skip: reason is well-formed, nothing to validate
51
53
  if (problem === undefined)
52
54
  return;
53
- throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares an invalid ` +
54
- `{ openToAll: ... } — ${problem}. Must be { reason: "<explanation>" } for why any ` +
55
- "authenticated user may call this handler. `{ openToAll: true }` is no longer accepted.");
55
+ throw bootRuleError(HANDLER_DECLARATION_RULES.openToAllReasonInvalid, {
56
+ message: `[Feature ${feature.name}] ${kind} handler "${handlerName}" declares an invalid ` +
57
+ `{ openToAll: ... } — ${problem}. Must be { reason: "<explanation>" } for why any ` +
58
+ "authenticated user may call this handler. `{ openToAll: true }` is no longer accepted.",
59
+ });
56
60
  }
57
61
  function validateEscapeHatchReason(feature, kind, handlerName, escapeHatch) {
58
62
  if (escapeHatch) {
59
63
  const grantsProblem = escapeHatchGrantsProblem(escapeHatch);
60
64
  if (grantsProblem !== undefined) {
61
- throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares an invalid escapeHatch — ${grantsProblem}`);
65
+ throw bootRuleError(HANDLER_DECLARATION_RULES.escapeHatchGrantsInvalid, {
66
+ message: `[Feature ${feature.name}] ${kind} handler "${handlerName}" declares an invalid escapeHatch — ${grantsProblem}`,
67
+ });
62
68
  }
63
69
  const problem = reasonProblem(escapeHatch.reason);
64
70
  if (problem !== undefined) {
65
- throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares an invalid escapeHatch — ${problem}`);
71
+ throw bootRuleError(HANDLER_DECLARATION_RULES.escapeHatchReasonInvalid, {
72
+ message: `[Feature ${feature.name}] ${kind} handler "${handlerName}" declares an invalid escapeHatch — ${problem}`,
73
+ });
66
74
  }
67
75
  }
68
76
  }
@@ -82,7 +90,9 @@ function validatePersonalDataSupportedForKind(feature, kind, handlerName, access
82
90
  ? 'only access.personalData: "public-intake" applies to query handlers, which write ' +
83
91
  "personal data through nested writes of an anonymous request."
84
92
  : "it only applies to write handlers, whose input is checked for personal-data fields.";
85
- throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares ${property} — ${onlyAllowed} Remove the personalData declaration from this handler.`);
93
+ throw bootRuleError(HANDLER_DECLARATION_RULES.personalDataUnsupportedForKind, {
94
+ message: `[Feature ${feature.name}] ${kind} handler "${handlerName}" declares ${property} — ${onlyAllowed} Remove the personalData declaration from this handler.`,
95
+ });
86
96
  }
87
97
  function validatePersonalDataValue(feature, kind, handlerName, access) {
88
98
  const declared = declaredPersonalData(access);
@@ -93,20 +103,26 @@ function validatePersonalDataValue(feature, kind, handlerName, access) {
93
103
  // skip: the one supported value on openToAll
94
104
  if (declared === "tenant-members")
95
105
  return;
96
- throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares an unknown ` +
97
- `openToAll.personalData ${JSON.stringify(declared)} — the only supported value is "tenant-members".`);
106
+ throw bootRuleError(HANDLER_DECLARATION_RULES.openToAllPersonalDataUnknown, {
107
+ message: `[Feature ${feature.name}] ${kind} handler "${handlerName}" declares an unknown ` +
108
+ `openToAll.personalData ${JSON.stringify(declared)} — the only supported value is "tenant-members".`,
109
+ });
98
110
  }
99
111
  if (declared !== "public-intake") {
100
- throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares an unknown ` +
101
- `access.personalData ${JSON.stringify(declared)} — the only supported value is "public-intake".`);
112
+ throw bootRuleError(HANDLER_DECLARATION_RULES.accessPersonalDataUnknown, {
113
+ message: `[Feature ${feature.name}] ${kind} handler "${handlerName}" declares an unknown ` +
114
+ `access.personalData ${JSON.stringify(declared)} — the only supported value is "public-intake".`,
115
+ });
102
116
  }
103
117
  // skip: roles include "anonymous", which personalData: "public-intake" requires
104
118
  if (accessAllowsAnonymous(access))
105
119
  return;
106
- throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares ` +
107
- 'access.personalData: "public-intake" but its roles do not include ' +
108
- `"${ANONYMOUS_ROLE}" — personalData: "public-intake" only applies to handlers ` +
109
- "that allow anonymous callers. Add the anonymous role to access.roles or remove personalData.");
120
+ throw bootRuleError(HANDLER_DECLARATION_RULES.publicIntakeWithoutAnonymous, {
121
+ message: `[Feature ${feature.name}] ${kind} handler "${handlerName}" declares ` +
122
+ 'access.personalData: "public-intake" but its roles do not include ' +
123
+ `"${ANONYMOUS_ROLE}" — personalData: "public-intake" only applies to handlers ` +
124
+ "that allow anonymous callers. Add the anonymous role to access.roles or remove personalData.",
125
+ });
110
126
  }
111
127
  function handlerInputKeys(feature, handlerName, handler) {
112
128
  try {
@@ -114,7 +130,9 @@ function handlerInputKeys(feature, handlerName, handler) {
114
130
  }
115
131
  catch (error) {
116
132
  const reason = error instanceof Error ? error.message : String(error);
117
- throw new Error(`[Feature ${feature.name}] write handler "${handlerName}": ${reason}`);
133
+ throw bootRuleError(HANDLER_DECLARATION_RULES.inputSchemaNotIntrospectable, {
134
+ message: `[Feature ${feature.name}] write handler "${handlerName}": ${reason}`,
135
+ });
118
136
  }
119
137
  }
120
138
  function validateOpenToAllPersonalData(feature, handlerName, handler) {
@@ -128,14 +146,16 @@ function validateOpenToAllPersonalData(feature, handlerName, handler) {
128
146
  // skip: no personal-data fields in the handler's input
129
147
  if (offending.length === 0)
130
148
  return;
131
- throw new Error(`[Feature ${feature.name}] write handler "${handlerName}" declares openToAll and ` +
132
- `accepts personal-data field(s) ${offending.map((f) => `"${f}"`).join(", ")} that are ` +
133
- "not bound to the caller. Choose one: (1) bind rows to the caller — every role in the " +
134
- 'entity\'s access.write is from("user:id", "<ownerField>") for a personal: { of: "<ownerField>" } ' +
135
- 'field, or from("user:id", "id") for a personal: "self" field, with no escapeHatch on the ' +
136
- "handler and no r.systemScope() on its feature; (2) restrict access to roles; (3) declare " +
137
- '{ openToAll: { reason: "<why any signed-in tenant member may write this personal data>", ' +
138
- 'personalData: "tenant-members" } }.');
149
+ throw bootRuleError(HANDLER_DECLARATION_RULES.openToAllPersonalDataUnbound, {
150
+ message: `[Feature ${feature.name}] write handler "${handlerName}" declares openToAll and ` +
151
+ `accepts personal-data field(s) ${offending.map((f) => `"${f}"`).join(", ")} that are ` +
152
+ "not bound to the caller. Choose one: (1) bind rows to the caller — every role in the " +
153
+ 'entity\'s access.write is from("user:id", "<ownerField>") for a personal: { of: "<ownerField>" } ' +
154
+ 'field, or from("user:id", "id") for a personal: "self" field, with no escapeHatch on the ' +
155
+ "handler and no r.systemScope() on its feature; (2) restrict access to roles; (3) declare " +
156
+ '{ openToAll: { reason: "<why any signed-in tenant member may write this personal data>", ' +
157
+ 'personalData: "tenant-members" } }.',
158
+ });
139
159
  }
140
160
  // Anonymous callers all share one user.id, so honorOwnerBindingOverride is always false here.
141
161
  function validateAnonymousPersonalData(feature, handlerName, handler) {
@@ -149,12 +169,30 @@ function validateAnonymousPersonalData(feature, handlerName, handler) {
149
169
  // skip: no personal-data fields in the handler's input
150
170
  if (offending.length === 0)
151
171
  return;
152
- throw new Error(`[Feature ${feature.name}] write handler "${handlerName}" allows anonymous callers ` +
153
- `("${ANONYMOUS_ROLE}" in access.roles) and accepts personal-data field(s) ` +
154
- `${offending.map((f) => `"${f}"`).join(", ")}. Declare ` +
155
- 'access: { roles: [..., "anonymous"], personalData: "public-intake" } — every anonymous ' +
156
- 'request shares one caller identity, so owner-binding via from("user:id", ...) does not ' +
157
- "vouch for it; protection comes from the handler's required rateLimit (per ip).");
172
+ throw bootRuleError(HANDLER_DECLARATION_RULES.anonymousPersonalDataUndeclared, {
173
+ message: `[Feature ${feature.name}] write handler "${handlerName}" allows anonymous callers ` +
174
+ `("${ANONYMOUS_ROLE}" in access.roles) and accepts personal-data field(s) ` +
175
+ `${offending.map((f) => `"${f}"`).join(", ")}. Declare ` +
176
+ 'access: { roles: [..., "anonymous"], personalData: "public-intake" } — every anonymous ' +
177
+ 'request shares one caller identity, so owner-binding via from("user:id", ...) does not ' +
178
+ "vouch for it; protection comes from the handler's required rateLimit (per ip).",
179
+ });
180
+ }
181
+ // Read via `unknown`: access can come from untyped sources (pattern JSON, Designer).
182
+ function validateAnySignedIn(feature, kind, handlerName, access) {
183
+ // skip: openToAll has no anySignedIn, or nothing declared
184
+ if (!("roles" in access) || !("anySignedIn" in access))
185
+ return;
186
+ const declared = access.anySignedIn;
187
+ // skip: a public rule that admits every signed-in caller as well
188
+ if (declared === true && accessAllowsAnonymous(access))
189
+ return;
190
+ const problem = declared === true
191
+ ? `its roles do not include "${ANONYMOUS_ROLE}"; for every signed-in user without anonymous callers use { openToAll: { reason } }`
192
+ : `the only supported value is true, got ${JSON.stringify(declared)}`;
193
+ throw bootRuleError(HANDLER_DECLARATION_RULES.anySignedInInvalid, {
194
+ message: `[Feature ${feature.name}] ${kind} handler "${handlerName}" declares access.anySignedIn but ${problem}.`,
195
+ });
158
196
  }
159
197
  // The rateLimit is the only protection of a public-intake handler, so the
160
198
  // generic anonymous opt-out (rateLimit: { disabled: true }) must not apply.
@@ -165,14 +203,17 @@ function validatePublicIntakeRateLimit(feature, kind, handlerName, handler) {
165
203
  // skip: rateLimit is active
166
204
  if (!isRateLimitDisabled(handler.rateLimit))
167
205
  return;
168
- throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares ` +
169
- 'access.personalData: "public-intake" with rateLimit: { disabled: true } — the rateLimit ' +
170
- 'is the only protection for anonymous personal-data writes. Declare rateLimit: { per: "ip" ' +
171
- 'or "ip+handler", ... } instead.');
206
+ throw bootRuleError(HANDLER_DECLARATION_RULES.publicIntakeRateLimitDisabled, {
207
+ message: `[Feature ${feature.name}] ${kind} handler "${handlerName}" declares ` +
208
+ 'access.personalData: "public-intake" with rateLimit: { disabled: true } — the rateLimit ' +
209
+ 'is the only protection for anonymous personal-data writes. Declare rateLimit: { per: "ip" ' +
210
+ 'or "ip+handler", ... } instead.',
211
+ });
172
212
  }
173
213
  export function validateAccessDeclarations(feature) {
174
214
  for (const [handlerName, handler] of Object.entries(feature.writeHandlers)) {
175
215
  validateOpenToAllReason(feature, "write", handlerName, handler.access);
216
+ validateAnySignedIn(feature, "write", handlerName, handler.access);
176
217
  validateEscapeHatchReason(feature, "write", handlerName, handler.escapeHatch);
177
218
  validatePersonalDataValue(feature, "write", handlerName, handler.access);
178
219
  validateOpenToAllPersonalData(feature, handlerName, handler);
@@ -181,6 +222,7 @@ export function validateAccessDeclarations(feature) {
181
222
  }
182
223
  for (const [handlerName, handler] of Object.entries(feature.queryHandlers)) {
183
224
  validateOpenToAllReason(feature, "query", handlerName, handler.access);
225
+ validateAnySignedIn(feature, "query", handlerName, handler.access);
184
226
  validateEscapeHatchReason(feature, "query", handlerName, handler.escapeHatch);
185
227
  validatePersonalDataSupportedForKind(feature, "query", handlerName, handler.access);
186
228
  validatePersonalDataValue(feature, "query", handlerName, handler.access);
@@ -188,6 +230,7 @@ export function validateAccessDeclarations(feature) {
188
230
  }
189
231
  for (const [handlerName, handler] of Object.entries(feature.streamHandlers)) {
190
232
  validateOpenToAllReason(feature, "stream", handlerName, handler.access);
233
+ validateAnySignedIn(feature, "stream", handlerName, handler.access);
191
234
  validateEscapeHatchReason(feature, "stream", handlerName, handler.escapeHatch);
192
235
  validatePersonalDataSupportedForKind(feature, "stream", handlerName, handler.access);
193
236
  }
@@ -1,9 +1,11 @@
1
1
  import { isEditLayoutScreen, isFieldsEditSection, normalizeEditField, normalizeListColumn, sectionFieldSpecs, } from "../screen-helpers.js";
2
+ import { bootRuleError } from "./boot-rule.js";
3
+ import { SCREEN_RULES } from "./screens-rules.js";
2
4
  const FUNCTION_DROPPED_HINT = "functions are dropped by JSON.stringify when the screen config reaches the client " +
3
5
  "bundle — the action/field silently no-ops at runtime instead of failing loudly.";
4
- function throwIfFunction(value, message) {
6
+ function throwIfFunction(value, rule, message) {
5
7
  if (typeof value === "function") {
6
- throw new Error(message);
8
+ throw bootRuleError(rule, { message });
7
9
  }
8
10
  }
9
11
  // rowActions/toolbarActions carry row-context extractors (payload/params),
@@ -17,7 +19,7 @@ const ACTION_FUNCTION_FIELDS = ["payload", "params", "entityId", "visible"];
17
19
  function validateActionNoFunctions(featureName, screenId, actionKind, action) {
18
20
  const record = action;
19
21
  for (const field of ACTION_FUNCTION_FIELDS) {
20
- throwIfFunction(record[field], `[Feature ${featureName}] Screen "${screenId}" ${actionKind} "${action.id}" ${field} ` +
22
+ throwIfFunction(record[field], SCREEN_RULES.actionFieldFunction, `[Feature ${featureName}] Screen "${screenId}" ${actionKind} "${action.id}" ${field} ` +
21
23
  `is a function — ${FUNCTION_DROPPED_HINT} Use the declarative DSL ({ pick }, { map }, ` +
22
24
  `"fieldName", { field, eq }/{ field, in }) instead.`);
23
25
  }
@@ -50,17 +52,17 @@ function validateEditFieldNoFunctions(featureName, screenId, screenType, fieldSp
50
52
  const normalized = normalizeEditField(fieldSpec);
51
53
  const record = normalized;
52
54
  for (const key of EDIT_FIELD_FUNCTION_FIELDS) {
53
- throwIfFunction(record[key], `[Feature ${featureName}] Screen "${screenId}" (${screenType}) field "${normalized.field}" ` +
55
+ throwIfFunction(record[key], SCREEN_RULES.editFieldConditionFunction, `[Feature ${featureName}] Screen "${screenId}" (${screenType}) field "${normalized.field}" ` +
54
56
  `${key} is a function — ${FUNCTION_DROPPED_HINT} Use a FieldCondition ` +
55
57
  `(boolean or { field, eq }/{ field, ne }/{ field, in }/{ field, notIn }) instead.`);
56
58
  }
57
- throwIfFunction(normalized.renderer, `[Feature ${featureName}] Screen "${screenId}" (${screenType}) field "${normalized.field}" ` +
59
+ throwIfFunction(normalized.renderer, SCREEN_RULES.rendererFunction, `[Feature ${featureName}] Screen "${screenId}" (${screenType}) field "${normalized.field}" ` +
58
60
  `renderer is a function — ${FUNCTION_DROPPED_HINT} Use a FormatSpec ({ format: "..." }) instead.`);
59
61
  }
60
62
  function validateColumnsNoFunctions(featureName, screenId, screenType, columns) {
61
63
  for (const col of columns) {
62
64
  const normalized = normalizeListColumn(col);
63
- throwIfFunction(normalized.renderer, `[Feature ${featureName}] Screen "${screenId}" (${screenType}) column ` +
65
+ throwIfFunction(normalized.renderer, SCREEN_RULES.rendererFunction, `[Feature ${featureName}] Screen "${screenId}" (${screenType}) column ` +
64
66
  `"${normalized.field}" renderer is a function — ${FUNCTION_DROPPED_HINT} ` +
65
67
  `Use a FormatSpec ({ format: "..." }) instead.`);
66
68
  }
@@ -0,0 +1,12 @@
1
+ export declare const AGENT_EFFECT_RULES: {
2
+ readonly effectOnWriteOnly: {
3
+ readonly id: "agent-effect/write-only";
4
+ readonly summary: "Only write handlers declare agent.effect; a query has nothing to approve.";
5
+ readonly fix: "Drop agent.effect from the query handler.";
6
+ };
7
+ readonly proposalNeedsLowRisk: {
8
+ readonly id: "agent-effect/proposal-needs-low-risk";
9
+ readonly summary: 'A write handler with agent.effect "proposal" declares agent.risk "low".';
10
+ readonly fix: 'Set agent.risk to "low", or drop agent.effect so the agent asks for approval.';
11
+ };
12
+ };
@@ -0,0 +1,12 @@
1
+ export const AGENT_EFFECT_RULES = {
2
+ effectOnWriteOnly: {
3
+ id: "agent-effect/write-only",
4
+ summary: "Only write handlers declare agent.effect; a query has nothing to approve.",
5
+ fix: "Drop agent.effect from the query handler.",
6
+ },
7
+ proposalNeedsLowRisk: {
8
+ id: "agent-effect/proposal-needs-low-risk",
9
+ summary: 'A write handler with agent.effect "proposal" declares agent.risk "low".',
10
+ fix: 'Set agent.risk to "low", or drop agent.effect so the agent asks for approval.',
11
+ },
12
+ };
@@ -0,0 +1,2 @@
1
+ import type { AgentHandlerHints } from "@cosmicdrift/kumiko-types/handlers";
2
+ export declare function validateAgentProposalEffect(featureName: string, kind: "write" | "query", handlerName: string, agent: AgentHandlerHints | undefined): void;
@@ -0,0 +1,20 @@
1
+ import { AGENT_EFFECT_RULES } from "./agent-effect-rules.js";
2
+ import { bootRuleError } from "./boot-rule.js";
3
+ // effect "proposal" lets the agent run the write without an approval card, which is only safe when
4
+ // the result is itself a suggestion a person still approves and the handler is declared low risk.
5
+ export function validateAgentProposalEffect(featureName, kind, handlerName, agent) {
6
+ // skip: handler declares no agent effect
7
+ if (agent?.effect === undefined)
8
+ return;
9
+ const where = `${kind} handler "${featureName}:${kind}:${handlerName}" declares agent.effect "${agent.effect}"`;
10
+ if (kind === "query") {
11
+ throw bootRuleError(AGENT_EFFECT_RULES.effectOnWriteOnly, {
12
+ message: `${where}, but only write handlers have an effect — drop it.`,
13
+ });
14
+ }
15
+ if (agent.risk !== "low") {
16
+ throw bootRuleError(AGENT_EFFECT_RULES.proposalNeedsLowRisk, {
17
+ message: `${where} with agent.risk "${agent.risk ?? "mid (default)"}" — a proposal write skips the approval step, so it must declare risk: "low".`,
18
+ });
19
+ }
20
+ }
@@ -1,4 +1,6 @@
1
1
  import { QnTypes, qualifyEntityName } from "../qualified-name.js";
2
+ import { BOOT_ENVIRONMENT_RULES } from "./boot-environment-rules.js";
3
+ import { bootRuleError } from "./boot-rule.js";
2
4
  import { collectKnownRoles, collectNavQns, collectWriteHandlerQns } from "./nav.js";
3
5
  import { collectClaimKeys } from "./ownership.js";
4
6
  import { buildQueryHandlerMap } from "./projection-list-screens.js";
@@ -48,7 +50,9 @@ export function collectExposedApis(features) {
48
50
  for (const apiName of f.exposedApis) {
49
51
  const existing = allExposedApis.get(apiName);
50
52
  if (existing && existing !== f.name) {
51
- throw new Error(`Cross-feature API "${apiName}" exposed by both "${existing}" and "${f.name}" — API names must be globally unique.`);
53
+ throw bootRuleError(BOOT_ENVIRONMENT_RULES.duplicateExposedApi, {
54
+ message: `Cross-feature API "${apiName}" exposed by both "${existing}" and "${f.name}" — API names must be globally unique.`,
55
+ });
52
56
  }
53
57
  allExposedApis.set(apiName, f.name);
54
58
  }
@@ -0,0 +1,12 @@
1
+ export declare const BOOT_ENVIRONMENT_RULES: {
2
+ readonly fileStorageProviderMissing: {
3
+ readonly id: "file-storage/provider-env-missing";
4
+ readonly summary: "An app with file or image fields sets the FILE_STORAGE_PROVIDER environment variable.";
5
+ readonly fix: "Set FILE_STORAGE_PROVIDER in the environment.";
6
+ };
7
+ readonly duplicateExposedApi: {
8
+ readonly id: "api/duplicate-exposed-name";
9
+ readonly summary: "A cross-feature API name is exposed by exactly one feature.";
10
+ readonly fix: "Rename the API in one of the exposing features.";
11
+ };
12
+ };
@@ -0,0 +1,12 @@
1
+ export const BOOT_ENVIRONMENT_RULES = {
2
+ fileStorageProviderMissing: {
3
+ id: "file-storage/provider-env-missing",
4
+ summary: "An app with file or image fields sets the FILE_STORAGE_PROVIDER environment variable.",
5
+ fix: "Set FILE_STORAGE_PROVIDER in the environment.",
6
+ },
7
+ duplicateExposedApi: {
8
+ id: "api/duplicate-exposed-name",
9
+ summary: "A cross-feature API name is exposed by exactly one feature.",
10
+ fix: "Rename the API in one of the exposing features.",
11
+ },
12
+ };
@@ -3,6 +3,8 @@ import { FILE_STORAGE_PROVIDER_ENV } from "../extension-names.js";
3
3
  import { createRegistry } from "../registry.js";
4
4
  import { validateProjectionAllowlist } from "../validate-projection-allowlist.js";
5
5
  import { runFeatureBootCheck } from "./boot-check.js";
6
+ import { BOOT_ENVIRONMENT_RULES } from "./boot-environment-rules.js";
7
+ import { bootRuleError } from "./boot-rule.js";
6
8
  import { validateCardMetaOverflow } from "./card-meta-overflow.js";
7
9
  import { validateConfigReads } from "./config-deps.js";
8
10
  import { validateDashboardStatNavigate } from "./dashboard-stat-navigate.js";
@@ -106,7 +108,9 @@ export function runEnvironmentPhase(report, ctx, flags) {
106
108
  }
107
109
  report.check("fileStorageProvider", undefined, () => {
108
110
  if (flags.hasFileFields && !(options?.env ?? process.env)[FILE_STORAGE_PROVIDER_ENV]) {
109
- throw new Error(`${FILE_STORAGE_PROVIDER_ENV} environment variable is required (file/image fields in use)`);
111
+ throw bootRuleError(BOOT_ENVIRONMENT_RULES.fileStorageProviderMissing, {
112
+ message: `${FILE_STORAGE_PROVIDER_ENV} environment variable is required (file/image fields in use)`,
113
+ });
110
114
  }
111
115
  });
112
116
  }
@@ -5,7 +5,9 @@ import { collectExposedApis } from "./boot-context.js";
5
5
  import { validateCircularDeps, validateConfigKeyAllowPerRequest, validateConfigKeyBacking, validateConfigKeyBounds, validateConfigKeyComputed, validateConfigKeyOptionsQuery, validateConfigKeyPiiEncrypted, validateConfigKeyRequired, } from "./config-deps.js";
6
6
  import { validateSqlDerivedFields } from "./derived-sql-fields.js";
7
7
  import { collectDetailForScreens } from "./detail-screens.js";
8
- import { validateDerivedFieldCollisions, validateEmbeddedFields, validateEncryptedFields, validateEntityIndexes, validateEntitySelectAvailabilityQuery, validateEntitySelectConditionalOptions, validateEntitySelectOptionsQuery, validateExtendSchemaCollisions, validateFileFields, validateHandlerAccess, validateImageVariants, validateLocatedTimestamps, validateLockedWhen, validateMultiSelectFields, validateMultiStreamProjections, validateReferenceFields, validateSearchableFieldReadAccess, validateTransitions, } from "./entity-handler.js";
8
+ import { validateDerivedFieldCollisions, validateEmbeddedFields, validateEncryptedFields, validateEntityIndexes, validateExtendSchemaCollisions, validateFileFields, validateHandlerAccess, validateLocatedTimestamps, validateLockedWhen, validateMultiStreamProjections, validateReferenceFields, validateSearchableFieldReadAccess, validateTransitions, } from "./entity-handler.js";
9
+ import { validateImageVariants } from "./entity-image-variants.js";
10
+ import { validateEntitySelectAvailabilityQuery, validateEntitySelectConditionalOptions, validateEntitySelectOptionsQuery, validateMultiSelectFields, } from "./entity-select.js";
9
11
  import { validateFieldConditions } from "./field-conditions.js";
10
12
  import { validateHandlerFieldReferences } from "./handler-field-references.js";
11
13
  import { validateNavs } from "./nav.js";