@cosmicdrift/kumiko-framework 0.413.1 → 0.415.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (479) hide show
  1. package/AGENTS.md +5 -2
  2. package/agents/api/framework-db.md +14 -3
  3. package/agents/api/framework-engine.md +69 -13
  4. package/agents/api/framework-errors.md +1 -1
  5. package/agents/api/framework-event-store.md +14 -0
  6. package/agents/api/framework-ui-types.md +158 -21
  7. package/agents/api/renderer-web.md +112 -11
  8. package/agents/api/testing-helpers.md +3 -2
  9. package/agents/api/testing-stack.md +3 -0
  10. package/agents/api/types.md +248 -24
  11. package/agents/api.md +7 -7
  12. package/agents/boot-rules.md +66 -10
  13. package/agents/examples/api-docs.md +2 -6
  14. package/agents/examples/auth-mfa.md +57 -10
  15. package/agents/examples/chat-channels.md +2 -0
  16. package/agents/examples/crypto-shredding-hr.md +63 -1
  17. package/agents/examples/currencies-global.md +1 -0
  18. package/agents/examples/env-composition.md +7 -11
  19. package/agents/examples/managed-pages.md +90 -1
  20. package/agents/examples/pwa-shell.md +210 -0
  21. package/agents/examples/rate-limiting.md +3 -3
  22. package/agents/examples/record-detail-layout.md +1643 -67
  23. package/agents/examples/workflow-engine.md +16 -12
  24. package/agents/examples.md +1 -0
  25. package/agents/features-index.md +4 -2
  26. package/agents/features.md +22 -7
  27. package/agents/widgets.md +26 -1
  28. package/dist/api/api-constants.d.ts +1 -0
  29. package/dist/api/api-constants.js +4 -0
  30. package/dist/api/auth-middleware.js +4 -3
  31. package/dist/api/auth-routes-shared.js +2 -1
  32. package/dist/api/entity-read-access.d.ts +1 -0
  33. package/dist/api/entity-read-access.js +18 -0
  34. package/dist/api/export/export-route.d.ts +6 -1
  35. package/dist/api/export/export-route.js +27 -1
  36. package/dist/api/export/export-rows.js +19 -3
  37. package/dist/api/request-context-internals.d.ts +2 -0
  38. package/dist/api/request-context-scopes.js +9 -2
  39. package/dist/api/request-context.js +1 -1
  40. package/dist/api/routes.d.ts +2 -0
  41. package/dist/api/routes.js +9 -1
  42. package/dist/api/server-event-dispatcher.js +3 -0
  43. package/dist/api/server-extra-routes.js +2 -1
  44. package/dist/api/server-feature-http-routes.d.ts +9 -0
  45. package/dist/api/server-feature-http-routes.js +109 -0
  46. package/dist/api/server-middleware.js +2 -19
  47. package/dist/api/server-pat-rate-limit-guard.d.ts +3 -0
  48. package/dist/api/server-pat-rate-limit-guard.js +19 -0
  49. package/dist/api/server-rate-limit-wiring.d.ts +10 -0
  50. package/dist/api/server-rate-limit-wiring.js +37 -0
  51. package/dist/api/server-routes.d.ts +4 -12
  52. package/dist/api/server-routes.js +12 -171
  53. package/dist/api/server-schema-route.d.ts +3 -0
  54. package/dist/api/server-schema-route.js +58 -0
  55. package/dist/api/server-wiring.js +2 -37
  56. package/dist/api/server.js +3 -1
  57. package/dist/compliance/override-schema.js +5 -5
  58. package/dist/compliance/sub-processors.js +10 -1
  59. package/dist/crypto/index.d.ts +1 -1
  60. package/dist/crypto/index.js +1 -1
  61. package/dist/crypto/pii-field-encryption.d.ts +2 -0
  62. package/dist/crypto/pii-field-encryption.js +16 -1
  63. package/dist/db/apply-entity-event.js +4 -0
  64. package/dist/db/bun-sql-connection-codes.d.ts +1 -0
  65. package/dist/db/bun-sql-connection-codes.js +7 -0
  66. package/dist/db/collect-table-metas.js +4 -1
  67. package/dist/db/config-seed.js +1 -1
  68. package/dist/db/derived-field-sql.js +15 -13
  69. package/dist/db/derived-related-sql.d.ts +2 -2
  70. package/dist/db/derived-related-sql.js +4 -2
  71. package/dist/db/dialect.d.ts +3 -0
  72. package/dist/db/dialect.js +1 -3
  73. package/dist/db/driver-row-coercion.js +2 -2
  74. package/dist/db/driver-value-preparation.js +1 -1
  75. package/dist/db/eagerload.js +15 -12
  76. package/dist/db/entity-table-meta.d.ts +2 -0
  77. package/dist/db/entity-table-meta.js +7 -0
  78. package/dist/db/event-store-executor-context.js +13 -8
  79. package/dist/db/event-store-executor-read-aggregate-currencies.js +2 -2
  80. package/dist/db/event-store-executor-read-aggregate.js +2 -2
  81. package/dist/db/event-store-executor-read-filter.d.ts +4 -0
  82. package/dist/db/event-store-executor-read-filter.js +28 -11
  83. package/dist/db/event-store-executor-read-search.d.ts +1 -0
  84. package/dist/db/event-store-executor-read-search.js +6 -6
  85. package/dist/db/event-store-executor-read-sort.js +3 -3
  86. package/dist/db/event-store-executor-read-where.js +14 -5
  87. package/dist/db/event-store-executor-read.js +7 -7
  88. package/dist/db/event-store-executor-write.js +50 -95
  89. package/dist/db/executor-managed-tables.js +4 -1
  90. package/dist/db/index.d.ts +4 -2
  91. package/dist/db/index.js +4 -2
  92. package/dist/db/known-table-names.d.ts +1 -0
  93. package/dist/db/known-table-names.js +7 -5
  94. package/dist/db/list-aggregate-labels.d.ts +1 -0
  95. package/dist/db/list-aggregate-labels.js +9 -1
  96. package/dist/db/migrate-generator.js +23 -4
  97. package/dist/db/migrate-rls-diff.d.ts +1 -0
  98. package/dist/db/migrate-rls-diff.js +15 -1
  99. package/dist/db/migrate-runner.js +2 -2
  100. package/dist/db/money.d.ts +1 -1
  101. package/dist/db/money.js +1 -4
  102. package/dist/db/parent-ref-clause.d.ts +6 -2
  103. package/dist/db/parent-ref-clause.js +105 -24
  104. package/dist/db/parent-ref-global-hosts.d.ts +23 -0
  105. package/dist/db/parent-ref-global-hosts.js +85 -0
  106. package/dist/db/production-schema-command-hint.d.ts +1 -0
  107. package/dist/db/production-schema-command-hint.js +3 -0
  108. package/dist/db/queries/backfill-pii.js +55 -29
  109. package/dist/db/queries/ddl.js +13 -2
  110. package/dist/db/queries/event-store-open-streams.d.ts +15 -0
  111. package/dist/db/queries/event-store-open-streams.js +33 -0
  112. package/dist/db/queries/event-store-payload-scrub.d.ts +5 -0
  113. package/dist/db/queries/event-store-payload-scrub.js +11 -0
  114. package/dist/db/queries/event-store.js +0 -1
  115. package/dist/db/queries/raw-sql.js +0 -1
  116. package/dist/db/queries/rebuild-rls-guard.d.ts +2 -1
  117. package/dist/db/queries/rebuild-rls-guard.js +24 -11
  118. package/dist/db/queries/rls-boot-catalog.d.ts +1 -0
  119. package/dist/db/queries/rls-boot-catalog.js +13 -9
  120. package/dist/db/queries/rls-shape.d.ts +3 -1
  121. package/dist/db/queries/rls-shape.js +31 -6
  122. package/dist/db/queries/session-advisory-lock.js +2 -1
  123. package/dist/db/queries/test-stack.js +7 -7
  124. package/dist/db/query.js +16 -11
  125. package/dist/db/rebuild-marker.js +11 -2
  126. package/dist/db/render-rls-ddl.d.ts +2 -0
  127. package/dist/db/render-rls-ddl.js +16 -11
  128. package/dist/db/replay-migration-sql.js +1 -1
  129. package/dist/db/row-level-security-boot-check.js +18 -5
  130. package/dist/db/row-level-security-connection.js +25 -12
  131. package/dist/db/row-level-security-scope.d.ts +2 -1
  132. package/dist/db/row-level-security-scope.js +9 -5
  133. package/dist/db/sql-identifier.d.ts +1 -0
  134. package/dist/db/sql-identifier.js +3 -0
  135. package/dist/db/system-tenant-read-db.d.ts +5 -0
  136. package/dist/db/system-tenant-read-db.js +28 -0
  137. package/dist/db/table-builder.d.ts +3 -1
  138. package/dist/db/table-builder.js +18 -8
  139. package/dist/db/table-info.d.ts +1 -2
  140. package/dist/db/table-introspection.d.ts +3 -0
  141. package/dist/db/table-introspection.js +6 -0
  142. package/dist/db/table-push.d.ts +1 -0
  143. package/dist/db/table-push.js +7 -1
  144. package/dist/db/tenant-db-runner.d.ts +3 -0
  145. package/dist/db/tenant-db-runner.js +19 -1
  146. package/dist/db/transaction-serialization.d.ts +1 -0
  147. package/dist/db/transaction-serialization.js +20 -3
  148. package/dist/db/where-clause.js +11 -2
  149. package/dist/db/write-ownership-failures.d.ts +25 -0
  150. package/dist/db/write-ownership-failures.js +82 -0
  151. package/dist/engine/boot-validator/boot-check.js +7 -1
  152. package/dist/engine/boot-validator/boot-phases-app.js +5 -5
  153. package/dist/engine/boot-validator/boot-phases.js +3 -2
  154. package/dist/engine/boot-validator/boot-rules.d.ts +305 -28
  155. package/dist/engine/boot-validator/boot-rules.js +4 -0
  156. package/dist/engine/boot-validator/bundled-lists-table.js +2 -2
  157. package/dist/engine/boot-validator/card-meta-overflow-rules.d.ts +2 -2
  158. package/dist/engine/boot-validator/card-meta-overflow-rules.js +2 -2
  159. package/dist/engine/boot-validator/card-meta-overflow.js +8 -5
  160. package/dist/engine/boot-validator/config-deps.d.ts +0 -1
  161. package/dist/engine/boot-validator/config-deps.js +0 -28
  162. package/dist/engine/boot-validator/config-key-rules.d.ts +0 -15
  163. package/dist/engine/boot-validator/config-key-rules.js +0 -15
  164. package/dist/engine/boot-validator/dashboard-screen-target.d.ts +22 -0
  165. package/dist/engine/boot-validator/dashboard-screen-target.js +20 -0
  166. package/dist/engine/boot-validator/dashboard-stat-navigate.d.ts +1 -0
  167. package/dist/engine/boot-validator/dashboard-stat-navigate.js +25 -17
  168. package/dist/engine/boot-validator/definition-webhook-events-rules.d.ts +5 -0
  169. package/dist/engine/boot-validator/definition-webhook-events-rules.js +5 -0
  170. package/dist/engine/boot-validator/derived-sql-fields.js +1 -2
  171. package/dist/engine/boot-validator/entity-declaration-rules.d.ts +5 -0
  172. package/dist/engine/boot-validator/entity-declaration-rules.js +5 -0
  173. package/dist/engine/boot-validator/entity-list-screens.d.ts +1 -0
  174. package/dist/engine/boot-validator/entity-list-screens.js +35 -13
  175. package/dist/engine/boot-validator/entity-structure-rules.d.ts +5 -0
  176. package/dist/engine/boot-validator/entity-structure-rules.js +5 -0
  177. package/dist/engine/boot-validator/list-column-layout.js +10 -6
  178. package/dist/engine/boot-validator/list-row-guidance-rules.d.ts +67 -0
  179. package/dist/engine/boot-validator/list-row-guidance-rules.js +67 -0
  180. package/dist/engine/boot-validator/list-row-guidance.d.ts +20 -0
  181. package/dist/engine/boot-validator/list-row-guidance.js +143 -0
  182. package/dist/engine/boot-validator/list-sort-summary-rules.d.ts +42 -0
  183. package/dist/engine/boot-validator/list-sort-summary-rules.js +42 -0
  184. package/dist/engine/boot-validator/list-sort-summary.d.ts +5 -0
  185. package/dist/engine/boot-validator/list-sort-summary.js +160 -0
  186. package/dist/engine/boot-validator/list-table-options.js +15 -1
  187. package/dist/engine/boot-validator/list-table-rules.d.ts +10 -5
  188. package/dist/engine/boot-validator/list-table-rules.js +10 -5
  189. package/dist/engine/boot-validator/list-toolbar-options.d.ts +10 -0
  190. package/dist/engine/boot-validator/list-toolbar-options.js +30 -0
  191. package/dist/engine/boot-validator/named-filter-rules.d.ts +42 -2
  192. package/dist/engine/boot-validator/named-filter-rules.js +42 -2
  193. package/dist/engine/boot-validator/ownership.js +10 -1
  194. package/dist/engine/boot-validator/parent-ref.js +87 -50
  195. package/dist/engine/boot-validator/projection-list-screens.d.ts +1 -0
  196. package/dist/engine/boot-validator/projection-list-screens.js +32 -1
  197. package/dist/engine/boot-validator/query-output-columns.js +62 -9
  198. package/dist/engine/boot-validator/query-output-guidance.d.ts +7 -0
  199. package/dist/engine/boot-validator/query-output-guidance.js +40 -0
  200. package/dist/engine/boot-validator/query-refs.js +34 -1
  201. package/dist/engine/boot-validator/row-decoration.d.ts +11 -0
  202. package/dist/engine/boot-validator/row-decoration.js +16 -0
  203. package/dist/engine/boot-validator/screens-actions.js +1 -1
  204. package/dist/engine/boot-validator/screens-dashboard-links.d.ts +10 -0
  205. package/dist/engine/boot-validator/screens-dashboard-links.js +36 -0
  206. package/dist/engine/boot-validator/screens-dashboard-narrow.d.ts +4 -0
  207. package/dist/engine/boot-validator/screens-dashboard-narrow.js +211 -0
  208. package/dist/engine/boot-validator/screens-dashboard-rules.d.ts +84 -4
  209. package/dist/engine/boot-validator/screens-dashboard-rules.js +84 -4
  210. package/dist/engine/boot-validator/screens-dashboard.js +29 -7
  211. package/dist/engine/boot-validator/screens-kind-entity-list.js +32 -27
  212. package/dist/engine/boot-validator/screens-kind-projection-detail-guidance.d.ts +3 -0
  213. package/dist/engine/boot-validator/screens-kind-projection-detail-guidance.js +46 -0
  214. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +20 -0
  215. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +20 -0
  216. package/dist/engine/boot-validator/screens-kind-projection-detail.js +2 -0
  217. package/dist/engine/boot-validator/screens-kind-projection-list.js +4 -0
  218. package/dist/engine/boot-validator/screens-kind-rules.d.ts +25 -0
  219. package/dist/engine/boot-validator/screens-kind-rules.js +25 -0
  220. package/dist/engine/boot-validator/screens-lists.d.ts +8 -2
  221. package/dist/engine/boot-validator/screens-lists.js +19 -3
  222. package/dist/engine/boot-validator/screens.js +1 -1
  223. package/dist/engine/boot-validator/sort-nulls.d.ts +2 -0
  224. package/dist/engine/boot-validator/sort-nulls.js +15 -0
  225. package/dist/engine/boot-validator/zod-shape.d.ts +2 -1
  226. package/dist/engine/boot-validator/zod-shape.js +19 -1
  227. package/dist/engine/build-app-schema.js +4 -0
  228. package/dist/engine/config-helpers.d.ts +1 -2
  229. package/dist/engine/config-helpers.js +6 -7
  230. package/dist/engine/define-feature.js +1 -0
  231. package/dist/engine/define-handler.d.ts +1 -0
  232. package/dist/engine/define-handler.js +4 -2
  233. package/dist/engine/definition-violations.js +2 -2
  234. package/dist/engine/entity-handlers.js +3 -8
  235. package/dist/engine/entity-list-runtime-options.js +9 -8
  236. package/dist/engine/factories.d.ts +2 -0
  237. package/dist/engine/feature-config-events-jobs.js +1 -0
  238. package/dist/engine/feature-entity-handlers.js +5 -2
  239. package/dist/engine/field-access.d.ts +1 -1
  240. package/dist/engine/field-access.js +7 -10
  241. package/dist/engine/find-entity.js +3 -3
  242. package/dist/engine/form-derivations.js +3 -3
  243. package/dist/engine/index.d.ts +3 -3
  244. package/dist/engine/index.js +2 -2
  245. package/dist/engine/named-filter-roles.d.ts +3 -0
  246. package/dist/engine/named-filter-roles.js +15 -0
  247. package/dist/engine/pipeline.js +0 -1
  248. package/dist/engine/project-app-schema-for-roles.js +17 -2
  249. package/dist/engine/qualified-name.js +0 -1
  250. package/dist/engine/registry-facade.js +1 -2
  251. package/dist/engine/registry-state.d.ts +1 -1
  252. package/dist/engine/registry-state.js +5 -2
  253. package/dist/engine/registry-validate.js +2 -1
  254. package/dist/engine/resolve-named-list-filters.js +5 -2
  255. package/dist/engine/schema-builder.js +9 -11
  256. package/dist/engine/screen-helpers.d.ts +12 -0
  257. package/dist/engine/screen-helpers.js +17 -1
  258. package/dist/engine/soft-delete-cleanup.js +3 -5
  259. package/dist/engine/state-machine.js +0 -1
  260. package/dist/engine/steps/_database-clock.d.ts +2 -0
  261. package/dist/engine/steps/_database-clock.js +6 -0
  262. package/dist/engine/steps/compute.js +1 -1
  263. package/dist/engine/steps/retry.js +5 -1
  264. package/dist/engine/steps/return.js +0 -1
  265. package/dist/engine/steps/wait-for-event.js +2 -1
  266. package/dist/engine/steps/wait.js +2 -1
  267. package/dist/engine/system-user.d.ts +2 -2
  268. package/dist/engine/system-user.js +2 -2
  269. package/dist/engine/types/handlers.d.ts +1 -1
  270. package/dist/engine/types/handlers.js +1 -1
  271. package/dist/engine/types/screen.d.ts +1 -1
  272. package/dist/engine/types/screen.js +1 -1
  273. package/dist/engine/webhook-contracts.d.ts +2 -3
  274. package/dist/engine/webhook-contracts.js +2 -25
  275. package/dist/engine/webhook-events.js +48 -29
  276. package/dist/engine/webhook-payload-strictness.d.ts +7 -0
  277. package/dist/engine/webhook-payload-strictness.js +53 -0
  278. package/dist/env/_zod-introspect.d.ts +1 -0
  279. package/dist/env/dry-run.d.ts +1 -1
  280. package/dist/env/dry-run.js +1 -1
  281. package/dist/env/field-meta.d.ts +4 -0
  282. package/dist/env/field-meta.js +67 -0
  283. package/dist/env/field-rules.d.ts +9 -0
  284. package/dist/env/field-rules.js +46 -0
  285. package/dist/env/index.d.ts +3 -3
  286. package/dist/env/index.js +16 -71
  287. package/dist/env/internals.d.ts +3 -0
  288. package/dist/env/internals.js +1 -2
  289. package/dist/env/required-env.d.ts +3 -1
  290. package/dist/env/required-env.js +5 -2
  291. package/dist/errors/reasons.d.ts +1 -0
  292. package/dist/errors/reasons.js +4 -0
  293. package/dist/errors/serialize.js +2 -2
  294. package/dist/errors/write-error-info.js +0 -2
  295. package/dist/es-ops/operations-schema.js +18 -7
  296. package/dist/event-store/admin-api.js +3 -3
  297. package/dist/event-store/event-store.js +0 -3
  298. package/dist/event-store/index.d.ts +1 -0
  299. package/dist/event-store/index.js +1 -0
  300. package/dist/event-store/transfer.js +1 -1
  301. package/dist/files/assert-file-refs-belong-to-tenant.d.ts +2 -1
  302. package/dist/files/assert-file-refs-belong-to-tenant.js +15 -13
  303. package/dist/files/bind-pending-file-refs.d.ts +3 -1
  304. package/dist/files/bind-pending-file-refs.js +54 -27
  305. package/dist/files/copy-pending-file-refs-to-tenant.js +7 -3
  306. package/dist/files/create-file-ref.d.ts +4 -1
  307. package/dist/files/create-file-ref.js +14 -3
  308. package/dist/files/default-file-guard.js +4 -1
  309. package/dist/files/file-claim.d.ts +6 -0
  310. package/dist/files/file-claim.js +17 -0
  311. package/dist/files/file-field-slots.d.ts +2 -0
  312. package/dist/files/file-field-slots.js +28 -0
  313. package/dist/files/file-ref-entity.d.ts +3 -0
  314. package/dist/files/file-ref-entity.js +2 -0
  315. package/dist/files/file-ref-table.d.ts +3 -0
  316. package/dist/files/file-routes.d.ts +4 -1
  317. package/dist/files/file-routes.js +80 -16
  318. package/dist/files/in-memory-provider.d.ts +1 -1
  319. package/dist/files/in-memory-provider.js +2 -1
  320. package/dist/files/index.d.ts +1 -1
  321. package/dist/files/index.js +1 -1
  322. package/dist/files/invalid-file-ref-error.d.ts +2 -0
  323. package/dist/files/invalid-file-ref-error.js +15 -0
  324. package/dist/files/local-provider.js +9 -2
  325. package/dist/files/provider-resolver.js +1 -1
  326. package/dist/files/rebind-file-ref.d.ts +3 -2
  327. package/dist/files/rebind-file-ref.js +24 -18
  328. package/dist/files/resolve-file-handles.d.ts +13 -0
  329. package/dist/files/resolve-file-handles.js +57 -0
  330. package/dist/files/storage-tracking.d.ts +1 -1
  331. package/dist/files/storage-tracking.js +5 -2
  332. package/dist/files/sweep-stale-pending-file-refs.js +10 -4
  333. package/dist/files/types.d.ts +4 -0
  334. package/dist/files/types.js +10 -0
  335. package/dist/files/upload-field-resolution.d.ts +1 -0
  336. package/dist/files/upload-field-resolution.js +16 -2
  337. package/dist/files/upload-ledger.js +1 -1
  338. package/dist/i18n/required-surface-guidance-keys.d.ts +3 -0
  339. package/dist/i18n/required-surface-guidance-keys.js +9 -0
  340. package/dist/i18n/required-surface-keys.js +21 -5
  341. package/dist/internal/boot-rule-table-expectations.d.ts +2 -0
  342. package/dist/internal/boot-rule-table-expectations.js +29 -0
  343. package/dist/internal/row-level-security.d.ts +1 -0
  344. package/dist/internal/row-level-security.js +1 -0
  345. package/dist/internal/testing.d.ts +1 -0
  346. package/dist/internal/testing.js +1 -0
  347. package/dist/jobs/index.d.ts +1 -0
  348. package/dist/jobs/index.js +1 -0
  349. package/dist/jobs/job-load-events.d.ts +10 -0
  350. package/dist/jobs/job-load-events.js +12 -0
  351. package/dist/jobs/job-runner-context.js +6 -158
  352. package/dist/jobs/job-runner-dispatch.d.ts +7 -0
  353. package/dist/jobs/job-runner-dispatch.js +57 -0
  354. package/dist/jobs/job-runner-event-triggers.js +18 -9
  355. package/dist/jobs/job-runner-execution.js +5 -2
  356. package/dist/jobs/job-runner-facets.d.ts +48 -0
  357. package/dist/jobs/job-runner-facets.js +156 -0
  358. package/dist/jobs/job-runner-gates.js +19 -11
  359. package/dist/jobs/job-runner-helpers.d.ts +5 -1
  360. package/dist/jobs/job-runner-helpers.js +18 -3
  361. package/dist/jobs/job-runner-scope.d.ts +1 -0
  362. package/dist/jobs/job-runner-scope.js +2 -0
  363. package/dist/jobs/job-runner-tenant-cap-lock.d.ts +2 -0
  364. package/dist/jobs/job-runner-tenant-cap-lock.js +30 -0
  365. package/dist/jobs/job-runner-types.d.ts +1 -0
  366. package/dist/jobs/job-runner.js +39 -70
  367. package/dist/jobs/obliterate-job-queues.d.ts +6 -0
  368. package/dist/jobs/obliterate-job-queues.js +23 -0
  369. package/dist/lifecycle/lifecycle.js +1 -1
  370. package/dist/migrations/event-header-scrub.d.ts +11 -0
  371. package/dist/migrations/event-header-scrub.js +33 -0
  372. package/dist/migrations/event-payload-scrub.d.ts +1 -1
  373. package/dist/migrations/event-payload-scrub.js +36 -4
  374. package/dist/migrations/index.d.ts +1 -0
  375. package/dist/migrations/index.js +2 -0
  376. package/dist/migrations/kumiko-drift.d.ts +5 -2
  377. package/dist/migrations/kumiko-drift.js +51 -14
  378. package/dist/migrations/pending-rebuilds.js +4 -5
  379. package/dist/observability/sensitive-filter.js +0 -12
  380. package/dist/pipeline/aggregate-type-removal.js +17 -4
  381. package/dist/pipeline/context-services.d.ts +2 -0
  382. package/dist/pipeline/context-services.js +5 -2
  383. package/dist/pipeline/dispatch-batch.js +4 -3
  384. package/dist/pipeline/dispatch-context-helpers.d.ts +11 -0
  385. package/dist/pipeline/dispatch-context-helpers.js +58 -0
  386. package/dist/pipeline/dispatch-nested-write.d.ts +7 -0
  387. package/dist/pipeline/dispatch-nested-write.js +119 -0
  388. package/dist/pipeline/dispatch-query.js +10 -3
  389. package/dist/pipeline/dispatch-scope.js +4 -3
  390. package/dist/pipeline/dispatch-shared.d.ts +2 -6
  391. package/dist/pipeline/dispatch-shared.js +6 -38
  392. package/dist/pipeline/dispatch-write.d.ts +0 -1
  393. package/dist/pipeline/dispatch-write.js +3 -302
  394. package/dist/pipeline/dispatcher-utils.js +6 -0
  395. package/dist/pipeline/effective-system-scope.d.ts +3 -0
  396. package/dist/pipeline/effective-system-scope.js +22 -0
  397. package/dist/pipeline/event-dispatcher-delivery.d.ts +1 -0
  398. package/dist/pipeline/event-dispatcher-delivery.js +20 -9
  399. package/dist/pipeline/event-dispatcher.d.ts +6 -1
  400. package/dist/pipeline/event-dispatcher.js +6 -7
  401. package/dist/pipeline/handler-context-auth.d.ts +3 -2
  402. package/dist/pipeline/handler-context-auth.js +3 -4
  403. package/dist/pipeline/handler-context-db.js +11 -4
  404. package/dist/pipeline/handler-context-dispatch.js +2 -2
  405. package/dist/pipeline/handler-context-events.d.ts +8 -3
  406. package/dist/pipeline/handler-context-events.js +20 -65
  407. package/dist/pipeline/handler-context-member-resolution.js +16 -8
  408. package/dist/pipeline/handler-context-notify.d.ts +1 -0
  409. package/dist/pipeline/handler-context-notify.js +2 -0
  410. package/dist/pipeline/handler-context-phase-denials.js +3 -2
  411. package/dist/pipeline/handler-context-projection.d.ts +3 -0
  412. package/dist/pipeline/handler-context-projection.js +39 -0
  413. package/dist/pipeline/handler-context-scope.d.ts +1 -1
  414. package/dist/pipeline/handler-context-scope.js +14 -2
  415. package/dist/pipeline/index.d.ts +1 -1
  416. package/dist/pipeline/index.js +1 -1
  417. package/dist/pipeline/irreversible-operation-gate.js +36 -10
  418. package/dist/pipeline/lifecycle-pipeline.d.ts +1 -0
  419. package/dist/pipeline/lifecycle-pipeline.js +7 -4
  420. package/dist/pipeline/member-reader.js +4 -2
  421. package/dist/pipeline/msp-rebuild.js +1 -1
  422. package/dist/pipeline/nested-write-parent-guard.d.ts +5 -0
  423. package/dist/pipeline/nested-write-parent-guard.js +81 -0
  424. package/dist/pipeline/projection-rebuild.d.ts +2 -0
  425. package/dist/pipeline/projection-rebuild.js +16 -7
  426. package/dist/pipeline/projection-state.js +4 -6
  427. package/dist/pipeline/system-hooks.js +36 -6
  428. package/dist/pipeline/write-result-masking.js +31 -3
  429. package/dist/pipeline/write-transition-guard.d.ts +7 -0
  430. package/dist/pipeline/write-transition-guard.js +95 -0
  431. package/dist/schema-cli/shared.d.ts +2 -0
  432. package/dist/schema-cli/shared.js +4 -2
  433. package/dist/schema-cli/validate-command.js +43 -28
  434. package/dist/search/meilisearch-adapter-internals.d.ts +2 -0
  435. package/dist/search/meilisearch-adapter-internals.js +5 -0
  436. package/dist/search/meilisearch-adapter.d.ts +1 -0
  437. package/dist/search/meilisearch-adapter.js +17 -11
  438. package/dist/search/reindex-entity.d.ts +2 -0
  439. package/dist/search/reindex-entity.js +32 -4
  440. package/dist/search/reindex-tenants-search.js +20 -4
  441. package/dist/time/tz-context.js +1 -1
  442. package/dist/ui-types/card-column-roles.d.ts +6 -0
  443. package/dist/ui-types/card-column-roles.js +21 -3
  444. package/dist/ui-types/index.d.ts +3 -3
  445. package/dist/ui-types/index.js +2 -2
  446. package/dist/utils/ids.js +0 -1
  447. package/dist/utils/index.d.ts +1 -0
  448. package/dist/utils/index.js +1 -0
  449. package/dist/utils/return-path-limit.d.ts +1 -0
  450. package/dist/utils/return-path-limit.js +1 -0
  451. package/package.json +5 -3
  452. package/presets/biome-app.json +39 -21
  453. package/presets/biome-plugins/admin-api.grit +10 -0
  454. package/presets/biome-plugins/error-reasons.grit +53 -0
  455. package/presets/biome-plugins/es-literal-writes-tests.grit +18 -0
  456. package/presets/biome-plugins/es-literal-writes.grit +22 -0
  457. package/presets/biome-plugins/i18n-locale-terminology-de.grit +15 -0
  458. package/presets/biome-plugins/i18n-locale-terminology-romance.grit +10 -0
  459. package/presets/biome-plugins/no-create-test-dispatcher.grit +5 -0
  460. package/presets/biome-plugins/no-css-properties-type.grit +7 -0
  461. package/presets/biome-plugins/no-date-api.grit +11 -0
  462. package/presets/biome-plugins/no-direct-fetch.grit +16 -0
  463. package/presets/biome-plugins/no-direct-fs.grit +16 -0
  464. package/presets/biome-plugins/no-external-font-cdn-css.grit +9 -0
  465. package/presets/biome-plugins/no-external-font-cdn.grit +12 -0
  466. package/presets/biome-plugins/no-raw-hooks.grit +10 -0
  467. package/presets/biome-plugins/no-same-folder-barrel-import.grit +11 -0
  468. package/presets/biome-plugins/no-screen-container-classes.grit +7 -0
  469. package/presets/biome-plugins/no-skipped-or-retried-tests.grit +34 -0
  470. package/presets/biome-plugins/no-temporal-polyfill-require.grit +10 -0
  471. package/presets/biome-plugins/raw-html-in-web.grit +40 -0
  472. package/presets/biome-plugins/raw-ui-in-app.grit +142 -0
  473. package/presets/biome-plugins/restricted-event-store-symbols.grit +18 -0
  474. package/presets/biome-plugins/test-title.grit +20 -0
  475. package/presets/biome-plugins/unsafe-json-parse.grit +12 -0
  476. package/presets/biome-rules.json +467 -0
  477. package/src/changes.json +366 -0
  478. package/dist/engine/minor-units.d.ts +0 -2
  479. package/dist/engine/minor-units.js +0 -8
@@ -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
@@ -347,6 +350,9 @@ function buildConsumerRequestScope(consumer, causationSource) {
347
350
  handler: consumer.name,
348
351
  feature: consumer.featureName ?? qnScope(consumer.name),
349
352
  writeOrigin,
353
+ ...(consumer.irreversibleWithoutEntryHandler && {
354
+ irreversibleWithoutEntryHandler: consumer.irreversibleWithoutEntryHandler,
355
+ }),
350
356
  };
351
357
  }
352
358
  async function applyEvent(consumer, row, context) {
@@ -357,17 +363,22 @@ async function applyEvent(consumer, row, context) {
357
363
  }
358
364
  async function tryApplyBatch(consumer, events, context) {
359
365
  const held = new Set();
360
- let heldReason = null;
366
+ const heldReasons = new Map();
367
+ let anyHoldAfterAttempt = false;
361
368
  const turn = {
362
- holdForRetry: (eventIds, reason) => {
363
- for (const id of eventIds)
369
+ holdForRetry: (eventIds, reason, options) => {
370
+ for (const id of eventIds) {
364
371
  held.add(id);
365
- heldReason ??= reason;
372
+ if (!heldReasons.has(id))
373
+ heldReasons.set(id, reason);
374
+ }
375
+ if (options?.stillBackingOff !== true)
376
+ anyHoldAfterAttempt = true;
366
377
  },
367
378
  };
368
379
  try {
369
380
  await applyBatch(consumer, events, context, turn);
370
- return { applied: true, held, heldReason };
381
+ return { applied: true, held, heldReasons, anyHoldAfterAttempt };
371
382
  }
372
383
  catch (e) {
373
384
  const errMessage = e instanceof Error ? e.message : String(e);
@@ -1,3 +1,4 @@
1
+ import type { IrreversibleWithoutEntryHandler } from "@cosmicdrift/kumiko-types/config";
1
2
  import type { Meter, Tracer } from "@cosmicdrift/kumiko-types/observability";
2
3
  import type { PgListenClient } from "../db/connection.ts";
3
4
  import type { AppContext } from "../engine/types/index.ts";
@@ -5,7 +6,9 @@ import type { StoredEvent } from "../event-store/index.ts";
5
6
  export type EventConsumerHandler = (event: StoredEvent, ctx: AppContext) => Promise<void>;
6
7
  export type EventConsumerBatchHandler = (events: readonly StoredEvent[], ctx: AppContext, turn: BatchTurnControl) => Promise<void>;
7
8
  export type BatchTurnControl = {
8
- readonly holdForRetry: (eventIds: readonly string[], reason: string) => void;
9
+ readonly holdForRetry: (eventIds: readonly string[], reason: string, options?: {
10
+ readonly stillBackingOff?: boolean;
11
+ }) => void;
9
12
  };
10
13
  export type EventConsumerErrorPolicy = {
11
14
  readonly skipApplyErrors?: boolean;
@@ -20,6 +23,7 @@ export type EventConsumer = {
20
23
  readonly featureName?: string;
21
24
  readonly delivery?: "shared" | "per-instance";
22
25
  readonly startFrom?: "beginning" | "now";
26
+ readonly irreversibleWithoutEntryHandler?: IrreversibleWithoutEntryHandler;
23
27
  };
24
28
  export type DispatcherPassResult = {
25
29
  readonly processed: number;
@@ -53,6 +57,7 @@ export type EventDispatcherOptions = {
53
57
  readonly instanceId?: string;
54
58
  readonly pgClient?: PgListenClient;
55
59
  };
60
+ export declare const DEFAULT_BATCH_SIZE = 200;
56
61
  export declare function createEventDispatcher(options: EventDispatcherOptions): EventDispatcher;
57
62
  export type { ConsumerProgress, ConsumerRecoveryState, ConsumerTransitionRejection, } from "./event-dispatcher-admin.ts";
58
63
  export { ConsumerTransitionError, disableConsumer, enableConsumer, getAllConsumerProgress, getConsumerState, listConsumersWithState, restartConsumer, skipPoisonEvent, } from "./event-dispatcher-admin.ts";
@@ -1,3 +1,4 @@
1
+ import { BUN_SQL_CONNECTION_ERROR_CODES } from "../db/bun-sql-connection-codes.js";
1
2
  import { extractPgError } from "../db/pg-error.js";
2
3
  import { recordConsumerPassFailure, selectSnapshotXmax, selectSnapshotXmin, } from "../db/queries/event-consumer.js";
3
4
  import { assertNoActiveRowLevelSecurityScope, runInSystemRowLevelSecurityScope, } from "../db/row-level-security-scope.js";
@@ -9,7 +10,7 @@ import { emitEventConsumerPassOutcome, emitEventConsumerPassSkipped, emitEventCo
9
10
  import { SHARED_INSTANCE_SENTINEL } from "./event-consumer-state.js";
10
11
  import { acquireConsumerState, consumerInstanceId, deliverConsumerTurn, emitLagFromTx, fetchPendingEvents, markProcessing, pendingFetchLimit, persistConsumerOutcome, preRegisterConsumers, selectIdleConsumerKeys, } from "./event-dispatcher-delivery.js";
11
12
  import { mergeContiguousGapRanges, partitionBurntGaps, splitRangeExcludingIds, toIdRanges, } from "./pending-gap-ranges.js";
12
- const DEFAULT_BATCH_SIZE = 200;
13
+ export const DEFAULT_BATCH_SIZE = 200;
13
14
  const DEFAULT_POLL_MS = 100;
14
15
  const DEFAULT_MAX_ATTEMPTS = 10;
15
16
  const DEFAULT_REARM_COOLDOWN_MS = 5 * 60_000;
@@ -17,12 +18,10 @@ const DEFAULT_MAX_REARM_COUNT = 3;
17
18
  const PENDING_GAPS_WARN_THRESHOLD = 1000;
18
19
  const DEFAULT_MAX_PENDING_GAP_RANGES = 2 * PENDING_GAPS_WARN_THRESHOLD;
19
20
  // Only these say the database socket itself is gone; timeouts, schema or pool errors do not
20
- // imply the dedicated LISTEN connection dropped.
21
+ // imply the dedicated LISTEN connection dropped. Raw socket codes (ECONNRESET, ...) are not
22
+ // counted: the driver reports a lost connection as ERR_POSTGRES_CONNECTION_*.
21
23
  const CONNECTION_LOSS_CODES = new Set([
22
- "ERR_POSTGRES_CONNECTION_CLOSED",
23
- "ERR_POSTGRES_CONNECTION_REFUSED",
24
- "ERR_POSTGRES_CONNECTION_TIMEOUT",
25
- "ERR_POSTGRES_CONNECTION_FAILED",
24
+ ...BUN_SQL_CONNECTION_ERROR_CODES,
26
25
  "57P01",
27
26
  ]);
28
27
  function isConnectionLossError(e) {
@@ -150,7 +149,7 @@ export function createEventDispatcher(options) {
150
149
  async function runConsumerTurn(consumer, effective, idleKeys) {
151
150
  const key = `${consumer.name}:${consumerInstanceId(consumer, options.instanceId)}`;
152
151
  const existing = inFlightTurns.get(key);
153
- if (existing)
152
+ if (existing !== undefined)
154
153
  return existing;
155
154
  // Feature-gate, backoff-gate and idle-gate are resolved synchronously,
156
155
  // before any promise is registered — a gated consumer must resolve
@@ -1,7 +1,8 @@
1
1
  import type { MemberReader } from "@cosmicdrift/kumiko-types/handlers";
2
- import type { HandlerAuth } from "../engine/types/index.ts";
2
+ import type { HandlerAuth, SessionUser } from "../engine/types/index.ts";
3
3
  import type { HandlerContextScope } from "./handler-context-scope.ts";
4
- export declare function buildAuthFacet(scope: HandlerContextScope): {
4
+ export type ResolveAuthClaimsFn = (ctx: HandlerContextScope["ctx"], user: SessionUser) => Promise<Record<string, unknown>>;
5
+ export declare function buildAuthFacet(scope: HandlerContextScope, resolveAuthClaimsFn: ResolveAuthClaimsFn): {
5
6
  readonly auth: HandlerAuth;
6
7
  readonly queryAsMember: MemberReader;
7
8
  readonly hasFeature: (featureName: string) => Promise<boolean>;
@@ -1,8 +1,7 @@
1
1
  import { INTERACTIVE_SIGN_IN_POLICY, resolveActiveMembershipFn } from "./active-membership.js";
2
- import { resolveAuthClaimsFn } from "./dispatch-shared.js";
3
2
  import { createMemberReaderFn } from "./member-reader.js";
4
3
  import { createGatedMemberReader, systemIdentitySwitchDenied } from "./system-identity-switch.js";
5
- export function buildAuthFacet(scope) {
4
+ export function buildAuthFacet(scope, resolveAuthClaimsFn) {
6
5
  const { ctx, type, user, tx, hasIdentitySwitchGrant, identitySwitchAudit } = scope;
7
6
  const { effectiveFeatures } = ctx;
8
7
  // Lazy — creates the reader (which fails closed on SYSTEM_TENANT_ID) only
@@ -17,7 +16,7 @@ export function buildAuthFacet(scope) {
17
16
  // handler surface just forwards the call so both entry points (login
18
17
  // handler via ctx.auth.resolveClaims, switch-tenant route via
19
18
  // dispatcher.resolveAuthClaims) cannot drift.
20
- resolveClaims: (claimsUser) => resolveAuthClaimsFn(ctx, claimsUser), // @wrapper-known semantic-alias
19
+ resolveClaims: (claimsUser) => resolveAuthClaimsFn(ctx, claimsUser),
21
20
  // Thin pass-through, same reasoning as resolveClaims above — one
22
21
  // resolve impl lives on the dispatcher so callers can't drift apart.
23
22
  // Internally queries memberships as SYSTEM, so it needs the same grant
@@ -25,7 +24,7 @@ export function buildAuthFacet(scope) {
25
24
  resolveActiveMembership: (userId, tenantId) => {
26
25
  if (!hasIdentitySwitchGrant)
27
26
  throw systemIdentitySwitchDenied(`handler "${type}"`);
28
- return resolveActiveMembershipFn(ctx, userId, tenantId, INTERACTIVE_SIGN_IN_POLICY); // @wrapper-known semantic-alias
27
+ return resolveActiveMembershipFn(ctx, userId, tenantId, INTERACTIVE_SIGN_IN_POLICY);
29
28
  },
30
29
  };
31
30
  return {
@@ -1,16 +1,19 @@
1
1
  import { crossTenantReadsGrantFor, escapeHatchFor } from "@cosmicdrift/kumiko-types/handlers";
2
2
  import { isAgentToolCallScope } from "../api/request-context-scopes.js";
3
3
  import { createHandlerCrossTenantReads } from "../db/cross-tenant-reads.js";
4
- import { createTenantDb, createUncheckedSystemDb } from "../db/tenant-db.js";
4
+ import { createSystemDbView, createTenantDb, createUncheckedSystemDb, } from "../db/tenant-db.js";
5
5
  import { createDerivativesContext } from "../derivatives/derivatives-context.js";
6
6
  import { mayOverrideTenant } from "../engine/cross-tenant.js";
7
7
  import { AccessDeniedError, FrameworkReasons } from "../errors/index.js";
8
8
  import { createTenantFileContext } from "../files/file-handle.js";
9
9
  import { attachOutsideTransaction } from "./attach-outside-transaction.js";
10
- import { createSystemScopedDbGuard, isMemberResolutionPrincipal, resolveAppPoolDb, } from "./dispatch-shared.js";
10
+ import { createSystemScopedDbGuard, isMemberResolutionPrincipal, resolveAppPoolDb, } from "./dispatch-context-helpers.js";
11
11
  import { buildPersonalDataGate } from "./write-origin.js";
12
12
  export function buildTenantScopedDb(scope, source, signal, foreignTenantId, denyWrites = false) {
13
13
  const { user, context, registry, origin, isSystem, writeEscapeHatch, handlerEscapeHatch } = scope;
14
+ // An agent tool call feeds the LLM context with the user's session: raw SQL and global writes
15
+ // would bypass the tenant and read filtering the tool result relies on.
16
+ const grantsEscapeHatches = foreignTenantId === undefined && !isAgentToolCallScope();
14
17
  const options = {
15
18
  db: source,
16
19
  tenantId: foreignTenantId ?? user.tenantId,
@@ -18,7 +21,7 @@ export function buildTenantScopedDb(scope, source, signal, foreignTenantId, deny
18
21
  meter: context.meter,
19
22
  signal,
20
23
  grants: {
21
- ...(foreignTenantId === undefined && {
24
+ ...(grantsEscapeHatches && {
22
25
  globalWrites: escapeHatchFor(writeEscapeHatch, "globalWrites"),
23
26
  unsafeRaw: escapeHatchFor(handlerEscapeHatch, "unsafeRaw"),
24
27
  }),
@@ -80,8 +83,12 @@ export function buildHandlerDbFacet(scope) {
80
83
  const rawDbOutsideTransaction = outsideTxSource
81
84
  ? buildTenantScopedDb(scope, outsideTxSource, undefined)
82
85
  : undefined;
86
+ // A resolved member gets the view: its unsafeRaw follows db's memberReadOnly denial and it has no
87
+ // outside-transaction source, whereas the unchecked variant would hand out a raw runner.
83
88
  const systemDb = isSystem && db
84
- ? createUncheckedSystemDb(db, rawDbOutsideTransaction, scope.reportEscapeHatch)
89
+ ? isMemberResolutionPrincipal(scope.user)
90
+ ? createSystemDbView(db, undefined, scope.reportEscapeHatch)
91
+ : createUncheckedSystemDb(db, rawDbOutsideTransaction, scope.reportEscapeHatch)
85
92
  : undefined;
86
93
  const crossTenantReads = buildHandlerCrossTenantReads(scope);
87
94
  // Same fail-closed treatment as `exposedDb` — a system handler reaching
@@ -81,13 +81,13 @@ export function buildDispatchFacet(scope, sinks, readers) {
81
81
  : unwrapSingle(await runBatch(ctx, [{ type: targetType, payload }], asUser, undefined, origin));
82
82
  const identitySwitch = createGatedIdentitySwitch(`handler "${type}"`, user, hasIdentitySwitchGrant, {
83
83
  // Inherits the caller's origin, so switching to SYSTEM cannot shed an anonymous root.
84
- queryAs: (asUser, targetType, payload) => executeQuery(ctx, targetType, payload, asUser, origin, tx, sinks.notifyCommitSink), // @wrapper-known semantic-alias
84
+ queryAs: (asUser, targetType, payload) => executeQuery(ctx, targetType, payload, asUser, origin, tx, sinks.notifyCommitSink),
85
85
  writeAs: writeAsUser,
86
86
  }, identitySwitchAudit);
87
87
  return {
88
88
  dispatch: {
89
89
  ...readers,
90
- query: (targetType, payload) => executeQuery(ctx, targetType, payload, user, origin, tx, sinks.notifyCommitSink), // @wrapper-known semantic-alias
90
+ query: (targetType, payload) => executeQuery(ctx, targetType, payload, user, origin, tx, sinks.notifyCommitSink),
91
91
  queryAs: identitySwitch.queryAs,
92
92
  write: (targetType, payload) => writeAsUser(user, targetType, payload),
93
93
  writeAs: identitySwitch.writeAs,