@cosmicdrift/kumiko-framework 0.413.1 → 0.414.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 (463) hide show
  1. package/AGENTS.md +5 -2
  2. package/agents/api/framework-db.md +14 -3
  3. package/agents/api/framework-engine.md +63 -13
  4. package/agents/api/framework-event-store.md +14 -0
  5. package/agents/api/framework-ui-types.md +149 -21
  6. package/agents/api/renderer-web.md +93 -9
  7. package/agents/api/testing-helpers.md +3 -2
  8. package/agents/api/testing-stack.md +3 -0
  9. package/agents/api/types.md +205 -14
  10. package/agents/api.md +7 -7
  11. package/agents/boot-rules.md +63 -9
  12. package/agents/examples/api-docs.md +2 -6
  13. package/agents/examples/auth-mfa.md +57 -10
  14. package/agents/examples/chat-channels.md +2 -0
  15. package/agents/examples/currencies-global.md +1 -0
  16. package/agents/examples/env-composition.md +7 -11
  17. package/agents/examples/managed-pages.md +90 -1
  18. package/agents/examples/pwa-shell.md +210 -0
  19. package/agents/examples/rate-limiting.md +3 -3
  20. package/agents/examples/record-detail-layout.md +1537 -67
  21. package/agents/examples/workflow-engine.md +16 -12
  22. package/agents/examples.md +1 -0
  23. package/agents/features-index.md +4 -2
  24. package/agents/features.md +22 -7
  25. package/agents/widgets.md +19 -1
  26. package/dist/api/api-constants.d.ts +1 -0
  27. package/dist/api/api-constants.js +4 -0
  28. package/dist/api/auth-middleware.js +4 -3
  29. package/dist/api/auth-routes-shared.js +2 -1
  30. package/dist/api/entity-read-access.d.ts +1 -0
  31. package/dist/api/entity-read-access.js +18 -0
  32. package/dist/api/export/export-route.d.ts +6 -1
  33. package/dist/api/export/export-route.js +27 -1
  34. package/dist/api/export/export-rows.js +19 -3
  35. package/dist/api/routes.d.ts +2 -0
  36. package/dist/api/routes.js +9 -1
  37. package/dist/api/server-extra-routes.js +2 -1
  38. package/dist/api/server-feature-http-routes.d.ts +9 -0
  39. package/dist/api/server-feature-http-routes.js +109 -0
  40. package/dist/api/server-middleware.js +2 -19
  41. package/dist/api/server-pat-rate-limit-guard.d.ts +3 -0
  42. package/dist/api/server-pat-rate-limit-guard.js +19 -0
  43. package/dist/api/server-rate-limit-wiring.d.ts +10 -0
  44. package/dist/api/server-rate-limit-wiring.js +37 -0
  45. package/dist/api/server-routes.d.ts +4 -12
  46. package/dist/api/server-routes.js +12 -171
  47. package/dist/api/server-schema-route.d.ts +3 -0
  48. package/dist/api/server-schema-route.js +58 -0
  49. package/dist/api/server-wiring.js +2 -37
  50. package/dist/api/server.js +3 -1
  51. package/dist/compliance/override-schema.js +5 -5
  52. package/dist/compliance/sub-processors.js +10 -1
  53. package/dist/crypto/index.d.ts +1 -1
  54. package/dist/crypto/index.js +1 -1
  55. package/dist/crypto/pii-field-encryption.d.ts +2 -0
  56. package/dist/crypto/pii-field-encryption.js +16 -1
  57. package/dist/db/apply-entity-event.js +4 -0
  58. package/dist/db/bun-sql-connection-codes.d.ts +1 -0
  59. package/dist/db/bun-sql-connection-codes.js +7 -0
  60. package/dist/db/collect-table-metas.js +4 -1
  61. package/dist/db/config-seed.js +1 -1
  62. package/dist/db/derived-field-sql.js +15 -13
  63. package/dist/db/derived-related-sql.d.ts +2 -2
  64. package/dist/db/derived-related-sql.js +4 -2
  65. package/dist/db/dialect.d.ts +3 -0
  66. package/dist/db/dialect.js +1 -3
  67. package/dist/db/driver-row-coercion.js +2 -2
  68. package/dist/db/driver-value-preparation.js +1 -1
  69. package/dist/db/eagerload.js +15 -12
  70. package/dist/db/entity-table-meta.d.ts +2 -0
  71. package/dist/db/entity-table-meta.js +7 -0
  72. package/dist/db/event-store-executor-context.js +13 -8
  73. package/dist/db/event-store-executor-read-aggregate-currencies.js +2 -2
  74. package/dist/db/event-store-executor-read-aggregate.js +2 -2
  75. package/dist/db/event-store-executor-read-filter.d.ts +4 -0
  76. package/dist/db/event-store-executor-read-filter.js +28 -11
  77. package/dist/db/event-store-executor-read-search.d.ts +1 -0
  78. package/dist/db/event-store-executor-read-search.js +6 -6
  79. package/dist/db/event-store-executor-read-sort.js +3 -3
  80. package/dist/db/event-store-executor-read-where.js +14 -5
  81. package/dist/db/event-store-executor-read.js +7 -7
  82. package/dist/db/event-store-executor-write.js +50 -95
  83. package/dist/db/executor-managed-tables.js +4 -1
  84. package/dist/db/index.d.ts +4 -2
  85. package/dist/db/index.js +4 -2
  86. package/dist/db/known-table-names.d.ts +1 -0
  87. package/dist/db/known-table-names.js +7 -5
  88. package/dist/db/list-aggregate-labels.d.ts +1 -0
  89. package/dist/db/list-aggregate-labels.js +9 -1
  90. package/dist/db/migrate-generator.js +23 -4
  91. package/dist/db/migrate-rls-diff.d.ts +1 -0
  92. package/dist/db/migrate-rls-diff.js +15 -1
  93. package/dist/db/migrate-runner.js +2 -2
  94. package/dist/db/money.d.ts +1 -1
  95. package/dist/db/money.js +1 -4
  96. package/dist/db/parent-ref-clause.d.ts +6 -2
  97. package/dist/db/parent-ref-clause.js +76 -23
  98. package/dist/db/parent-ref-global-hosts.d.ts +20 -0
  99. package/dist/db/parent-ref-global-hosts.js +47 -0
  100. package/dist/db/production-schema-command-hint.d.ts +1 -0
  101. package/dist/db/production-schema-command-hint.js +3 -0
  102. package/dist/db/queries/backfill-pii.js +55 -29
  103. package/dist/db/queries/ddl.js +13 -2
  104. package/dist/db/queries/event-store-open-streams.d.ts +15 -0
  105. package/dist/db/queries/event-store-open-streams.js +33 -0
  106. package/dist/db/queries/event-store-payload-scrub.d.ts +5 -0
  107. package/dist/db/queries/event-store-payload-scrub.js +11 -0
  108. package/dist/db/queries/event-store.js +0 -1
  109. package/dist/db/queries/raw-sql.js +0 -1
  110. package/dist/db/queries/rebuild-rls-guard.d.ts +2 -1
  111. package/dist/db/queries/rebuild-rls-guard.js +24 -11
  112. package/dist/db/queries/rls-boot-catalog.d.ts +1 -0
  113. package/dist/db/queries/rls-boot-catalog.js +13 -8
  114. package/dist/db/queries/rls-shape.d.ts +2 -1
  115. package/dist/db/queries/rls-shape.js +10 -0
  116. package/dist/db/queries/session-advisory-lock.js +2 -1
  117. package/dist/db/queries/test-stack.js +7 -7
  118. package/dist/db/query.js +16 -11
  119. package/dist/db/rebuild-marker.js +11 -2
  120. package/dist/db/render-rls-ddl.d.ts +2 -0
  121. package/dist/db/render-rls-ddl.js +16 -11
  122. package/dist/db/replay-migration-sql.js +1 -1
  123. package/dist/db/row-level-security-boot-check.js +18 -5
  124. package/dist/db/row-level-security-connection.js +25 -12
  125. package/dist/db/row-level-security-scope.d.ts +2 -1
  126. package/dist/db/row-level-security-scope.js +9 -5
  127. package/dist/db/sql-identifier.d.ts +1 -0
  128. package/dist/db/sql-identifier.js +3 -0
  129. package/dist/db/system-tenant-read-db.d.ts +5 -0
  130. package/dist/db/system-tenant-read-db.js +28 -0
  131. package/dist/db/table-builder.d.ts +3 -1
  132. package/dist/db/table-builder.js +18 -8
  133. package/dist/db/table-info.d.ts +1 -2
  134. package/dist/db/table-introspection.d.ts +3 -0
  135. package/dist/db/table-introspection.js +6 -0
  136. package/dist/db/table-push.d.ts +1 -0
  137. package/dist/db/table-push.js +7 -1
  138. package/dist/db/tenant-db-runner.d.ts +3 -0
  139. package/dist/db/tenant-db-runner.js +19 -1
  140. package/dist/db/transaction-serialization.d.ts +1 -0
  141. package/dist/db/transaction-serialization.js +20 -3
  142. package/dist/db/where-clause.js +11 -2
  143. package/dist/db/write-ownership-failures.d.ts +25 -0
  144. package/dist/db/write-ownership-failures.js +82 -0
  145. package/dist/engine/boot-validator/boot-check.js +7 -1
  146. package/dist/engine/boot-validator/boot-phases-app.js +5 -5
  147. package/dist/engine/boot-validator/boot-phases.js +3 -2
  148. package/dist/engine/boot-validator/boot-rules.d.ts +293 -26
  149. package/dist/engine/boot-validator/boot-rules.js +4 -0
  150. package/dist/engine/boot-validator/bundled-lists-table.js +2 -2
  151. package/dist/engine/boot-validator/card-meta-overflow.js +1 -0
  152. package/dist/engine/boot-validator/config-deps.d.ts +0 -1
  153. package/dist/engine/boot-validator/config-deps.js +0 -28
  154. package/dist/engine/boot-validator/config-key-rules.d.ts +0 -15
  155. package/dist/engine/boot-validator/config-key-rules.js +0 -15
  156. package/dist/engine/boot-validator/dashboard-screen-target.d.ts +22 -0
  157. package/dist/engine/boot-validator/dashboard-screen-target.js +20 -0
  158. package/dist/engine/boot-validator/dashboard-stat-navigate.d.ts +1 -0
  159. package/dist/engine/boot-validator/dashboard-stat-navigate.js +25 -17
  160. package/dist/engine/boot-validator/definition-webhook-events-rules.d.ts +5 -0
  161. package/dist/engine/boot-validator/definition-webhook-events-rules.js +5 -0
  162. package/dist/engine/boot-validator/derived-sql-fields.js +1 -2
  163. package/dist/engine/boot-validator/entity-declaration-rules.d.ts +5 -0
  164. package/dist/engine/boot-validator/entity-declaration-rules.js +5 -0
  165. package/dist/engine/boot-validator/entity-list-screens.d.ts +1 -0
  166. package/dist/engine/boot-validator/entity-list-screens.js +33 -6
  167. package/dist/engine/boot-validator/entity-structure-rules.d.ts +5 -0
  168. package/dist/engine/boot-validator/entity-structure-rules.js +5 -0
  169. package/dist/engine/boot-validator/list-column-layout.js +10 -6
  170. package/dist/engine/boot-validator/list-row-guidance-rules.d.ts +67 -0
  171. package/dist/engine/boot-validator/list-row-guidance-rules.js +67 -0
  172. package/dist/engine/boot-validator/list-row-guidance.d.ts +20 -0
  173. package/dist/engine/boot-validator/list-row-guidance.js +129 -0
  174. package/dist/engine/boot-validator/list-sort-summary-rules.d.ts +42 -0
  175. package/dist/engine/boot-validator/list-sort-summary-rules.js +42 -0
  176. package/dist/engine/boot-validator/list-sort-summary.d.ts +5 -0
  177. package/dist/engine/boot-validator/list-sort-summary.js +149 -0
  178. package/dist/engine/boot-validator/list-table-options.js +15 -1
  179. package/dist/engine/boot-validator/list-table-rules.d.ts +10 -5
  180. package/dist/engine/boot-validator/list-table-rules.js +10 -5
  181. package/dist/engine/boot-validator/list-toolbar-options.d.ts +10 -0
  182. package/dist/engine/boot-validator/list-toolbar-options.js +31 -0
  183. package/dist/engine/boot-validator/named-filter-rules.d.ts +32 -2
  184. package/dist/engine/boot-validator/named-filter-rules.js +32 -2
  185. package/dist/engine/boot-validator/ownership.js +10 -1
  186. package/dist/engine/boot-validator/parent-ref.js +87 -50
  187. package/dist/engine/boot-validator/projection-list-screens.d.ts +1 -0
  188. package/dist/engine/boot-validator/projection-list-screens.js +31 -1
  189. package/dist/engine/boot-validator/query-output-columns.js +62 -9
  190. package/dist/engine/boot-validator/query-output-guidance.d.ts +7 -0
  191. package/dist/engine/boot-validator/query-output-guidance.js +39 -0
  192. package/dist/engine/boot-validator/query-refs.js +24 -1
  193. package/dist/engine/boot-validator/row-decoration.d.ts +11 -0
  194. package/dist/engine/boot-validator/row-decoration.js +16 -0
  195. package/dist/engine/boot-validator/screens-dashboard-links.d.ts +10 -0
  196. package/dist/engine/boot-validator/screens-dashboard-links.js +36 -0
  197. package/dist/engine/boot-validator/screens-dashboard-narrow.d.ts +4 -0
  198. package/dist/engine/boot-validator/screens-dashboard-narrow.js +211 -0
  199. package/dist/engine/boot-validator/screens-dashboard-rules.d.ts +84 -4
  200. package/dist/engine/boot-validator/screens-dashboard-rules.js +84 -4
  201. package/dist/engine/boot-validator/screens-dashboard.js +29 -7
  202. package/dist/engine/boot-validator/screens-kind-entity-list.js +32 -27
  203. package/dist/engine/boot-validator/screens-kind-projection-detail-guidance.d.ts +3 -0
  204. package/dist/engine/boot-validator/screens-kind-projection-detail-guidance.js +46 -0
  205. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +20 -0
  206. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +20 -0
  207. package/dist/engine/boot-validator/screens-kind-projection-detail.js +2 -0
  208. package/dist/engine/boot-validator/screens-kind-projection-list.js +4 -0
  209. package/dist/engine/boot-validator/screens-kind-rules.d.ts +25 -0
  210. package/dist/engine/boot-validator/screens-kind-rules.js +25 -0
  211. package/dist/engine/boot-validator/screens-lists.d.ts +8 -2
  212. package/dist/engine/boot-validator/screens-lists.js +19 -3
  213. package/dist/engine/boot-validator/screens.js +1 -1
  214. package/dist/engine/boot-validator/sort-nulls.d.ts +2 -0
  215. package/dist/engine/boot-validator/sort-nulls.js +15 -0
  216. package/dist/engine/boot-validator/zod-shape.d.ts +2 -1
  217. package/dist/engine/boot-validator/zod-shape.js +19 -1
  218. package/dist/engine/build-app-schema.js +4 -0
  219. package/dist/engine/config-helpers.d.ts +1 -2
  220. package/dist/engine/config-helpers.js +6 -7
  221. package/dist/engine/define-feature.js +1 -0
  222. package/dist/engine/define-handler.d.ts +1 -0
  223. package/dist/engine/define-handler.js +4 -2
  224. package/dist/engine/definition-violations.js +2 -2
  225. package/dist/engine/entity-handlers.js +3 -8
  226. package/dist/engine/entity-list-runtime-options.js +9 -8
  227. package/dist/engine/factories.d.ts +2 -0
  228. package/dist/engine/feature-config-events-jobs.js +1 -0
  229. package/dist/engine/feature-entity-handlers.js +5 -2
  230. package/dist/engine/field-access.d.ts +1 -1
  231. package/dist/engine/field-access.js +7 -10
  232. package/dist/engine/find-entity.js +3 -3
  233. package/dist/engine/form-derivations.js +3 -3
  234. package/dist/engine/index.d.ts +3 -3
  235. package/dist/engine/index.js +2 -2
  236. package/dist/engine/named-filter-roles.d.ts +3 -0
  237. package/dist/engine/named-filter-roles.js +23 -0
  238. package/dist/engine/pipeline.js +0 -1
  239. package/dist/engine/project-app-schema-for-roles.js +17 -2
  240. package/dist/engine/qualified-name.js +0 -1
  241. package/dist/engine/registry-facade.js +1 -2
  242. package/dist/engine/registry-state.d.ts +1 -1
  243. package/dist/engine/registry-state.js +5 -2
  244. package/dist/engine/registry-validate.js +2 -1
  245. package/dist/engine/resolve-named-list-filters.js +5 -2
  246. package/dist/engine/schema-builder.js +6 -10
  247. package/dist/engine/screen-helpers.d.ts +12 -0
  248. package/dist/engine/screen-helpers.js +17 -1
  249. package/dist/engine/soft-delete-cleanup.js +1 -5
  250. package/dist/engine/state-machine.js +0 -1
  251. package/dist/engine/steps/_database-clock.d.ts +2 -0
  252. package/dist/engine/steps/_database-clock.js +6 -0
  253. package/dist/engine/steps/compute.js +1 -1
  254. package/dist/engine/steps/retry.js +5 -1
  255. package/dist/engine/steps/return.js +0 -1
  256. package/dist/engine/steps/wait-for-event.js +2 -1
  257. package/dist/engine/steps/wait.js +2 -1
  258. package/dist/engine/system-user.d.ts +2 -2
  259. package/dist/engine/system-user.js +2 -2
  260. package/dist/engine/types/handlers.d.ts +1 -1
  261. package/dist/engine/types/handlers.js +1 -1
  262. package/dist/engine/types/screen.d.ts +1 -1
  263. package/dist/engine/types/screen.js +1 -1
  264. package/dist/engine/webhook-contracts.d.ts +2 -3
  265. package/dist/engine/webhook-contracts.js +2 -25
  266. package/dist/engine/webhook-events.js +48 -29
  267. package/dist/engine/webhook-payload-strictness.d.ts +7 -0
  268. package/dist/engine/webhook-payload-strictness.js +53 -0
  269. package/dist/env/_zod-introspect.d.ts +1 -0
  270. package/dist/env/dry-run.d.ts +1 -1
  271. package/dist/env/dry-run.js +1 -1
  272. package/dist/env/field-meta.d.ts +4 -0
  273. package/dist/env/field-meta.js +67 -0
  274. package/dist/env/field-rules.d.ts +9 -0
  275. package/dist/env/field-rules.js +46 -0
  276. package/dist/env/index.d.ts +3 -3
  277. package/dist/env/index.js +16 -71
  278. package/dist/env/internals.d.ts +3 -0
  279. package/dist/env/internals.js +1 -2
  280. package/dist/env/required-env.d.ts +3 -1
  281. package/dist/env/required-env.js +5 -2
  282. package/dist/errors/serialize.js +2 -2
  283. package/dist/errors/write-error-info.js +0 -2
  284. package/dist/es-ops/operations-schema.js +18 -7
  285. package/dist/event-store/admin-api.js +3 -3
  286. package/dist/event-store/event-store.js +0 -3
  287. package/dist/event-store/index.d.ts +1 -0
  288. package/dist/event-store/index.js +1 -0
  289. package/dist/event-store/transfer.js +1 -1
  290. package/dist/files/assert-file-refs-belong-to-tenant.d.ts +2 -1
  291. package/dist/files/assert-file-refs-belong-to-tenant.js +15 -13
  292. package/dist/files/bind-pending-file-refs.d.ts +3 -1
  293. package/dist/files/bind-pending-file-refs.js +54 -27
  294. package/dist/files/copy-pending-file-refs-to-tenant.js +7 -3
  295. package/dist/files/create-file-ref.d.ts +4 -1
  296. package/dist/files/create-file-ref.js +14 -3
  297. package/dist/files/default-file-guard.js +4 -1
  298. package/dist/files/file-claim.d.ts +6 -0
  299. package/dist/files/file-claim.js +17 -0
  300. package/dist/files/file-field-slots.d.ts +2 -0
  301. package/dist/files/file-field-slots.js +28 -0
  302. package/dist/files/file-ref-entity.d.ts +3 -0
  303. package/dist/files/file-ref-entity.js +2 -0
  304. package/dist/files/file-ref-table.d.ts +3 -0
  305. package/dist/files/file-routes.d.ts +4 -1
  306. package/dist/files/file-routes.js +80 -16
  307. package/dist/files/in-memory-provider.d.ts +1 -1
  308. package/dist/files/in-memory-provider.js +2 -1
  309. package/dist/files/index.d.ts +1 -1
  310. package/dist/files/index.js +1 -1
  311. package/dist/files/invalid-file-ref-error.d.ts +2 -0
  312. package/dist/files/invalid-file-ref-error.js +15 -0
  313. package/dist/files/local-provider.js +9 -2
  314. package/dist/files/provider-resolver.js +1 -1
  315. package/dist/files/rebind-file-ref.d.ts +3 -2
  316. package/dist/files/rebind-file-ref.js +24 -18
  317. package/dist/files/resolve-file-handles.d.ts +13 -0
  318. package/dist/files/resolve-file-handles.js +57 -0
  319. package/dist/files/storage-tracking.d.ts +1 -1
  320. package/dist/files/storage-tracking.js +5 -2
  321. package/dist/files/sweep-stale-pending-file-refs.js +10 -4
  322. package/dist/files/types.d.ts +4 -0
  323. package/dist/files/types.js +10 -0
  324. package/dist/files/upload-field-resolution.d.ts +1 -0
  325. package/dist/files/upload-field-resolution.js +16 -2
  326. package/dist/files/upload-ledger.js +1 -1
  327. package/dist/i18n/required-surface-guidance-keys.d.ts +3 -0
  328. package/dist/i18n/required-surface-guidance-keys.js +9 -0
  329. package/dist/i18n/required-surface-keys.js +19 -4
  330. package/dist/internal/boot-rule-table-expectations.d.ts +2 -0
  331. package/dist/internal/boot-rule-table-expectations.js +29 -0
  332. package/dist/internal/row-level-security.d.ts +1 -0
  333. package/dist/internal/row-level-security.js +1 -0
  334. package/dist/internal/testing.d.ts +1 -0
  335. package/dist/internal/testing.js +1 -0
  336. package/dist/jobs/index.d.ts +1 -0
  337. package/dist/jobs/index.js +1 -0
  338. package/dist/jobs/job-load-events.d.ts +10 -0
  339. package/dist/jobs/job-load-events.js +12 -0
  340. package/dist/jobs/job-runner-context.js +6 -158
  341. package/dist/jobs/job-runner-dispatch.d.ts +7 -0
  342. package/dist/jobs/job-runner-dispatch.js +57 -0
  343. package/dist/jobs/job-runner-event-triggers.js +18 -9
  344. package/dist/jobs/job-runner-execution.js +2 -2
  345. package/dist/jobs/job-runner-facets.d.ts +48 -0
  346. package/dist/jobs/job-runner-facets.js +156 -0
  347. package/dist/jobs/job-runner-gates.js +19 -11
  348. package/dist/jobs/job-runner-helpers.d.ts +5 -1
  349. package/dist/jobs/job-runner-helpers.js +18 -3
  350. package/dist/jobs/job-runner-scope.d.ts +1 -0
  351. package/dist/jobs/job-runner-scope.js +2 -0
  352. package/dist/jobs/job-runner-tenant-cap-lock.d.ts +2 -0
  353. package/dist/jobs/job-runner-tenant-cap-lock.js +30 -0
  354. package/dist/jobs/job-runner.js +31 -70
  355. package/dist/jobs/obliterate-job-queues.d.ts +6 -0
  356. package/dist/jobs/obliterate-job-queues.js +23 -0
  357. package/dist/lifecycle/lifecycle.js +1 -1
  358. package/dist/migrations/event-header-scrub.d.ts +11 -0
  359. package/dist/migrations/event-header-scrub.js +33 -0
  360. package/dist/migrations/event-payload-scrub.d.ts +1 -1
  361. package/dist/migrations/event-payload-scrub.js +36 -4
  362. package/dist/migrations/index.d.ts +1 -0
  363. package/dist/migrations/index.js +2 -0
  364. package/dist/migrations/kumiko-drift.d.ts +5 -2
  365. package/dist/migrations/kumiko-drift.js +51 -14
  366. package/dist/migrations/pending-rebuilds.js +4 -5
  367. package/dist/observability/sensitive-filter.js +0 -12
  368. package/dist/pipeline/aggregate-type-removal.js +17 -4
  369. package/dist/pipeline/context-services.d.ts +2 -0
  370. package/dist/pipeline/context-services.js +5 -2
  371. package/dist/pipeline/dispatch-batch.js +4 -3
  372. package/dist/pipeline/dispatch-context-helpers.d.ts +11 -0
  373. package/dist/pipeline/dispatch-context-helpers.js +58 -0
  374. package/dist/pipeline/dispatch-nested-write.d.ts +7 -0
  375. package/dist/pipeline/dispatch-nested-write.js +119 -0
  376. package/dist/pipeline/dispatch-query.js +10 -3
  377. package/dist/pipeline/dispatch-scope.js +4 -3
  378. package/dist/pipeline/dispatch-shared.d.ts +2 -6
  379. package/dist/pipeline/dispatch-shared.js +6 -38
  380. package/dist/pipeline/dispatch-write.d.ts +0 -1
  381. package/dist/pipeline/dispatch-write.js +3 -302
  382. package/dist/pipeline/dispatcher-utils.js +6 -0
  383. package/dist/pipeline/effective-system-scope.d.ts +3 -0
  384. package/dist/pipeline/effective-system-scope.js +22 -0
  385. package/dist/pipeline/event-dispatcher-delivery.d.ts +1 -0
  386. package/dist/pipeline/event-dispatcher-delivery.js +17 -9
  387. package/dist/pipeline/event-dispatcher.d.ts +4 -1
  388. package/dist/pipeline/event-dispatcher.js +6 -7
  389. package/dist/pipeline/handler-context-auth.d.ts +3 -2
  390. package/dist/pipeline/handler-context-auth.js +3 -4
  391. package/dist/pipeline/handler-context-db.js +11 -4
  392. package/dist/pipeline/handler-context-dispatch.js +2 -2
  393. package/dist/pipeline/handler-context-events.d.ts +8 -3
  394. package/dist/pipeline/handler-context-events.js +20 -65
  395. package/dist/pipeline/handler-context-member-resolution.js +16 -8
  396. package/dist/pipeline/handler-context-notify.d.ts +1 -0
  397. package/dist/pipeline/handler-context-notify.js +2 -0
  398. package/dist/pipeline/handler-context-phase-denials.js +3 -2
  399. package/dist/pipeline/handler-context-projection.d.ts +3 -0
  400. package/dist/pipeline/handler-context-projection.js +39 -0
  401. package/dist/pipeline/handler-context-scope.d.ts +1 -1
  402. package/dist/pipeline/handler-context-scope.js +14 -2
  403. package/dist/pipeline/index.d.ts +1 -1
  404. package/dist/pipeline/index.js +1 -1
  405. package/dist/pipeline/lifecycle-pipeline.d.ts +1 -0
  406. package/dist/pipeline/lifecycle-pipeline.js +7 -4
  407. package/dist/pipeline/member-reader.js +4 -2
  408. package/dist/pipeline/msp-rebuild.js +1 -1
  409. package/dist/pipeline/nested-write-parent-guard.d.ts +5 -0
  410. package/dist/pipeline/nested-write-parent-guard.js +81 -0
  411. package/dist/pipeline/projection-rebuild.d.ts +2 -0
  412. package/dist/pipeline/projection-rebuild.js +16 -7
  413. package/dist/pipeline/projection-state.js +4 -6
  414. package/dist/pipeline/system-hooks.js +36 -6
  415. package/dist/pipeline/write-result-masking.js +31 -3
  416. package/dist/pipeline/write-transition-guard.d.ts +7 -0
  417. package/dist/pipeline/write-transition-guard.js +95 -0
  418. package/dist/schema-cli/shared.d.ts +2 -0
  419. package/dist/schema-cli/shared.js +4 -2
  420. package/dist/schema-cli/validate-command.js +43 -28
  421. package/dist/search/meilisearch-adapter.js +14 -9
  422. package/dist/search/reindex-entity.d.ts +2 -0
  423. package/dist/search/reindex-entity.js +32 -4
  424. package/dist/search/reindex-tenants-search.js +20 -4
  425. package/dist/time/tz-context.js +1 -1
  426. package/dist/ui-types/card-column-roles.d.ts +4 -0
  427. package/dist/ui-types/card-column-roles.js +6 -3
  428. package/dist/ui-types/index.d.ts +2 -2
  429. package/dist/ui-types/index.js +1 -1
  430. package/dist/utils/ids.js +0 -1
  431. package/dist/utils/index.d.ts +1 -0
  432. package/dist/utils/index.js +1 -0
  433. package/dist/utils/return-path-limit.d.ts +1 -0
  434. package/dist/utils/return-path-limit.js +1 -0
  435. package/package.json +5 -3
  436. package/presets/biome-app.json +39 -21
  437. package/presets/biome-plugins/admin-api.grit +10 -0
  438. package/presets/biome-plugins/error-reasons.grit +53 -0
  439. package/presets/biome-plugins/es-literal-writes-tests.grit +18 -0
  440. package/presets/biome-plugins/es-literal-writes.grit +22 -0
  441. package/presets/biome-plugins/i18n-locale-terminology-de.grit +15 -0
  442. package/presets/biome-plugins/i18n-locale-terminology-romance.grit +10 -0
  443. package/presets/biome-plugins/no-create-test-dispatcher.grit +5 -0
  444. package/presets/biome-plugins/no-css-properties-type.grit +7 -0
  445. package/presets/biome-plugins/no-date-api.grit +9 -0
  446. package/presets/biome-plugins/no-direct-fetch.grit +16 -0
  447. package/presets/biome-plugins/no-direct-fs.grit +16 -0
  448. package/presets/biome-plugins/no-external-font-cdn-css.grit +9 -0
  449. package/presets/biome-plugins/no-external-font-cdn.grit +12 -0
  450. package/presets/biome-plugins/no-raw-hooks.grit +10 -0
  451. package/presets/biome-plugins/no-same-folder-barrel-import.grit +11 -0
  452. package/presets/biome-plugins/no-screen-container-classes.grit +7 -0
  453. package/presets/biome-plugins/no-skipped-or-retried-tests.grit +34 -0
  454. package/presets/biome-plugins/no-temporal-polyfill-require.grit +10 -0
  455. package/presets/biome-plugins/raw-html-in-web.grit +40 -0
  456. package/presets/biome-plugins/raw-ui-in-app.grit +142 -0
  457. package/presets/biome-plugins/restricted-event-store-symbols.grit +18 -0
  458. package/presets/biome-plugins/test-title.grit +20 -0
  459. package/presets/biome-plugins/unsafe-json-parse.grit +6 -0
  460. package/presets/biome-rules.json +465 -0
  461. package/src/changes.json +309 -0
  462. package/dist/engine/minor-units.d.ts +0 -2
  463. package/dist/engine/minor-units.js +0 -8
@@ -27,7 +27,7 @@ export function buildQueryHandlerMap(features) {
27
27
  // Non-ZodObject schemas (e.g. a z.union across payload shapes) and
28
28
  // unresolved query handlers both fall through to "capability absent" —
29
29
  // consistent with buildAppSchema's derivation, no throw either way.
30
- function schemaAccepts(schema, key) {
30
+ export function schemaAccepts(schema, key) {
31
31
  const shape = getZodObjectShape(schema);
32
32
  return shape !== undefined && key in shape;
33
33
  }
@@ -82,6 +82,8 @@ function validateOneProjectionListScreen(feature, screen, queryHandlers, feature
82
82
  validateProjectionListFilterSchemaAcceptance(prefix, screen, schema);
83
83
  validateProjectionListFacetsSchemaAcceptance(prefix, screen, schema);
84
84
  validateProjectionListNamedFilterSchemaAcceptance(prefix, screen, schema);
85
+ validateProjectionListNamedFilterSortAcceptance(prefix, screen, schema);
86
+ validateProjectionListNamedFilterCountAcceptance(prefix, screen, schema);
85
87
  validateListTableAggregateQuery({ prefix, ...screen, handler, featureMap });
86
88
  }
87
89
  // filter sends `payload.filter` — same 422 footgun as facets below
@@ -106,6 +108,34 @@ function validateProjectionListNamedFilterSchemaAcceptance(prefix, screen, schem
106
108
  `Zod schema — add namedFilter: z.string().optional() to the handler's schema and resolve it with resolveNamedListFilters.`,
107
109
  });
108
110
  }
111
+ // showCounts asks the query once per filter with { limit: 1, totalCount: true, namedFilter }; a schema
112
+ // without those keys 422s every count request.
113
+ function validateProjectionListNamedFilterCountAcceptance(prefix, screen, schema) {
114
+ if (screen.namedFilterFacet?.showCounts !== true)
115
+ return;
116
+ const missing = ["limit", "totalCount"].filter((key) => !schemaAccepts(schema, key));
117
+ if (missing.length === 0)
118
+ return;
119
+ throw bootRuleError(NAMED_FILTER_RULES.projectionQueryAcceptsCount, {
120
+ message: `${prefix}: namedFilterFacet.showCounts needs query "${screen.query}" to accept ${missing.map((key) => `"${key}"`).join(" and ")} in its Zod schema ` +
121
+ `- add them or drop showCounts.`,
122
+ });
123
+ }
124
+ // A filter's own sort travels as `payload.sort`/`sortDirection`; without them in the schema it 422s
125
+ // the moment the filter is picked. The field itself is not checked: a projection row has no entity,
126
+ // and the query may order by a column it does not list.
127
+ function validateProjectionListNamedFilterSortAcceptance(prefix, screen, schema) {
128
+ const sorted = (screen.namedFilters ?? []).find((ref) => ref.sort !== undefined);
129
+ // skip: no filter sorts, or the schema already accepts both keys — nothing to reject.
130
+ if (sorted === undefined ||
131
+ (schemaAccepts(schema, "sort") && schemaAccepts(schema, "sortDirection"))) {
132
+ return;
133
+ }
134
+ throw bootRuleError(NAMED_FILTER_RULES.projectionQueryAcceptsSort, {
135
+ message: `${prefix}: namedFilters "${sorted.id}" sets sort but query "${screen.query}" has no ` +
136
+ `"sort" and "sortDirection" parameters in its Zod schema — add them or remove sort from the filter.`,
137
+ });
138
+ }
109
139
  // facets send `payload.filters` — same failure mode as search/sort:
110
140
  // definePagedQueryHandler doesn't auto-merge params into the
111
141
  // handler's own Zod schema, so a declared facet would 422 on every query
@@ -2,8 +2,10 @@ import { isPagedQueryHandler } from "../define-handler.js";
2
2
  import { normalizeListColumn, sectionFieldSpecs } from "../screen-helpers.js";
3
3
  import { bootRuleError } from "./boot-rule.js";
4
4
  import { buildQueryHandlerMap } from "./projection-list-screens.js";
5
+ import { detailGuidanceFieldRefs, listGuidanceFieldRefs } from "./query-output-guidance.js";
5
6
  import { QUERY_RULES } from "./query-rules.js";
6
7
  import { validateActionFieldRefs } from "./screens.js";
8
+ import { DASHBOARD_RULES } from "./screens-dashboard-rules.js";
7
9
  import { getZodObjectShape, getZodRowShape } from "./zod-shape.js";
8
10
  function checkFieldExists(shape, field, buildMessage) {
9
11
  // skip: capability absent (no introspectable shape) or field already present — nothing to validate
@@ -57,11 +59,23 @@ function resolveListRowShape(queryHandlers, queryQn, usage) {
57
59
  message: `${usage} uses query "${queryQn}" as a list source, but its outputSchema does not describe the paged envelope { rows: [...], nextCursor, total? } — it has no "rows" field. Did you pass the row schema instead of wrapping it in the envelope?`,
58
60
  });
59
61
  }
62
+ // Row fields a projectionList may name: its list rows plus the rowDecoration rows. An
63
+ // undeclared decoration outputSchema could add any field, so then nothing can be pinned.
64
+ function listRowShapeWithDecoration(queryHandlers, rowShape, decoration, usage) {
65
+ if (rowShape === undefined || decoration === undefined)
66
+ return rowShape;
67
+ const decorationShape = resolveListRowShape(queryHandlers, decoration.query, usage);
68
+ return decorationShape === undefined ? undefined : { ...rowShape, ...decorationShape };
69
+ }
60
70
  function checkProjectionListOutputColumns(queryHandlers, featureName, screenId, screen) {
61
- const rowShape = resolveListRowShape(queryHandlers, screen.query, `[Feature ${featureName}] Screen "${screenId}" (projectionList)`);
71
+ const usage = `[Feature ${featureName}] Screen "${screenId}" (projectionList)`;
72
+ const rowShape = listRowShapeWithDecoration(queryHandlers, resolveListRowShape(queryHandlers, screen.query, usage), screen.rowDecoration, `${usage} rowDecoration`);
62
73
  for (const column of screen.columns) {
63
74
  checkColumnField(rowShape, column, (field) => `[Feature ${featureName}] Screen "${screenId}" (projectionList) column "${field}" is not present in query "${screen.query}"'s outputSchema — check for a typo, or set virtual: true on it to mark it a virtual/computed column.`);
64
75
  }
76
+ for (const { option, field } of listGuidanceFieldRefs(screen)) {
77
+ checkFieldExists(rowShape, field, () => `[Feature ${featureName}] Screen "${screenId}" (projectionList) ${option} references field "${field}" which is not present in query "${screen.query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`);
78
+ }
65
79
  }
66
80
  function checkEditLayoutOutputColumns(queryHandlers, featureName, screenId, screenType, layout) {
67
81
  for (const section of layout.sections) {
@@ -71,12 +85,14 @@ function checkEditLayoutOutputColumns(queryHandlers, featureName, screenId, scre
71
85
  for (const column of section.columns) {
72
86
  checkColumnField(rowShape, column, (field) => `[Feature ${featureName}] Screen "${screenId}" (${screenType}) relatedList section "${section.title}" column "${field}" is not present in query "${section.query}"'s outputSchema — check for a typo, or set virtual: true on it to mark it a virtual/computed column.`);
73
87
  }
88
+ for (const { option, field } of listGuidanceFieldRefs({ columns: section.columns })) {
89
+ checkFieldExists(rowShape, field, () => `[Feature ${featureName}] Screen "${screenId}" (${screenType}) relatedList section "${section.title}" ${option} references field "${field}" which is not present in query "${section.query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`);
90
+ }
74
91
  }
75
92
  }
76
93
  function checkProjectionDetailOutputFields(queryHandlers, featureName, screenId, screen) {
77
94
  const recordShape = getZodObjectShape(queryHandlers.get(screen.query)?.outputSchema);
78
95
  const prefix = `[Feature ${featureName}] Screen "${screenId}" (projectionDetail)`;
79
- // @wrapper-known semantic-alias
80
96
  const checkHeaderField = (part, field) => {
81
97
  checkFieldExists(recordShape, field, () => `${prefix} header.${part} references field "${field}" which is not present in query "${screen.query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`);
82
98
  };
@@ -97,13 +113,17 @@ function checkProjectionDetailOutputFields(queryHandlers, featureName, screenId,
97
113
  }
98
114
  }
99
115
  }
100
- if (screen.header.subtitleHref !== undefined) {
101
- checkHeaderField("subtitleHref", screen.header.subtitleHref);
102
- }
103
- if (screen.header.status !== undefined)
104
- checkHeaderField("status", screen.header.status);
105
- if (screen.header.statusToneField !== undefined) {
106
- checkHeaderField("statusToneField", screen.header.statusToneField);
116
+ const { shortTitle, narrowSubtitle, subtitleHref, status, statusToneField } = screen.header;
117
+ const optionalParts = [
118
+ ["shortTitle", shortTitle],
119
+ ["narrowSubtitle", narrowSubtitle],
120
+ ["subtitleHref", subtitleHref],
121
+ ["status", status],
122
+ ["statusToneField", statusToneField],
123
+ ];
124
+ for (const [part, field] of optionalParts) {
125
+ if (field !== undefined)
126
+ checkHeaderField(part, field);
107
127
  }
108
128
  }
109
129
  if (screen.recordTitleField !== undefined) {
@@ -114,6 +134,9 @@ function checkProjectionDetailOutputFields(queryHandlers, featureName, screenId,
114
134
  const field = metric.field;
115
135
  checkFieldExists(recordShape, field, () => `${prefix} metrics references field "${field}" which is not present in query "${screen.query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`);
116
136
  }
137
+ for (const { option, field } of detailGuidanceFieldRefs(screen)) {
138
+ checkFieldExists(recordShape, field, () => `${prefix} ${option} references field "${field}" which is not present in query "${screen.query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`);
139
+ }
117
140
  checkDetailSectionFields(recordShape, prefix, screen);
118
141
  checkRelatedListToolbarActionFields(recordShape, featureName, screenId, screen);
119
142
  }
@@ -166,6 +189,7 @@ function checkDashboardStatPanelFields(queryHandlers, featureName, screenId, pan
166
189
  checkFieldExists(recordShape, field, () => `${prefix} ${part} references field "${field}" which is not present in query "${panel.query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`);
167
190
  };
168
191
  checkPanelField("valueField", panel.valueField);
192
+ checkPanelField("labelField", panel.labelField);
169
193
  checkPanelField("subField", panel.subField);
170
194
  checkPanelField("toneField", panel.toneField);
171
195
  checkPanelField("deltaField", panel.deltaField);
@@ -181,6 +205,21 @@ function checkVisibleWhenField(queryHandlers, visibleWhen, owner) {
181
205
  const { query, field } = visibleWhen;
182
206
  checkFieldExists(getZodObjectShape(queryHandlers.get(query)?.outputSchema), field, () => `${owner} visibleWhen references field "${field}" which is not present in query "${query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`);
183
207
  }
208
+ // Without an introspectable output shape the only fields known to exist are the panel's own columns.
209
+ function checkRowFieldsAreColumns(featureName, screenId, panel, refs) {
210
+ const columnFields = new Set(panel.columns.map((column) => normalizeListColumn(column).field));
211
+ for (const { option, field } of refs) {
212
+ if (columnFields.has(field))
213
+ continue;
214
+ const isNarrow = option.startsWith("narrow.");
215
+ const isNewRowLink = option === "rowLink.screenField" || option === "rowLink.paramsField";
216
+ if (!isNarrow && !isNewRowLink)
217
+ continue;
218
+ throw bootRuleError(isNarrow ? DASHBOARD_RULES.listNarrowFieldUnknown : DASHBOARD_RULES.listRowLinkInvalid, {
219
+ message: `[Feature ${featureName}] Screen "${screenId}" (dashboard) list-panel "${panel.id}" ${option} names "${field}", but query "${panel.query}" declares no outputSchema, so only a column of the panel can be checked. Declare the outputSchema or use a column.`,
220
+ });
221
+ }
222
+ }
184
223
  function checkDashboardOutputFields(queryHandlers, featureName, screenId, screen) {
185
224
  for (const panel of screen.panels) {
186
225
  if (panel.kind !== "custom") {
@@ -199,6 +238,20 @@ function checkDashboardOutputFields(queryHandlers, featureName, screenId, screen
199
238
  for (const column of panel.columns) {
200
239
  checkColumnField(rowShape, column, (field) => `[Feature ${featureName}] Screen "${screenId}" (dashboard) panel "${panel.id}" column "${field}" is not present in query "${panel.query}"'s outputSchema — check for a typo, or set virtual: true on it to mark it a virtual/computed column.`);
201
240
  }
241
+ const { rowLink, narrow } = panel;
242
+ const rowLinkRefs = [
243
+ { option: "rowLink.paramField", field: rowLink?.paramField },
244
+ { option: "rowLink.screenField", field: rowLink?.screenField },
245
+ { option: "rowLink.paramsField", field: rowLink?.paramsField },
246
+ { option: "narrow.titleField", field: narrow?.titleField },
247
+ { option: "narrow.field", field: narrow?.field },
248
+ ].flatMap(({ option, field }) => (field === undefined ? [] : [{ option, field }]));
249
+ if (rowShape === undefined) {
250
+ checkRowFieldsAreColumns(featureName, screenId, panel, rowLinkRefs);
251
+ }
252
+ for (const { option, field } of [...listGuidanceFieldRefs(panel), ...rowLinkRefs]) {
253
+ checkFieldExists(rowShape, field, () => `[Feature ${featureName}] Screen "${screenId}" (dashboard) list-panel "${panel.id}" ${option} references field "${field}" which is not present in query "${panel.query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`);
254
+ }
202
255
  }
203
256
  // chart/feed/progress-list/custom panels have a fixed query-result
204
257
  // contract with no author-declared field names to check.
@@ -0,0 +1,7 @@
1
+ import type { ProjectionDetailScreenDefinition, ProjectionListScreenDefinition } from "@cosmicdrift/kumiko-types/screen";
2
+ export type GuidanceFieldRef = {
3
+ readonly option: string;
4
+ readonly field: string;
5
+ };
6
+ export declare function detailGuidanceFieldRefs(screen: ProjectionDetailScreenDefinition): readonly GuidanceFieldRef[];
7
+ export declare function listGuidanceFieldRefs(screen: Pick<ProjectionListScreenDefinition, "columns" | "rowToneField">): readonly GuidanceFieldRef[];
@@ -0,0 +1,39 @@
1
+ import { normalizeListColumn } from "../screen-helpers.js";
2
+ function definedRefs(candidates) {
3
+ return candidates.flatMap(({ option, field }) => field === undefined ? [] : [{ option, field }]);
4
+ }
5
+ export function detailGuidanceFieldRefs(screen) {
6
+ return definedRefs([
7
+ { option: "breadcrumb.field", field: screen.breadcrumb?.field },
8
+ { option: "summary.field", field: screen.summary?.field },
9
+ { option: "summary.toneField", field: screen.summary?.toneField },
10
+ { option: "summary.narrowField", field: screen.summary?.narrowField },
11
+ { option: "banner.field", field: screen.banner?.field },
12
+ { option: "steps.field", field: screen.steps?.field },
13
+ { option: "steps.subtitleField", field: screen.steps?.subtitleField },
14
+ { option: "progress.field", field: screen.progress?.field },
15
+ ...(screen.metrics ?? []).flatMap((metric) => [
16
+ { option: "metrics.toneField", field: metric.toneField },
17
+ { option: "metrics.subField", field: metric.subField },
18
+ { option: "metrics.labelField", field: metric.labelField },
19
+ ]),
20
+ ]);
21
+ }
22
+ export function listGuidanceFieldRefs(screen) {
23
+ return definedRefs([
24
+ { option: "rowToneField", field: screen.rowToneField },
25
+ ...screen.columns.flatMap((col) => {
26
+ const column = normalizeListColumn(col);
27
+ const hint = column.hint;
28
+ return [
29
+ { option: "linkParamsField", field: column.linkParamsField },
30
+ { option: "hint.detailField", field: hint?.detailField },
31
+ { option: "hint.narrowDetailField", field: hint?.narrowDetailField },
32
+ { option: "hint.toneField", field: hint?.toneField },
33
+ { option: "hint.reasonField", field: hint?.reasonField },
34
+ { option: "hint.reasonOpenField", field: hint?.reasonOpenField },
35
+ { option: "hint.reasonTitleField", field: hint?.reasonTitleField },
36
+ ];
37
+ }),
38
+ ]);
39
+ }
@@ -1,7 +1,9 @@
1
1
  import { isFieldsEditSection, normalizeEditField, sectionFieldSpecs } from "../screen-helpers.js";
2
2
  import { bootRuleError } from "./boot-rule.js";
3
+ import { LIST_ROW_GUIDANCE_RULES } from "./list-row-guidance-rules.js";
3
4
  import { buildQueryHandlerMap } from "./projection-list-screens.js";
4
5
  import { QUERY_RULES } from "./query-rules.js";
6
+ import { getZodObjectShape } from "./zod-shape.js";
5
7
  const NOT_REGISTERED_SUFFIX = "is not a registered query-handler. Check the QN spelling (expected " +
6
8
  '"<feature>:query:<short>") and that the handler is declared via r.queryHandler(...).';
7
9
  function isNonEmptyQueryString(value) {
@@ -67,7 +69,7 @@ function checkDashboardQueryRefs(queryHandlers, featureName, screenId, screen) {
67
69
  if (panel.visibleWhen !== undefined) {
68
70
  checkVisibleWhenQueryRef(queryHandlers, panel.visibleWhen.query, () => `[Feature ${featureName}] Screen "${screenId}" (dashboard) ${panel.kind === "screen" ? "screen-panel" : "panel"} "${panel.id}" visibleWhen`);
69
71
  }
70
- if (panel.kind === "screen" || panel.kind === "text")
72
+ if (panel.kind === "screen")
71
73
  continue;
72
74
  if (panel.kind === "stat-group") {
73
75
  for (const stat of panel.stats) {
@@ -75,6 +77,9 @@ function checkDashboardQueryRefs(queryHandlers, featureName, screenId, screen) {
75
77
  }
76
78
  continue;
77
79
  }
80
+ // skip: a text panel without a query shows only its static blocks
81
+ if (panel.query === undefined)
82
+ continue;
78
83
  checkQueryRef(queryHandlers, panel.query, () => `[Feature ${featureName}] Screen "${screenId}" (dashboard) panel "${panel.id}"`);
79
84
  }
80
85
  if (screen.filter?.optionsQuery !== undefined) {
@@ -118,6 +123,22 @@ function checkEditFormScreenQueryRefs(queryHandlers, featureName, screenId, scre
118
123
  checkFormFieldQueryRefs(queryHandlers, featureName, screenId, "secretMint confirm", screen.confirm.fields);
119
124
  }
120
125
  }
126
+ // The list always sends `ids`; a closed input object without it would reject every decoration call.
127
+ function checkRowDecorationQueryRef(queryHandlers, featureName, screenId, screen) {
128
+ const decoration = screen.rowDecoration;
129
+ // skip: no rowDecoration declared
130
+ if (decoration === undefined)
131
+ return;
132
+ const prefix = `[Feature ${featureName}] Screen "${screenId}" (${screen.type}) rowDecoration`;
133
+ checkQueryRef(queryHandlers, decoration.query, () => prefix);
134
+ const inputShape = getZodObjectShape(queryHandlers.get(decoration.query)?.schema);
135
+ // skip: unregistered or non-introspectable input schema, nothing to pin
136
+ if (inputShape === undefined || "ids" in inputShape)
137
+ return;
138
+ throw bootRuleError(LIST_ROW_GUIDANCE_RULES.rowDecorationIdsMissing, {
139
+ message: `${prefix} query "${decoration.query}" does not declare "ids" in its input schema. The list sends the loaded row ids as "ids"; add ids: z.array(z.string()).`,
140
+ });
141
+ }
121
142
  function checkToolbarVisibleWhenQueryRefs(queryHandlers, featureName, screenId, screen) {
122
143
  for (const action of screen.toolbarActions ?? []) {
123
144
  if (action.visibleWhen === undefined)
@@ -139,9 +160,11 @@ function checkScreenQueryRefs(queryHandlers, featureName, screenId, screen) {
139
160
  if (screen.type === "projectionList") {
140
161
  checkQueryRef(queryHandlers, screen.query, () => `[Feature ${featureName}] Screen "${screenId}" (projectionList)`);
141
162
  checkToolbarVisibleWhenQueryRefs(queryHandlers, featureName, screenId, screen);
163
+ checkRowDecorationQueryRef(queryHandlers, featureName, screenId, screen);
142
164
  }
143
165
  else if (screen.type === "entityList") {
144
166
  checkToolbarVisibleWhenQueryRefs(queryHandlers, featureName, screenId, screen);
167
+ checkRowDecorationQueryRef(queryHandlers, featureName, screenId, screen);
145
168
  if (screen.expandableRow !== undefined) {
146
169
  checkQueryRef(queryHandlers, screen.expandableRow.query, () => `[Feature ${featureName}] Screen "${screenId}" (entityList) expandableRow "${screen.expandableRow?.title}"`);
147
170
  }
@@ -0,0 +1,11 @@
1
+ import type { FeatureDefinition } from "../types/index.ts";
2
+ export type RowDecorationFields = {
3
+ readonly kind: "known";
4
+ readonly names: ReadonlySet<string>;
5
+ } | {
6
+ readonly kind: "opaque";
7
+ };
8
+ export declare function resolveRowDecorationFields(features: Iterable<FeatureDefinition>, rowDecoration: {
9
+ readonly query: string;
10
+ } | undefined): RowDecorationFields | undefined;
11
+ export declare function acceptsRowDecorationField(decoration: RowDecorationFields | undefined, field: string): boolean;
@@ -0,0 +1,16 @@
1
+ import { buildQueryHandlerMap } from "./projection-list-screens.js";
2
+ import { getZodRowShape } from "./zod-shape.js";
3
+ export function resolveRowDecorationFields(features, rowDecoration) {
4
+ if (rowDecoration === undefined)
5
+ return undefined;
6
+ const handler = buildQueryHandlerMap([...features]).get(rowDecoration.query);
7
+ const rowShape = getZodRowShape(handler?.outputSchema);
8
+ return rowShape === undefined
9
+ ? { kind: "opaque" }
10
+ : { kind: "known", names: new Set(Object.keys(rowShape)) };
11
+ }
12
+ export function acceptsRowDecorationField(decoration, field) {
13
+ if (decoration === undefined)
14
+ return false;
15
+ return decoration.kind === "opaque" || decoration.names.has(field);
16
+ }
@@ -0,0 +1,10 @@
1
+ import type { FeatureDefinition } from "../types/index.ts";
2
+ export type DashboardPanelLinkTarget = {
3
+ readonly screen: string;
4
+ readonly namedFilter?: string;
5
+ readonly params?: Readonly<Record<string, unknown>>;
6
+ };
7
+ export declare function validateListRowLinkTarget(where: string, rowLink: {
8
+ readonly screen?: string | undefined;
9
+ } | undefined, featureName: string, featureMap: ReadonlyMap<string, FeatureDefinition>): void;
10
+ export declare function validateDashboardPanelLink(where: string, link: DashboardPanelLinkTarget | undefined, featureName: string, featureMap: ReadonlyMap<string, FeatureDefinition>): void;
@@ -0,0 +1,36 @@
1
+ import { bootRuleError } from "./boot-rule.js";
2
+ import { declaredNamedFilterIds, resolveDashboardScreenTarget } from "./dashboard-screen-target.js";
3
+ import { validateNavigateParams } from "./dashboard-stat-navigate.js";
4
+ import { DASHBOARD_RULES } from "./screens-dashboard-rules.js";
5
+ // A rowLink naming its target per row (screenField) has nothing to resolve at boot.
6
+ export function validateListRowLinkTarget(where, rowLink, featureName, featureMap) {
7
+ if (rowLink?.screen === undefined)
8
+ return;
9
+ validateDashboardPanelLink(where, { screen: rowLink.screen }, featureName, featureMap);
10
+ }
11
+ // `where` names the option ("... list-panel "x" footerLink") so the one rule reads right for
12
+ // both the list footer and the stat-group link.
13
+ export function validateDashboardPanelLink(where, link, featureName, featureMap) {
14
+ // skip: the panel declares no link
15
+ if (link === undefined)
16
+ return;
17
+ validateNavigateParams(where, link.params);
18
+ const resolved = resolveDashboardScreenTarget(featureName, link.screen, featureMap);
19
+ if (resolved.kind === "unresolved") {
20
+ throw bootRuleError(DASHBOARD_RULES.panelLinkTarget, {
21
+ message: `${where} screen "${link.screen}" does not resolve to a registered screen (checked "${resolved.qn}"). Use a same-feature short id or a cross-feature QN "<feature>:screen:<id>".`,
22
+ });
23
+ }
24
+ if (link.namedFilter === undefined)
25
+ return;
26
+ if (resolved.kind !== "list") {
27
+ throw bootRuleError(DASHBOARD_RULES.panelLinkTarget, {
28
+ message: `${where} sets namedFilter "${link.namedFilter}" but screen "${resolved.screenId}" is not a list screen. Remove namedFilter.`,
29
+ });
30
+ }
31
+ if (!declaredNamedFilterIds(resolved.target).has(link.namedFilter)) {
32
+ throw bootRuleError(DASHBOARD_RULES.panelLinkTarget, {
33
+ message: `${where} namedFilter "${link.namedFilter}" is not declared in namedFilters of screen "${resolved.target.screen.id}". Add { id, label } to that screen.`,
34
+ });
35
+ }
36
+ }
@@ -0,0 +1,4 @@
1
+ import type { DashboardListPanel, DashboardPanelDefinition } from "../types/screen.ts";
2
+ /** The screen itself is checked by validateDashboardPanelLink; this covers the rest of the shape. */
3
+ export declare function validateListRowLinkShape(context: string, panel: DashboardListPanel): void;
4
+ export declare function validateDashboardPanelNarrow(featureName: string, screenId: string, panel: DashboardPanelDefinition): void;
@@ -0,0 +1,211 @@
1
+ import { normalizeListColumn } from "../screen-helpers.js";
2
+ import { bootRuleError } from "./boot-rule.js";
3
+ import { DASHBOARD_RULES } from "./screens-dashboard-rules.js";
4
+ import { isSelectOptionTone } from "./select-option-tone.js";
5
+ const STAT_GROUP_COLUMN_COUNTS = [2, 3, 4];
6
+ const LIST_NARROW_LAYOUTS = ["cards", "line"];
7
+ const ROW_TONE_MARKERS = ["bar", "dot"];
8
+ function validateListNarrowTexts(context, panel, narrow) {
9
+ if (narrow.titleField !== undefined) {
10
+ const hasHintColumn = panel.columns.some((column) => normalizeListColumn(column).hint !== undefined);
11
+ if (narrow.layout === "line" || !hasHintColumn || narrow.titleField.trim().length === 0) {
12
+ throw bootRuleError(DASHBOARD_RULES.listNarrowFieldUnknown, {
13
+ message: `${context} sets narrow.titleField "${narrow.titleField}", which needs a non-empty field name, the "cards" layout and a hint column whose sentence it replaces.`,
14
+ });
15
+ }
16
+ }
17
+ if (narrow.moreText !== undefined &&
18
+ (narrow.layout !== "line" || narrow.moreText.trim().length === 0)) {
19
+ throw bootRuleError(DASHBOARD_RULES.listNarrowInvalid, {
20
+ message: `${context} sets narrow.moreText, which needs a non-empty i18n key and narrow.layout "line" (the only layout that draws it).`,
21
+ });
22
+ }
23
+ }
24
+ function validateListLook(context, panel) {
25
+ if (panel.icon !== undefined && panel.narrow?.layout !== "line") {
26
+ throw bootRuleError(DASHBOARD_RULES.listNarrowInvalid, {
27
+ message: `${context} sets icon, which only the narrow.layout "line" draws. Set narrow.layout "line" or remove icon.`,
28
+ });
29
+ }
30
+ if (panel.footerLink?.narrowOnly === true && panel.narrow?.layout !== "line") {
31
+ throw bootRuleError(DASHBOARD_RULES.listNarrowInvalid, {
32
+ message: `${context} sets footerLink.narrowOnly, which only serves the narrow.layout "line". Set narrow.layout "line" or remove narrowOnly (the footer link would never be drawn).`,
33
+ });
34
+ }
35
+ if (panel.rowToneMarker !== undefined && !ROW_TONE_MARKERS.includes(panel.rowToneMarker)) {
36
+ throw bootRuleError(DASHBOARD_RULES.listRowToneMarkerInvalid, {
37
+ message: `${context} rowToneMarker "${String(panel.rowToneMarker)}" is not "bar" or "dot".`,
38
+ });
39
+ }
40
+ }
41
+ function validateListNarrow(context, panel) {
42
+ const { narrow } = panel;
43
+ validateListLook(context, panel);
44
+ // skip: the list keeps its table on a phone
45
+ if (narrow === undefined)
46
+ return;
47
+ if (narrow.limit !== undefined && (!Number.isInteger(narrow.limit) || narrow.limit < 1)) {
48
+ throw bootRuleError(DASHBOARD_RULES.listNarrowInvalid, {
49
+ message: `${context} narrow.limit "${String(narrow.limit)}" is not a positive integer. Set it to a whole number of at least 1.`,
50
+ });
51
+ }
52
+ if (narrow.layout !== undefined && !LIST_NARROW_LAYOUTS.includes(narrow.layout)) {
53
+ throw bootRuleError(DASHBOARD_RULES.listNarrowInvalid, {
54
+ message: `${context} narrow.layout "${String(narrow.layout)}" is not "cards" or "line".`,
55
+ });
56
+ }
57
+ if (narrow.field !== undefined) {
58
+ if (narrow.layout !== "line" || narrow.field.trim().length === 0) {
59
+ throw bootRuleError(DASHBOARD_RULES.listNarrowFieldUnknown, {
60
+ message: `${context} sets narrow.field "${narrow.field}", which needs narrow.layout "line" and a non-empty name of a field of the query output.`,
61
+ });
62
+ }
63
+ }
64
+ validateListNarrowTexts(context, panel, narrow);
65
+ if (narrow.layout === "line" && panel.footerLink === undefined) {
66
+ throw bootRuleError(DASHBOARD_RULES.listNarrowLineWithoutFooterLink, {
67
+ message: `${context} sets narrow.layout "line" without footerLink — the line links to it. Add footerLink or use "cards".`,
68
+ });
69
+ }
70
+ }
71
+ const ROW_LINK_ICONS = ["arrow", "chevron"];
72
+ /** The screen itself is checked by validateDashboardPanelLink; this covers the rest of the shape. */
73
+ export function validateListRowLinkShape(context, panel) {
74
+ const { rowLink } = panel;
75
+ // skip: the rows are not links
76
+ if (rowLink === undefined)
77
+ return;
78
+ if ((rowLink.screen === undefined) === (rowLink.screenField === undefined)) {
79
+ throw bootRuleError(DASHBOARD_RULES.listRowLinkInvalid, {
80
+ message: `${context} rowLink sets ${rowLink.screen === undefined ? "neither screen nor screenField" : "both screen and screenField"}. Name one target screen with screen, or the row field holding it with screenField.`,
81
+ });
82
+ }
83
+ if (rowLink.screen !== undefined && rowLink.paramsField !== undefined) {
84
+ throw bootRuleError(DASHBOARD_RULES.listRowLinkInvalid, {
85
+ message: `${context} rowLink combines screen with paramsField. Use paramField with screen, paramsField with screenField.`,
86
+ });
87
+ }
88
+ if (rowLink.screenField !== undefined && rowLink.paramField !== undefined) {
89
+ throw bootRuleError(DASHBOARD_RULES.listRowLinkInvalid, {
90
+ message: `${context} rowLink combines screenField with paramField. Use paramsField with screenField, paramField with screen.`,
91
+ });
92
+ }
93
+ for (const [option, field] of [
94
+ ["paramField", rowLink.paramField],
95
+ ["screenField", rowLink.screenField],
96
+ ["paramsField", rowLink.paramsField],
97
+ ]) {
98
+ if (field !== undefined && field.trim().length === 0) {
99
+ throw bootRuleError(DASHBOARD_RULES.listRowLinkInvalid, {
100
+ message: `${context} rowLink.${option} is empty. Name the row field or remove it.`,
101
+ });
102
+ }
103
+ }
104
+ if (rowLink.icon !== undefined && !ROW_LINK_ICONS.includes(rowLink.icon)) {
105
+ throw bootRuleError(DASHBOARD_RULES.listRowLinkInvalid, {
106
+ message: `${context} rowLink.icon "${String(rowLink.icon)}" is not "arrow" or "chevron".`,
107
+ });
108
+ }
109
+ }
110
+ // "strip" is the default only without a label; a labelled group defaults to "cards".
111
+ function isTitledStrip(panel) {
112
+ return panel.label !== undefined && panel.layout === "strip";
113
+ }
114
+ function validateStatGroupChildren(context, panel) {
115
+ for (const stat of panel.stats) {
116
+ if (stat.narrowLabel !== undefined && !isTitledStrip(panel)) {
117
+ throw bootRuleError(DASHBOARD_RULES.statNarrowLabelOutsideGroup, {
118
+ message: `${context} child "${stat.id}" sets narrowLabel, but only the one-line phone strip of a titled group with layout "strip" draws it. Give the group a label and layout "strip", or remove narrowLabel.`,
119
+ });
120
+ }
121
+ if (stat.hideOnNarrow !== undefined) {
122
+ throw bootRuleError(DASHBOARD_RULES.statGroupChildHideOnNarrow, {
123
+ message: `${context} child "${stat.id}" sets hideOnNarrow — set it on the whole group instead; a hidden cell would leave a gap.`,
124
+ });
125
+ }
126
+ if (stat.narrowOrder !== undefined) {
127
+ throw bootRuleError(DASHBOARD_RULES.narrowOrderInvalid, {
128
+ message: `${context} child "${stat.id}" sets narrowOrder — set it on the whole group instead.`,
129
+ });
130
+ }
131
+ if (stat.narrowLabel !== undefined && stat.narrowLabel.trim().length === 0) {
132
+ throw bootRuleError(DASHBOARD_RULES.statNarrowLabelOutsideGroup, {
133
+ message: `${context} child "${stat.id}" sets an empty narrowLabel. Name an i18n key or remove it.`,
134
+ });
135
+ }
136
+ }
137
+ }
138
+ function validateStatGroupNarrow(context, panel) {
139
+ validateStatGroupChildren(context, panel);
140
+ if (panel.icon !== undefined && !isTitledStrip(panel)) {
141
+ throw bootRuleError(DASHBOARD_RULES.statGroupIconWithoutTitledStrip, {
142
+ message: `${context} sets icon without a label or with layout "cards" — only the titled strip draws it. Add a label and layout "strip", or remove icon.`,
143
+ });
144
+ }
145
+ if (panel.narrow !== undefined && !isTitledStrip(panel)) {
146
+ throw bootRuleError(DASHBOARD_RULES.statGroupNarrowWithoutTitledStrip, {
147
+ message: `${context} sets narrow without a label or with layout "cards" — only the titled strip has a phone line to tint. Add a label and layout "strip", or remove narrow.`,
148
+ });
149
+ }
150
+ if (panel.narrow?.tone !== undefined && !isSelectOptionTone(panel.narrow.tone)) {
151
+ throw bootRuleError(DASHBOARD_RULES.statGroupNarrowToneInvalid, {
152
+ message: `${context} narrow.tone "${String(panel.narrow.tone)}" is not a select option tone.`,
153
+ });
154
+ }
155
+ // skip: no column count declared
156
+ if (panel.columns === undefined)
157
+ return;
158
+ if (!STAT_GROUP_COLUMN_COUNTS.includes(panel.columns)) {
159
+ throw bootRuleError(DASHBOARD_RULES.statGroupColumnsInvalid, {
160
+ message: `${context} columns "${String(panel.columns)}" is not 2, 3 or 4.`,
161
+ });
162
+ }
163
+ const layout = panel.layout ?? (panel.label === undefined ? "strip" : "cards");
164
+ if (layout !== "cards") {
165
+ throw bootRuleError(DASHBOARD_RULES.statGroupColumnsInvalid, {
166
+ message: `${context} sets columns on a "strip" group — columns only lays out layout "cards". Give the group a label or layout: "cards", or remove columns.`,
167
+ });
168
+ }
169
+ }
170
+ function validateTextNarrow(context, panel) {
171
+ // skip: no narrow variant
172
+ if (panel.narrowBlocks === undefined)
173
+ return;
174
+ if (panel.narrowBlocks.length === 0 || (panel.blocks ?? []).length === 0) {
175
+ throw bootRuleError(DASHBOARD_RULES.textNarrowBlocksWithoutBlocks, {
176
+ message: `${context} sets narrowBlocks without blocks, or an empty narrowBlocks. Declare blocks (shown from sm up) and at least one narrow block, or remove narrowBlocks.`,
177
+ });
178
+ }
179
+ }
180
+ function validateStatNarrowLabel(context, panel) {
181
+ if (panel.narrowLabel !== undefined) {
182
+ throw bootRuleError(DASHBOARD_RULES.statNarrowLabelOutsideGroup, {
183
+ message: `${context} sets narrowLabel outside a stat-group — only the one-line phone strip of a titled stat-group draws it. Move the stat into a group or remove narrowLabel.`,
184
+ });
185
+ }
186
+ }
187
+ function validateNarrowOrder(context, panel) {
188
+ const { narrowOrder } = panel;
189
+ // skip: declared order
190
+ if (narrowOrder === undefined)
191
+ return;
192
+ if (!Number.isInteger(narrowOrder) || narrowOrder < 0) {
193
+ throw bootRuleError(DASHBOARD_RULES.narrowOrderInvalid, {
194
+ message: `${context} narrowOrder "${String(narrowOrder)}" is not an integer of at least 0.`,
195
+ });
196
+ }
197
+ }
198
+ // Phone-layout options per panel kind; `hideOnNarrow` itself is a plain flag with no cross-field rule.
199
+ export function validateDashboardPanelNarrow(featureName, screenId, panel) {
200
+ const prefix = `[Feature ${featureName}] Screen "${screenId}" (dashboard)`;
201
+ validateNarrowOrder(`${prefix} panel "${panel.id}"`, panel);
202
+ if (panel.kind === "stat")
203
+ validateStatNarrowLabel(`${prefix} stat "${panel.id}"`, panel);
204
+ if (panel.kind === "list")
205
+ validateListNarrow(`${prefix} list-panel "${panel.id}"`, panel);
206
+ else if (panel.kind === "stat-group") {
207
+ validateStatGroupNarrow(`${prefix} stat-group "${panel.id}"`, panel);
208
+ }
209
+ else if (panel.kind === "text")
210
+ validateTextNarrow(`${prefix} text-panel "${panel.id}"`, panel);
211
+ }