@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
@@ -17,6 +17,7 @@ function dropTestDb(baseUrl: string, dbName: string): Promise<void>;
17
17
  function pushEntityProjectionTables(stack: DbHolder, registry: Registry): Promise<void>; // Push all implicit-projection tables — one per `r.entity()` — that the registry knows about.
18
18
  function resetEventStore(stack: { db: unknown; eventDispatcher?: EventDispatcher; }, extraTables?: (unknown | string)[]): Promise<void>; // Wipes event store + framework-state + the given feature read-models in one TRUNCATE, then re-registers the event-consumer state rows.
19
19
  function setupTestStack(options: TestStackOptions): Promise<TestStack>;
20
+ function testRunQueueNamePrefix(label: string): string; // Queue-name prefix for a JobRunner a test builds itself (`jobs.queueNamePrefix`, `createJobRunner`): it sits in the test run's namespace, so the run sweep removes its BullMQ keys even when the test never cleans them up.
20
21
  function unsafeCreateEntityTable(db: DbConnection, entity: EntityDefinition, entityName?: string): Promise<void>; // Bypass: creates an entity-table directly without going through the full registry.
21
22
  function unsafeEnsureEntityTable(db: DbConnection, entity: EntityDefinition, entityName?: string): Promise<boolean>;
22
23
  function unsafePushTables(db: DbConnection, tables: Record<string, unknown>, prevTables?: Record<string, unknown>, options?: { rowLevelSecurity?: RowLevelSecurityMode; }): Promise<void>; // Bypass: pushes table definitions to the database directly.
@@ -90,6 +91,7 @@ type TestStack = {
90
91
  sseBroker: SseBroker;
91
92
  dispatcher: Dispatcher;
92
93
  context: AppContext;
94
+ clock?: ManualClock; // The effective manual clock behind `ctx.tz.now()`: `extraContext.clock` when it is one, else the clock created from `options.now`; absent when neither is manual.
93
95
  eventDispatcher?: EventDispatcher;
94
96
  lifecycle?: Lifecycle;
95
97
  jobRunner?: JobRunner;
@@ -107,6 +109,7 @@ type TestStackOptions = {
107
109
  }; // Search config per tenant — defaults to tenant 1 with all text fields
108
110
  jwtSecret?: string;
109
111
  defaultLocale?: string; // Boot default locale (BCP-47) merged into AppContext before extraContext.
112
+ now?: string | Temporal.Instant; // Fixed wall clock for `ctx.tz.now()`: becomes a manual clock merged into the AppContext as `clock`; an `extraContext.clock` wins.
110
113
  extraContext?: Record<string, unknown> | ((deps: { registry: Registry; db: DbConnection; sseBroker: SseBroker; redis: Redis; }) => Record<string, unknown>);
111
114
  authConfig?: AuthRoutesConfig; // Wire up auth routes (login, tenant-switch).
112
115
  files?: {
@@ -485,6 +485,7 @@ type GenerateMigrationOutput = {
485
485
  retiredDrops: RetiredFrameworkTable[];
486
486
  rowLevelSecurityChanges: RowLevelSecurityChange[];
487
487
  };
488
+ const SNAPSHOT_VERSION: 1;
488
489
  type SchemaDiff = {
489
490
  newTables: EntityTableMeta[];
490
491
  droppedTables: string[];
@@ -699,6 +700,8 @@ type RenderDdlOptions = {
699
700
  ## packages/framework/src/db/render-rls-ddl.ts
700
701
 
701
702
  ```ts
703
+ const POLICY_COMMANDS: ["ALL", "SELECT", "INSERT", "UPDATE", "DELETE"];
704
+ const POLICY_KINDS: ["PERMISSIVE", "RESTRICTIVE"];
702
705
  type RowLevelSecurityPolicy = {
703
706
  name: string;
704
707
  command: (typeof POLICY_COMMANDS)[number];
@@ -859,7 +862,6 @@ type ConfigKeyOptions<T extends ConfigKeyType> = {
859
862
  pattern?: T extends "text" ? { regex: string; flags?: string; } : never;
860
863
  computed?: ConfigComputedFn<T>;
861
864
  validate?: ConfigValidateFn<T>;
862
- allowPerRequest?: T extends "text" ? never : boolean;
863
865
  required?: boolean;
864
866
  env?: string;
865
867
  inheritedToTenant?: boolean;
@@ -996,6 +998,7 @@ type UserId = string;
996
998
  ## packages/framework/src/engine/feature-changelog.ts
997
999
 
998
1000
  ```ts
1001
+ const CHANGELOG_TYPES: ["breaking", "improvement", "fix"];
999
1002
  type ChangelogType = (typeof CHANGELOG_TYPES)[number];
1000
1003
  type FeatureChangelog = {
1001
1004
  feature: string;
@@ -1059,6 +1062,7 @@ type QnType = string;
1059
1062
  ## packages/framework/src/engine/role-assignment.ts
1060
1063
 
1061
1064
  ```ts
1065
+ const ASSIGNABLE_FROM_ROLE_LIST: ["User", "Member", "Editor", "Admin", "TenantAdmin", "SystemAdmin"];
1062
1066
  type AssignableFromRole = (typeof ASSIGNABLE_FROM_ROLE_LIST)[number];
1063
1067
  ```
1064
1068
 
@@ -1083,6 +1087,10 @@ type StepListOutcome =
1083
1087
  ## packages/framework/src/engine/screen-helpers.ts
1084
1088
 
1085
1089
  ```ts
1090
+ type EmptyStateText = {
1091
+ title: string;
1092
+ description?: string | undefined;
1093
+ };
1086
1094
  type FieldsOrGroupsSection = { // Structural reader contract for every section that can carry `fields` and/or `groups`: the `EditFieldsSection` union members and `EditWriteFormSection` all assign without narrowing.
1087
1095
  fields?: EditFieldSpec[];
1088
1096
  groups?: { title: string; fields: EditFieldSpec[]; }[];
@@ -1413,7 +1421,7 @@ type Dispatcher = {
1413
1421
 
1414
1422
  ```ts
1415
1423
  type BatchTurnControl = {
1416
- holdForRetry: (eventIds: string[], reason: string) => void;
1424
+ holdForRetry: (eventIds: string[], reason: string, options?: { stillBackingOff?: boolean; }) => void;
1417
1425
  };
1418
1426
  type DispatcherPassResult = {
1419
1427
  processed: number;
@@ -1515,6 +1523,7 @@ type RunEventStoreSeedOptions<TId extends string | number = string, TExisting ex
1515
1523
  ```ts
1516
1524
  type CardColumnRoles<C extends CardRoleColumn> = {
1517
1525
  image: C | undefined;
1526
+ lead: C | undefined; // The "to do" sentence shown above the title.
1518
1527
  title: C | undefined;
1519
1528
  status: C | undefined;
1520
1529
  meta: C[];
@@ -1528,6 +1537,7 @@ type CardRoleColumn = {
1528
1537
  fileDisplay?: {
1529
1538
  kind: string;
1530
1539
  };
1540
+ hint?: unknown; // A "to do" hint column: never the default card title.
1531
1541
  };
1532
1542
  ```
1533
1543
 
@@ -1593,6 +1603,40 @@ type ContentEditorProps = {
1593
1603
  };
1594
1604
  ```
1595
1605
 
1606
+ ## packages/renderer/src/app/content-previews.tsx
1607
+
1608
+ ```ts
1609
+ type ContentPreviewsMap = Partial<Record<PreviewTarget, PreviewRenderer>>;
1610
+ const PREVIEW_TARGETS: ["pdf", "mail", "web", "text"];
1611
+ type PreviewRenderer = ComponentType<PreviewRendererProps>;
1612
+ type PreviewRendererProps = {
1613
+ content: string;
1614
+ editFormat: ContentEditorFormat;
1615
+ variables: Readonly<Record<string, unknown>>;
1616
+ subject: PreviewSubject;
1617
+ onResult?: (result: unknown) => void; // The renderer hands the answer of its server call to a host that shows it elsewhere (the mail editor's side rail).
1618
+ };
1619
+ type PreviewSubject =
1620
+ | {
1621
+ kind: "template";
1622
+ templateKind: string;
1623
+ slug: string;
1624
+ locale: string;
1625
+ meta: unknown;
1626
+ variableSchema?: unknown; // Placeholder schema of the template; the server derives sample values from it.
1627
+ }
1628
+ | {
1629
+ kind: "layout";
1630
+ templateKind: string;
1631
+ html: string;
1632
+ }
1633
+ | {
1634
+ kind: "body";
1635
+ }
1636
+ ;
1637
+ type PreviewTarget = (typeof PREVIEW_TARGETS)[number];
1638
+ ```
1639
+
1596
1640
  ## packages/renderer/src/app/extension-sections.tsx
1597
1641
 
1598
1642
  ```ts
@@ -1634,6 +1678,12 @@ type ScreenTarget = {
1634
1678
  };
1635
1679
  ```
1636
1680
 
1681
+ ## packages/renderer/src/components/form-pending-uploads.tsx
1682
+
1683
+ ```ts
1684
+ type TrackFormUpload = <T>(upload: () => Promise<T>) => Promise<T>;
1685
+ ```
1686
+
1637
1687
  ## packages/renderer/src/components/list-empty-state.tsx
1638
1688
 
1639
1689
  ```ts
@@ -1642,6 +1692,11 @@ type ListEmptyStateContent = {
1642
1692
  description?: string;
1643
1693
  action?: RenderEditAction;
1644
1694
  };
1695
+ type NamedFilterEmptyContent = {
1696
+ title: string;
1697
+ description?: string;
1698
+ onReset: () => void;
1699
+ };
1645
1700
  ```
1646
1701
 
1647
1702
  ## packages/renderer/src/components/render-edit-types.ts
@@ -1652,6 +1707,7 @@ type RenderEditAction = {
1652
1707
  label: string;
1653
1708
  onPress: () => void | Promise<void>;
1654
1709
  style?: "primary" | "secondary" | "danger";
1710
+ display?: RowActionDisplay; // `"link"` draws the action as a text link; `style: "danger"` keeps its colour.
1655
1711
  confirm?: string;
1656
1712
  confirmLabel?: string;
1657
1713
  confirmRequired?: boolean; // Overrides the default "danger implies a confirm dialog" rule.
@@ -1670,7 +1726,7 @@ type ToolbarActionButton = {
1670
1726
  confirmLabel?: string;
1671
1727
  confirmRequired?: boolean; // Overrides the default "danger implies a confirm dialog" rule.
1672
1728
  onTrigger: () => Promise<void> | void;
1673
- icon?: IconKey; // Id-derived default icon (ACTION_ICON_BY_ID in kumiko-screen.tsx) — ToolbarAction has no author-declared icon field, unlike RowAction.
1729
+ icon?: IconKey; // The action's declared icon, else the id-derived default (ACTION_ICON_BY_ID).
1674
1730
  };
1675
1731
  ```
1676
1732
 
@@ -1767,6 +1823,7 @@ type DataTableFacet = {
1767
1823
  label: string; // Translated Button-Label ("Status", "Active").
1768
1824
  options: { value: string; label: string; }[]; // Selectable values with display labels.
1769
1825
  chips?: DataTableFacetChip[]; // Present: render the facet as a row of single-choice toggle chips instead of a dropdown.
1826
+ display?: "select"; // Chips only: "select" renders the chips as one single-choice dropdown instead of a row of toggles.
1770
1827
  showCounts?: boolean; // Chips only: show each chip's `count` next to its label.
1771
1828
  hideEmpty?: boolean; // Chips only: hide chips whose `count` is 0 (unless pressed).
1772
1829
  onSearchChange?: (query: string) => void; // Present: the options come from a server-side search (reference facets), so the dropdown shows a search field and reports the typed term instead of filtering `options` itself.
@@ -1802,12 +1859,24 @@ type DataTableResetAll = {
1802
1859
  active: boolean; // True while something deviates from the screen default.
1803
1860
  onReset: () => void;
1804
1861
  };
1862
+ type DataTableSummaryItem = {
1863
+ label?: string; // Absent: the cell shows the value alone, for values that carry their own meaning ("7 need action").
1864
+ value: string | number;
1865
+ tone?: SelectOptionTone;
1866
+ column?: string; // Column field the value stands under when the table draws the row as cells; absent goes to the first column.
1867
+ };
1868
+ type DataTableSummaryRow = { // One line of "label value" pairs (the label is optional) under the rows, answered by the screen's summaryRow query.
1869
+ items: DataTableSummaryItem[];
1870
+ };
1805
1871
  type DataTableTableBlock = { // The DataTable props a screen's `table` block feeds.
1806
1872
  view?: DataTableViewOptions; // View menu (column picker, density); absent = no menu.
1807
1873
  resetAll?: DataTableResetAll; // Replaces the facet reset with one that also covers sort, search and page size.
1808
1874
  exportList?: DataTableExport; // Present: the toolbar has an export button (web only).
1809
1875
  compactHeader?: boolean; // Smaller (12px) semibold header row.
1876
+ frame?: ListTableFrame; // "card": table, summary row and pager in one bordered card from sm; bordered cards with a gap below sm.
1877
+ narrowFacets?: ListNarrowFacets; // "pills": below sm the select facets render as rounded pill triggers with a stronger border.
1810
1878
  serverGroups?: DataTableServerGroups; // Present: the rows are grouped on the server; replaces pager and infinite scroll.
1879
+ summaryRow?: DataTableSummaryRow; // Present: a footer line above the totals row with the summary query's items.
1811
1880
  totals?: DataTableTotals; // Present: a footer row with the server-computed totals of the filtered list.
1812
1881
  notice?: DataTableListNotice; // Present: the toolbar says the answer is incomplete and asks to narrow the list.
1813
1882
  rangeFacets?: DataTableRangeFacet[];
@@ -2195,6 +2264,7 @@ type EmbeddedListCellViewModel = {
2195
2264
  refOptionsQuery?: string;
2196
2265
  scale?: number; // Only for `type: "decimal"`.
2197
2266
  };
2267
+ type ListColumnCellDisplay = "badge" | "button";
2198
2268
  type ListColumnFileDisplay = // How a list cell shows a FileRef value (id or id array).
2199
2269
  | {
2200
2270
  kind: "image";
@@ -2202,14 +2272,27 @@ type ListColumnFileDisplay = // How a list cell shows a FileRef value (id or id
2202
2272
  }
2203
2273
  | {
2204
2274
  kind: "file";
2275
+ viewInDrawer?: true;
2205
2276
  }
2206
2277
  ;
2278
+ type ListColumnHintViewModel = {
2279
+ detailField?: string;
2280
+ narrowDetailField?: string; // `ListColumnHint.narrowDetailField`: replaces `detailField` in the phone card.
2281
+ toneField?: string;
2282
+ reasonField?: string;
2283
+ reasonOpenField?: string;
2284
+ reasonTitleField?: string;
2285
+ plainSentence?: boolean; // `ListColumnHint.plainSentence`: the sentence keeps the normal text color.
2286
+ emptyLabel: string;
2287
+ reasonLabel: string; // Label of the reason toggle, already translated.
2288
+ };
2207
2289
  type ListColumnViewModel = {
2208
2290
  field: string;
2209
2291
  label: string;
2210
2292
  type: string;
2211
2293
  renderer?: FieldRenderer | RuntimeRenderer;
2212
2294
  linkFor?: RuntimeCellLink;
2295
+ rowActionLink?: boolean; // Per-row action link column: a text link right-aligned without header text from sm, a small outline button on cards.
2213
2296
  linkItemsFor?: RuntimeCellLinkItems;
2214
2297
  sortable: boolean;
2215
2298
  optionLabels?: Readonly<Record<string, string>>; // Only for `type: "select"` or `type: "multiSelect"` — translated option labels keyed by raw value.
@@ -2219,8 +2302,16 @@ type ListColumnViewModel = {
2219
2302
  refLabelField?: string; // Only for `type: "reference"` — which field of the referenced entity appears as the display value in the cell (default "id").
2220
2303
  highlighted?: boolean; // Set by the caller at runtime (not schema-derived) to emphasize one column — e.g. the currently selected base-year column in a multi-year statement grid.
2221
2304
  hideOnNarrow?: boolean; // Mirrors `ListColumnSpec.hideOnNarrow`: card layout skips the column.
2305
+ showOnNarrowOnly?: boolean; // Mirrors `ListColumnSpec.showOnNarrowOnly`: the table layout skips the column.
2222
2306
  grouping?: boolean; // Only for `type: "number"` — mirrors `NumberFieldDef.grouping` (default `true`).
2223
2307
  fileDisplay?: ListColumnFileDisplay; // Set for file/image columns: from the entity field type, or from a `{ format: "image" | "file" }` renderer.
2308
+ hint?: ListColumnHintViewModel; // "To do" cell (`ListColumnSpec.hint`), `emptyLabel` already translated.
2309
+ width?: number; // Start width and floor in px of a hint column; unlike other columns they apply without `table.resizing`.
2310
+ minWidth?: number;
2311
+ display?: ListColumnCellDisplay; // `ListColumnSpec.display` for list tables: a status pill or a link drawn as a button.
2312
+ badgeToneField?: string; // Row field naming the pill tone; only with `display: "badge"`.
2313
+ badgeDot?: false; // `false`: the pill has no leading dot.
2314
+ emptyPlaceholder?: false; // `false`: an empty cell stays blank instead of showing "—".
2224
2315
  };
2225
2316
  type ListRowViewModel = {
2226
2317
  id: string;
@@ -2256,6 +2347,35 @@ type MetricProps = { // Compact label/value tile (record-detail metrics band).
2256
2347
  tile?: boolean; // Draw as a KPI tile (the dashboard StatCard) instead of a band entry.
2257
2348
  tone?: DashboardStatTone;
2258
2349
  icon?: NavIconKey;
2350
+ sub?: string; // Small muted line under the value (see `MetricSpec.subField`).
2351
+ };
2352
+ ```
2353
+
2354
+ ## packages/renderer/src/primitives-record-guidance.ts
2355
+
2356
+ ```ts
2357
+ type RecordBreadcrumbProps = { // Path above a record header; an item with a `link` is a link, the last item without one names the current record.
2358
+ items: { label: string; link?: CellLink; }[];
2359
+ ariaLabel: string;
2360
+ testId?: string;
2361
+ };
2362
+ type RecordStepsProps = { // "Next steps" panel; an item's `reason` sits behind a toggle labelled `reasonLabel`.
2363
+ title: string;
2364
+ subtitle?: string;
2365
+ emptyLabel: string; // Shown instead of the list when there are no items.
2366
+ reasonLabel: string;
2367
+ narrowLimit?: number; // Below the sm breakpoint only this many steps show; the rest sits behind a toggle.
2368
+ moreLabel?: (hiddenCount: number) => string; // Toggle label for the hidden steps; receives their count.
2369
+ lessLabel?: string;
2370
+ items: { id: string; title: string; detail?: string; narrowDetail?: string; tone?: SelectOptionTone; reason?: string; reasonOpen?: true; reasonTitle?: string; actions?: ReactNode; moreActions?: ReactNode; }[];
2371
+ count?: number; // Total number of steps, shown small beside the heading even when `narrowLimit` shortens the list.
2372
+ testId?: string;
2373
+ };
2374
+ type RecordSummaryProps = { // One emphasized sentence below a record header; `tone` sets the accent color.
2375
+ text: string;
2376
+ narrowText?: string; // Shown instead of `text` below the sm breakpoint.
2377
+ tone?: SelectOptionTone;
2378
+ testId?: string;
2259
2379
  };
2260
2380
  ```
2261
2381
 
@@ -2346,7 +2466,7 @@ type DataTableRowAction = {
2346
2466
  icon?: IconKey; // Resolved icon (author `RowAction.icon` or the id-derived default) — drives both the icon-left-of-text render and the icon-only collapse rule (see `shouldRenderActionsIconOnly`).
2347
2467
  display?: RowActionDisplay; // Author-chosen inline form (`RowAction.display`).
2348
2468
  };
2349
- type DataTableRowActionMode = "adaptive" | "inline";
2469
+ type DataTableRowActionMode = "adaptive" | "inline" | "menu";
2350
2470
  type DataTableSort = {
2351
2471
  field: string;
2352
2472
  dir: DataTableSortDir;
@@ -2383,6 +2503,7 @@ type FileValueListProps = { // Read-only list of stored files (FileRef ids): nam
2383
2503
  type FillContainerProps = { // Chromeless flex-fill layout host — no title, no card frame, no padding, just a container that sizes to its content and, once the ancestor chain is height-constrained, shrinks so one scrolling child can scroll internally instead of the page growing.
2384
2504
  children: ReactNode;
2385
2505
  testId?: string;
2506
+ className?: string; // Layout extras, merged via cn().
2386
2507
  grow?: boolean; // Claims the remaining height of the flex chain (`flex-1`) instead of sizing to its content, so a footer inside the child sits at the bottom edge even with few rows.
2387
2508
  };
2388
2509
  type FormSectionNavItem = { // One entry of a form's "on this page" navigation: `id` matches the `SectionProps.id` of the section it scrolls to.
@@ -2440,9 +2561,10 @@ type PageHeaderProps = { // Page title area rendered by the app shell's header i
2440
2561
  recordTitle?: string; // Name of the loaded record; shown as an extra breadcrumb before the last one.
2441
2562
  status?: ReactNode;
2442
2563
  actions?: ReactNode;
2564
+ bodyTitle?: boolean; // Screen renders its own h1: the shell header shows only the parent crumb, as text.
2443
2565
  overflowItems?: ActionMenuItemSpec[]; // Land in the shell header's overflow menu at phone width.
2444
- hideBreadcrumb?: boolean; // Hide the shell header's breadcrumb while mounted, for a screen that stands in for the one the route names (a locked screen's fallback).
2445
- breadcrumbScreenId?: string; // Label the breadcrumb with this screen (id as in the route) instead of the one the route names, for a locked screen's fallback.
2566
+ hideBreadcrumb?: boolean; // Hide the shell header's breadcrumb while mounted (a locked screen's fallback).
2567
+ breadcrumbScreenId?: string; // Label the breadcrumb with this screen (route id) instead of the routed one; wins over `hideBreadcrumb`.
2446
2568
  };
2447
2569
  type PickedFile = { // Platform-neutral view of a picked file; the DOM `File` satisfies it.
2448
2570
  name: string;
@@ -2510,10 +2632,10 @@ type StepBarProps = { // Wizard step overview — numbered chips, one per step l
2510
2632
  doneSteps?: boolean[]; // Explicit done state per step index.
2511
2633
  selectableSteps?: "done" | "all"; // "done" (default): only done steps are jump targets.
2512
2634
  narrowLayout?: "label" | "steps"; // "label" (default) swaps the step row for `compactLabel` on narrow viewports; "steps" keeps the row there too — for short wizards whose labels fit a phone and whose done steps must stay tappable.
2513
- orientation?: "horizontal" | "vertical"; // "vertical" renders a step rail (from `lg`, with `compactLabel` as the single line below it) instead of the chip row.
2635
+ orientation?: "horizontal" | "vertical" | "stacked"; // "vertical" renders a step rail (from `lg`, with `compactLabel` as the single line below it); "stacked": plain stage list at every width.
2514
2636
  heading?: string; // Vertical only: rail heading ("Step 4 of 6") and optional description.
2515
2637
  description?: string;
2516
- subtitles?: (string | undefined)[]; // Vertical only: line under each step label, same order as `steps`.
2638
+ subtitles?: (string | undefined)[]; // Vertical and stacked only: line under each step label, same order as `steps`.
2517
2639
  upNext?: {
2518
2640
  heading: string;
2519
2641
  title: string;
@@ -2554,7 +2676,6 @@ type WizardStepGroupProps = { // Wraps a single wizard step so it stays mounted
2554
2676
 
2555
2677
  ```ts
2556
2678
  type StatusBadgeOptionTone = StatusTone | "accent"; // Tones a select option can request: the status tones plus the brand `accent`.
2557
- type StatusTone = "ok" | "warn" | "bad" | "critical" | "muted";
2558
2679
  ```
2559
2680
 
2560
2681
  ## packages/renderer/src/web/app/client-plugin.tsx
@@ -2582,6 +2703,12 @@ type BoundaryErrorHandler = (error: Error, info: ErrorInfo, context: BoundaryErr
2582
2703
  type ResolverComponent = ComponentType<{ target: TargetRef; onClose: () => void; }>;
2583
2704
  ```
2584
2705
 
2706
+ ## packages/renderer/src/web/editor/editor-rail.tsx
2707
+
2708
+ ```ts
2709
+ const TRAILING_TONE: { ok: "text-status-ok"; bad: "text-status-bad"; muted: "text-muted-foreground"; };
2710
+ ```
2711
+
2585
2712
  ## packages/renderer/src/web/layout/default-app-shell.tsx
2586
2713
 
2587
2714
  ```ts
@@ -2633,6 +2760,7 @@ type PageSectionProps = {
2633
2760
  testId?: string;
2634
2761
  maxWidth?: ScreenWidth;
2635
2762
  };
2763
+ const STACK_GAP: { sm: "gap-2"; md: "gap-4"; lg: "gap-6"; };
2636
2764
  type ScreenWidth = FormWidth;
2637
2765
  type StackGap = keyof typeof STACK_GAP;
2638
2766
  type StackProps = {
@@ -2641,6 +2769,7 @@ type StackProps = {
2641
2769
  children?: ReactNode;
2642
2770
  testId?: string;
2643
2771
  };
2772
+ const screenFormColumnWidthClassName: Record<ScreenWidth, string>;
2644
2773
  ```
2645
2774
 
2646
2775
  ## packages/renderer/src/web/primitives/toast.tsx
@@ -2659,6 +2788,12 @@ type LiveEventTimers = {
2659
2788
  };
2660
2789
  ```
2661
2790
 
2791
+ ## packages/renderer/src/web/ui/sidebar.tsx
2792
+
2793
+ ```ts
2794
+ const sidebarMenuButtonVariants;
2795
+ ```
2796
+
2662
2797
  ## packages/renderer/src/web/widgets/ai-text-field.tsx
2663
2798
 
2664
2799
  ```ts
@@ -2808,6 +2943,9 @@ type ClockStep = {
2808
2943
  ## packages/testing/src/helpers/seed.ts
2809
2944
 
2810
2945
  ```ts
2946
+ type SeedOptions = {
2947
+ projectionOnly?: string;
2948
+ };
2811
2949
  type SeedTable = EntityTable | EntityTableMeta;
2812
2950
  ```
2813
2951
 
@@ -3128,7 +3266,6 @@ type PgListenSubscription = {
3128
3266
  type RawDbClient = {
3129
3267
  unsafe: (sql: string, params?: unknown[]) => PromiseLike<unknown[]>;
3130
3268
  begin: <T>(fn: (tx: DbTx) => Promise<T>) => Promise<T>;
3131
- end?: (options?: { timeout?: number; }) => Promise<void>;
3132
3269
  };
3133
3270
  ```
3134
3271
 
@@ -3282,6 +3419,7 @@ type UnmanagedTableInput = {
3282
3419
  indexes?: IndexMeta[];
3283
3420
  compositePrimaryKey?: CompositePrimaryKeyMeta;
3284
3421
  tenancy?: EntityTenancy;
3422
+ systemRowsReadable?: true;
3285
3423
  };
3286
3424
  ```
3287
3425
 
@@ -3343,6 +3481,7 @@ type ParentVisibilityOption = {
3343
3481
  readModelEntities?: ReadonlyMap<string, { entity: EntityDefinition; table: SchemaTable; }>;
3344
3482
  canReadEntity?: (entityName: string) => boolean;
3345
3483
  resolveTable?: (entityName: string) => SchemaTable;
3484
+ globalHostIds?: ReadonlyMap<string, string[]>;
3346
3485
  };
3347
3486
  type PreSaveRunner = (changes: Record<string, unknown>, previous: Readonly<Record<string, unknown>>, isNew: boolean) => Promise<Record<string, unknown>>;
3348
3487
  type StreamTenantOption = {
@@ -3825,6 +3964,7 @@ type ResolvedPiiStance =
3825
3964
  subjectRef: true;
3826
3965
  }
3827
3966
  ;
3967
+ const SELECT_OPTION_TONES: ["ok", "warn", "bad", "critical", "accent", "neutral"];
3828
3968
  type SelectConditionalOptions<TOption extends string = string> = { // Options of a select field that are only available while `when` holds for the row values.
3829
3969
  options: TOption[];
3830
3970
  when: Exclude<FieldCondition, boolean>;
@@ -3976,6 +4116,8 @@ type ContextServices = { // Infrastructure the app wired at boot, as the handler
3976
4116
  _notifyFactory?: NotifyFactory;
3977
4117
  _notifyInTransactionFactory?: (user: SessionUser, tenantId: TenantId) => NotifyFn;
3978
4118
  _notifyAfterCommitFactory?: (user: SessionUser, tenantId: TenantId) => NotifyFn;
4119
+ _deliveryAttemptLogFactory?: DeliveryAttemptLogFactory;
4120
+ _logOwnDeliveryAttempt?: DeliveryAttemptLogFn;
3979
4121
  _escapeHatchAuditSink?: EscapeHatchAuditSink;
3980
4122
  extensions: Readonly<Record<string, unknown>>;
3981
4123
  };
@@ -4060,6 +4202,7 @@ type DispatchWriteRef = {
4060
4202
  queryAs: (user: SessionUser, qn: string, payload: unknown, inheritedOrigin?: WriteOrigin) => Promise<unknown>;
4061
4203
  createMemberReader: (tenantId: TenantId) => MemberReader;
4062
4204
  };
4205
+ const ESCAPE_HATCH_GRANTS: ["systemIdentity", "globalWrites", "unsafeRaw", "crossTenantReads"];
4063
4206
  type EntityRef = {
4064
4207
  name: string;
4065
4208
  table: string;
@@ -4149,6 +4292,7 @@ type PreparedOrSkipped<TPrepared, TWhenNested> = [ TWhenNested ] extends [ Befor
4149
4292
  type PreparedWriteEvent<TPayload = unknown, TPrepared = unknown> = WriteEvent<TPayload> & ([ TPrepared ] extends [ undefined ] ? { prepared?: undefined; } : { prepared: TPrepared; }); // What a handler sees when its `beforeTransaction` phase ran: the phase's `data` as `prepared`; absent for handlers without the phase.
4150
4293
  type QualifiedEventName<TFeature extends string, TInner extends string> = `${CamelToKebab<TFeature>}:event:${CamelToKebab<TInner>}`; // Builds the qualified event-name from feature + inner-name in the same shape the runtime emits via `qn(toKebab(feature), "event", toKebab(inner))`.
4151
4294
  type QueryHandlerFn<TPayload = unknown, TResult = unknown> = (query: QueryEvent<TPayload>, context: HandlerContext) => Promise<TResult>;
4295
+ const RATE_LIMIT_PERS: ["user", "tenant", "ip", "user+handler", "tenant+handler", "ip+handler"];
4152
4296
  type RateLimitDeclaration = RateLimitOption | RateLimitOptions | RateLimitDisabled;
4153
4297
  type RateLimitDisabled = {
4154
4298
  disabled: true;
@@ -4196,6 +4340,8 @@ type SharedContextFields = {
4196
4340
  _notifyFactory?: NotifyFactory;
4197
4341
  _notifyInTransactionFactory?: (user: SessionUser, tenantId: TenantId) => NotifyFn;
4198
4342
  _notifyAfterCommitFactory?: (user: SessionUser, tenantId: TenantId) => NotifyFn;
4343
+ _deliveryAttemptLogFactory?: DeliveryAttemptLogFactory;
4344
+ _logOwnDeliveryAttempt?: DeliveryAttemptLogFn;
4199
4345
  _escapeHatchAuditSink?: EscapeHatchAuditSink;
4200
4346
  secrets?: SecretsContext;
4201
4347
  masterKeyProvider?: MasterKeyProvider;
@@ -4346,6 +4492,7 @@ type SubjectId =
4346
4492
  ## packages/types/src/list-aggregate-types.ts
4347
4493
 
4348
4494
  ```ts
4495
+ const LIST_AGGREGATE_MEASURE_KINDS: ["sum", "avg", "count", "min", "max"];
4349
4496
  type ListAggregateCurrencyAmount = {
4350
4497
  currency: string;
4351
4498
  value: number;
@@ -4401,6 +4548,12 @@ type MultiStreamApplyContext<TMap extends object = KumikoEventTypeMap> = {
4401
4548
  ## packages/types/src/named-list-filters.ts
4402
4549
 
4403
4550
  ```ts
4551
+ type ListSortDir = "asc" | "desc";
4552
+ type NamedFilterFacetOptions = { // How the named filters appear in the toolbar: toggle chips (default) or one single-choice select.
4553
+ display?: "chips" | "select";
4554
+ showCounts?: boolean; // Ask the list query for each filter's hit count and show it next to the label.
4555
+ label?: string; // i18n key for the select's label, e.g. "To do".
4556
+ };
4404
4557
  type NamedListFilterCondition = {
4405
4558
  field: string;
4406
4559
  op: NamedListFilterOp;
@@ -4414,6 +4567,12 @@ type NamedListFilterOp = "eq" | "ne" | "lt" | "gt" | "lte" | "gte" | "in";
4414
4567
  type NamedListFilterRef = { // Screen-side reference to an entity-defined named filter; `label` is an i18n key.
4415
4568
  id: string;
4416
4569
  label: string;
4570
+ sort?: ListSortSpec; // Order while this filter is active and the URL carries no sort of its own; wins over `defaultSort`.
4571
+ emptyState?: {
4572
+ title: string;
4573
+ description?: string;
4574
+ }; // Shown instead of the generic "no matches" text when this filter yields an empty list and no search term is set; both are i18n keys.
4575
+ roles?: string[]; // Set by the framework from the entity filter's role rule; the chip is offered only to users holding one of them.
4417
4576
  };
4418
4577
  type NamedListFilterScope = {
4419
4578
  ctx: HandlerContext;
@@ -4422,6 +4581,12 @@ type NamedListFilterScope = {
4422
4581
  };
4423
4582
  ```
4424
4583
 
4584
+ ## packages/types/src/nav-icon.ts
4585
+
4586
+ ```ts
4587
+ const NAV_ICON_KEYS;
4588
+ ```
4589
+
4425
4590
  ## packages/types/src/nav.ts
4426
4591
 
4427
4592
  ```ts
@@ -4488,8 +4653,6 @@ type SamplingConfig = {
4488
4653
  };
4489
4654
  };
4490
4655
  type SensitiveFilterConfig = {
4491
- redactedHeaders: string[];
4492
- redactedQueryParams: string[];
4493
4656
  redactedAttributeKeyPatterns: RegExp[];
4494
4657
  };
4495
4658
  ```
@@ -4768,6 +4931,7 @@ type SecretsEditSection = {
4768
4931
  ## packages/types/src/screen-dashboard.ts
4769
4932
 
4770
4933
  ```ts
4934
+ const DASHBOARD_STAT_TONES: ["default", "positive", "ok", "warn", "negative"];
4771
4935
  type DashboardChartKind = "timeseries" | "stacked-bars" | "segment-bars" | "stacked-area";
4772
4936
  type DashboardChartRangeOption = { // One option of a stacked-area range switch.
4773
4937
  value: string;
@@ -4779,6 +4943,13 @@ type DashboardChartRanges = {
4779
4943
  default: string;
4780
4944
  };
4781
4945
  type DashboardChartTone = "positive" | "negative" | "active" | "neutral";
4946
+ type DashboardListRowLink = ({ screen: string; paramField?: string; screenField?: never; paramsField?: never; } | { screenField: string; paramsField?: string; screen?: never; paramField?: never; }) & { // Row link of a list panel: one fixed target screen (`screen`) or, when the rows point to different places, the screen named by each row (`screenField`).
4947
+ icon?: "arrow" | "chevron"; // "arrow" (default) draws ↗ for a jump to another place, "chevron" draws › for opening the row.
4948
+ };
4949
+ type DashboardListShowTotal = { // Texts of the "n of m" count in a list panel's subtitle; without `text` the default i18n text stands.
4950
+ text?: string; // i18n key, placeholders `{shown}` and `{total}`.
4951
+ narrowText?: string; // i18n key used instead of `text` below `sm`.
4952
+ };
4782
4953
  type DashboardPanelGate = {
4783
4954
  visibleWhen?: DashboardPanelVisibility;
4784
4955
  };
@@ -4841,9 +5012,8 @@ type EntityListFacetExtraOption = { // An extra choice on a facet next to the fi
4841
5012
  values: string[]; // Option values this choice selects; `[]` selects nothing, i.e. no filter.
4842
5013
  position?: "start" | "end"; // Where the chip sits relative to the field's own options.
4843
5014
  };
4844
- type ListColumnDisplay = "bar" | "badge" | "datetime";
5015
+ type ListColumnDisplay = "bar" | "badge" | "datetime" | "button";
4845
5016
  type ListPaginationMode = "pages" | "infinite" | false;
4846
- type ListSortDir = "asc" | "desc";
4847
5017
  type RowActionNavigateBase = {
4848
5018
  kind: "navigate";
4849
5019
  id: string;
@@ -4882,12 +5052,18 @@ type ExpandableRowGrouping = Omit<ListTableGrouping, "field" | "userChoice" | "f
4882
5052
  ## packages/types/src/screen-list-table.ts
4883
5053
 
4884
5054
  ```ts
5055
+ const LIST_COLUMN_PINS: ["left", "right"];
5056
+ const LIST_NARROW_FACETS: ["pills"];
5057
+ const LIST_TABLE_DENSITIES: ["comfortable", "compact", "relaxed"];
5058
+ const LIST_TABLE_FRAMES: ["card"];
4885
5059
  type ListColumnPin = (typeof LIST_COLUMN_PINS)[number];
5060
+ type ListNarrowFacets = (typeof LIST_NARROW_FACETS)[number];
4886
5061
  type ListTableDensity = (typeof LIST_TABLE_DENSITIES)[number];
4887
5062
  type ListTableExportOptions = {
4888
5063
  xlsx: true;
4889
5064
  maxRows?: number; // Export is refused above this many rows.
4890
5065
  };
5066
+ type ListTableFrame = (typeof LIST_TABLE_FRAMES)[number];
4891
5067
  type ListTableGrouping = {
4892
5068
  field?: string; // Start grouping.
4893
5069
  collapsedWhen?: string | number | boolean | null; // Groups whose key equals this start collapsed and load no rows until opened.
@@ -4908,14 +5084,20 @@ type ListTableTotal = {
4908
5084
  type MetricSpec = {
4909
5085
  field: string;
4910
5086
  label: string;
5087
+ labelField?: string; // Record field of the detail query holding the label text, e.g. "Rent from 01.12."; it replaces the static `label` while it holds a non-empty string.
4911
5088
  navigate?: MetricNavigate;
5089
+ hideOnNarrow?: true; // Leaves the metric out below `sm`.
4912
5090
  tone?: DashboardStatTone; // Tile color as on dashboard stat panels; not applied while the value is 0.
5091
+ toneField?: string; // Record field of the detail query holding a SelectOptionTone; a valid value overrides `tone`, also at value 0.
5092
+ subField?: string; // Record field of the detail query shown as a small line under the value; the value stays the number.
4913
5093
  icon?: NavIconKey; // Icon chip of the tile; only drawn with `metricsStyle: "tiles"`.
4914
5094
  format?: FormatSpec; // Formats the displayed value (e.g. `date`, `enumOption`); the tone still resolves on the raw value.
4915
5095
  };
4916
5096
  type RecordHeaderSpec = {
4917
5097
  title: string;
5098
+ shortTitle?: string; // Field holding a short title for the desktop top bar ("Orders › SO-10482 ● processing"); the body keeps the full `title` as the h1.
4918
5099
  subtitle?: string | RecordHeaderSubtitlePart[]; // Field name, or several parts (field name or `{ field, navigate }`) joined by a separator; parts with an empty value are dropped.
5100
+ narrowSubtitle?: string; // Field holding a plain-text subtitle shown instead of `subtitle` below `sm` (e.g. "Main St 12, Berlin · 3 rooms").
4919
5101
  status?: string;
4920
5102
  statusFormat?: FormatSpec; // Formats the badge text (typically `enumOption` with a `keyPrefix`); tones still resolve on the raw value.
4921
5103
  subtitleHref?: string; // Record field holding an absolute http(s) URL.
@@ -4926,6 +5108,15 @@ type RecordHeaderSpec = {
4926
5108
  };
4927
5109
  ```
4928
5110
 
5111
+ ## packages/types/src/screen-record-guidance.ts
5112
+
5113
+ ```ts
5114
+ type RecordGuidanceAction = RowAction & { // A banner or step action.
5115
+ hideIcon?: true;
5116
+ narrowLabel?: string; // i18n key shown as the button label below `sm` (a shorter word, e.g. "Plan" for "Plan handover").
5117
+ };
5118
+ ```
5119
+
4929
5120
  ## packages/types/src/screen.ts
4930
5121
 
4931
5122
  ```ts
package/agents/api.md CHANGED
@@ -8,13 +8,13 @@ Format: one line per function or constant, object and options types as property
8
8
 
9
9
  | Import path | File | Exports |
10
10
  | --- | --- | --- |
11
- | `@cosmicdrift/kumiko-framework/engine` | `api/framework-engine.md` | 440 |
11
+ | `@cosmicdrift/kumiko-framework/engine` | `api/framework-engine.md` | 446 |
12
12
  | `@cosmicdrift/kumiko-framework/errors` | `api/framework-errors.md` | 27 |
13
- | `@cosmicdrift/kumiko-framework/ui-types` | `api/framework-ui-types.md` | 156 |
14
- | `@cosmicdrift/kumiko-framework/db` | `api/framework-db.md` | 151 |
15
- | `@cosmicdrift/kumiko-framework/event-store` | `api/framework-event-store.md` | 38 |
13
+ | `@cosmicdrift/kumiko-framework/ui-types` | `api/framework-ui-types.md` | 178 |
14
+ | `@cosmicdrift/kumiko-framework/db` | `api/framework-db.md` | 157 |
15
+ | `@cosmicdrift/kumiko-framework/event-store` | `api/framework-event-store.md` | 41 |
16
16
  | `@cosmicdrift/kumiko-framework/seeding` | `api/framework-seeding.md` | 6 |
17
- | `@cosmicdrift/kumiko-renderer/web` | `api/renderer-web.md` | 344 |
18
- | `@cosmicdrift/kumiko-testing/stack` | `api/testing-stack.md` | 22 |
19
- | `@cosmicdrift/kumiko-testing/helpers` | `api/testing-helpers.md` | 71 |
17
+ | `@cosmicdrift/kumiko-renderer/web` | `api/renderer-web.md` | 372 |
18
+ | `@cosmicdrift/kumiko-testing/stack` | `api/testing-stack.md` | 23 |
19
+ | `@cosmicdrift/kumiko-testing/helpers` | `api/testing-helpers.md` | 72 |
20
20
  | `@cosmicdrift/kumiko-dev-server/testing` | `api/dev-server-testing.md` | 5 |