@cosmicdrift/kumiko-framework 0.413.1 → 0.415.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 (479) hide show
  1. package/AGENTS.md +5 -2
  2. package/agents/api/framework-db.md +14 -3
  3. package/agents/api/framework-engine.md +69 -13
  4. package/agents/api/framework-errors.md +1 -1
  5. package/agents/api/framework-event-store.md +14 -0
  6. package/agents/api/framework-ui-types.md +158 -21
  7. package/agents/api/renderer-web.md +112 -11
  8. package/agents/api/testing-helpers.md +3 -2
  9. package/agents/api/testing-stack.md +3 -0
  10. package/agents/api/types.md +248 -24
  11. package/agents/api.md +7 -7
  12. package/agents/boot-rules.md +66 -10
  13. package/agents/examples/api-docs.md +2 -6
  14. package/agents/examples/auth-mfa.md +57 -10
  15. package/agents/examples/chat-channels.md +2 -0
  16. package/agents/examples/crypto-shredding-hr.md +63 -1
  17. package/agents/examples/currencies-global.md +1 -0
  18. package/agents/examples/env-composition.md +7 -11
  19. package/agents/examples/managed-pages.md +90 -1
  20. package/agents/examples/pwa-shell.md +210 -0
  21. package/agents/examples/rate-limiting.md +3 -3
  22. package/agents/examples/record-detail-layout.md +1643 -67
  23. package/agents/examples/workflow-engine.md +16 -12
  24. package/agents/examples.md +1 -0
  25. package/agents/features-index.md +4 -2
  26. package/agents/features.md +22 -7
  27. package/agents/widgets.md +26 -1
  28. package/dist/api/api-constants.d.ts +1 -0
  29. package/dist/api/api-constants.js +4 -0
  30. package/dist/api/auth-middleware.js +4 -3
  31. package/dist/api/auth-routes-shared.js +2 -1
  32. package/dist/api/entity-read-access.d.ts +1 -0
  33. package/dist/api/entity-read-access.js +18 -0
  34. package/dist/api/export/export-route.d.ts +6 -1
  35. package/dist/api/export/export-route.js +27 -1
  36. package/dist/api/export/export-rows.js +19 -3
  37. package/dist/api/request-context-internals.d.ts +2 -0
  38. package/dist/api/request-context-scopes.js +9 -2
  39. package/dist/api/request-context.js +1 -1
  40. package/dist/api/routes.d.ts +2 -0
  41. package/dist/api/routes.js +9 -1
  42. package/dist/api/server-event-dispatcher.js +3 -0
  43. package/dist/api/server-extra-routes.js +2 -1
  44. package/dist/api/server-feature-http-routes.d.ts +9 -0
  45. package/dist/api/server-feature-http-routes.js +109 -0
  46. package/dist/api/server-middleware.js +2 -19
  47. package/dist/api/server-pat-rate-limit-guard.d.ts +3 -0
  48. package/dist/api/server-pat-rate-limit-guard.js +19 -0
  49. package/dist/api/server-rate-limit-wiring.d.ts +10 -0
  50. package/dist/api/server-rate-limit-wiring.js +37 -0
  51. package/dist/api/server-routes.d.ts +4 -12
  52. package/dist/api/server-routes.js +12 -171
  53. package/dist/api/server-schema-route.d.ts +3 -0
  54. package/dist/api/server-schema-route.js +58 -0
  55. package/dist/api/server-wiring.js +2 -37
  56. package/dist/api/server.js +3 -1
  57. package/dist/compliance/override-schema.js +5 -5
  58. package/dist/compliance/sub-processors.js +10 -1
  59. package/dist/crypto/index.d.ts +1 -1
  60. package/dist/crypto/index.js +1 -1
  61. package/dist/crypto/pii-field-encryption.d.ts +2 -0
  62. package/dist/crypto/pii-field-encryption.js +16 -1
  63. package/dist/db/apply-entity-event.js +4 -0
  64. package/dist/db/bun-sql-connection-codes.d.ts +1 -0
  65. package/dist/db/bun-sql-connection-codes.js +7 -0
  66. package/dist/db/collect-table-metas.js +4 -1
  67. package/dist/db/config-seed.js +1 -1
  68. package/dist/db/derived-field-sql.js +15 -13
  69. package/dist/db/derived-related-sql.d.ts +2 -2
  70. package/dist/db/derived-related-sql.js +4 -2
  71. package/dist/db/dialect.d.ts +3 -0
  72. package/dist/db/dialect.js +1 -3
  73. package/dist/db/driver-row-coercion.js +2 -2
  74. package/dist/db/driver-value-preparation.js +1 -1
  75. package/dist/db/eagerload.js +15 -12
  76. package/dist/db/entity-table-meta.d.ts +2 -0
  77. package/dist/db/entity-table-meta.js +7 -0
  78. package/dist/db/event-store-executor-context.js +13 -8
  79. package/dist/db/event-store-executor-read-aggregate-currencies.js +2 -2
  80. package/dist/db/event-store-executor-read-aggregate.js +2 -2
  81. package/dist/db/event-store-executor-read-filter.d.ts +4 -0
  82. package/dist/db/event-store-executor-read-filter.js +28 -11
  83. package/dist/db/event-store-executor-read-search.d.ts +1 -0
  84. package/dist/db/event-store-executor-read-search.js +6 -6
  85. package/dist/db/event-store-executor-read-sort.js +3 -3
  86. package/dist/db/event-store-executor-read-where.js +14 -5
  87. package/dist/db/event-store-executor-read.js +7 -7
  88. package/dist/db/event-store-executor-write.js +50 -95
  89. package/dist/db/executor-managed-tables.js +4 -1
  90. package/dist/db/index.d.ts +4 -2
  91. package/dist/db/index.js +4 -2
  92. package/dist/db/known-table-names.d.ts +1 -0
  93. package/dist/db/known-table-names.js +7 -5
  94. package/dist/db/list-aggregate-labels.d.ts +1 -0
  95. package/dist/db/list-aggregate-labels.js +9 -1
  96. package/dist/db/migrate-generator.js +23 -4
  97. package/dist/db/migrate-rls-diff.d.ts +1 -0
  98. package/dist/db/migrate-rls-diff.js +15 -1
  99. package/dist/db/migrate-runner.js +2 -2
  100. package/dist/db/money.d.ts +1 -1
  101. package/dist/db/money.js +1 -4
  102. package/dist/db/parent-ref-clause.d.ts +6 -2
  103. package/dist/db/parent-ref-clause.js +105 -24
  104. package/dist/db/parent-ref-global-hosts.d.ts +23 -0
  105. package/dist/db/parent-ref-global-hosts.js +85 -0
  106. package/dist/db/production-schema-command-hint.d.ts +1 -0
  107. package/dist/db/production-schema-command-hint.js +3 -0
  108. package/dist/db/queries/backfill-pii.js +55 -29
  109. package/dist/db/queries/ddl.js +13 -2
  110. package/dist/db/queries/event-store-open-streams.d.ts +15 -0
  111. package/dist/db/queries/event-store-open-streams.js +33 -0
  112. package/dist/db/queries/event-store-payload-scrub.d.ts +5 -0
  113. package/dist/db/queries/event-store-payload-scrub.js +11 -0
  114. package/dist/db/queries/event-store.js +0 -1
  115. package/dist/db/queries/raw-sql.js +0 -1
  116. package/dist/db/queries/rebuild-rls-guard.d.ts +2 -1
  117. package/dist/db/queries/rebuild-rls-guard.js +24 -11
  118. package/dist/db/queries/rls-boot-catalog.d.ts +1 -0
  119. package/dist/db/queries/rls-boot-catalog.js +13 -9
  120. package/dist/db/queries/rls-shape.d.ts +3 -1
  121. package/dist/db/queries/rls-shape.js +31 -6
  122. package/dist/db/queries/session-advisory-lock.js +2 -1
  123. package/dist/db/queries/test-stack.js +7 -7
  124. package/dist/db/query.js +16 -11
  125. package/dist/db/rebuild-marker.js +11 -2
  126. package/dist/db/render-rls-ddl.d.ts +2 -0
  127. package/dist/db/render-rls-ddl.js +16 -11
  128. package/dist/db/replay-migration-sql.js +1 -1
  129. package/dist/db/row-level-security-boot-check.js +18 -5
  130. package/dist/db/row-level-security-connection.js +25 -12
  131. package/dist/db/row-level-security-scope.d.ts +2 -1
  132. package/dist/db/row-level-security-scope.js +9 -5
  133. package/dist/db/sql-identifier.d.ts +1 -0
  134. package/dist/db/sql-identifier.js +3 -0
  135. package/dist/db/system-tenant-read-db.d.ts +5 -0
  136. package/dist/db/system-tenant-read-db.js +28 -0
  137. package/dist/db/table-builder.d.ts +3 -1
  138. package/dist/db/table-builder.js +18 -8
  139. package/dist/db/table-info.d.ts +1 -2
  140. package/dist/db/table-introspection.d.ts +3 -0
  141. package/dist/db/table-introspection.js +6 -0
  142. package/dist/db/table-push.d.ts +1 -0
  143. package/dist/db/table-push.js +7 -1
  144. package/dist/db/tenant-db-runner.d.ts +3 -0
  145. package/dist/db/tenant-db-runner.js +19 -1
  146. package/dist/db/transaction-serialization.d.ts +1 -0
  147. package/dist/db/transaction-serialization.js +20 -3
  148. package/dist/db/where-clause.js +11 -2
  149. package/dist/db/write-ownership-failures.d.ts +25 -0
  150. package/dist/db/write-ownership-failures.js +82 -0
  151. package/dist/engine/boot-validator/boot-check.js +7 -1
  152. package/dist/engine/boot-validator/boot-phases-app.js +5 -5
  153. package/dist/engine/boot-validator/boot-phases.js +3 -2
  154. package/dist/engine/boot-validator/boot-rules.d.ts +305 -28
  155. package/dist/engine/boot-validator/boot-rules.js +4 -0
  156. package/dist/engine/boot-validator/bundled-lists-table.js +2 -2
  157. package/dist/engine/boot-validator/card-meta-overflow-rules.d.ts +2 -2
  158. package/dist/engine/boot-validator/card-meta-overflow-rules.js +2 -2
  159. package/dist/engine/boot-validator/card-meta-overflow.js +8 -5
  160. package/dist/engine/boot-validator/config-deps.d.ts +0 -1
  161. package/dist/engine/boot-validator/config-deps.js +0 -28
  162. package/dist/engine/boot-validator/config-key-rules.d.ts +0 -15
  163. package/dist/engine/boot-validator/config-key-rules.js +0 -15
  164. package/dist/engine/boot-validator/dashboard-screen-target.d.ts +22 -0
  165. package/dist/engine/boot-validator/dashboard-screen-target.js +20 -0
  166. package/dist/engine/boot-validator/dashboard-stat-navigate.d.ts +1 -0
  167. package/dist/engine/boot-validator/dashboard-stat-navigate.js +25 -17
  168. package/dist/engine/boot-validator/definition-webhook-events-rules.d.ts +5 -0
  169. package/dist/engine/boot-validator/definition-webhook-events-rules.js +5 -0
  170. package/dist/engine/boot-validator/derived-sql-fields.js +1 -2
  171. package/dist/engine/boot-validator/entity-declaration-rules.d.ts +5 -0
  172. package/dist/engine/boot-validator/entity-declaration-rules.js +5 -0
  173. package/dist/engine/boot-validator/entity-list-screens.d.ts +1 -0
  174. package/dist/engine/boot-validator/entity-list-screens.js +35 -13
  175. package/dist/engine/boot-validator/entity-structure-rules.d.ts +5 -0
  176. package/dist/engine/boot-validator/entity-structure-rules.js +5 -0
  177. package/dist/engine/boot-validator/list-column-layout.js +10 -6
  178. package/dist/engine/boot-validator/list-row-guidance-rules.d.ts +67 -0
  179. package/dist/engine/boot-validator/list-row-guidance-rules.js +67 -0
  180. package/dist/engine/boot-validator/list-row-guidance.d.ts +20 -0
  181. package/dist/engine/boot-validator/list-row-guidance.js +143 -0
  182. package/dist/engine/boot-validator/list-sort-summary-rules.d.ts +42 -0
  183. package/dist/engine/boot-validator/list-sort-summary-rules.js +42 -0
  184. package/dist/engine/boot-validator/list-sort-summary.d.ts +5 -0
  185. package/dist/engine/boot-validator/list-sort-summary.js +160 -0
  186. package/dist/engine/boot-validator/list-table-options.js +15 -1
  187. package/dist/engine/boot-validator/list-table-rules.d.ts +10 -5
  188. package/dist/engine/boot-validator/list-table-rules.js +10 -5
  189. package/dist/engine/boot-validator/list-toolbar-options.d.ts +10 -0
  190. package/dist/engine/boot-validator/list-toolbar-options.js +30 -0
  191. package/dist/engine/boot-validator/named-filter-rules.d.ts +42 -2
  192. package/dist/engine/boot-validator/named-filter-rules.js +42 -2
  193. package/dist/engine/boot-validator/ownership.js +10 -1
  194. package/dist/engine/boot-validator/parent-ref.js +87 -50
  195. package/dist/engine/boot-validator/projection-list-screens.d.ts +1 -0
  196. package/dist/engine/boot-validator/projection-list-screens.js +32 -1
  197. package/dist/engine/boot-validator/query-output-columns.js +62 -9
  198. package/dist/engine/boot-validator/query-output-guidance.d.ts +7 -0
  199. package/dist/engine/boot-validator/query-output-guidance.js +40 -0
  200. package/dist/engine/boot-validator/query-refs.js +34 -1
  201. package/dist/engine/boot-validator/row-decoration.d.ts +11 -0
  202. package/dist/engine/boot-validator/row-decoration.js +16 -0
  203. package/dist/engine/boot-validator/screens-actions.js +1 -1
  204. package/dist/engine/boot-validator/screens-dashboard-links.d.ts +10 -0
  205. package/dist/engine/boot-validator/screens-dashboard-links.js +36 -0
  206. package/dist/engine/boot-validator/screens-dashboard-narrow.d.ts +4 -0
  207. package/dist/engine/boot-validator/screens-dashboard-narrow.js +211 -0
  208. package/dist/engine/boot-validator/screens-dashboard-rules.d.ts +84 -4
  209. package/dist/engine/boot-validator/screens-dashboard-rules.js +84 -4
  210. package/dist/engine/boot-validator/screens-dashboard.js +29 -7
  211. package/dist/engine/boot-validator/screens-kind-entity-list.js +32 -27
  212. package/dist/engine/boot-validator/screens-kind-projection-detail-guidance.d.ts +3 -0
  213. package/dist/engine/boot-validator/screens-kind-projection-detail-guidance.js +46 -0
  214. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +20 -0
  215. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +20 -0
  216. package/dist/engine/boot-validator/screens-kind-projection-detail.js +2 -0
  217. package/dist/engine/boot-validator/screens-kind-projection-list.js +4 -0
  218. package/dist/engine/boot-validator/screens-kind-rules.d.ts +25 -0
  219. package/dist/engine/boot-validator/screens-kind-rules.js +25 -0
  220. package/dist/engine/boot-validator/screens-lists.d.ts +8 -2
  221. package/dist/engine/boot-validator/screens-lists.js +19 -3
  222. package/dist/engine/boot-validator/screens.js +1 -1
  223. package/dist/engine/boot-validator/sort-nulls.d.ts +2 -0
  224. package/dist/engine/boot-validator/sort-nulls.js +15 -0
  225. package/dist/engine/boot-validator/zod-shape.d.ts +2 -1
  226. package/dist/engine/boot-validator/zod-shape.js +19 -1
  227. package/dist/engine/build-app-schema.js +4 -0
  228. package/dist/engine/config-helpers.d.ts +1 -2
  229. package/dist/engine/config-helpers.js +6 -7
  230. package/dist/engine/define-feature.js +1 -0
  231. package/dist/engine/define-handler.d.ts +1 -0
  232. package/dist/engine/define-handler.js +4 -2
  233. package/dist/engine/definition-violations.js +2 -2
  234. package/dist/engine/entity-handlers.js +3 -8
  235. package/dist/engine/entity-list-runtime-options.js +9 -8
  236. package/dist/engine/factories.d.ts +2 -0
  237. package/dist/engine/feature-config-events-jobs.js +1 -0
  238. package/dist/engine/feature-entity-handlers.js +5 -2
  239. package/dist/engine/field-access.d.ts +1 -1
  240. package/dist/engine/field-access.js +7 -10
  241. package/dist/engine/find-entity.js +3 -3
  242. package/dist/engine/form-derivations.js +3 -3
  243. package/dist/engine/index.d.ts +3 -3
  244. package/dist/engine/index.js +2 -2
  245. package/dist/engine/named-filter-roles.d.ts +3 -0
  246. package/dist/engine/named-filter-roles.js +15 -0
  247. package/dist/engine/pipeline.js +0 -1
  248. package/dist/engine/project-app-schema-for-roles.js +17 -2
  249. package/dist/engine/qualified-name.js +0 -1
  250. package/dist/engine/registry-facade.js +1 -2
  251. package/dist/engine/registry-state.d.ts +1 -1
  252. package/dist/engine/registry-state.js +5 -2
  253. package/dist/engine/registry-validate.js +2 -1
  254. package/dist/engine/resolve-named-list-filters.js +5 -2
  255. package/dist/engine/schema-builder.js +9 -11
  256. package/dist/engine/screen-helpers.d.ts +12 -0
  257. package/dist/engine/screen-helpers.js +17 -1
  258. package/dist/engine/soft-delete-cleanup.js +3 -5
  259. package/dist/engine/state-machine.js +0 -1
  260. package/dist/engine/steps/_database-clock.d.ts +2 -0
  261. package/dist/engine/steps/_database-clock.js +6 -0
  262. package/dist/engine/steps/compute.js +1 -1
  263. package/dist/engine/steps/retry.js +5 -1
  264. package/dist/engine/steps/return.js +0 -1
  265. package/dist/engine/steps/wait-for-event.js +2 -1
  266. package/dist/engine/steps/wait.js +2 -1
  267. package/dist/engine/system-user.d.ts +2 -2
  268. package/dist/engine/system-user.js +2 -2
  269. package/dist/engine/types/handlers.d.ts +1 -1
  270. package/dist/engine/types/handlers.js +1 -1
  271. package/dist/engine/types/screen.d.ts +1 -1
  272. package/dist/engine/types/screen.js +1 -1
  273. package/dist/engine/webhook-contracts.d.ts +2 -3
  274. package/dist/engine/webhook-contracts.js +2 -25
  275. package/dist/engine/webhook-events.js +48 -29
  276. package/dist/engine/webhook-payload-strictness.d.ts +7 -0
  277. package/dist/engine/webhook-payload-strictness.js +53 -0
  278. package/dist/env/_zod-introspect.d.ts +1 -0
  279. package/dist/env/dry-run.d.ts +1 -1
  280. package/dist/env/dry-run.js +1 -1
  281. package/dist/env/field-meta.d.ts +4 -0
  282. package/dist/env/field-meta.js +67 -0
  283. package/dist/env/field-rules.d.ts +9 -0
  284. package/dist/env/field-rules.js +46 -0
  285. package/dist/env/index.d.ts +3 -3
  286. package/dist/env/index.js +16 -71
  287. package/dist/env/internals.d.ts +3 -0
  288. package/dist/env/internals.js +1 -2
  289. package/dist/env/required-env.d.ts +3 -1
  290. package/dist/env/required-env.js +5 -2
  291. package/dist/errors/reasons.d.ts +1 -0
  292. package/dist/errors/reasons.js +4 -0
  293. package/dist/errors/serialize.js +2 -2
  294. package/dist/errors/write-error-info.js +0 -2
  295. package/dist/es-ops/operations-schema.js +18 -7
  296. package/dist/event-store/admin-api.js +3 -3
  297. package/dist/event-store/event-store.js +0 -3
  298. package/dist/event-store/index.d.ts +1 -0
  299. package/dist/event-store/index.js +1 -0
  300. package/dist/event-store/transfer.js +1 -1
  301. package/dist/files/assert-file-refs-belong-to-tenant.d.ts +2 -1
  302. package/dist/files/assert-file-refs-belong-to-tenant.js +15 -13
  303. package/dist/files/bind-pending-file-refs.d.ts +3 -1
  304. package/dist/files/bind-pending-file-refs.js +54 -27
  305. package/dist/files/copy-pending-file-refs-to-tenant.js +7 -3
  306. package/dist/files/create-file-ref.d.ts +4 -1
  307. package/dist/files/create-file-ref.js +14 -3
  308. package/dist/files/default-file-guard.js +4 -1
  309. package/dist/files/file-claim.d.ts +6 -0
  310. package/dist/files/file-claim.js +17 -0
  311. package/dist/files/file-field-slots.d.ts +2 -0
  312. package/dist/files/file-field-slots.js +28 -0
  313. package/dist/files/file-ref-entity.d.ts +3 -0
  314. package/dist/files/file-ref-entity.js +2 -0
  315. package/dist/files/file-ref-table.d.ts +3 -0
  316. package/dist/files/file-routes.d.ts +4 -1
  317. package/dist/files/file-routes.js +80 -16
  318. package/dist/files/in-memory-provider.d.ts +1 -1
  319. package/dist/files/in-memory-provider.js +2 -1
  320. package/dist/files/index.d.ts +1 -1
  321. package/dist/files/index.js +1 -1
  322. package/dist/files/invalid-file-ref-error.d.ts +2 -0
  323. package/dist/files/invalid-file-ref-error.js +15 -0
  324. package/dist/files/local-provider.js +9 -2
  325. package/dist/files/provider-resolver.js +1 -1
  326. package/dist/files/rebind-file-ref.d.ts +3 -2
  327. package/dist/files/rebind-file-ref.js +24 -18
  328. package/dist/files/resolve-file-handles.d.ts +13 -0
  329. package/dist/files/resolve-file-handles.js +57 -0
  330. package/dist/files/storage-tracking.d.ts +1 -1
  331. package/dist/files/storage-tracking.js +5 -2
  332. package/dist/files/sweep-stale-pending-file-refs.js +10 -4
  333. package/dist/files/types.d.ts +4 -0
  334. package/dist/files/types.js +10 -0
  335. package/dist/files/upload-field-resolution.d.ts +1 -0
  336. package/dist/files/upload-field-resolution.js +16 -2
  337. package/dist/files/upload-ledger.js +1 -1
  338. package/dist/i18n/required-surface-guidance-keys.d.ts +3 -0
  339. package/dist/i18n/required-surface-guidance-keys.js +9 -0
  340. package/dist/i18n/required-surface-keys.js +21 -5
  341. package/dist/internal/boot-rule-table-expectations.d.ts +2 -0
  342. package/dist/internal/boot-rule-table-expectations.js +29 -0
  343. package/dist/internal/row-level-security.d.ts +1 -0
  344. package/dist/internal/row-level-security.js +1 -0
  345. package/dist/internal/testing.d.ts +1 -0
  346. package/dist/internal/testing.js +1 -0
  347. package/dist/jobs/index.d.ts +1 -0
  348. package/dist/jobs/index.js +1 -0
  349. package/dist/jobs/job-load-events.d.ts +10 -0
  350. package/dist/jobs/job-load-events.js +12 -0
  351. package/dist/jobs/job-runner-context.js +6 -158
  352. package/dist/jobs/job-runner-dispatch.d.ts +7 -0
  353. package/dist/jobs/job-runner-dispatch.js +57 -0
  354. package/dist/jobs/job-runner-event-triggers.js +18 -9
  355. package/dist/jobs/job-runner-execution.js +5 -2
  356. package/dist/jobs/job-runner-facets.d.ts +48 -0
  357. package/dist/jobs/job-runner-facets.js +156 -0
  358. package/dist/jobs/job-runner-gates.js +19 -11
  359. package/dist/jobs/job-runner-helpers.d.ts +5 -1
  360. package/dist/jobs/job-runner-helpers.js +18 -3
  361. package/dist/jobs/job-runner-scope.d.ts +1 -0
  362. package/dist/jobs/job-runner-scope.js +2 -0
  363. package/dist/jobs/job-runner-tenant-cap-lock.d.ts +2 -0
  364. package/dist/jobs/job-runner-tenant-cap-lock.js +30 -0
  365. package/dist/jobs/job-runner-types.d.ts +1 -0
  366. package/dist/jobs/job-runner.js +39 -70
  367. package/dist/jobs/obliterate-job-queues.d.ts +6 -0
  368. package/dist/jobs/obliterate-job-queues.js +23 -0
  369. package/dist/lifecycle/lifecycle.js +1 -1
  370. package/dist/migrations/event-header-scrub.d.ts +11 -0
  371. package/dist/migrations/event-header-scrub.js +33 -0
  372. package/dist/migrations/event-payload-scrub.d.ts +1 -1
  373. package/dist/migrations/event-payload-scrub.js +36 -4
  374. package/dist/migrations/index.d.ts +1 -0
  375. package/dist/migrations/index.js +2 -0
  376. package/dist/migrations/kumiko-drift.d.ts +5 -2
  377. package/dist/migrations/kumiko-drift.js +51 -14
  378. package/dist/migrations/pending-rebuilds.js +4 -5
  379. package/dist/observability/sensitive-filter.js +0 -12
  380. package/dist/pipeline/aggregate-type-removal.js +17 -4
  381. package/dist/pipeline/context-services.d.ts +2 -0
  382. package/dist/pipeline/context-services.js +5 -2
  383. package/dist/pipeline/dispatch-batch.js +4 -3
  384. package/dist/pipeline/dispatch-context-helpers.d.ts +11 -0
  385. package/dist/pipeline/dispatch-context-helpers.js +58 -0
  386. package/dist/pipeline/dispatch-nested-write.d.ts +7 -0
  387. package/dist/pipeline/dispatch-nested-write.js +119 -0
  388. package/dist/pipeline/dispatch-query.js +10 -3
  389. package/dist/pipeline/dispatch-scope.js +4 -3
  390. package/dist/pipeline/dispatch-shared.d.ts +2 -6
  391. package/dist/pipeline/dispatch-shared.js +6 -38
  392. package/dist/pipeline/dispatch-write.d.ts +0 -1
  393. package/dist/pipeline/dispatch-write.js +3 -302
  394. package/dist/pipeline/dispatcher-utils.js +6 -0
  395. package/dist/pipeline/effective-system-scope.d.ts +3 -0
  396. package/dist/pipeline/effective-system-scope.js +22 -0
  397. package/dist/pipeline/event-dispatcher-delivery.d.ts +1 -0
  398. package/dist/pipeline/event-dispatcher-delivery.js +20 -9
  399. package/dist/pipeline/event-dispatcher.d.ts +6 -1
  400. package/dist/pipeline/event-dispatcher.js +6 -7
  401. package/dist/pipeline/handler-context-auth.d.ts +3 -2
  402. package/dist/pipeline/handler-context-auth.js +3 -4
  403. package/dist/pipeline/handler-context-db.js +11 -4
  404. package/dist/pipeline/handler-context-dispatch.js +2 -2
  405. package/dist/pipeline/handler-context-events.d.ts +8 -3
  406. package/dist/pipeline/handler-context-events.js +20 -65
  407. package/dist/pipeline/handler-context-member-resolution.js +16 -8
  408. package/dist/pipeline/handler-context-notify.d.ts +1 -0
  409. package/dist/pipeline/handler-context-notify.js +2 -0
  410. package/dist/pipeline/handler-context-phase-denials.js +3 -2
  411. package/dist/pipeline/handler-context-projection.d.ts +3 -0
  412. package/dist/pipeline/handler-context-projection.js +39 -0
  413. package/dist/pipeline/handler-context-scope.d.ts +1 -1
  414. package/dist/pipeline/handler-context-scope.js +14 -2
  415. package/dist/pipeline/index.d.ts +1 -1
  416. package/dist/pipeline/index.js +1 -1
  417. package/dist/pipeline/irreversible-operation-gate.js +36 -10
  418. package/dist/pipeline/lifecycle-pipeline.d.ts +1 -0
  419. package/dist/pipeline/lifecycle-pipeline.js +7 -4
  420. package/dist/pipeline/member-reader.js +4 -2
  421. package/dist/pipeline/msp-rebuild.js +1 -1
  422. package/dist/pipeline/nested-write-parent-guard.d.ts +5 -0
  423. package/dist/pipeline/nested-write-parent-guard.js +81 -0
  424. package/dist/pipeline/projection-rebuild.d.ts +2 -0
  425. package/dist/pipeline/projection-rebuild.js +16 -7
  426. package/dist/pipeline/projection-state.js +4 -6
  427. package/dist/pipeline/system-hooks.js +36 -6
  428. package/dist/pipeline/write-result-masking.js +31 -3
  429. package/dist/pipeline/write-transition-guard.d.ts +7 -0
  430. package/dist/pipeline/write-transition-guard.js +95 -0
  431. package/dist/schema-cli/shared.d.ts +2 -0
  432. package/dist/schema-cli/shared.js +4 -2
  433. package/dist/schema-cli/validate-command.js +43 -28
  434. package/dist/search/meilisearch-adapter-internals.d.ts +2 -0
  435. package/dist/search/meilisearch-adapter-internals.js +5 -0
  436. package/dist/search/meilisearch-adapter.d.ts +1 -0
  437. package/dist/search/meilisearch-adapter.js +17 -11
  438. package/dist/search/reindex-entity.d.ts +2 -0
  439. package/dist/search/reindex-entity.js +32 -4
  440. package/dist/search/reindex-tenants-search.js +20 -4
  441. package/dist/time/tz-context.js +1 -1
  442. package/dist/ui-types/card-column-roles.d.ts +6 -0
  443. package/dist/ui-types/card-column-roles.js +21 -3
  444. package/dist/ui-types/index.d.ts +3 -3
  445. package/dist/ui-types/index.js +2 -2
  446. package/dist/utils/ids.js +0 -1
  447. package/dist/utils/index.d.ts +1 -0
  448. package/dist/utils/index.js +1 -0
  449. package/dist/utils/return-path-limit.d.ts +1 -0
  450. package/dist/utils/return-path-limit.js +1 -0
  451. package/package.json +5 -3
  452. package/presets/biome-app.json +39 -21
  453. package/presets/biome-plugins/admin-api.grit +10 -0
  454. package/presets/biome-plugins/error-reasons.grit +53 -0
  455. package/presets/biome-plugins/es-literal-writes-tests.grit +18 -0
  456. package/presets/biome-plugins/es-literal-writes.grit +22 -0
  457. package/presets/biome-plugins/i18n-locale-terminology-de.grit +15 -0
  458. package/presets/biome-plugins/i18n-locale-terminology-romance.grit +10 -0
  459. package/presets/biome-plugins/no-create-test-dispatcher.grit +5 -0
  460. package/presets/biome-plugins/no-css-properties-type.grit +7 -0
  461. package/presets/biome-plugins/no-date-api.grit +11 -0
  462. package/presets/biome-plugins/no-direct-fetch.grit +16 -0
  463. package/presets/biome-plugins/no-direct-fs.grit +16 -0
  464. package/presets/biome-plugins/no-external-font-cdn-css.grit +9 -0
  465. package/presets/biome-plugins/no-external-font-cdn.grit +12 -0
  466. package/presets/biome-plugins/no-raw-hooks.grit +10 -0
  467. package/presets/biome-plugins/no-same-folder-barrel-import.grit +11 -0
  468. package/presets/biome-plugins/no-screen-container-classes.grit +7 -0
  469. package/presets/biome-plugins/no-skipped-or-retried-tests.grit +34 -0
  470. package/presets/biome-plugins/no-temporal-polyfill-require.grit +10 -0
  471. package/presets/biome-plugins/raw-html-in-web.grit +40 -0
  472. package/presets/biome-plugins/raw-ui-in-app.grit +142 -0
  473. package/presets/biome-plugins/restricted-event-store-symbols.grit +18 -0
  474. package/presets/biome-plugins/test-title.grit +20 -0
  475. package/presets/biome-plugins/unsafe-json-parse.grit +12 -0
  476. package/presets/biome-rules.json +467 -0
  477. package/src/changes.json +366 -0
  478. package/dist/engine/minor-units.d.ts +0 -2
  479. package/dist/engine/minor-units.js +0 -8
@@ -4,10 +4,50 @@ export const NAMED_FILTER_RULES = {
4
4
  summary: "A projectionList with namedFilters binds a query whose schema has a namedFilter key.",
5
5
  fix: "Add namedFilter: z.string().optional() to the query schema, resolve it with resolveNamedListFilters and pass the conditions into executor.list filters, the only path that applies field-read and PII guards.",
6
6
  },
7
+ projectionQueryAcceptsCount: {
8
+ id: "named-filter/projection-query-accepts-count",
9
+ summary: "A projectionList with namedFilterFacet.showCounts binds a query whose schema has limit and totalCount keys.",
10
+ fix: "Add limit and totalCount: z.boolean().optional() to the query schema and return the total, or drop showCounts.",
11
+ },
12
+ projectionQueryAcceptsSort: {
13
+ id: "named-filter/projection-query-accepts-sort",
14
+ summary: "A projectionList whose namedFilter sets a sort binds a query whose schema has sort and sortDirection keys.",
15
+ fix: "Add sort: z.enum([...sortable fields]) and sortDirection to the query schema and order by them, or remove sort from the named filter.",
16
+ },
17
+ filterSortNotListed: {
18
+ id: "list/named-filter-sort-not-listed",
19
+ summary: "A named filter's sort.field is one of the listed columns.",
20
+ fix: "Pick a field from columns or add it there.",
21
+ },
22
+ filterSortNotSortable: {
23
+ id: "list/named-filter-sort-not-sortable",
24
+ summary: "A named filter's sort column is sortable.",
25
+ fix: "Mark the field sortable or pick another sort field.",
26
+ },
27
+ facetWithoutFilters: {
28
+ id: "list/named-filter-facet-without-filters",
29
+ summary: "namedFilterFacet only presents the screen's namedFilters.",
30
+ fix: "Declare namedFilters on the screen or remove namedFilterFacet.",
31
+ },
32
+ emptyStateTitleEmpty: {
33
+ id: "list/named-filter-empty-state-title-empty",
34
+ summary: "A named filter's emptyState.title is a non-empty i18n key.",
35
+ fix: "Name the title key or remove emptyState from the filter.",
36
+ },
37
+ emptyStateParamsQueryEmpty: {
38
+ id: "list/named-filter-empty-state-params-query-empty",
39
+ summary: "A named filter's emptyState.paramsQuery is a non-empty query QN.",
40
+ fix: "Name the query or remove paramsQuery from the emptyState.",
41
+ },
42
+ emptyStateParamsQueryWithoutDescription: {
43
+ id: "list/named-filter-empty-state-params-query-without-description",
44
+ summary: "A named filter's emptyState.paramsQuery feeds the description, so it needs one.",
45
+ fix: "Set emptyState.description (an i18n key with {params}) or remove paramsQuery.",
46
+ },
7
47
  statNavigateTarget: {
8
48
  id: "named-filter/stat-navigate-target",
9
- summary: "A stat navigate.screen resolves to an entityList or projectionList screen.",
10
- fix: "Point navigate.screen at a registered list screen.",
49
+ summary: "A stat navigate.screen resolves to an entityList, projectionList or custom screen.",
50
+ fix: "Point navigate.screen at a registered list or custom screen.",
11
51
  },
12
52
  statNavigateFilterDeclared: {
13
53
  id: "named-filter/stat-navigate-filter-declared",
@@ -61,7 +61,16 @@ export function validateOwnershipBoot(features) {
61
61
  // undefined corpus = "this caller cannot answer that question", not "skip the
62
62
  // check" — see validateOwnershipBoot. validateBoot passes the real corpora.
63
63
  export function validateOwnershipRules(feature, allClaimKeys, knownRoles) {
64
- for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
64
+ // A read model's access.read is the file-owner gate (readGate.fileOwner), so it gets the same
65
+ // role/column/where-lint pass as a registered entity.
66
+ const readModelEntities = Object.values(feature.projections ?? {}).flatMap((projection) => !projection.isImplicit &&
67
+ projection.entity !== undefined &&
68
+ typeof projection.source === "string" &&
69
+ feature.entities?.[projection.source] === undefined
70
+ ? [[projection.source, projection.entity]]
71
+ : []);
72
+ const entries = [...Object.entries(feature.entities ?? {}), ...readModelEntities];
73
+ for (const [entityName, entity] of entries) {
65
74
  const columnNames = new Set(Object.keys(entity.fields));
66
75
  // Framework-managed columns that rules are allowed to reference too.
67
76
  // These are the base columns buildEntityTable adds unconditionally.
@@ -1,4 +1,4 @@
1
- import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handlers";
1
+ import { ENTITY_CONVENTION_QUERY_BRAND, ENTITY_CONVENTION_WRITE_BRAND, } from "@cosmicdrift/kumiko-types/handlers";
2
2
  import { findEntity } from "../find-entity.js";
3
3
  import { bootRuleError } from "./boot-rule.js";
4
4
  import { ENTITY_DECLARATION_RULES } from "./entity-declaration-rules.js";
@@ -19,60 +19,97 @@ function findQueryHandler(featureMap, handlerName) {
19
19
  }
20
20
  return undefined;
21
21
  }
22
- export function validateParentRefs(feature, featureMap) {
23
- for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
24
- const parentRef = entity.parentRef;
25
- if (parentRef === undefined)
26
- continue;
27
- if (entity.fields[parentRef.entityTypeField] === undefined) {
28
- throw bootRuleError(ENTITY_DECLARATION_RULES.parentRefTypeFieldUnknown, {
29
- message: `[Kumiko ParentRef] entity "${entityName}".parentRef.entityTypeField references ` +
30
- `"${parentRef.entityTypeField}" — which is not a declared field on "${entityName}" ` +
31
- `(feature: "${feature.name}"). Fix: point entityTypeField at a real field on the entity.`,
22
+ function findWriteHandler(featureMap, handlerName) {
23
+ for (const f of featureMap.values()) {
24
+ const handler = f.writeHandlers[handlerName];
25
+ if (handler)
26
+ return handler;
27
+ }
28
+ return undefined;
29
+ }
30
+ function assertParentRefFields(feature, entityName, entity, parentRef) {
31
+ if (entity.fields[parentRef.entityTypeField] === undefined) {
32
+ throw bootRuleError(ENTITY_DECLARATION_RULES.parentRefTypeFieldUnknown, {
33
+ message: `[Kumiko ParentRef] entity "${entityName}".parentRef.entityTypeField references ` +
34
+ `"${parentRef.entityTypeField}" — which is not a declared field on "${entityName}" ` +
35
+ `(feature: "${feature.name}"). Fix: point entityTypeField at a real field on the entity.`,
36
+ });
37
+ }
38
+ if (entity.fields[parentRef.entityIdField] === undefined) {
39
+ throw bootRuleError(ENTITY_DECLARATION_RULES.parentRefIdFieldUnknown, {
40
+ message: `[Kumiko ParentRef] entity "${entityName}".parentRef.entityIdField references ` +
41
+ `"${parentRef.entityIdField}" — which is not a declared field on "${entityName}" ` +
42
+ `(feature: "${feature.name}"). Fix: point entityIdField at a real field on the entity.`,
43
+ });
44
+ }
45
+ }
46
+ function assertAllowedTypeHosts(feature, featureMap, entityName, parentRef) {
47
+ for (const hostName of parentRef.allowedTypes ?? []) {
48
+ const host = findEntity(featureMap, hostName);
49
+ if (host === undefined) {
50
+ throw bootRuleError(ENTITY_DECLARATION_RULES.parentRefAllowedTypeUnregistered, {
51
+ message: `[Kumiko ParentRef] entity "${entityName}".parentRef.allowedTypes names "${hostName}" ` +
52
+ `— no entity with that name is registered in this feature set (feature: ` +
53
+ `"${feature.name}"). Fix: remove "${hostName}" from allowedTypes, or register it.`,
32
54
  });
33
55
  }
34
- if (entity.fields[parentRef.entityIdField] === undefined) {
35
- throw bootRuleError(ENTITY_DECLARATION_RULES.parentRefIdFieldUnknown, {
36
- message: `[Kumiko ParentRef] entity "${entityName}".parentRef.entityIdField references ` +
37
- `"${parentRef.entityIdField}" — which is not a declared field on "${entityName}" ` +
38
- `(feature: "${feature.name}"). Fix: point entityIdField at a real field on the entity.`,
56
+ if (host.parentRef !== undefined) {
57
+ throw bootRuleError(ENTITY_DECLARATION_RULES.parentRefAllowedTypeHasParentRef, {
58
+ message: `[Kumiko ParentRef] entity "${entityName}".parentRef.allowedTypes names "${hostName}" ` +
59
+ `— which itself declares a parentRef (feature: "${feature.name}"). A join-row ` +
60
+ `entity can't act as a host for another join-row entity (no recursive gating). ` +
61
+ `Fix: remove "${hostName}" from allowedTypes, or drop its own parentRef.`,
39
62
  });
40
63
  }
41
- for (const hostName of parentRef.allowedTypes ?? []) {
42
- const host = findEntity(featureMap, hostName);
43
- if (host === undefined) {
44
- throw bootRuleError(ENTITY_DECLARATION_RULES.parentRefAllowedTypeUnregistered, {
45
- message: `[Kumiko ParentRef] entity "${entityName}".parentRef.allowedTypes names "${hostName}" ` +
46
- `— no entity with that name is registered in this feature set (feature: ` +
47
- `"${feature.name}"). Fix: remove "${hostName}" from allowedTypes, or register it.`,
48
- });
49
- }
50
- if (host.parentRef !== undefined) {
51
- throw bootRuleError(ENTITY_DECLARATION_RULES.parentRefAllowedTypeHasParentRef, {
52
- message: `[Kumiko ParentRef] entity "${entityName}".parentRef.allowedTypes names "${hostName}" ` +
53
- `— which itself declares a parentRef (feature: "${feature.name}"). A join-row ` +
54
- `entity can't act as a host for another join-row entity (no recursive gating). ` +
55
- `Fix: remove "${hostName}" from allowedTypes, or drop its own parentRef.`,
56
- });
57
- }
64
+ }
65
+ }
66
+ function assertConventionQueryHandlers(feature, featureMap, entityName) {
67
+ for (const verb of ["list", "detail"]) {
68
+ const handlerName = `${entityName}:${verb}`;
69
+ const handler = findQueryHandler(featureMap, handlerName);
70
+ // skip: no handler registered for this verb — nothing to brand-check
71
+ if (handler === undefined)
72
+ continue;
73
+ if (handler[ENTITY_CONVENTION_QUERY_BRAND] !== true) {
74
+ throw bootRuleError(ENTITY_DECLARATION_RULES.parentRefHandWrittenQuery, {
75
+ message: `[Kumiko ParentRef] query handler "${handlerName}" does not carry ` +
76
+ `ENTITY_CONVENTION_QUERY_BRAND, but entity "${entityName}" declares a parentRef ` +
77
+ `(feature: "${feature.name}"). A hand-written handler bypasses the parent-ref ` +
78
+ `read-gate unless it explicitly wires parentVisibility. Fix: register "${handlerName}" ` +
79
+ `via defineEntityListHandler/defineEntityDetailHandler (or defineEntityQueryHandler), ` +
80
+ `or pass { parentVisibility: { entities: ctx.registry.getAllEntities() } } to ` +
81
+ `executor.${verb} yourself.`,
82
+ });
58
83
  }
59
- for (const verb of ["list", "detail"]) {
60
- const handlerName = `${entityName}:${verb}`;
61
- const handler = findQueryHandler(featureMap, handlerName);
62
- // skip: no handler registered for this verb — nothing to brand-check
63
- if (handler === undefined)
64
- continue;
65
- if (handler[ENTITY_CONVENTION_QUERY_BRAND] !== true) {
66
- throw bootRuleError(ENTITY_DECLARATION_RULES.parentRefHandWrittenQuery, {
67
- message: `[Kumiko ParentRef] query handler "${handlerName}" does not carry ` +
68
- `ENTITY_CONVENTION_QUERY_BRAND, but entity "${entityName}" declares a parentRef ` +
69
- `(feature: "${feature.name}"). A hand-written handler bypasses the parent-ref ` +
70
- `read-gate unless it explicitly wires parentVisibility. Fix: register "${handlerName}" ` +
71
- `via defineEntityListHandler/defineEntityDetailHandler (or defineEntityQueryHandler), ` +
72
- `or pass { parentVisibility: { entities: ctx.registry.getAllEntities() } } to ` +
73
- `executor.${verb} yourself.`,
74
- });
75
- }
84
+ }
85
+ }
86
+ function assertConventionWriteHandlers(feature, featureMap, entityName) {
87
+ for (const verb of ["update", "delete", "restore"]) {
88
+ const handlerName = `${entityName}:${verb}`;
89
+ const handler = findWriteHandler(featureMap, handlerName);
90
+ // skip: no handler registered for this verb — nothing to brand-check
91
+ if (handler === undefined)
92
+ continue;
93
+ if (handler[ENTITY_CONVENTION_WRITE_BRAND] !== true) {
94
+ throw bootRuleError(ENTITY_DECLARATION_RULES.parentRefHandWrittenWrite, {
95
+ message: `[Kumiko ParentRef] write handler "${handlerName}" does not carry ` +
96
+ `ENTITY_CONVENTION_WRITE_BRAND, but entity "${entityName}" declares a parentRef ` +
97
+ `(feature: "${feature.name}"). A hand-written handler bypasses the parent visibility ` +
98
+ `gate unless it explicitly wires parentVisibility. Fix: register "${handlerName}" ` +
99
+ `via defineEntityWriteHandler, or pass parentVisibility: ` +
100
+ `parentVisibilityFor(ctx, event.user) to executor.${verb} yourself.`,
101
+ });
76
102
  }
77
103
  }
78
104
  }
105
+ export function validateParentRefs(feature, featureMap) {
106
+ for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
107
+ const parentRef = entity.parentRef;
108
+ if (parentRef === undefined)
109
+ continue;
110
+ assertParentRefFields(feature, entityName, entity, parentRef);
111
+ assertAllowedTypeHosts(feature, featureMap, entityName, parentRef);
112
+ assertConventionQueryHandlers(feature, featureMap, entityName);
113
+ assertConventionWriteHandlers(feature, featureMap, entityName);
114
+ }
115
+ }
@@ -1,5 +1,6 @@
1
1
  import type { QueryHandlerDef } from "@cosmicdrift/kumiko-types/handlers";
2
2
  import type { FeatureDefinition } from "../types/index.ts";
3
3
  export declare function buildQueryHandlerMap(features: readonly FeatureDefinition[]): ReadonlyMap<string, QueryHandlerDef>;
4
+ export declare function schemaAccepts(schema: QueryHandlerDef["schema"] | undefined, key: string): boolean;
4
5
  export declare function validateProjectionListScreens(features: readonly FeatureDefinition[]): void;
5
6
  export declare function validateRelatedListSectionQueries(features: readonly FeatureDefinition[]): void;
@@ -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,35 @@ 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 and hideEmpty ask 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 && screen.namedFilterFacet?.hideEmpty !== true) {
115
+ return;
116
+ }
117
+ const missing = ["limit", "totalCount"].filter((key) => !schemaAccepts(schema, key));
118
+ if (missing.length === 0)
119
+ return;
120
+ throw bootRuleError(NAMED_FILTER_RULES.projectionQueryAcceptsCount, {
121
+ message: `${prefix}: namedFilterFacet.${screen.namedFilterFacet.showCounts === true ? "showCounts" : "hideEmpty"} needs query "${screen.query}" to accept ${missing.map((key) => `"${key}"`).join(" and ")} in its Zod schema ` +
122
+ `- add them or drop showCounts and hideEmpty.`,
123
+ });
124
+ }
125
+ // A filter's own sort travels as `payload.sort`/`sortDirection`; without them in the schema it 422s
126
+ // the moment the filter is picked. The field itself is not checked: a projection row has no entity,
127
+ // and the query may order by a column it does not list.
128
+ function validateProjectionListNamedFilterSortAcceptance(prefix, screen, schema) {
129
+ const sorted = (screen.namedFilters ?? []).find((ref) => ref.sort !== undefined);
130
+ // skip: no filter sorts, or the schema already accepts both keys — nothing to reject.
131
+ if (sorted === undefined ||
132
+ (schemaAccepts(schema, "sort") && schemaAccepts(schema, "sortDirection"))) {
133
+ return;
134
+ }
135
+ throw bootRuleError(NAMED_FILTER_RULES.projectionQueryAcceptsSort, {
136
+ message: `${prefix}: namedFilters "${sorted.id}" sets sort but query "${screen.query}" has no ` +
137
+ `"sort" and "sortDirection" parameters in its Zod schema — add them or remove sort from the filter.`,
138
+ });
139
+ }
109
140
  // facets send `payload.filters` — same failure mode as search/sort:
110
141
  // definePagedQueryHandler doesn't auto-merge params into the
111
142
  // 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,40 @@
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.narrowField", field: hint?.narrowField },
33
+ { option: "hint.toneField", field: hint?.toneField },
34
+ { option: "hint.reasonField", field: hint?.reasonField },
35
+ { option: "hint.reasonOpenField", field: hint?.reasonOpenField },
36
+ { option: "hint.reasonTitleField", field: hint?.reasonTitleField },
37
+ ];
38
+ }),
39
+ ]);
40
+ }
@@ -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,30 @@ 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
+ }
142
+ function checkEmptyStateParamsQueryRefs(queryHandlers, featureName, screenId, screen) {
143
+ for (const ref of screen.namedFilters ?? []) {
144
+ const query = ref.emptyState?.paramsQuery;
145
+ if (query === undefined)
146
+ continue;
147
+ checkQueryRef(queryHandlers, query, () => `[Feature ${featureName}] Screen "${screenId}" (${screen.type}) namedFilters "${ref.id}" emptyState.paramsQuery`);
148
+ }
149
+ }
121
150
  function checkToolbarVisibleWhenQueryRefs(queryHandlers, featureName, screenId, screen) {
122
151
  for (const action of screen.toolbarActions ?? []) {
123
152
  if (action.visibleWhen === undefined)
@@ -139,9 +168,13 @@ function checkScreenQueryRefs(queryHandlers, featureName, screenId, screen) {
139
168
  if (screen.type === "projectionList") {
140
169
  checkQueryRef(queryHandlers, screen.query, () => `[Feature ${featureName}] Screen "${screenId}" (projectionList)`);
141
170
  checkToolbarVisibleWhenQueryRefs(queryHandlers, featureName, screenId, screen);
171
+ checkRowDecorationQueryRef(queryHandlers, featureName, screenId, screen);
172
+ checkEmptyStateParamsQueryRefs(queryHandlers, featureName, screenId, screen);
142
173
  }
143
174
  else if (screen.type === "entityList") {
144
175
  checkToolbarVisibleWhenQueryRefs(queryHandlers, featureName, screenId, screen);
176
+ checkRowDecorationQueryRef(queryHandlers, featureName, screenId, screen);
177
+ checkEmptyStateParamsQueryRefs(queryHandlers, featureName, screenId, screen);
145
178
  if (screen.expandableRow !== undefined) {
146
179
  checkQueryRef(queryHandlers, screen.expandableRow.query, () => `[Feature ${featureName}] Screen "${screenId}" (entityList) expandableRow "${screen.expandableRow?.title}"`);
147
180
  }
@@ -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
+ }
@@ -116,7 +116,7 @@ export function validateRowActionNavigateParams(featureName, screenId, screenTyp
116
116
  //
117
117
  // Registration check (not just "resolved is not undefined"): action.icon is
118
118
  // typed IconKey, a closed union — but that only protects call sites this
119
- // repo's own `tsc --build` actually covers (samples and external consumers
119
+ // repo's own typecheck actually covers (samples and external consumers
120
120
  // aren't in that project graph). The renderer's actionIconFor
121
121
  // (renderer/src/web/primitives/index.tsx) already falls back to "no icon"
122
122
  // for an unregistered key instead of crashing — this check makes the same
@@ -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;