@cosmicdrift/kumiko-framework 0.413.0 → 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 (467) hide show
  1. package/AGENTS.md +5 -2
  2. package/agents/api/framework-db.md +14 -3
  3. package/agents/api/framework-engine.md +64 -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/helpdesk.md +15 -8
  18. package/agents/examples/managed-pages.md +90 -1
  19. package/agents/examples/pwa-shell.md +210 -0
  20. package/agents/examples/rate-limiting.md +3 -3
  21. package/agents/examples/record-detail-layout.md +1537 -67
  22. package/agents/examples/workflow-engine.md +16 -12
  23. package/agents/examples.md +1 -0
  24. package/agents/features-index.md +4 -2
  25. package/agents/features.md +22 -7
  26. package/agents/widgets.md +19 -1
  27. package/dist/api/api-constants.d.ts +1 -0
  28. package/dist/api/api-constants.js +4 -0
  29. package/dist/api/auth-middleware.js +4 -3
  30. package/dist/api/auth-routes-shared.js +2 -1
  31. package/dist/api/entity-read-access.d.ts +1 -0
  32. package/dist/api/entity-read-access.js +18 -0
  33. package/dist/api/export/export-route.d.ts +6 -1
  34. package/dist/api/export/export-route.js +27 -1
  35. package/dist/api/export/export-rows.js +19 -3
  36. package/dist/api/routes.d.ts +2 -0
  37. package/dist/api/routes.js +9 -1
  38. package/dist/api/server-extra-routes.js +2 -1
  39. package/dist/api/server-feature-http-routes.d.ts +9 -0
  40. package/dist/api/server-feature-http-routes.js +109 -0
  41. package/dist/api/server-middleware.js +2 -19
  42. package/dist/api/server-pat-rate-limit-guard.d.ts +3 -0
  43. package/dist/api/server-pat-rate-limit-guard.js +19 -0
  44. package/dist/api/server-rate-limit-wiring.d.ts +10 -0
  45. package/dist/api/server-rate-limit-wiring.js +37 -0
  46. package/dist/api/server-routes.d.ts +4 -12
  47. package/dist/api/server-routes.js +12 -171
  48. package/dist/api/server-schema-route.d.ts +3 -0
  49. package/dist/api/server-schema-route.js +58 -0
  50. package/dist/api/server-wiring.js +2 -37
  51. package/dist/api/server.js +3 -1
  52. package/dist/compliance/override-schema.js +5 -5
  53. package/dist/compliance/sub-processors.js +10 -1
  54. package/dist/crypto/index.d.ts +1 -1
  55. package/dist/crypto/index.js +1 -1
  56. package/dist/crypto/pii-field-encryption.d.ts +2 -0
  57. package/dist/crypto/pii-field-encryption.js +16 -1
  58. package/dist/db/apply-entity-event.js +4 -0
  59. package/dist/db/bun-sql-connection-codes.d.ts +1 -0
  60. package/dist/db/bun-sql-connection-codes.js +7 -0
  61. package/dist/db/collect-table-metas.js +4 -1
  62. package/dist/db/config-seed.js +1 -1
  63. package/dist/db/derived-field-sql.js +15 -13
  64. package/dist/db/derived-related-sql.d.ts +2 -2
  65. package/dist/db/derived-related-sql.js +4 -2
  66. package/dist/db/dialect.d.ts +3 -0
  67. package/dist/db/dialect.js +1 -3
  68. package/dist/db/driver-row-coercion.js +2 -2
  69. package/dist/db/driver-value-preparation.js +1 -1
  70. package/dist/db/eagerload.js +15 -12
  71. package/dist/db/entity-table-meta.d.ts +2 -0
  72. package/dist/db/entity-table-meta.js +7 -0
  73. package/dist/db/event-store-executor-context.js +13 -8
  74. package/dist/db/event-store-executor-read-aggregate-currencies.js +2 -2
  75. package/dist/db/event-store-executor-read-aggregate.js +2 -2
  76. package/dist/db/event-store-executor-read-filter.d.ts +4 -0
  77. package/dist/db/event-store-executor-read-filter.js +28 -11
  78. package/dist/db/event-store-executor-read-search.d.ts +1 -0
  79. package/dist/db/event-store-executor-read-search.js +6 -6
  80. package/dist/db/event-store-executor-read-sort.js +3 -3
  81. package/dist/db/event-store-executor-read-where.js +14 -5
  82. package/dist/db/event-store-executor-read.js +7 -7
  83. package/dist/db/event-store-executor-write.js +50 -95
  84. package/dist/db/executor-managed-tables.js +4 -1
  85. package/dist/db/index.d.ts +4 -2
  86. package/dist/db/index.js +4 -2
  87. package/dist/db/known-table-names.d.ts +1 -0
  88. package/dist/db/known-table-names.js +7 -5
  89. package/dist/db/list-aggregate-labels.d.ts +1 -0
  90. package/dist/db/list-aggregate-labels.js +9 -1
  91. package/dist/db/migrate-generator.js +23 -4
  92. package/dist/db/migrate-rls-diff.d.ts +1 -0
  93. package/dist/db/migrate-rls-diff.js +15 -1
  94. package/dist/db/migrate-runner.js +2 -2
  95. package/dist/db/money.d.ts +1 -1
  96. package/dist/db/money.js +1 -4
  97. package/dist/db/parent-ref-clause.d.ts +6 -2
  98. package/dist/db/parent-ref-clause.js +76 -23
  99. package/dist/db/parent-ref-global-hosts.d.ts +20 -0
  100. package/dist/db/parent-ref-global-hosts.js +47 -0
  101. package/dist/db/production-schema-command-hint.d.ts +1 -0
  102. package/dist/db/production-schema-command-hint.js +3 -0
  103. package/dist/db/queries/backfill-pii.js +55 -29
  104. package/dist/db/queries/ddl.js +13 -2
  105. package/dist/db/queries/event-store-open-streams.d.ts +15 -0
  106. package/dist/db/queries/event-store-open-streams.js +33 -0
  107. package/dist/db/queries/event-store-payload-scrub.d.ts +5 -0
  108. package/dist/db/queries/event-store-payload-scrub.js +11 -0
  109. package/dist/db/queries/event-store.js +0 -1
  110. package/dist/db/queries/raw-sql.js +0 -1
  111. package/dist/db/queries/rebuild-rls-guard.d.ts +2 -1
  112. package/dist/db/queries/rebuild-rls-guard.js +24 -11
  113. package/dist/db/queries/rls-boot-catalog.d.ts +1 -0
  114. package/dist/db/queries/rls-boot-catalog.js +13 -8
  115. package/dist/db/queries/rls-shape.d.ts +2 -1
  116. package/dist/db/queries/rls-shape.js +10 -0
  117. package/dist/db/queries/session-advisory-lock.js +2 -1
  118. package/dist/db/queries/test-stack.js +7 -7
  119. package/dist/db/query.js +16 -11
  120. package/dist/db/rebuild-marker.js +11 -2
  121. package/dist/db/render-rls-ddl.d.ts +2 -0
  122. package/dist/db/render-rls-ddl.js +16 -11
  123. package/dist/db/replay-migration-sql.js +1 -1
  124. package/dist/db/row-level-security-boot-check.js +18 -5
  125. package/dist/db/row-level-security-connection.js +25 -12
  126. package/dist/db/row-level-security-scope.d.ts +2 -1
  127. package/dist/db/row-level-security-scope.js +9 -5
  128. package/dist/db/sql-identifier.d.ts +1 -0
  129. package/dist/db/sql-identifier.js +3 -0
  130. package/dist/db/system-tenant-read-db.d.ts +5 -0
  131. package/dist/db/system-tenant-read-db.js +28 -0
  132. package/dist/db/table-builder.d.ts +3 -1
  133. package/dist/db/table-builder.js +18 -8
  134. package/dist/db/table-info.d.ts +1 -2
  135. package/dist/db/table-introspection.d.ts +3 -0
  136. package/dist/db/table-introspection.js +6 -0
  137. package/dist/db/table-push.d.ts +1 -0
  138. package/dist/db/table-push.js +7 -1
  139. package/dist/db/tenant-db-runner.d.ts +3 -0
  140. package/dist/db/tenant-db-runner.js +19 -1
  141. package/dist/db/transaction-serialization.d.ts +1 -0
  142. package/dist/db/transaction-serialization.js +20 -3
  143. package/dist/db/where-clause.js +11 -2
  144. package/dist/db/write-ownership-failures.d.ts +25 -0
  145. package/dist/db/write-ownership-failures.js +82 -0
  146. package/dist/engine/boot-validator/boot-check.js +7 -1
  147. package/dist/engine/boot-validator/boot-phases-app.js +5 -5
  148. package/dist/engine/boot-validator/boot-phases.js +3 -2
  149. package/dist/engine/boot-validator/boot-rules.d.ts +293 -26
  150. package/dist/engine/boot-validator/boot-rules.js +4 -0
  151. package/dist/engine/boot-validator/bundled-lists-table.js +2 -2
  152. package/dist/engine/boot-validator/card-meta-overflow.js +1 -0
  153. package/dist/engine/boot-validator/config-deps.d.ts +0 -1
  154. package/dist/engine/boot-validator/config-deps.js +0 -28
  155. package/dist/engine/boot-validator/config-key-rules.d.ts +0 -15
  156. package/dist/engine/boot-validator/config-key-rules.js +0 -15
  157. package/dist/engine/boot-validator/dashboard-screen-target.d.ts +22 -0
  158. package/dist/engine/boot-validator/dashboard-screen-target.js +20 -0
  159. package/dist/engine/boot-validator/dashboard-stat-navigate.d.ts +1 -0
  160. package/dist/engine/boot-validator/dashboard-stat-navigate.js +25 -17
  161. package/dist/engine/boot-validator/definition-webhook-events-rules.d.ts +5 -0
  162. package/dist/engine/boot-validator/definition-webhook-events-rules.js +5 -0
  163. package/dist/engine/boot-validator/derived-sql-fields.js +1 -2
  164. package/dist/engine/boot-validator/entity-declaration-rules.d.ts +5 -0
  165. package/dist/engine/boot-validator/entity-declaration-rules.js +5 -0
  166. package/dist/engine/boot-validator/entity-list-screens.d.ts +1 -0
  167. package/dist/engine/boot-validator/entity-list-screens.js +33 -6
  168. package/dist/engine/boot-validator/entity-structure-rules.d.ts +5 -0
  169. package/dist/engine/boot-validator/entity-structure-rules.js +5 -0
  170. package/dist/engine/boot-validator/list-column-layout.js +10 -6
  171. package/dist/engine/boot-validator/list-row-guidance-rules.d.ts +67 -0
  172. package/dist/engine/boot-validator/list-row-guidance-rules.js +67 -0
  173. package/dist/engine/boot-validator/list-row-guidance.d.ts +20 -0
  174. package/dist/engine/boot-validator/list-row-guidance.js +129 -0
  175. package/dist/engine/boot-validator/list-sort-summary-rules.d.ts +42 -0
  176. package/dist/engine/boot-validator/list-sort-summary-rules.js +42 -0
  177. package/dist/engine/boot-validator/list-sort-summary.d.ts +5 -0
  178. package/dist/engine/boot-validator/list-sort-summary.js +149 -0
  179. package/dist/engine/boot-validator/list-table-options.js +15 -1
  180. package/dist/engine/boot-validator/list-table-rules.d.ts +10 -5
  181. package/dist/engine/boot-validator/list-table-rules.js +10 -5
  182. package/dist/engine/boot-validator/list-toolbar-options.d.ts +10 -0
  183. package/dist/engine/boot-validator/list-toolbar-options.js +31 -0
  184. package/dist/engine/boot-validator/named-filter-rules.d.ts +32 -2
  185. package/dist/engine/boot-validator/named-filter-rules.js +32 -2
  186. package/dist/engine/boot-validator/ownership.js +10 -1
  187. package/dist/engine/boot-validator/parent-ref.js +87 -50
  188. package/dist/engine/boot-validator/projection-list-screens.d.ts +1 -0
  189. package/dist/engine/boot-validator/projection-list-screens.js +31 -1
  190. package/dist/engine/boot-validator/query-output-columns.js +62 -9
  191. package/dist/engine/boot-validator/query-output-guidance.d.ts +7 -0
  192. package/dist/engine/boot-validator/query-output-guidance.js +39 -0
  193. package/dist/engine/boot-validator/query-refs.js +24 -1
  194. package/dist/engine/boot-validator/row-decoration.d.ts +11 -0
  195. package/dist/engine/boot-validator/row-decoration.js +16 -0
  196. package/dist/engine/boot-validator/screens-dashboard-links.d.ts +10 -0
  197. package/dist/engine/boot-validator/screens-dashboard-links.js +36 -0
  198. package/dist/engine/boot-validator/screens-dashboard-narrow.d.ts +4 -0
  199. package/dist/engine/boot-validator/screens-dashboard-narrow.js +211 -0
  200. package/dist/engine/boot-validator/screens-dashboard-rules.d.ts +84 -4
  201. package/dist/engine/boot-validator/screens-dashboard-rules.js +84 -4
  202. package/dist/engine/boot-validator/screens-dashboard.js +29 -7
  203. package/dist/engine/boot-validator/screens-kind-entity-list.js +32 -27
  204. package/dist/engine/boot-validator/screens-kind-projection-detail-guidance.d.ts +3 -0
  205. package/dist/engine/boot-validator/screens-kind-projection-detail-guidance.js +46 -0
  206. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +20 -0
  207. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +20 -0
  208. package/dist/engine/boot-validator/screens-kind-projection-detail.js +2 -0
  209. package/dist/engine/boot-validator/screens-kind-projection-list.js +4 -0
  210. package/dist/engine/boot-validator/screens-kind-rules.d.ts +25 -0
  211. package/dist/engine/boot-validator/screens-kind-rules.js +25 -0
  212. package/dist/engine/boot-validator/screens-lists.d.ts +8 -2
  213. package/dist/engine/boot-validator/screens-lists.js +19 -3
  214. package/dist/engine/boot-validator/screens.js +1 -1
  215. package/dist/engine/boot-validator/sort-nulls.d.ts +2 -0
  216. package/dist/engine/boot-validator/sort-nulls.js +15 -0
  217. package/dist/engine/boot-validator/zod-shape.d.ts +2 -1
  218. package/dist/engine/boot-validator/zod-shape.js +19 -1
  219. package/dist/engine/build-app-schema.js +4 -0
  220. package/dist/engine/config-helpers.d.ts +1 -2
  221. package/dist/engine/config-helpers.js +6 -7
  222. package/dist/engine/define-feature.js +1 -0
  223. package/dist/engine/define-handler.d.ts +1 -0
  224. package/dist/engine/define-handler.js +4 -2
  225. package/dist/engine/definition-violations.js +2 -2
  226. package/dist/engine/entity-handlers.js +3 -8
  227. package/dist/engine/entity-list-runtime-options.js +9 -8
  228. package/dist/engine/factories.d.ts +2 -0
  229. package/dist/engine/feature-config-events-jobs.js +1 -0
  230. package/dist/engine/feature-entity-handlers.js +5 -2
  231. package/dist/engine/field-access.d.ts +1 -1
  232. package/dist/engine/field-access.js +7 -10
  233. package/dist/engine/find-entity.js +3 -3
  234. package/dist/engine/form-derivations.js +3 -3
  235. package/dist/engine/index.d.ts +3 -3
  236. package/dist/engine/index.js +2 -2
  237. package/dist/engine/named-filter-roles.d.ts +3 -0
  238. package/dist/engine/named-filter-roles.js +23 -0
  239. package/dist/engine/pipeline.js +0 -1
  240. package/dist/engine/project-app-schema-for-roles.js +17 -2
  241. package/dist/engine/qualified-name.js +0 -1
  242. package/dist/engine/registry-facade.js +1 -2
  243. package/dist/engine/registry-state.d.ts +1 -1
  244. package/dist/engine/registry-state.js +5 -2
  245. package/dist/engine/registry-validate.d.ts +1 -0
  246. package/dist/engine/registry-validate.js +9 -1
  247. package/dist/engine/registry.js +2 -1
  248. package/dist/engine/resolve-named-list-filters.js +5 -2
  249. package/dist/engine/schema-builder.js +6 -10
  250. package/dist/engine/screen-helpers.d.ts +12 -0
  251. package/dist/engine/screen-helpers.js +17 -1
  252. package/dist/engine/soft-delete-cleanup.js +5 -8
  253. package/dist/engine/state-machine.js +0 -1
  254. package/dist/engine/steps/_database-clock.d.ts +2 -0
  255. package/dist/engine/steps/_database-clock.js +6 -0
  256. package/dist/engine/steps/compute.js +1 -1
  257. package/dist/engine/steps/retry.js +5 -1
  258. package/dist/engine/steps/return.js +0 -1
  259. package/dist/engine/steps/wait-for-event.js +2 -1
  260. package/dist/engine/steps/wait.js +2 -1
  261. package/dist/engine/system-user.d.ts +2 -2
  262. package/dist/engine/system-user.js +2 -2
  263. package/dist/engine/types/handlers.d.ts +1 -1
  264. package/dist/engine/types/handlers.js +1 -1
  265. package/dist/engine/types/screen.d.ts +1 -1
  266. package/dist/engine/types/screen.js +1 -1
  267. package/dist/engine/webhook-contracts.d.ts +2 -3
  268. package/dist/engine/webhook-contracts.js +2 -25
  269. package/dist/engine/webhook-events.js +48 -29
  270. package/dist/engine/webhook-payload-strictness.d.ts +7 -0
  271. package/dist/engine/webhook-payload-strictness.js +53 -0
  272. package/dist/env/_zod-introspect.d.ts +1 -0
  273. package/dist/env/dry-run.d.ts +1 -1
  274. package/dist/env/dry-run.js +1 -1
  275. package/dist/env/field-meta.d.ts +4 -0
  276. package/dist/env/field-meta.js +67 -0
  277. package/dist/env/field-rules.d.ts +9 -0
  278. package/dist/env/field-rules.js +46 -0
  279. package/dist/env/index.d.ts +3 -3
  280. package/dist/env/index.js +16 -71
  281. package/dist/env/internals.d.ts +3 -0
  282. package/dist/env/internals.js +1 -2
  283. package/dist/env/required-env.d.ts +3 -1
  284. package/dist/env/required-env.js +5 -2
  285. package/dist/errors/serialize.js +2 -2
  286. package/dist/errors/write-error-info.js +0 -2
  287. package/dist/es-ops/operations-schema.js +18 -7
  288. package/dist/event-store/admin-api.js +3 -3
  289. package/dist/event-store/event-store.js +0 -3
  290. package/dist/event-store/index.d.ts +1 -0
  291. package/dist/event-store/index.js +1 -0
  292. package/dist/event-store/transfer.js +1 -1
  293. package/dist/files/assert-file-refs-belong-to-tenant.d.ts +2 -1
  294. package/dist/files/assert-file-refs-belong-to-tenant.js +15 -13
  295. package/dist/files/bind-pending-file-refs.d.ts +3 -1
  296. package/dist/files/bind-pending-file-refs.js +54 -27
  297. package/dist/files/copy-pending-file-refs-to-tenant.js +7 -3
  298. package/dist/files/create-file-ref.d.ts +4 -1
  299. package/dist/files/create-file-ref.js +14 -3
  300. package/dist/files/default-file-guard.js +4 -1
  301. package/dist/files/feature.js +1 -0
  302. package/dist/files/file-claim.d.ts +6 -0
  303. package/dist/files/file-claim.js +17 -0
  304. package/dist/files/file-field-slots.d.ts +2 -0
  305. package/dist/files/file-field-slots.js +28 -0
  306. package/dist/files/file-ref-entity.d.ts +3 -0
  307. package/dist/files/file-ref-entity.js +2 -0
  308. package/dist/files/file-ref-table.d.ts +3 -0
  309. package/dist/files/file-routes.d.ts +4 -1
  310. package/dist/files/file-routes.js +80 -16
  311. package/dist/files/in-memory-provider.d.ts +1 -1
  312. package/dist/files/in-memory-provider.js +2 -1
  313. package/dist/files/index.d.ts +1 -1
  314. package/dist/files/index.js +1 -1
  315. package/dist/files/invalid-file-ref-error.d.ts +2 -0
  316. package/dist/files/invalid-file-ref-error.js +15 -0
  317. package/dist/files/local-provider.js +9 -2
  318. package/dist/files/provider-resolver.js +1 -1
  319. package/dist/files/rebind-file-ref.d.ts +3 -2
  320. package/dist/files/rebind-file-ref.js +24 -18
  321. package/dist/files/resolve-file-handles.d.ts +13 -0
  322. package/dist/files/resolve-file-handles.js +57 -0
  323. package/dist/files/storage-tracking.d.ts +1 -1
  324. package/dist/files/storage-tracking.js +5 -2
  325. package/dist/files/sweep-stale-pending-file-refs.js +10 -4
  326. package/dist/files/types.d.ts +4 -0
  327. package/dist/files/types.js +10 -0
  328. package/dist/files/upload-field-resolution.d.ts +1 -0
  329. package/dist/files/upload-field-resolution.js +16 -2
  330. package/dist/files/upload-ledger.js +1 -1
  331. package/dist/i18n/required-surface-guidance-keys.d.ts +3 -0
  332. package/dist/i18n/required-surface-guidance-keys.js +9 -0
  333. package/dist/i18n/required-surface-keys.js +19 -4
  334. package/dist/internal/boot-rule-table-expectations.d.ts +2 -0
  335. package/dist/internal/boot-rule-table-expectations.js +29 -0
  336. package/dist/internal/row-level-security.d.ts +1 -0
  337. package/dist/internal/row-level-security.js +1 -0
  338. package/dist/internal/testing.d.ts +1 -0
  339. package/dist/internal/testing.js +1 -0
  340. package/dist/jobs/index.d.ts +1 -0
  341. package/dist/jobs/index.js +1 -0
  342. package/dist/jobs/job-load-events.d.ts +10 -0
  343. package/dist/jobs/job-load-events.js +12 -0
  344. package/dist/jobs/job-runner-context.js +6 -158
  345. package/dist/jobs/job-runner-dispatch.d.ts +7 -0
  346. package/dist/jobs/job-runner-dispatch.js +57 -0
  347. package/dist/jobs/job-runner-event-triggers.js +18 -9
  348. package/dist/jobs/job-runner-execution.js +2 -2
  349. package/dist/jobs/job-runner-facets.d.ts +48 -0
  350. package/dist/jobs/job-runner-facets.js +156 -0
  351. package/dist/jobs/job-runner-gates.js +24 -12
  352. package/dist/jobs/job-runner-helpers.d.ts +5 -1
  353. package/dist/jobs/job-runner-helpers.js +18 -3
  354. package/dist/jobs/job-runner-scope.d.ts +1 -0
  355. package/dist/jobs/job-runner-scope.js +2 -0
  356. package/dist/jobs/job-runner-tenant-cap-lock.d.ts +2 -0
  357. package/dist/jobs/job-runner-tenant-cap-lock.js +30 -0
  358. package/dist/jobs/job-runner.js +31 -70
  359. package/dist/jobs/obliterate-job-queues.d.ts +6 -0
  360. package/dist/jobs/obliterate-job-queues.js +23 -0
  361. package/dist/lifecycle/lifecycle.js +1 -1
  362. package/dist/migrations/event-header-scrub.d.ts +11 -0
  363. package/dist/migrations/event-header-scrub.js +33 -0
  364. package/dist/migrations/event-payload-scrub.d.ts +1 -1
  365. package/dist/migrations/event-payload-scrub.js +36 -4
  366. package/dist/migrations/index.d.ts +1 -0
  367. package/dist/migrations/index.js +2 -0
  368. package/dist/migrations/kumiko-drift.d.ts +5 -2
  369. package/dist/migrations/kumiko-drift.js +51 -14
  370. package/dist/migrations/pending-rebuilds.js +4 -5
  371. package/dist/observability/sensitive-filter.js +0 -12
  372. package/dist/pipeline/aggregate-type-removal.js +17 -4
  373. package/dist/pipeline/context-services.d.ts +2 -0
  374. package/dist/pipeline/context-services.js +5 -2
  375. package/dist/pipeline/dispatch-batch.js +4 -3
  376. package/dist/pipeline/dispatch-context-helpers.d.ts +11 -0
  377. package/dist/pipeline/dispatch-context-helpers.js +58 -0
  378. package/dist/pipeline/dispatch-nested-write.d.ts +7 -0
  379. package/dist/pipeline/dispatch-nested-write.js +119 -0
  380. package/dist/pipeline/dispatch-query.js +10 -3
  381. package/dist/pipeline/dispatch-scope.js +4 -3
  382. package/dist/pipeline/dispatch-shared.d.ts +2 -6
  383. package/dist/pipeline/dispatch-shared.js +6 -38
  384. package/dist/pipeline/dispatch-write.d.ts +0 -1
  385. package/dist/pipeline/dispatch-write.js +3 -302
  386. package/dist/pipeline/dispatcher-utils.js +6 -0
  387. package/dist/pipeline/effective-system-scope.d.ts +3 -0
  388. package/dist/pipeline/effective-system-scope.js +22 -0
  389. package/dist/pipeline/event-dispatcher-delivery.d.ts +1 -0
  390. package/dist/pipeline/event-dispatcher-delivery.js +17 -9
  391. package/dist/pipeline/event-dispatcher.d.ts +4 -1
  392. package/dist/pipeline/event-dispatcher.js +6 -7
  393. package/dist/pipeline/handler-context-auth.d.ts +3 -2
  394. package/dist/pipeline/handler-context-auth.js +3 -4
  395. package/dist/pipeline/handler-context-db.js +11 -4
  396. package/dist/pipeline/handler-context-dispatch.js +2 -2
  397. package/dist/pipeline/handler-context-events.d.ts +8 -3
  398. package/dist/pipeline/handler-context-events.js +20 -65
  399. package/dist/pipeline/handler-context-member-resolution.js +16 -8
  400. package/dist/pipeline/handler-context-notify.d.ts +1 -0
  401. package/dist/pipeline/handler-context-notify.js +2 -0
  402. package/dist/pipeline/handler-context-phase-denials.js +3 -2
  403. package/dist/pipeline/handler-context-projection.d.ts +3 -0
  404. package/dist/pipeline/handler-context-projection.js +39 -0
  405. package/dist/pipeline/handler-context-scope.d.ts +1 -1
  406. package/dist/pipeline/handler-context-scope.js +14 -2
  407. package/dist/pipeline/index.d.ts +1 -1
  408. package/dist/pipeline/index.js +1 -1
  409. package/dist/pipeline/lifecycle-pipeline.d.ts +1 -0
  410. package/dist/pipeline/lifecycle-pipeline.js +7 -4
  411. package/dist/pipeline/member-reader.js +4 -2
  412. package/dist/pipeline/msp-rebuild.js +1 -1
  413. package/dist/pipeline/nested-write-parent-guard.d.ts +5 -0
  414. package/dist/pipeline/nested-write-parent-guard.js +81 -0
  415. package/dist/pipeline/projection-rebuild.d.ts +2 -0
  416. package/dist/pipeline/projection-rebuild.js +16 -7
  417. package/dist/pipeline/projection-state.js +4 -6
  418. package/dist/pipeline/system-hooks.js +36 -6
  419. package/dist/pipeline/write-result-masking.js +31 -3
  420. package/dist/pipeline/write-transition-guard.d.ts +7 -0
  421. package/dist/pipeline/write-transition-guard.js +95 -0
  422. package/dist/schema-cli/shared.d.ts +2 -0
  423. package/dist/schema-cli/shared.js +4 -2
  424. package/dist/schema-cli/validate-command.js +43 -28
  425. package/dist/search/meilisearch-adapter.js +14 -9
  426. package/dist/search/reindex-entity.d.ts +2 -0
  427. package/dist/search/reindex-entity.js +32 -4
  428. package/dist/search/reindex-tenants-search.js +20 -4
  429. package/dist/time/tz-context.js +1 -1
  430. package/dist/ui-types/card-column-roles.d.ts +4 -0
  431. package/dist/ui-types/card-column-roles.js +6 -3
  432. package/dist/ui-types/index.d.ts +2 -2
  433. package/dist/ui-types/index.js +1 -1
  434. package/dist/utils/ids.js +0 -1
  435. package/dist/utils/index.d.ts +1 -0
  436. package/dist/utils/index.js +1 -0
  437. package/dist/utils/return-path-limit.d.ts +1 -0
  438. package/dist/utils/return-path-limit.js +1 -0
  439. package/package.json +5 -3
  440. package/presets/biome-app.json +39 -21
  441. package/presets/biome-plugins/admin-api.grit +10 -0
  442. package/presets/biome-plugins/error-reasons.grit +53 -0
  443. package/presets/biome-plugins/es-literal-writes-tests.grit +18 -0
  444. package/presets/biome-plugins/es-literal-writes.grit +22 -0
  445. package/presets/biome-plugins/i18n-locale-terminology-de.grit +15 -0
  446. package/presets/biome-plugins/i18n-locale-terminology-romance.grit +10 -0
  447. package/presets/biome-plugins/no-create-test-dispatcher.grit +5 -0
  448. package/presets/biome-plugins/no-css-properties-type.grit +7 -0
  449. package/presets/biome-plugins/no-date-api.grit +9 -0
  450. package/presets/biome-plugins/no-direct-fetch.grit +16 -0
  451. package/presets/biome-plugins/no-direct-fs.grit +16 -0
  452. package/presets/biome-plugins/no-external-font-cdn-css.grit +9 -0
  453. package/presets/biome-plugins/no-external-font-cdn.grit +12 -0
  454. package/presets/biome-plugins/no-raw-hooks.grit +10 -0
  455. package/presets/biome-plugins/no-same-folder-barrel-import.grit +11 -0
  456. package/presets/biome-plugins/no-screen-container-classes.grit +7 -0
  457. package/presets/biome-plugins/no-skipped-or-retried-tests.grit +34 -0
  458. package/presets/biome-plugins/no-temporal-polyfill-require.grit +10 -0
  459. package/presets/biome-plugins/raw-html-in-web.grit +40 -0
  460. package/presets/biome-plugins/raw-ui-in-app.grit +142 -0
  461. package/presets/biome-plugins/restricted-event-store-symbols.grit +18 -0
  462. package/presets/biome-plugins/test-title.grit +20 -0
  463. package/presets/biome-plugins/unsafe-json-parse.grit +6 -0
  464. package/presets/biome-rules.json +465 -0
  465. package/src/changes.json +309 -0
  466. package/dist/engine/minor-units.d.ts +0 -2
  467. package/dist/engine/minor-units.js +0 -8
@@ -1,10 +1,11 @@
1
- import { runInRowLevelSecurityScope, SYSTEM_ROW_LEVEL_SECURITY_SCOPE, tenantRowLevelSecurityScope, } from "../db/row-level-security-scope.js";
1
+ import { runInRowLevelSecurityScope, systemRowLevelSecurityScope, tenantRowLevelSecurityScope, } from "../db/row-level-security-scope.js";
2
+ import { isEffectivelySystemScoped } from "./effective-system-scope.js";
2
3
  // Handlers declared with r.systemScope() act across tenants, so a single-type dispatch of one runs system-scoped.
3
4
  // The caller picks the types of a batch, so a batch is system-scoped only when every command is; each command then
4
5
  // narrows or widens to its own type's scope (runInDispatchScope in runReservedCommand).
5
6
  export function dispatchRowLevelSecurityScope(registry, types, user) {
6
- return types.length > 0 && types.every((type) => registry.isHandlerSystemScoped(type))
7
- ? SYSTEM_ROW_LEVEL_SECURITY_SCOPE
7
+ return types.length > 0 && types.every((type) => isEffectivelySystemScoped(registry, type))
8
+ ? systemRowLevelSecurityScope("dispatch of system-scoped handlers")
8
9
  : tenantRowLevelSecurityScope(user.tenantId);
9
10
  }
10
11
  export function runInDispatchScope(registry, types, user, fn) {
@@ -3,7 +3,6 @@ import type { JobRunnerRef, PayloadRateLimitOption, RateLimitDeclaration, WriteR
3
3
  import type { SseBroker } from "../api/sse-broker.ts";
4
4
  import type { DbConnection, DbTx } from "../db/connection.ts";
5
5
  import type { buildEntityTable } from "../db/table-builder.ts";
6
- import { type TenantDb } from "../db/tenant-db.ts";
7
6
  import type { defineTransitions } from "../engine/state-machine.ts";
8
7
  import type { EffectiveFeaturesResolver } from "../engine/tier-resolver-extension.ts";
9
8
  import type { TenantId } from "../engine/types/identifiers.ts";
@@ -11,6 +10,7 @@ import type { AppContext, BeforeTransactionContext, HandlerContext, Registry, Re
11
10
  import { type WriteErrorInfo } from "../errors/index.ts";
12
11
  import type { EscapeHatchReportWindow } from "../observability/escape-hatch-report.ts";
13
12
  import type { getFallbackMeter, getFallbackTracer } from "../observability/fallback.ts";
13
+ import { createSystemScopedDbGuard, isMemberResolutionPrincipal, resolveAppPoolDb, resolveDbSource } from "./dispatch-context-helpers.ts";
14
14
  import { type AfterCommitHook } from "./dispatcher-utils.ts";
15
15
  import type { IdempotencyGuard } from "./idempotency.ts";
16
16
  import type { LifecycleHooks } from "./lifecycle-pipeline.ts";
@@ -18,7 +18,7 @@ import type { TenantTimezoneCache } from "./tenant-timezone-cache.ts";
18
18
  import { TENANT_TIMEZONE_CONFIG_KEY } from "./tenant-timezone-config-key.ts";
19
19
  import { type WriteOrigin } from "./write-origin.ts";
20
20
  export type { WriteOrigin } from "./write-origin.ts";
21
- export { TENANT_TIMEZONE_CONFIG_KEY };
21
+ export { createSystemScopedDbGuard, isMemberResolutionPrincipal, resolveAppPoolDb, resolveDbSource, TENANT_TIMEZONE_CONFIG_KEY, };
22
22
  export declare const CONFIG_WRITE_SET_TYPE = "config:write:set";
23
23
  export declare const CONFIG_WRITE_RESET_TYPE = "config:write:reset";
24
24
  export type BatchCommand = {
@@ -54,10 +54,6 @@ export type DispatchContext = {
54
54
  outsideTransactionDb: DbConnection | undefined;
55
55
  };
56
56
  export declare const DEFAULT_MEMBER_READ_TIMEOUT_MS = 10000;
57
- export declare function resolveDbSource(ctx: DispatchContext, tx: DbTx | undefined): DbConnection | DbTx | undefined;
58
- export declare function resolveAppPoolDb(ctx: DispatchContext): DbConnection | undefined;
59
- export declare function createSystemScopedDbGuard(handlerType: string, fieldName: "db" | "db.outsideTransaction", hint: string): TenantDb;
60
- export declare function isMemberResolutionPrincipal(user: SessionUser): boolean;
61
57
  export type HandlerTransactionScope = "inTransaction" | "withoutTransaction" | "postCommit";
62
58
  export type BuildHandlerContextOptions = {
63
59
  tx?: DbTx;
@@ -15,6 +15,7 @@ import { isPlainObject } from "../utils/is-plain-object.js";
15
15
  import { resolveAuthClaims as runAuthClaimsResolver } from "./auth-claims-resolver.js";
16
16
  import { configAccessorFactoryOf } from "./config-accessor-factory.js";
17
17
  import { buildContextServices } from "./context-services.js";
18
+ import { createSystemScopedDbGuard, isMemberResolutionPrincipal, resolveAppPoolDb, resolveDbSource, } from "./dispatch-context-helpers.js";
18
19
  import { executeQuery } from "./dispatch-query.js";
19
20
  import { dispatcherSpanAttributes, isFailedWriteResult, } from "./dispatcher-utils.js";
20
21
  import { buildAuthFacet } from "./handler-context-auth.js";
@@ -26,11 +27,12 @@ import { applyMemberResolutionReadOnly } from "./handler-context-member-resoluti
26
27
  import { buildNotifyFacet } from "./handler-context-notify.js";
27
28
  import { buildObservabilityFacet } from "./handler-context-observability.js";
28
29
  import { applyBeforeTransactionReadOnly, denyEventStoreSurfaces, denyTransactionBoundSurfaces, withoutTransactionDenied, } from "./handler-context-phase-denials.js";
30
+ import { buildHandlerProjectionReader } from "./handler-context-projection.js";
29
31
  import { buildLifecycleSignal, buildPreSave, buildRuntimeServices, resolveHandlerContextScope, } from "./handler-context-scope.js";
30
32
  import { createGatedIdentitySwitch, isSystemIdentity } from "./system-identity-switch.js";
31
33
  import { TENANT_TIMEZONE_CONFIG_KEY } from "./tenant-timezone-config-key.js";
32
34
  import { rootWriteOrigin } from "./write-origin.js";
33
- export { TENANT_TIMEZONE_CONFIG_KEY };
35
+ export { createSystemScopedDbGuard, isMemberResolutionPrincipal, resolveAppPoolDb, resolveDbSource, TENANT_TIMEZONE_CONFIG_KEY, };
34
36
  // Same bundled-features-free constraint as above — these name the config
35
37
  // feature's write handlers so dispatch-write.ts can invalidate
36
38
  // TENANT_TIMEZONE_CONFIG_KEY's cache entry on a successful write without
@@ -39,40 +41,6 @@ export { TENANT_TIMEZONE_CONFIG_KEY };
39
41
  export const CONFIG_WRITE_SET_TYPE = "config:write:set";
40
42
  export const CONFIG_WRITE_RESET_TYPE = "config:write:reset";
41
43
  export const DEFAULT_MEMBER_READ_TIMEOUT_MS = 10_000;
42
- // Narrowing helper: AppContext.db is DbConnection|TenantDb|undefined. The
43
- // dispatch paths need DbConnection (or DbTx from the caller scope) for
44
- // appendEvent/projection writes; the TenantDb branch is excluded here.
45
- export function resolveDbSource(ctx, tx) {
46
- return tx ?? resolveAppPoolDb(ctx);
47
- }
48
- export function resolveAppPoolDb(ctx) {
49
- return ctx.appContext.db; // @cast-boundary db-operator
50
- }
51
- // r.systemScope() handlers must go through ctx.systemDb's guarded methods
52
- // (assertTenantMatch / acknowledgeCrossTenant) instead of plain ctx.db —
53
- // "system" mode has no tenant filter at all, so silent ctx.db or
54
- // ctx.db.outsideTransaction use there is a cross-tenant leak. HandlerContext
55
- // has no way to make either field optional per handler (isSystem is a
56
- // runtime-only registry lookup, not a type-level discriminant), so instead
57
- // of omitting the key we hand back a Proxy that throws on first touch,
58
- // naming the handler and pointing at the matching ctx.systemDb escape hatch.
59
- // Only the db guard answers `outsideTransaction` (the inner guard, set by attachOutsideTransaction).
60
- export function createSystemScopedDbGuard(handlerType, fieldName, hint) {
61
- return new Proxy({}, {
62
- get(target, prop) {
63
- if (fieldName === "db" && prop === "outsideTransaction")
64
- return Reflect.get(target, prop);
65
- throw new InternalError({
66
- message: `Handler "${handlerType}" is r.systemScope()'d — ctx.${fieldName} is unavailable ` +
67
- `(it would be unfiltered across every tenant). Use ${hint} ` +
68
- `instead (attempted to read "${String(prop)}").`,
69
- });
70
- },
71
- });
72
- }
73
- export function isMemberResolutionPrincipal(user) {
74
- return user.origin === "member-resolution";
75
- }
76
44
  export async function buildHandlerContext(ctx, type, user, origin, options = {}) {
77
45
  const { tx, afterCommitHooks, includeDeleted, onlyDeleted, outerNotifySink, phase = "handler", transactionScope = tx ? "inTransaction" : "withoutTransaction", } = options;
78
46
  const readOnlyForTenant = phase === "beforeTransaction";
@@ -84,11 +52,11 @@ export async function buildHandlerContext(ctx, type, user, origin, options = {})
84
52
  const configFacet = buildConfigFacet(scope, dbFacet.db);
85
53
  const writeTarget = buildWriteTarget(scope, dbFacet.exposedDb, readOnlyForTenant);
86
54
  const fileFragment = buildFileFragment(scope, dbFacet.db);
87
- const authFacet = buildAuthFacet(scope);
55
+ const authFacet = buildAuthFacet(scope, resolveAuthClaimsFn);
88
56
  const eventStoreFacet = buildEventStoreFacet(scope);
89
57
  const dispatchFacet = buildDispatchFacet(scope, sinks, {
90
58
  queryAsMember: authFacet.queryAsMember,
91
- queryProjection: eventStoreFacet.queryProjection,
59
+ queryProjection: buildHandlerProjectionReader(scope),
92
60
  });
93
61
  const tz = await resolveHandlerTz(scope, configFacet.config);
94
62
  const locale = resolveHandlerLocale(scope);
@@ -521,7 +489,7 @@ function buildAuthClaimsContext(ctx, user) {
521
489
  : undefined;
522
490
  const identitySwitch = createGatedIdentitySwitch("r.authClaims hook", user, false, {
523
491
  // Login is itself the root operation; the hook context is read-only.
524
- queryAs: (asUser, qn, payload) => executeQuery(ctx, qn, payload, asUser, rootWriteOrigin(ctx.registry, qn, asUser)), // @wrapper-known semantic-alias
492
+ queryAs: (asUser, qn, payload) => executeQuery(ctx, qn, payload, asUser, rootWriteOrigin(ctx.registry, qn, asUser)),
525
493
  writeAs: async () => {
526
494
  throw new InternalError({
527
495
  message: "r.authClaims hook context has no writeAs — auth-claims hooks are read-only.",
@@ -4,4 +4,3 @@ import type { SessionUser } from "../engine/types/index.ts";
4
4
  import type { DispatchContext, WriteOrigin } from "./dispatch-shared.ts";
5
5
  import { type AfterCommitHook } from "./dispatcher-utils.ts";
6
6
  export declare function executeWrite(ctx: DispatchContext, type: string, payload: unknown, user: SessionUser, origin: WriteOrigin, tx: DbTx | undefined, afterCommitHooks: AfterCommitHook[]): Promise<WriteResult>;
7
- export declare function executeNestedWrite(ctx: DispatchContext, type: string, payload: unknown, user: SessionUser, origin: WriteOrigin, tx: DbTx | undefined, afterCommitHooks: AfterCommitHook[]): Promise<WriteResult>;
@@ -1,13 +1,6 @@
1
- import { selectRowForUpdateById } from "../db/queries/entity-read.js";
2
- import { asEntityTableMeta, selectMany } from "../db/query.js";
3
- import { buildEntityTable, toSnakeCase } from "../db/table-builder.js";
4
- import { createTenantDb, hasTenantColumn } from "../db/tenant-db.js";
5
- import { tenantDbRunner } from "../db/tenant-db-runner.js";
6
1
  import { ConfigScopes } from "../engine/constants.js";
7
- import { checkWriteFieldOwnership, maskWriteOnlyFields } from "../engine/field-access.js";
8
2
  import { HookPhases } from "../engine/hook-helpers.js";
9
- import { defineTransitions, guardTransition } from "../engine/state-machine.js";
10
- import { AccessDeniedError, FrameworkReasons, InternalError, NotFoundError, ValidationError, writeFailure, } from "../errors/index.js";
3
+ import { InternalError, NotFoundError, writeFailure } from "../errors/index.js";
11
4
  import { memberResolutionReadOnlyDenied } from "../errors/member-resolution.js";
12
5
  import { assertFileRefsBelongToTenant } from "../files/assert-file-refs-belong-to-tenant.js";
13
6
  import { bindPendingFileRefs } from "../files/bind-pending-file-refs.js";
@@ -16,38 +9,12 @@ import { loadSaveFileRefs } from "../files/load-save-file-refs.js";
16
9
  import { CACHE_SYNC_TOPICS } from "../redis/cache-sync-topics.js";
17
10
  import { assertNoSecretLeak } from "../secrets/leak-guard.js";
18
11
  import { buildHandlerContext, CONFIG_WRITE_RESET_TYPE, CONFIG_WRITE_SET_TYPE, isMemberResolutionPrincipal, resolveDbSource, runHandlerInstrumented, TENANT_TIMEZONE_CONFIG_KEY, } from "./dispatch-shared.js";
19
- import { describeShape, extractNestedSpecs, isLifecycleResult, isWriteResultShape, prefixValidationPath, wrapToKumiko, } from "./dispatcher-utils.js";
12
+ import { describeShape, isLifecycleResult, isWriteResultShape, wrapToKumiko, } from "./dispatcher-utils.js";
20
13
  import { perCommandNestedDenied } from "./handler-context-phase-denials.js";
21
14
  import { runPreHandlerGates } from "./pre-handler-gates.js";
22
15
  import { consumeReservation, hasPreTransactionPhase, nestedPreTransactionDenial, } from "./pre-transaction-reservations.js";
23
16
  import { runProjections } from "./projections-runner.js";
24
- function getTable(ctx, entityName) {
25
- const { registry, tableCache } = ctx;
26
- if (tableCache.has(entityName))
27
- return tableCache.get(entityName);
28
- const entity = registry.getEntity(entityName);
29
- if (!entity)
30
- return undefined;
31
- const table = buildEntityTable(entityName, entity, {
32
- relations: registry.getRelations(entityName),
33
- });
34
- tableCache.set(entityName, table);
35
- return table;
36
- }
37
- function getTransitions(ctx, args) {
38
- const { transitionCache } = ctx;
39
- // Scope by entity — `fieldName` alone collides across entities (e.g. both
40
- // `invoice.status` and `driverOrder.status` exist with different maps),
41
- // which would apply the wrong transition rules to whichever entity arrives
42
- // second.
43
- const key = `${args.entityName}:${args.fieldName}`;
44
- const cached = transitionCache.get(key);
45
- if (cached)
46
- return cached;
47
- const transitions = defineTransitions(args.map);
48
- transitionCache.set(key, transitions);
49
- return transitions;
50
- }
17
+ import { guardAutoTransitions, resolveTransitionGuardDb } from "./write-transition-guard.js";
51
18
  // A successful config:write:set/reset returns { key, scope, ... } — see
52
19
  // bundled-features/src/config/handlers/{set,reset}.write.ts. Narrows the
53
20
  // otherwise-`unknown` WriteResult.data without an unchecked cast.
@@ -154,197 +121,6 @@ async function runLifecycle(ctx, type, data, handlerContext, user, origin, after
154
121
  export async function executeWrite(ctx, type, payload, user, origin, tx, afterCommitHooks) {
155
122
  return runHandlerInstrumented(ctx, type, "write", user, () => executeWriteInner(ctx, type, payload, user, origin, tx, afterCommitHooks));
156
123
  }
157
- function isForeignTenantParentRow(parentRow, user) {
158
- const rowTenantId = parentRow["tenantId"];
159
- return typeof rowTenantId === "string" && rowTenantId !== user.tenantId;
160
- }
161
- // A custom create handler may return a row without a string tenantId; the row's
162
- // tenant is then unknown from the payload, so re-read it through the caller's tenant
163
- // filter. Fail-closed: anything that cannot be verified counts as not visible.
164
- // Tenant reads also return SYSTEM reference rows, so the row's own tenantId must match
165
- // (same rule as the string path) unless the entity has no tenant column.
166
- async function isParentRowHiddenFromCaller(ctx, parentEntityName, parentId, user, tx) {
167
- if (parentEntityName === undefined)
168
- return true;
169
- const table = getTable(ctx, parentEntityName);
170
- const source = resolveDbSource(ctx, tx);
171
- if (!table || !source)
172
- return true;
173
- const callerDb = createTenantDb({ db: source, tenantId: user.tenantId, mode: "tenant" });
174
- const visibleRow = await callerDb.fetchOne(table, { id: parentId });
175
- if (visibleRow === undefined)
176
- return true;
177
- return hasTenantColumn(table) && visibleRow["tenantId"] !== user.tenantId;
178
- }
179
- // A custom create handler may return a partial row. The ownership check only
180
- // inspects the keys it is given, so a row missing the ownership-bound field
181
- // would be denied (rule evaluated against undefined) or skipped entirely.
182
- // Complete it from the stored row, read through the caller's tenant filter.
183
- async function completeParentRow(ctx, parentEntityName, parentEntity, parentRow, user, tx) {
184
- if (Object.keys(parentEntity.fields).every((fieldName) => fieldName in parentRow)) {
185
- return parentRow;
186
- }
187
- const table = getTable(ctx, parentEntityName);
188
- const source = resolveDbSource(ctx, tx);
189
- if (!table || !source || typeof parentRow["id"] !== "string")
190
- return parentRow;
191
- const stored = await createTenantDb({
192
- db: source,
193
- tenantId: user.tenantId,
194
- mode: "tenant",
195
- }).fetchOne(table, {
196
- id: parentRow["id"],
197
- });
198
- return stored ? { ...stored, ...parentRow } : parentRow;
199
- }
200
- function collectNestedForeignKeyIssues(nested) {
201
- // Pre-flight client-shape checks. Merge non-array issues (collected up
202
- // front by extractNestedSpecs) with fk-injection issues into one error
203
- // so the client sees every problem in a single round-trip.
204
- //
205
- // Security rail: the client MUST NOT supply the foreign key on nested
206
- // items. The framework binds it from the parent's new id. Silent-overwrite
207
- // would mask an attempt to attach children to a different parent — fail
208
- // loud with a ValidationError carrying a client-mappable path.
209
- const issues = [...nested.typeIssues];
210
- for (const spec of nested.specs) {
211
- for (let i = 0; i < spec.items.length; i++) {
212
- const item = spec.items[i];
213
- if (item && typeof item === "object" && spec.foreignKey in item) {
214
- issues.push({
215
- path: `${spec.key}.${i}.${spec.foreignKey}`,
216
- code: "unexpected_field",
217
- i18nKey: "errors.validation.unexpected_field",
218
- });
219
- }
220
- }
221
- }
222
- return issues;
223
- }
224
- // Handlers built on the CRUD executor return a SaveContext wrapper —
225
- // `{ kind: "save", id, data: <row>, changes, previous, event, ... }`.
226
- // The wrapper is load-bearing for batch-level hooks downstream (see
227
- // flushBatchHooks), so we mutate in place: nested children land on the
228
- // inner `data` (which mirrors the entity shape the client expects) while
229
- // the wrapper keeps its SaveContext semantics intact for the lifecycle
230
- // pipeline. For handlers that return a bare row (no wrapper), children
231
- // land directly on that object.
232
- //
233
- // Hook-ordering note: per-entity postSave hooks already ran inside the
234
- // parent's executeWrite call — they never saw `tasks`, which is
235
- // the right semantic (postSave gets the entity's own columns, not
236
- // synthetic relation keys). A future postSaveBatch subscriber that
237
- // enumerates columns generically WOULD see `tasks`; no such subscriber
238
- // exists today. If you add one that iterates `Object.keys(save.data)`,
239
- // filter by `entity.fields` membership to stay correct.
240
- // handler-Result.data is generic across all entity handlers; nested-
241
- // write inspects the shape structurally.
242
- function unwrapSaveRow(data) {
243
- const wrapper = data; // @cast-boundary engine-payload
244
- return (wrapper["data"] ?? wrapper); // @cast-boundary engine-payload
245
- }
246
- // A custom create handler may return an existing foreign row; verify it before attaching children.
247
- async function rejectUnverifiedParent(ctx, type, parentRow, parentId, user, tx) {
248
- const { registry } = ctx;
249
- const parentEntityName = registry.getHandlerEntity(type);
250
- const isCallerScoped = !registry.isHandlerSystemScoped(type);
251
- const isParentForeign = isCallerScoped &&
252
- (typeof parentRow["tenantId"] === "string"
253
- ? isForeignTenantParentRow(parentRow, user)
254
- : await isParentRowHiddenFromCaller(ctx, parentEntityName, parentId, user, tx));
255
- if (isParentForeign) {
256
- return writeFailure(new AccessDeniedError({
257
- message: `nested-write: parent row belongs to another tenant — refusing to attach children to "${type}"`,
258
- details: { reason: FrameworkReasons.fieldAccessDenied, handler: type },
259
- }));
260
- }
261
- if (!parentEntityName)
262
- return undefined;
263
- const parentEntity = registry.getEntity(parentEntityName);
264
- if (!parentEntity)
265
- return undefined;
266
- const ownershipRow = await completeParentRow(ctx, parentEntityName, parentEntity, parentRow, user, tx);
267
- const deniedField = checkWriteFieldOwnership(parentEntity, ownershipRow, user);
268
- if (!deniedField)
269
- return undefined;
270
- return writeFailure(new AccessDeniedError({
271
- message: `nested-write: parent row ownership check failed on field "${deniedField}" of "${type}" — refusing to attach children to a parent row the caller does not own`,
272
- i18nKey: "errors.access.fieldDenied",
273
- details: {
274
- reason: FrameworkReasons.fieldAccessDenied,
275
- field: deniedField,
276
- handler: type,
277
- },
278
- }));
279
- }
280
- async function writeNestedChildren(ctx, spec, parentId, user, origin, tx, afterCommitHooks) {
281
- const { registry } = ctx;
282
- const subRows = [];
283
- for (let i = 0; i < spec.items.length; i++) {
284
- const rawItem = spec.items[i];
285
- const itemObj = (rawItem ?? {}); // @cast-boundary engine-payload
286
- const subPayload = { ...itemObj, [spec.foreignKey]: parentId };
287
- const subResult = await executeWrite(ctx, spec.subType, subPayload, user, origin, tx, afterCommitHooks);
288
- if (!subResult.isSuccess) {
289
- return {
290
- kind: "failed",
291
- failure: {
292
- isSuccess: false,
293
- error: prefixValidationPath(subResult.error, `${spec.key}.${i}`),
294
- },
295
- };
296
- }
297
- const subRow = unwrapSaveRow(subResult.data);
298
- const subEntityName = registry.getHandlerEntity(spec.subType);
299
- const subEntity = subEntityName ? registry.getEntity(subEntityName) : undefined;
300
- // parentRow is returned to the client; the child's own SaveContext keeps the plaintext.
301
- subRows.push(subEntity ? maskWriteOnlyFields(subEntity, subRow) : subRow);
302
- }
303
- return { kind: "written", rows: subRows };
304
- }
305
- // Nested-write orchestration (v1: depth=1, create-only, hasMany-only).
306
- //
307
- // When a parent `:create` handler's payload carries values under keys
308
- // declared as `hasMany` relations with `nestedWrite: true`, those values
309
- // are expanded into child writes: parent first (so its new id exists),
310
- // then each nested entry as a separate `<target>:create` write with the
311
- // foreign key set by the framework — never taken from the client. All of
312
- // this runs inside the caller's transaction, so a child failure rolls the
313
- // parent (and any earlier children) back together.
314
- //
315
- // This wrapper is what runBatch calls, not executeWrite. Single writes
316
- // (`dispatcher.write`) flow through runBatch as batch-of-one, so they get
317
- // nested-expansion too for free. A batch with N heterogeneous commands
318
- // can each independently carry nested-children — all still one TX.
319
- export async function executeNestedWrite(ctx, type, payload, user, origin, tx, afterCommitHooks) {
320
- const nested = extractNestedSpecs(type, payload, ctx.registry);
321
- if (!nested)
322
- return executeWrite(ctx, type, payload, user, origin, tx, afterCommitHooks);
323
- const issues = collectNestedForeignKeyIssues(nested);
324
- if (issues.length > 0) {
325
- return writeFailure(new ValidationError({ fields: issues }));
326
- }
327
- const parentResult = await executeWrite(ctx, type, nested.cleanPayload, user, origin, tx, afterCommitHooks);
328
- if (!parentResult.isSuccess)
329
- return parentResult;
330
- const parentRow = unwrapSaveRow(parentResult.data);
331
- const parentId = parentRow["id"];
332
- if (typeof parentId !== "string") {
333
- return writeFailure(new InternalError({
334
- message: `nested-write: parent handler "${type}" returned no string "id" — cannot attach children`,
335
- }));
336
- }
337
- const parentRejection = await rejectUnverifiedParent(ctx, type, parentRow, parentId, user, tx);
338
- if (parentRejection)
339
- return parentRejection;
340
- for (const spec of nested.specs) {
341
- const children = await writeNestedChildren(ctx, spec, parentId, user, origin, tx, afterCommitHooks);
342
- if (children.kind === "failed")
343
- return children.failure;
344
- parentRow[spec.key] = children.rows;
345
- }
346
- return parentResult;
347
- }
348
124
  async function confirmReservation(reservation, tx, user) {
349
125
  if (!reservation.confirmInTransaction)
350
126
  return undefined;
@@ -393,81 +169,6 @@ async function runWriteGates(ctx, handler, type, payload, user) {
393
169
  return failedStep(nestedDenial);
394
170
  return { kind: "run", parsedPayload, reservation };
395
171
  }
396
- // Reads via the guard's own db handle — for r.systemScope() handlers
397
- // handlerContext.db is fail-closed, so this reaches for
398
- // systemDb.acknowledgeCrossTenant like any other framework-internal
399
- // mechanism that touches a system-scoped handler's data.
400
- function resolveTransitionGuardDb(handlerContext, type) {
401
- return handlerContext.systemDb
402
- ? handlerContext.systemDb.acknowledgeCrossTenant(`auto transition guard for r.systemScope() write handler (${type})`)
403
- : handlerContext.db;
404
- }
405
- // Auto transition guard: if entity has transitions and handler doesn't skip it.
406
- async function guardAutoTransitions(ctx, handler, type, parsedPayload, transitionGuardDb, tx) {
407
- const entityName = ctx.registry.getHandlerEntity(type);
408
- // skip: handler has no entity or opted out of the transition guard
409
- if (!entityName || handler.unsafeSkipTransitionGuard)
410
- return;
411
- const entity = ctx.registry.getEntity(entityName);
412
- // skip: entity declares no transitions, or there is no db to read the current value from
413
- if (!entity?.transitions || !transitionGuardDb)
414
- return;
415
- const parsedData = parsedPayload; // @cast-boundary engine-payload
416
- const changes = parsedData["changes"] ?? parsedData; // @cast-boundary engine-payload
417
- const id = parsedData["id"] ?? undefined; // @cast-boundary engine-payload
418
- for (const [fieldName, transitionMap] of Object.entries(entity.transitions)) {
419
- await guardFieldTransition(ctx, {
420
- entityName,
421
- entity,
422
- fieldName,
423
- transitionMap,
424
- changes,
425
- id,
426
- transitionGuardDb,
427
- tx,
428
- });
429
- }
430
- }
431
- async function guardFieldTransition(ctx, args) {
432
- const { entityName, entity, fieldName, transitionMap, changes, id, transitionGuardDb, tx } = args;
433
- const newValue = changes[fieldName]; // @cast-boundary engine-bridge
434
- // skip: field is not part of this write
435
- if (!newValue || !id)
436
- return;
437
- const table = getTable(ctx, entityName);
438
- // skip: entity has no table to read the current value from
439
- if (!table)
440
- return;
441
- // SELECT FOR UPDATE inside the surrounding transaction — locks the
442
- // row so a concurrent handler can't mutate `status` between our
443
- // guard check and the handler's UPDATE. Without this lock the guard
444
- // can false-pass; optimistic locking would catch it later, but with
445
- // a less specific error. Falls back to a plain SELECT if no tx is
446
- // active (tests without a DB connection).
447
- const tableName = asEntityTableMeta(table)?.tableName ?? "";
448
- const rows = tx
449
- ? await selectRowForUpdateById(tenantDbRunner(transitionGuardDb), tableName, id)
450
- : await selectMany(transitionGuardDb, table, { id });
451
- const row = rows[0];
452
- // skip: no stored row to transition from
453
- if (!row)
454
- return;
455
- // Skip guard for soft-deleted rows — they shouldn't be transitioning
456
- // at all; a handler that wants to move a deleted row should use
457
- // unsafeSkipTransitionGuard or restore first.
458
- const rowAsRow = row; // @cast-boundary engine-payload
459
- const isDeleted = rowAsRow["isDeleted"] ?? rowAsRow["is_deleted"];
460
- // skip: soft-deleted row
461
- if (entity.softDelete && isDeleted === true) {
462
- return;
463
- }
464
- const currentValue = row[fieldName] ??
465
- row[toSnakeCase(fieldName)]; // @cast-boundary engine-bridge
466
- // skip: an unchanged value is no transition (an edit form resends the current status)
467
- if (currentValue === newValue)
468
- return;
469
- guardTransition(getTransitions(ctx, { entityName, fieldName, map: transitionMap }), currentValue, newValue);
470
- }
471
172
  // The handler itself plus the lifecycle pipeline run under the same
472
173
  // try-wrapper: any KumikoError bubbles up as a typed WriteErrorInfo, any
473
174
  // other throw gets wrapped in InternalError so the Prod contract holds
@@ -3,6 +3,8 @@ import { parseQn, qn } from "../engine/qualified-name.js";
3
3
  import { ValidationError, VersionConflictError, } from "../errors/index.js";
4
4
  import { toKumikoError } from "../errors/to-kumiko-error.js";
5
5
  import { VersionConflictError as EventStoreVersionConflictError } from "../event-store/errors.js";
6
+ import { createFallbackLogger } from "../logging/utils.js";
7
+ const dispatcherUtilsLog = createFallbackLogger("dispatcher-utils");
6
8
  export function isFailedWriteResult(result) {
7
9
  return (!!result && typeof result === "object" && "isSuccess" in result && result.isSuccess === false);
8
10
  }
@@ -156,6 +158,10 @@ export function wrapToKumiko(e) {
156
158
  }
157
159
  // Payload schemas without z.iso.date() let impossible dates reach the column; that is bad input, not a 500.
158
160
  if (isInvalidDateTimeValue(e)) {
161
+ // Also hit by server-generated dates (hooks, jobs); the 400 hides those, so leave a trail.
162
+ dispatcherUtilsLog.warn("invalid datetime value mapped to validation error", {
163
+ cause: e instanceof Error ? e.message : String(e),
164
+ });
159
165
  return new ValidationError({ fields: [] }, { cause: e instanceof Error ? e : undefined });
160
166
  }
161
167
  return toKumikoError(e);
@@ -0,0 +1,3 @@
1
+ import type { Registry } from "../engine/types/index.ts";
2
+ export declare function isGlobalEntityReadInAgentToolCall(registry: Registry, type: string): boolean;
3
+ export declare function isEffectivelySystemScoped(registry: Registry, type: string): boolean;
@@ -0,0 +1,22 @@
1
+ import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handlers";
2
+ import { isAgentToolCallScope } from "../api/request-context-scopes.js";
3
+ // A global entity's rows are shared reference data every tenant already reads in tenant mode, so an
4
+ // agent tool call may run the generated list/detail query of a system-scope feature that serves
5
+ // one. A hand-written query could do anything with system scope, and an escapeHatch (e.g.
6
+ // systemIdentity) must never run on behalf of the LLM, so both stay refused.
7
+ export function isGlobalEntityReadInAgentToolCall(registry, type) {
8
+ if (!isAgentToolCallScope())
9
+ return false;
10
+ const handler = registry.getQueryHandler(type);
11
+ if (handler === undefined || handler[ENTITY_CONVENTION_QUERY_BRAND] !== true)
12
+ return false;
13
+ if (handler.escapeHatch !== undefined)
14
+ return false;
15
+ const entityName = registry.getHandlerEntity(type);
16
+ return entityName !== undefined && registry.getEntity(entityName)?.tenancy === "global";
17
+ }
18
+ // What the dispatcher treats as system scope for this handler: the feature flag, minus the
19
+ // agent-tool-call global-read carve-out, which runs with the caller's tenant scope.
20
+ export function isEffectivelySystemScoped(registry, type) {
21
+ return registry.isHandlerSystemScoped(type) && !isGlobalEntityReadInAgentToolCall(registry, type);
22
+ }
@@ -64,6 +64,7 @@ export type DeliveryOutcome = {
64
64
  readonly failedEventId: bigint | null;
65
65
  readonly resolvedPendingIds: readonly bigint[];
66
66
  readonly heldNewIds: readonly bigint[];
67
+ readonly heldOnlyWhileBackingOff?: boolean;
67
68
  };
68
69
  export declare function deliverEvents(consumer: EventConsumer, events: ReadonlyArray<StoredEventRow>, context: AppContext, maxAttempts: number, state: ConsumerStateRow): Promise<DeliveryOutcome>;
69
70
  export type ConsumerTurnInput = {
@@ -264,7 +264,7 @@ function escalateIntakePausedOutcome(outcome, state, deliverable, pendingGapCoun
264
264
  const lastError = `${pendingGapCount} pending gap ranges reached the limit of ${maxPendingGapRanges}; ` +
265
265
  `no new events are taken until the held events of tenant ${heldTenant} drain ` +
266
266
  `(first held event ${firstHeld ?? "unknown"})`;
267
- if (outcome.processed > 0)
267
+ if (outcome.processed > 0 || outcome.heldOnlyWhileBackingOff)
268
268
  return { ...outcome, lastError };
269
269
  const attempts = state.attempts + 1;
270
270
  return {
@@ -309,8 +309,10 @@ function outcomeOfAppliedBatch(events, state, batch) {
309
309
  const newIds = events.map((row) => row.id).filter((id) => id > startCursor);
310
310
  const anyDelivered = deliveredIds.length > 0;
311
311
  let lastError = anyDelivered ? null : (state.lastError ?? null);
312
- if (heldIds.length > 0 && batch.heldReason !== null)
313
- lastError = batch.heldReason;
312
+ const failedEventId = heldIds[0] ?? null;
313
+ const failedReason = failedEventId === null ? undefined : batch.heldReasons.get(String(failedEventId));
314
+ if (failedReason !== undefined)
315
+ lastError = failedReason;
314
316
  return {
315
317
  cursor: newIds.at(-1) ?? startCursor,
316
318
  attempts: anyDelivered ? 0 : state.attempts,
@@ -318,9 +320,10 @@ function outcomeOfAppliedBatch(events, state, batch) {
318
320
  deadLettered: false,
319
321
  processed: deliveredIds.length,
320
322
  failed: heldIds.length,
321
- failedEventId: heldIds[0] ?? null,
323
+ failedEventId,
322
324
  resolvedPendingIds: deliveredIds.filter((id) => id <= startCursor),
323
325
  heldNewIds: heldIds.filter((id) => id > startCursor),
326
+ heldOnlyWhileBackingOff: heldIds.length > 0 && !batch.anyHoldAfterAttempt,
324
327
  };
325
328
  }
326
329
  // Shared requestContext scope for one apply — event-derived fields
@@ -357,17 +360,22 @@ async function applyEvent(consumer, row, context) {
357
360
  }
358
361
  async function tryApplyBatch(consumer, events, context) {
359
362
  const held = new Set();
360
- let heldReason = null;
363
+ const heldReasons = new Map();
364
+ let anyHoldAfterAttempt = false;
361
365
  const turn = {
362
- holdForRetry: (eventIds, reason) => {
363
- for (const id of eventIds)
366
+ holdForRetry: (eventIds, reason, options) => {
367
+ for (const id of eventIds) {
364
368
  held.add(id);
365
- heldReason ??= reason;
369
+ if (!heldReasons.has(id))
370
+ heldReasons.set(id, reason);
371
+ }
372
+ if (options?.stillBackingOff !== true)
373
+ anyHoldAfterAttempt = true;
366
374
  },
367
375
  };
368
376
  try {
369
377
  await applyBatch(consumer, events, context, turn);
370
- return { applied: true, held, heldReason };
378
+ return { applied: true, held, heldReasons, anyHoldAfterAttempt };
371
379
  }
372
380
  catch (e) {
373
381
  const errMessage = e instanceof Error ? e.message : String(e);
@@ -5,7 +5,9 @@ import type { StoredEvent } from "../event-store/index.ts";
5
5
  export type EventConsumerHandler = (event: StoredEvent, ctx: AppContext) => Promise<void>;
6
6
  export type EventConsumerBatchHandler = (events: readonly StoredEvent[], ctx: AppContext, turn: BatchTurnControl) => Promise<void>;
7
7
  export type BatchTurnControl = {
8
- readonly holdForRetry: (eventIds: readonly string[], reason: string) => void;
8
+ readonly holdForRetry: (eventIds: readonly string[], reason: string, options?: {
9
+ readonly stillBackingOff?: boolean;
10
+ }) => void;
9
11
  };
10
12
  export type EventConsumerErrorPolicy = {
11
13
  readonly skipApplyErrors?: boolean;
@@ -53,6 +55,7 @@ export type EventDispatcherOptions = {
53
55
  readonly instanceId?: string;
54
56
  readonly pgClient?: PgListenClient;
55
57
  };
58
+ export declare const DEFAULT_BATCH_SIZE = 200;
56
59
  export declare function createEventDispatcher(options: EventDispatcherOptions): EventDispatcher;
57
60
  export type { ConsumerProgress, ConsumerRecoveryState, ConsumerTransitionRejection, } from "./event-dispatcher-admin.ts";
58
61
  export { ConsumerTransitionError, disableConsumer, enableConsumer, getAllConsumerProgress, getConsumerState, listConsumersWithState, restartConsumer, skipPoisonEvent, } from "./event-dispatcher-admin.ts";