@cosmicdrift/kumiko-framework 0.413.1 → 0.414.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (463) hide show
  1. package/AGENTS.md +5 -2
  2. package/agents/api/framework-db.md +14 -3
  3. package/agents/api/framework-engine.md +63 -13
  4. package/agents/api/framework-event-store.md +14 -0
  5. package/agents/api/framework-ui-types.md +149 -21
  6. package/agents/api/renderer-web.md +93 -9
  7. package/agents/api/testing-helpers.md +3 -2
  8. package/agents/api/testing-stack.md +3 -0
  9. package/agents/api/types.md +205 -14
  10. package/agents/api.md +7 -7
  11. package/agents/boot-rules.md +63 -9
  12. package/agents/examples/api-docs.md +2 -6
  13. package/agents/examples/auth-mfa.md +57 -10
  14. package/agents/examples/chat-channels.md +2 -0
  15. package/agents/examples/currencies-global.md +1 -0
  16. package/agents/examples/env-composition.md +7 -11
  17. package/agents/examples/managed-pages.md +90 -1
  18. package/agents/examples/pwa-shell.md +210 -0
  19. package/agents/examples/rate-limiting.md +3 -3
  20. package/agents/examples/record-detail-layout.md +1537 -67
  21. package/agents/examples/workflow-engine.md +16 -12
  22. package/agents/examples.md +1 -0
  23. package/agents/features-index.md +4 -2
  24. package/agents/features.md +22 -7
  25. package/agents/widgets.md +19 -1
  26. package/dist/api/api-constants.d.ts +1 -0
  27. package/dist/api/api-constants.js +4 -0
  28. package/dist/api/auth-middleware.js +4 -3
  29. package/dist/api/auth-routes-shared.js +2 -1
  30. package/dist/api/entity-read-access.d.ts +1 -0
  31. package/dist/api/entity-read-access.js +18 -0
  32. package/dist/api/export/export-route.d.ts +6 -1
  33. package/dist/api/export/export-route.js +27 -1
  34. package/dist/api/export/export-rows.js +19 -3
  35. package/dist/api/routes.d.ts +2 -0
  36. package/dist/api/routes.js +9 -1
  37. package/dist/api/server-extra-routes.js +2 -1
  38. package/dist/api/server-feature-http-routes.d.ts +9 -0
  39. package/dist/api/server-feature-http-routes.js +109 -0
  40. package/dist/api/server-middleware.js +2 -19
  41. package/dist/api/server-pat-rate-limit-guard.d.ts +3 -0
  42. package/dist/api/server-pat-rate-limit-guard.js +19 -0
  43. package/dist/api/server-rate-limit-wiring.d.ts +10 -0
  44. package/dist/api/server-rate-limit-wiring.js +37 -0
  45. package/dist/api/server-routes.d.ts +4 -12
  46. package/dist/api/server-routes.js +12 -171
  47. package/dist/api/server-schema-route.d.ts +3 -0
  48. package/dist/api/server-schema-route.js +58 -0
  49. package/dist/api/server-wiring.js +2 -37
  50. package/dist/api/server.js +3 -1
  51. package/dist/compliance/override-schema.js +5 -5
  52. package/dist/compliance/sub-processors.js +10 -1
  53. package/dist/crypto/index.d.ts +1 -1
  54. package/dist/crypto/index.js +1 -1
  55. package/dist/crypto/pii-field-encryption.d.ts +2 -0
  56. package/dist/crypto/pii-field-encryption.js +16 -1
  57. package/dist/db/apply-entity-event.js +4 -0
  58. package/dist/db/bun-sql-connection-codes.d.ts +1 -0
  59. package/dist/db/bun-sql-connection-codes.js +7 -0
  60. package/dist/db/collect-table-metas.js +4 -1
  61. package/dist/db/config-seed.js +1 -1
  62. package/dist/db/derived-field-sql.js +15 -13
  63. package/dist/db/derived-related-sql.d.ts +2 -2
  64. package/dist/db/derived-related-sql.js +4 -2
  65. package/dist/db/dialect.d.ts +3 -0
  66. package/dist/db/dialect.js +1 -3
  67. package/dist/db/driver-row-coercion.js +2 -2
  68. package/dist/db/driver-value-preparation.js +1 -1
  69. package/dist/db/eagerload.js +15 -12
  70. package/dist/db/entity-table-meta.d.ts +2 -0
  71. package/dist/db/entity-table-meta.js +7 -0
  72. package/dist/db/event-store-executor-context.js +13 -8
  73. package/dist/db/event-store-executor-read-aggregate-currencies.js +2 -2
  74. package/dist/db/event-store-executor-read-aggregate.js +2 -2
  75. package/dist/db/event-store-executor-read-filter.d.ts +4 -0
  76. package/dist/db/event-store-executor-read-filter.js +28 -11
  77. package/dist/db/event-store-executor-read-search.d.ts +1 -0
  78. package/dist/db/event-store-executor-read-search.js +6 -6
  79. package/dist/db/event-store-executor-read-sort.js +3 -3
  80. package/dist/db/event-store-executor-read-where.js +14 -5
  81. package/dist/db/event-store-executor-read.js +7 -7
  82. package/dist/db/event-store-executor-write.js +50 -95
  83. package/dist/db/executor-managed-tables.js +4 -1
  84. package/dist/db/index.d.ts +4 -2
  85. package/dist/db/index.js +4 -2
  86. package/dist/db/known-table-names.d.ts +1 -0
  87. package/dist/db/known-table-names.js +7 -5
  88. package/dist/db/list-aggregate-labels.d.ts +1 -0
  89. package/dist/db/list-aggregate-labels.js +9 -1
  90. package/dist/db/migrate-generator.js +23 -4
  91. package/dist/db/migrate-rls-diff.d.ts +1 -0
  92. package/dist/db/migrate-rls-diff.js +15 -1
  93. package/dist/db/migrate-runner.js +2 -2
  94. package/dist/db/money.d.ts +1 -1
  95. package/dist/db/money.js +1 -4
  96. package/dist/db/parent-ref-clause.d.ts +6 -2
  97. package/dist/db/parent-ref-clause.js +76 -23
  98. package/dist/db/parent-ref-global-hosts.d.ts +20 -0
  99. package/dist/db/parent-ref-global-hosts.js +47 -0
  100. package/dist/db/production-schema-command-hint.d.ts +1 -0
  101. package/dist/db/production-schema-command-hint.js +3 -0
  102. package/dist/db/queries/backfill-pii.js +55 -29
  103. package/dist/db/queries/ddl.js +13 -2
  104. package/dist/db/queries/event-store-open-streams.d.ts +15 -0
  105. package/dist/db/queries/event-store-open-streams.js +33 -0
  106. package/dist/db/queries/event-store-payload-scrub.d.ts +5 -0
  107. package/dist/db/queries/event-store-payload-scrub.js +11 -0
  108. package/dist/db/queries/event-store.js +0 -1
  109. package/dist/db/queries/raw-sql.js +0 -1
  110. package/dist/db/queries/rebuild-rls-guard.d.ts +2 -1
  111. package/dist/db/queries/rebuild-rls-guard.js +24 -11
  112. package/dist/db/queries/rls-boot-catalog.d.ts +1 -0
  113. package/dist/db/queries/rls-boot-catalog.js +13 -8
  114. package/dist/db/queries/rls-shape.d.ts +2 -1
  115. package/dist/db/queries/rls-shape.js +10 -0
  116. package/dist/db/queries/session-advisory-lock.js +2 -1
  117. package/dist/db/queries/test-stack.js +7 -7
  118. package/dist/db/query.js +16 -11
  119. package/dist/db/rebuild-marker.js +11 -2
  120. package/dist/db/render-rls-ddl.d.ts +2 -0
  121. package/dist/db/render-rls-ddl.js +16 -11
  122. package/dist/db/replay-migration-sql.js +1 -1
  123. package/dist/db/row-level-security-boot-check.js +18 -5
  124. package/dist/db/row-level-security-connection.js +25 -12
  125. package/dist/db/row-level-security-scope.d.ts +2 -1
  126. package/dist/db/row-level-security-scope.js +9 -5
  127. package/dist/db/sql-identifier.d.ts +1 -0
  128. package/dist/db/sql-identifier.js +3 -0
  129. package/dist/db/system-tenant-read-db.d.ts +5 -0
  130. package/dist/db/system-tenant-read-db.js +28 -0
  131. package/dist/db/table-builder.d.ts +3 -1
  132. package/dist/db/table-builder.js +18 -8
  133. package/dist/db/table-info.d.ts +1 -2
  134. package/dist/db/table-introspection.d.ts +3 -0
  135. package/dist/db/table-introspection.js +6 -0
  136. package/dist/db/table-push.d.ts +1 -0
  137. package/dist/db/table-push.js +7 -1
  138. package/dist/db/tenant-db-runner.d.ts +3 -0
  139. package/dist/db/tenant-db-runner.js +19 -1
  140. package/dist/db/transaction-serialization.d.ts +1 -0
  141. package/dist/db/transaction-serialization.js +20 -3
  142. package/dist/db/where-clause.js +11 -2
  143. package/dist/db/write-ownership-failures.d.ts +25 -0
  144. package/dist/db/write-ownership-failures.js +82 -0
  145. package/dist/engine/boot-validator/boot-check.js +7 -1
  146. package/dist/engine/boot-validator/boot-phases-app.js +5 -5
  147. package/dist/engine/boot-validator/boot-phases.js +3 -2
  148. package/dist/engine/boot-validator/boot-rules.d.ts +293 -26
  149. package/dist/engine/boot-validator/boot-rules.js +4 -0
  150. package/dist/engine/boot-validator/bundled-lists-table.js +2 -2
  151. package/dist/engine/boot-validator/card-meta-overflow.js +1 -0
  152. package/dist/engine/boot-validator/config-deps.d.ts +0 -1
  153. package/dist/engine/boot-validator/config-deps.js +0 -28
  154. package/dist/engine/boot-validator/config-key-rules.d.ts +0 -15
  155. package/dist/engine/boot-validator/config-key-rules.js +0 -15
  156. package/dist/engine/boot-validator/dashboard-screen-target.d.ts +22 -0
  157. package/dist/engine/boot-validator/dashboard-screen-target.js +20 -0
  158. package/dist/engine/boot-validator/dashboard-stat-navigate.d.ts +1 -0
  159. package/dist/engine/boot-validator/dashboard-stat-navigate.js +25 -17
  160. package/dist/engine/boot-validator/definition-webhook-events-rules.d.ts +5 -0
  161. package/dist/engine/boot-validator/definition-webhook-events-rules.js +5 -0
  162. package/dist/engine/boot-validator/derived-sql-fields.js +1 -2
  163. package/dist/engine/boot-validator/entity-declaration-rules.d.ts +5 -0
  164. package/dist/engine/boot-validator/entity-declaration-rules.js +5 -0
  165. package/dist/engine/boot-validator/entity-list-screens.d.ts +1 -0
  166. package/dist/engine/boot-validator/entity-list-screens.js +33 -6
  167. package/dist/engine/boot-validator/entity-structure-rules.d.ts +5 -0
  168. package/dist/engine/boot-validator/entity-structure-rules.js +5 -0
  169. package/dist/engine/boot-validator/list-column-layout.js +10 -6
  170. package/dist/engine/boot-validator/list-row-guidance-rules.d.ts +67 -0
  171. package/dist/engine/boot-validator/list-row-guidance-rules.js +67 -0
  172. package/dist/engine/boot-validator/list-row-guidance.d.ts +20 -0
  173. package/dist/engine/boot-validator/list-row-guidance.js +129 -0
  174. package/dist/engine/boot-validator/list-sort-summary-rules.d.ts +42 -0
  175. package/dist/engine/boot-validator/list-sort-summary-rules.js +42 -0
  176. package/dist/engine/boot-validator/list-sort-summary.d.ts +5 -0
  177. package/dist/engine/boot-validator/list-sort-summary.js +149 -0
  178. package/dist/engine/boot-validator/list-table-options.js +15 -1
  179. package/dist/engine/boot-validator/list-table-rules.d.ts +10 -5
  180. package/dist/engine/boot-validator/list-table-rules.js +10 -5
  181. package/dist/engine/boot-validator/list-toolbar-options.d.ts +10 -0
  182. package/dist/engine/boot-validator/list-toolbar-options.js +31 -0
  183. package/dist/engine/boot-validator/named-filter-rules.d.ts +32 -2
  184. package/dist/engine/boot-validator/named-filter-rules.js +32 -2
  185. package/dist/engine/boot-validator/ownership.js +10 -1
  186. package/dist/engine/boot-validator/parent-ref.js +87 -50
  187. package/dist/engine/boot-validator/projection-list-screens.d.ts +1 -0
  188. package/dist/engine/boot-validator/projection-list-screens.js +31 -1
  189. package/dist/engine/boot-validator/query-output-columns.js +62 -9
  190. package/dist/engine/boot-validator/query-output-guidance.d.ts +7 -0
  191. package/dist/engine/boot-validator/query-output-guidance.js +39 -0
  192. package/dist/engine/boot-validator/query-refs.js +24 -1
  193. package/dist/engine/boot-validator/row-decoration.d.ts +11 -0
  194. package/dist/engine/boot-validator/row-decoration.js +16 -0
  195. package/dist/engine/boot-validator/screens-dashboard-links.d.ts +10 -0
  196. package/dist/engine/boot-validator/screens-dashboard-links.js +36 -0
  197. package/dist/engine/boot-validator/screens-dashboard-narrow.d.ts +4 -0
  198. package/dist/engine/boot-validator/screens-dashboard-narrow.js +211 -0
  199. package/dist/engine/boot-validator/screens-dashboard-rules.d.ts +84 -4
  200. package/dist/engine/boot-validator/screens-dashboard-rules.js +84 -4
  201. package/dist/engine/boot-validator/screens-dashboard.js +29 -7
  202. package/dist/engine/boot-validator/screens-kind-entity-list.js +32 -27
  203. package/dist/engine/boot-validator/screens-kind-projection-detail-guidance.d.ts +3 -0
  204. package/dist/engine/boot-validator/screens-kind-projection-detail-guidance.js +46 -0
  205. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +20 -0
  206. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +20 -0
  207. package/dist/engine/boot-validator/screens-kind-projection-detail.js +2 -0
  208. package/dist/engine/boot-validator/screens-kind-projection-list.js +4 -0
  209. package/dist/engine/boot-validator/screens-kind-rules.d.ts +25 -0
  210. package/dist/engine/boot-validator/screens-kind-rules.js +25 -0
  211. package/dist/engine/boot-validator/screens-lists.d.ts +8 -2
  212. package/dist/engine/boot-validator/screens-lists.js +19 -3
  213. package/dist/engine/boot-validator/screens.js +1 -1
  214. package/dist/engine/boot-validator/sort-nulls.d.ts +2 -0
  215. package/dist/engine/boot-validator/sort-nulls.js +15 -0
  216. package/dist/engine/boot-validator/zod-shape.d.ts +2 -1
  217. package/dist/engine/boot-validator/zod-shape.js +19 -1
  218. package/dist/engine/build-app-schema.js +4 -0
  219. package/dist/engine/config-helpers.d.ts +1 -2
  220. package/dist/engine/config-helpers.js +6 -7
  221. package/dist/engine/define-feature.js +1 -0
  222. package/dist/engine/define-handler.d.ts +1 -0
  223. package/dist/engine/define-handler.js +4 -2
  224. package/dist/engine/definition-violations.js +2 -2
  225. package/dist/engine/entity-handlers.js +3 -8
  226. package/dist/engine/entity-list-runtime-options.js +9 -8
  227. package/dist/engine/factories.d.ts +2 -0
  228. package/dist/engine/feature-config-events-jobs.js +1 -0
  229. package/dist/engine/feature-entity-handlers.js +5 -2
  230. package/dist/engine/field-access.d.ts +1 -1
  231. package/dist/engine/field-access.js +7 -10
  232. package/dist/engine/find-entity.js +3 -3
  233. package/dist/engine/form-derivations.js +3 -3
  234. package/dist/engine/index.d.ts +3 -3
  235. package/dist/engine/index.js +2 -2
  236. package/dist/engine/named-filter-roles.d.ts +3 -0
  237. package/dist/engine/named-filter-roles.js +23 -0
  238. package/dist/engine/pipeline.js +0 -1
  239. package/dist/engine/project-app-schema-for-roles.js +17 -2
  240. package/dist/engine/qualified-name.js +0 -1
  241. package/dist/engine/registry-facade.js +1 -2
  242. package/dist/engine/registry-state.d.ts +1 -1
  243. package/dist/engine/registry-state.js +5 -2
  244. package/dist/engine/registry-validate.js +2 -1
  245. package/dist/engine/resolve-named-list-filters.js +5 -2
  246. package/dist/engine/schema-builder.js +6 -10
  247. package/dist/engine/screen-helpers.d.ts +12 -0
  248. package/dist/engine/screen-helpers.js +17 -1
  249. package/dist/engine/soft-delete-cleanup.js +1 -5
  250. package/dist/engine/state-machine.js +0 -1
  251. package/dist/engine/steps/_database-clock.d.ts +2 -0
  252. package/dist/engine/steps/_database-clock.js +6 -0
  253. package/dist/engine/steps/compute.js +1 -1
  254. package/dist/engine/steps/retry.js +5 -1
  255. package/dist/engine/steps/return.js +0 -1
  256. package/dist/engine/steps/wait-for-event.js +2 -1
  257. package/dist/engine/steps/wait.js +2 -1
  258. package/dist/engine/system-user.d.ts +2 -2
  259. package/dist/engine/system-user.js +2 -2
  260. package/dist/engine/types/handlers.d.ts +1 -1
  261. package/dist/engine/types/handlers.js +1 -1
  262. package/dist/engine/types/screen.d.ts +1 -1
  263. package/dist/engine/types/screen.js +1 -1
  264. package/dist/engine/webhook-contracts.d.ts +2 -3
  265. package/dist/engine/webhook-contracts.js +2 -25
  266. package/dist/engine/webhook-events.js +48 -29
  267. package/dist/engine/webhook-payload-strictness.d.ts +7 -0
  268. package/dist/engine/webhook-payload-strictness.js +53 -0
  269. package/dist/env/_zod-introspect.d.ts +1 -0
  270. package/dist/env/dry-run.d.ts +1 -1
  271. package/dist/env/dry-run.js +1 -1
  272. package/dist/env/field-meta.d.ts +4 -0
  273. package/dist/env/field-meta.js +67 -0
  274. package/dist/env/field-rules.d.ts +9 -0
  275. package/dist/env/field-rules.js +46 -0
  276. package/dist/env/index.d.ts +3 -3
  277. package/dist/env/index.js +16 -71
  278. package/dist/env/internals.d.ts +3 -0
  279. package/dist/env/internals.js +1 -2
  280. package/dist/env/required-env.d.ts +3 -1
  281. package/dist/env/required-env.js +5 -2
  282. package/dist/errors/serialize.js +2 -2
  283. package/dist/errors/write-error-info.js +0 -2
  284. package/dist/es-ops/operations-schema.js +18 -7
  285. package/dist/event-store/admin-api.js +3 -3
  286. package/dist/event-store/event-store.js +0 -3
  287. package/dist/event-store/index.d.ts +1 -0
  288. package/dist/event-store/index.js +1 -0
  289. package/dist/event-store/transfer.js +1 -1
  290. package/dist/files/assert-file-refs-belong-to-tenant.d.ts +2 -1
  291. package/dist/files/assert-file-refs-belong-to-tenant.js +15 -13
  292. package/dist/files/bind-pending-file-refs.d.ts +3 -1
  293. package/dist/files/bind-pending-file-refs.js +54 -27
  294. package/dist/files/copy-pending-file-refs-to-tenant.js +7 -3
  295. package/dist/files/create-file-ref.d.ts +4 -1
  296. package/dist/files/create-file-ref.js +14 -3
  297. package/dist/files/default-file-guard.js +4 -1
  298. package/dist/files/file-claim.d.ts +6 -0
  299. package/dist/files/file-claim.js +17 -0
  300. package/dist/files/file-field-slots.d.ts +2 -0
  301. package/dist/files/file-field-slots.js +28 -0
  302. package/dist/files/file-ref-entity.d.ts +3 -0
  303. package/dist/files/file-ref-entity.js +2 -0
  304. package/dist/files/file-ref-table.d.ts +3 -0
  305. package/dist/files/file-routes.d.ts +4 -1
  306. package/dist/files/file-routes.js +80 -16
  307. package/dist/files/in-memory-provider.d.ts +1 -1
  308. package/dist/files/in-memory-provider.js +2 -1
  309. package/dist/files/index.d.ts +1 -1
  310. package/dist/files/index.js +1 -1
  311. package/dist/files/invalid-file-ref-error.d.ts +2 -0
  312. package/dist/files/invalid-file-ref-error.js +15 -0
  313. package/dist/files/local-provider.js +9 -2
  314. package/dist/files/provider-resolver.js +1 -1
  315. package/dist/files/rebind-file-ref.d.ts +3 -2
  316. package/dist/files/rebind-file-ref.js +24 -18
  317. package/dist/files/resolve-file-handles.d.ts +13 -0
  318. package/dist/files/resolve-file-handles.js +57 -0
  319. package/dist/files/storage-tracking.d.ts +1 -1
  320. package/dist/files/storage-tracking.js +5 -2
  321. package/dist/files/sweep-stale-pending-file-refs.js +10 -4
  322. package/dist/files/types.d.ts +4 -0
  323. package/dist/files/types.js +10 -0
  324. package/dist/files/upload-field-resolution.d.ts +1 -0
  325. package/dist/files/upload-field-resolution.js +16 -2
  326. package/dist/files/upload-ledger.js +1 -1
  327. package/dist/i18n/required-surface-guidance-keys.d.ts +3 -0
  328. package/dist/i18n/required-surface-guidance-keys.js +9 -0
  329. package/dist/i18n/required-surface-keys.js +19 -4
  330. package/dist/internal/boot-rule-table-expectations.d.ts +2 -0
  331. package/dist/internal/boot-rule-table-expectations.js +29 -0
  332. package/dist/internal/row-level-security.d.ts +1 -0
  333. package/dist/internal/row-level-security.js +1 -0
  334. package/dist/internal/testing.d.ts +1 -0
  335. package/dist/internal/testing.js +1 -0
  336. package/dist/jobs/index.d.ts +1 -0
  337. package/dist/jobs/index.js +1 -0
  338. package/dist/jobs/job-load-events.d.ts +10 -0
  339. package/dist/jobs/job-load-events.js +12 -0
  340. package/dist/jobs/job-runner-context.js +6 -158
  341. package/dist/jobs/job-runner-dispatch.d.ts +7 -0
  342. package/dist/jobs/job-runner-dispatch.js +57 -0
  343. package/dist/jobs/job-runner-event-triggers.js +18 -9
  344. package/dist/jobs/job-runner-execution.js +2 -2
  345. package/dist/jobs/job-runner-facets.d.ts +48 -0
  346. package/dist/jobs/job-runner-facets.js +156 -0
  347. package/dist/jobs/job-runner-gates.js +19 -11
  348. package/dist/jobs/job-runner-helpers.d.ts +5 -1
  349. package/dist/jobs/job-runner-helpers.js +18 -3
  350. package/dist/jobs/job-runner-scope.d.ts +1 -0
  351. package/dist/jobs/job-runner-scope.js +2 -0
  352. package/dist/jobs/job-runner-tenant-cap-lock.d.ts +2 -0
  353. package/dist/jobs/job-runner-tenant-cap-lock.js +30 -0
  354. package/dist/jobs/job-runner.js +31 -70
  355. package/dist/jobs/obliterate-job-queues.d.ts +6 -0
  356. package/dist/jobs/obliterate-job-queues.js +23 -0
  357. package/dist/lifecycle/lifecycle.js +1 -1
  358. package/dist/migrations/event-header-scrub.d.ts +11 -0
  359. package/dist/migrations/event-header-scrub.js +33 -0
  360. package/dist/migrations/event-payload-scrub.d.ts +1 -1
  361. package/dist/migrations/event-payload-scrub.js +36 -4
  362. package/dist/migrations/index.d.ts +1 -0
  363. package/dist/migrations/index.js +2 -0
  364. package/dist/migrations/kumiko-drift.d.ts +5 -2
  365. package/dist/migrations/kumiko-drift.js +51 -14
  366. package/dist/migrations/pending-rebuilds.js +4 -5
  367. package/dist/observability/sensitive-filter.js +0 -12
  368. package/dist/pipeline/aggregate-type-removal.js +17 -4
  369. package/dist/pipeline/context-services.d.ts +2 -0
  370. package/dist/pipeline/context-services.js +5 -2
  371. package/dist/pipeline/dispatch-batch.js +4 -3
  372. package/dist/pipeline/dispatch-context-helpers.d.ts +11 -0
  373. package/dist/pipeline/dispatch-context-helpers.js +58 -0
  374. package/dist/pipeline/dispatch-nested-write.d.ts +7 -0
  375. package/dist/pipeline/dispatch-nested-write.js +119 -0
  376. package/dist/pipeline/dispatch-query.js +10 -3
  377. package/dist/pipeline/dispatch-scope.js +4 -3
  378. package/dist/pipeline/dispatch-shared.d.ts +2 -6
  379. package/dist/pipeline/dispatch-shared.js +6 -38
  380. package/dist/pipeline/dispatch-write.d.ts +0 -1
  381. package/dist/pipeline/dispatch-write.js +3 -302
  382. package/dist/pipeline/dispatcher-utils.js +6 -0
  383. package/dist/pipeline/effective-system-scope.d.ts +3 -0
  384. package/dist/pipeline/effective-system-scope.js +22 -0
  385. package/dist/pipeline/event-dispatcher-delivery.d.ts +1 -0
  386. package/dist/pipeline/event-dispatcher-delivery.js +17 -9
  387. package/dist/pipeline/event-dispatcher.d.ts +4 -1
  388. package/dist/pipeline/event-dispatcher.js +6 -7
  389. package/dist/pipeline/handler-context-auth.d.ts +3 -2
  390. package/dist/pipeline/handler-context-auth.js +3 -4
  391. package/dist/pipeline/handler-context-db.js +11 -4
  392. package/dist/pipeline/handler-context-dispatch.js +2 -2
  393. package/dist/pipeline/handler-context-events.d.ts +8 -3
  394. package/dist/pipeline/handler-context-events.js +20 -65
  395. package/dist/pipeline/handler-context-member-resolution.js +16 -8
  396. package/dist/pipeline/handler-context-notify.d.ts +1 -0
  397. package/dist/pipeline/handler-context-notify.js +2 -0
  398. package/dist/pipeline/handler-context-phase-denials.js +3 -2
  399. package/dist/pipeline/handler-context-projection.d.ts +3 -0
  400. package/dist/pipeline/handler-context-projection.js +39 -0
  401. package/dist/pipeline/handler-context-scope.d.ts +1 -1
  402. package/dist/pipeline/handler-context-scope.js +14 -2
  403. package/dist/pipeline/index.d.ts +1 -1
  404. package/dist/pipeline/index.js +1 -1
  405. package/dist/pipeline/lifecycle-pipeline.d.ts +1 -0
  406. package/dist/pipeline/lifecycle-pipeline.js +7 -4
  407. package/dist/pipeline/member-reader.js +4 -2
  408. package/dist/pipeline/msp-rebuild.js +1 -1
  409. package/dist/pipeline/nested-write-parent-guard.d.ts +5 -0
  410. package/dist/pipeline/nested-write-parent-guard.js +81 -0
  411. package/dist/pipeline/projection-rebuild.d.ts +2 -0
  412. package/dist/pipeline/projection-rebuild.js +16 -7
  413. package/dist/pipeline/projection-state.js +4 -6
  414. package/dist/pipeline/system-hooks.js +36 -6
  415. package/dist/pipeline/write-result-masking.js +31 -3
  416. package/dist/pipeline/write-transition-guard.d.ts +7 -0
  417. package/dist/pipeline/write-transition-guard.js +95 -0
  418. package/dist/schema-cli/shared.d.ts +2 -0
  419. package/dist/schema-cli/shared.js +4 -2
  420. package/dist/schema-cli/validate-command.js +43 -28
  421. package/dist/search/meilisearch-adapter.js +14 -9
  422. package/dist/search/reindex-entity.d.ts +2 -0
  423. package/dist/search/reindex-entity.js +32 -4
  424. package/dist/search/reindex-tenants-search.js +20 -4
  425. package/dist/time/tz-context.js +1 -1
  426. package/dist/ui-types/card-column-roles.d.ts +4 -0
  427. package/dist/ui-types/card-column-roles.js +6 -3
  428. package/dist/ui-types/index.d.ts +2 -2
  429. package/dist/ui-types/index.js +1 -1
  430. package/dist/utils/ids.js +0 -1
  431. package/dist/utils/index.d.ts +1 -0
  432. package/dist/utils/index.js +1 -0
  433. package/dist/utils/return-path-limit.d.ts +1 -0
  434. package/dist/utils/return-path-limit.js +1 -0
  435. package/package.json +5 -3
  436. package/presets/biome-app.json +39 -21
  437. package/presets/biome-plugins/admin-api.grit +10 -0
  438. package/presets/biome-plugins/error-reasons.grit +53 -0
  439. package/presets/biome-plugins/es-literal-writes-tests.grit +18 -0
  440. package/presets/biome-plugins/es-literal-writes.grit +22 -0
  441. package/presets/biome-plugins/i18n-locale-terminology-de.grit +15 -0
  442. package/presets/biome-plugins/i18n-locale-terminology-romance.grit +10 -0
  443. package/presets/biome-plugins/no-create-test-dispatcher.grit +5 -0
  444. package/presets/biome-plugins/no-css-properties-type.grit +7 -0
  445. package/presets/biome-plugins/no-date-api.grit +9 -0
  446. package/presets/biome-plugins/no-direct-fetch.grit +16 -0
  447. package/presets/biome-plugins/no-direct-fs.grit +16 -0
  448. package/presets/biome-plugins/no-external-font-cdn-css.grit +9 -0
  449. package/presets/biome-plugins/no-external-font-cdn.grit +12 -0
  450. package/presets/biome-plugins/no-raw-hooks.grit +10 -0
  451. package/presets/biome-plugins/no-same-folder-barrel-import.grit +11 -0
  452. package/presets/biome-plugins/no-screen-container-classes.grit +7 -0
  453. package/presets/biome-plugins/no-skipped-or-retried-tests.grit +34 -0
  454. package/presets/biome-plugins/no-temporal-polyfill-require.grit +10 -0
  455. package/presets/biome-plugins/raw-html-in-web.grit +40 -0
  456. package/presets/biome-plugins/raw-ui-in-app.grit +142 -0
  457. package/presets/biome-plugins/restricted-event-store-symbols.grit +18 -0
  458. package/presets/biome-plugins/test-title.grit +20 -0
  459. package/presets/biome-plugins/unsafe-json-parse.grit +6 -0
  460. package/presets/biome-rules.json +465 -0
  461. package/src/changes.json +309 -0
  462. package/dist/engine/minor-units.d.ts +0 -2
  463. package/dist/engine/minor-units.js +0 -8
@@ -1,20 +1,12 @@
1
1
  /// <reference types="temporal-polyfill/global" preserve="true" />
2
- import { crossTenantReadsGrantFor, escapeHatchFor } from "@cosmicdrift/kumiko-types/handlers";
3
- import { createCrossTenantReads } from "../db/cross-tenant-reads.js";
4
- import { createTenantDb, createUncheckedSystemDb } from "../db/tenant-db.js";
5
- import { createDerivativesContext } from "../derivatives/derivatives-context.js";
6
2
  import { createSystemUser } from "../engine/system-user.js";
7
- import { InternalError } from "../errors/index.js";
8
- import { createTenantFileContext } from "../files/file-handle.js";
9
- import { createEscapeHatchReporter } from "../observability/escape-hatch-report.js";
10
3
  import { createMetricsForFactory } from "../observability/index.js";
11
- import { configAccessorFactoryOf } from "../pipeline/config-accessor-factory.js";
12
4
  import { buildContextServices } from "../pipeline/context-services.js";
13
- import { createGatedIdentitySwitch } from "../pipeline/system-identity-switch.js";
14
- import { buildPersonalDataGate, parseWriteOrigin } from "../pipeline/write-origin.js";
15
- import { isScheduledTrigger } from "./cron-repeat-options.js";
5
+ import { parseWriteOrigin } from "../pipeline/write-origin.js";
16
6
  import { createJobAppendEvent } from "./job-append-event.js";
17
- import { attemptNumberOf, createJobLogger, handlerPayloadOf, hasDeferBudgetLeft, isFinalAttempt, isJobTriggerEvent, jobSubjectKey, missingDbProxy, tenantIdOfJobData, } from "./job-runner-helpers.js";
7
+ import { createJobLoadEvents } from "./job-load-events.js";
8
+ import { buildJobDbFacets, buildJobDispatchFacets, buildJobServiceFacets, createJobDefer, createJobEscapeHatchReporter, } from "./job-runner-facets.js";
9
+ import { attemptNumberOf, createJobLogger, handlerPayloadOf, hasDeferBudgetLeft, isFinalAttempt, isJobTriggerEvent, isQueuedRun, jobSubjectKey, missingDbProxy, tenantIdOfJobData, } from "./job-runner-helpers.js";
18
10
  // Tenant-visible failure record (JobDefinition.tenantVisibleFailure). The
19
11
  // subject is read from the handler payload, so it is resolved where the
20
12
  // payload is built, not in the callbacks.
@@ -54,149 +46,6 @@ function parseJobWriteOrigin(rawData, jobName) {
54
46
  return { writeOrigin: undefined, writeOriginInvalid: true };
55
47
  return { writeOrigin: { ...parsed, viaJob: jobName }, writeOriginInvalid: false };
56
48
  }
57
- function createJobEscapeHatchReporter(scope, input, systemUser) {
58
- const { jobName, jobDef, tenantId, triggeredById } = input;
59
- // One reporter for ctx.systemDb and ctx.db.unsafeRaw() so both dedupe in the same window.
60
- const isSystemCronRun = triggeredById === null &&
61
- jobDef.escapeHatch !== undefined &&
62
- isScheduledTrigger(jobDef.trigger);
63
- return createEscapeHatchReporter({
64
- handler: jobName,
65
- tenantId,
66
- actor: systemUser.id,
67
- sink: scope.context._escapeHatchAuditSink,
68
- log: scope.errorLogger,
69
- window: scope.escapeHatchReportWindow,
70
- ...(triggeredById !== null && { caller: triggeredById }),
71
- ...(isSystemCronRun && { processDedup: scope.systemCronEscapeHatchDedup }),
72
- ...(scope.context.meter && { meter: scope.context.meter }),
73
- });
74
- }
75
- function buildJobDbFacets(scope, facetInput) {
76
- const { context, registry } = scope;
77
- const { input, isSystemJob, reportEscapeHatch } = facetInput;
78
- const { jobDef, tenantId, writeOrigin } = input;
79
- const personalDataGate = writeOrigin ? buildPersonalDataGate(registry, writeOrigin) : undefined;
80
- const configDb = context.db; // @cast-boundary db-operator
81
- // Shared by the config accessor and ctx.services.derivatives below — both need the
82
- // same tenant-scoped db, and building it twice would let the two calls
83
- // drift apart. Always "system" mode regardless of the job's own
84
- // systemScope() status (pre-existing, not something this change alters)
85
- // — isSystemJob below is what actually keeps ctx.systemDb off a
86
- // non-system job; it is the only thing standing between this db and an
87
- // unchecked cross-tenant escape hatch for such a job. Gated like jobDb so
88
- // ctx.systemDb, built from it, is gated too.
89
- const tenantScopedDb = configDb
90
- ? createTenantDb({
91
- db: configDb,
92
- tenantId,
93
- mode: "system",
94
- reason: "job context db for cross-tenant jobs, ctx.systemDb exposure is gated by isSystemJob",
95
- grants: {
96
- projectionRegistry: registry,
97
- ...(personalDataGate && { personalDataGate }),
98
- },
99
- })
100
- : undefined;
101
- const systemDb = isSystemJob && tenantScopedDb
102
- ? createUncheckedSystemDb(tenantScopedDb, undefined, reportEscapeHatch)
103
- : undefined;
104
- const jobDb = configDb
105
- ? createTenantDb({
106
- db: configDb,
107
- tenantId,
108
- mode: "tenant",
109
- tracer: context.tracer,
110
- meter: context.meter,
111
- grants: {
112
- unsafeRaw: escapeHatchFor(jobDef.escapeHatch, "unsafeRaw"),
113
- globalWrites: escapeHatchFor(jobDef.escapeHatch, "globalWrites"),
114
- report: reportEscapeHatch,
115
- projectionRegistry: registry,
116
- ...(personalDataGate && { personalDataGate }),
117
- },
118
- })
119
- : undefined;
120
- const crossTenantReadsReason = crossTenantReadsGrantFor(jobDef.escapeHatch)?.reason;
121
- const crossTenantReads = tenantScopedDb && crossTenantReadsReason !== undefined
122
- ? createCrossTenantReads(tenantScopedDb, crossTenantReadsReason, reportEscapeHatch)
123
- : undefined;
124
- return { tenantScopedDb, jobDb, systemDb, crossTenantReads };
125
- }
126
- function buildJobServiceFacets(scope, facetInput, tenantScopedDb) {
127
- const { context, registry } = scope;
128
- const { input, systemUser } = facetInput;
129
- const { tenantId } = input;
130
- // Mirror dispatch-shared.ts buildHandlerContext: ctx.services.files must resolve
131
- // through the same _fileProviderResolver for jobs as for write-handlers,
132
- // otherwise event-triggered jobs silently get an unresolved ctx.services.files.
133
- const fileResolver = context._fileProviderResolver;
134
- const files = fileResolver ? createTenantFileContext(fileResolver, tenantId) : context.files;
135
- // Same buildHandlerContext parity as ctx.services.files above: ctx.notify/ctx.config
136
- // must resolve for jobs the same way they do for write-handlers, or an
137
- // app-author job calling ctx.notify(...)/ctx.config(...) hits a TypeError
138
- // at runtime the write-handler path never would.
139
- const notify = context._notifyFactory?.(systemUser, tenantId, scope.getSelfRunner(), undefined, context._fileProviderResolver);
140
- const configFactory = configAccessorFactoryOf(context);
141
- const config = configFactory && tenantScopedDb
142
- ? configFactory({
143
- user: { id: systemUser.id, tenantId },
144
- db: tenantScopedDb,
145
- secrets: context.secrets,
146
- })
147
- : undefined;
148
- // Mirror dispatch-shared.ts: ctx.services.derivatives needs files+db, same
149
- // tenant-scoped db the config accessor above uses.
150
- const derivatives = files && tenantScopedDb
151
- ? createDerivativesContext({ files, registry, db: tenantScopedDb, tenantId })
152
- : context.derivatives;
153
- return { files, notify, config, derivatives };
154
- }
155
- function requireDispatchRef(scope, method) {
156
- const ref = scope.getDispatchWriteRef();
157
- if (!ref) {
158
- throw new Error(`JobContext.${method} called before dispatcher attached — call attachDispatcher() first`);
159
- }
160
- return ref;
161
- }
162
- function buildJobDispatchFacets(scope, facetInput) {
163
- const { input, systemUser, isSystemJob, reportEscapeHatch } = facetInput;
164
- const { jobName, jobDef, tenantId, writeOrigin } = input;
165
- // Per-job-run reader, created lazily on queryAsMember's first call and
166
- // cached for the rest of this run.
167
- let memberReader;
168
- const identitySwitchHatch = escapeHatchFor(jobDef.escapeHatch, "systemIdentity");
169
- const identitySwitchGrantReason = identitySwitchHatch?.reason ??
170
- (isSystemJob ? `r.systemScope() feature of job "${jobName}"` : undefined);
171
- const gatedIdentitySwitch = createGatedIdentitySwitch(`job "${jobName}"`, systemUser, isSystemJob || identitySwitchHatch !== undefined, {
172
- queryAs: (user, qn, payload) => requireDispatchRef(scope, "queryAs").queryAs(user, qn, payload, writeOrigin),
173
- writeAs: async (user, qn, payload) => requireDispatchRef(scope, "writeAs").write(user, qn, payload, writeOrigin),
174
- }, { reason: identitySwitchGrantReason, report: reportEscapeHatch });
175
- return {
176
- write: (qn, payload) => requireDispatchRef(scope, "write").write(systemUser, qn, payload, writeOrigin),
177
- writeAs: gatedIdentitySwitch.writeAs,
178
- queryAs: gatedIdentitySwitch.queryAs,
179
- queryAsMember: (userId, qn, payload) => {
180
- const ref = requireDispatchRef(scope, "queryAsMember");
181
- // Lazy per-run reader, mirroring the handler-context reader.
182
- memberReader ??= ref.createMemberReader(tenantId);
183
- return memberReader(userId, qn, payload);
184
- },
185
- };
186
- }
187
- function createJobDefer(jobName, bullJob, token) {
188
- return (delayMs) => {
189
- if (!Number.isInteger(delayMs) || delayMs <= 0) {
190
- throw new RangeError(`Job "${jobName}": ctx.defer needs a positive integer delay in ms (got ${delayMs})`);
191
- }
192
- if (token === undefined || !bullJob.moveToDelayed) {
193
- throw new InternalError({
194
- message: `Job "${jobName}": ctx.defer needs a queued run; it is not available inline (boot gate).`,
195
- });
196
- }
197
- return { kind: "job-deferral", delayMs };
198
- };
199
- }
200
49
  function buildJobServices(scope, parts) {
201
50
  const { files, derivatives, selfRunner } = parts;
202
51
  return buildContextServices(scope.context, {
@@ -240,9 +89,7 @@ function buildJobContext(scope, input) {
240
89
  const jobLogger = createJobLogger(input.logs);
241
90
  const jobContext = {
242
91
  defer: createJobDefer(jobName, bullJob, token),
243
- canDefer: token !== undefined &&
244
- bullJob.moveToDelayed !== undefined &&
245
- hasDeferBudgetLeft(rawData, input.jobDef.maxDefers),
92
+ canDefer: isQueuedRun(bullJob, token) && hasDeferBudgetLeft(rawData, input.jobDef.maxDefers),
246
93
  db: jobDb ?? missingDbProxy(jobName),
247
94
  events: {
248
95
  append: createJobAppendEvent({
@@ -252,6 +99,7 @@ function buildJobContext(scope, input) {
252
99
  systemUser,
253
100
  jobName,
254
101
  }),
102
+ load: createJobLoadEvents({ registry: scope.registry, jobDb, tenantId, jobName }),
255
103
  },
256
104
  services: buildJobServices(scope, { files, derivatives, selfRunner }),
257
105
  lifecycle: scope.context.signal ? { signal: scope.context.signal } : {},
@@ -0,0 +1,7 @@
1
+ import type { JobDefinition } from "@cosmicdrift/kumiko-types/config";
2
+ import type { Tracer } from "@cosmicdrift/kumiko-types/observability";
3
+ import type { Queue } from "bullmq";
4
+ import { type JobRunnerScope } from "./job-runner-scope.ts";
5
+ import type { JobMeta } from "./job-runner-types.ts";
6
+ export declare function applyConcurrencyMode(scope: JobRunnerScope, targetQueue: Queue, jobName: string, jobDef: JobDefinition, bullOpts: Record<string, unknown>): Promise<"skipped" | undefined>;
7
+ export declare function buildEnqueueInputs(tracer: Tracer, jobDef: JobDefinition, payload: Record<string, unknown> | undefined, meta: JobMeta | undefined, bullOpts: Record<string, unknown>): Record<string, unknown>;
@@ -0,0 +1,57 @@
1
+ import { requestContext } from "../api/request-context.js";
2
+ import { buildRetryBullOpts, captureTraceContext, stampGatedWriteOrigin, TRACE_CONTEXT_KEY, } from "./job-runner-helpers.js";
3
+ import { announceDropped } from "./job-runner-scope.js";
4
+ // case "sequential" is rejected at boot — see createJobRunner. Once the OSS-compatible
5
+ // implementation lands (per-name Redis lock), re-add the dispatch branch here.
6
+ export async function applyConcurrencyMode(scope, targetQueue, jobName, jobDef, bullOpts) {
7
+ switch (jobDef.concurrency ?? "parallel") {
8
+ case "skip": {
9
+ const active = await targetQueue.getActive();
10
+ const waiting = await targetQueue.getWaiting();
11
+ const isRunning = [...active, ...waiting].some((j) => j.name === jobName);
12
+ return isRunning ? "skipped" : undefined;
13
+ }
14
+ case "replace": {
15
+ const waiting = await targetQueue.getWaiting();
16
+ for (const j of waiting) {
17
+ if (j.name === jobName && j.id) {
18
+ await j.remove();
19
+ await announceDropped(scope, jobName, jobDef, j.id, j.data);
20
+ }
21
+ }
22
+ return undefined;
23
+ }
24
+ case "debounce": {
25
+ bullOpts["debounce"] = { id: jobName, ttl: jobDef.debounceMs ?? 5000 };
26
+ return undefined;
27
+ }
28
+ default:
29
+ return undefined;
30
+ }
31
+ }
32
+ // Fills bullOpts from the job definition and meta, and returns the job data with the _-prefixed meta.
33
+ export function buildEnqueueInputs(tracer, jobDef, payload, meta, bullOpts) {
34
+ Object.assign(bullOpts, buildRetryBullOpts(jobDef));
35
+ if (jobDef.timeout)
36
+ bullOpts["timeout"] = jobDef.timeout;
37
+ if (meta?.priority !== undefined)
38
+ bullOpts["priority"] = meta.priority;
39
+ if (meta?.jobId !== undefined)
40
+ bullOpts["jobId"] = meta.jobId;
41
+ const data = { ...payload };
42
+ if (meta?.triggeredById !== undefined)
43
+ data["_triggeredById"] = meta.triggeredById;
44
+ if (meta?.payload !== undefined)
45
+ data["_payload"] = meta.payload;
46
+ // Carry the enqueuing span context into the worker so job.execute shows as a child of the caller.
47
+ const traceCtx = captureTraceContext(tracer);
48
+ if (traceCtx)
49
+ data[TRACE_CONTEXT_KEY] = traceCtx;
50
+ // The worker re-enters requestContext.run with this value so writes during the job stamp the
51
+ // same correlation as the HTTP request that scheduled it.
52
+ const reqCtx = requestContext.get();
53
+ if (reqCtx?.correlationId)
54
+ data["_correlationId"] = reqCtx.correlationId;
55
+ stampGatedWriteOrigin(data);
56
+ return data;
57
+ }
@@ -1,6 +1,7 @@
1
1
  import { requestContext } from "../api/request-context.js";
2
2
  import { buildRetryBullOpts, captureTraceContext, catchUpJobId, eventTriggerMatches, stampGatedWriteOrigin, TRACE_CONTEXT_KEY, } from "./job-runner-helpers.js";
3
3
  import { announceQueued, isOverPerTenantLimit, laneForJob, } from "./job-runner-scope.js";
4
+ import { acquireTenantCapLock } from "./job-runner-tenant-cap-lock.js";
4
5
  import { resolveMaxPerTenant } from "./max-per-tenant.js";
5
6
  export function createJobEventTriggers(deps) {
6
7
  const { scope, queues, tracer, allJobs } = deps;
@@ -24,19 +25,27 @@ export function createJobEventTriggers(deps) {
24
25
  // Same maxPerTenant guard as dispatch — events that fan into many
25
26
  // jobs must respect the per-tenant cap or the limit is one-sided.
26
27
  const maxPerTenant = resolveMaxPerTenant(jobDef);
27
- if (maxPerTenant?.onLimit === "skip" && user?.tenantId !== undefined) {
28
- if (await isOverPerTenantLimit(scope, name, String(user.tenantId), maxPerTenant.limit)) {
28
+ const capped = maxPerTenant?.onLimit === "skip" && user?.tenantId !== undefined;
29
+ const releaseCapLock = capped
30
+ ? await acquireTenantCapLock(scope, name, String(user.tenantId))
31
+ : undefined;
32
+ try {
33
+ if (capped &&
34
+ (await isOverPerTenantLimit(scope, name, String(user.tenantId), maxPerTenant.limit))) {
29
35
  // skip: onLimit "skip" drops this trigger on purpose while the tenant is at its cap.
30
36
  return;
31
37
  }
38
+ stampGatedWriteOrigin(data);
39
+ const bullOpts = { ...buildRetryBullOpts(jobDef) };
40
+ if (jobId !== undefined)
41
+ bullOpts.jobId = jobId;
42
+ // Route to the job's declared lane, not a fixed queue.
43
+ const job = await queues[laneForJob(jobDef)].add(name, data, bullOpts);
44
+ await announceQueued(scope, name, jobDef, job, data);
45
+ }
46
+ finally {
47
+ await releaseCapLock?.();
32
48
  }
33
- stampGatedWriteOrigin(data);
34
- const bullOpts = { ...buildRetryBullOpts(jobDef) };
35
- if (jobId !== undefined)
36
- bullOpts.jobId = jobId;
37
- // Route to the job's declared lane, not a fixed queue.
38
- const job = await queues[laneForJob(jobDef)].add(name, data, bullOpts);
39
- await announceQueued(scope, name, jobDef, job, data);
40
49
  }
41
50
  return {
42
51
  async handleEvent(eventName, payload, user, triggerEvent) {
@@ -7,7 +7,7 @@ import { InternalError } from "../errors/index.js";
7
7
  import { scrubLogText } from "../logging/index.js";
8
8
  import { withEscapeHatchAuditScope } from "../observability/escape-hatch-report.js";
9
9
  import { emitJobLastSuccess } from "../observability/standard-metrics.js";
10
- import { DEFAULT_MAX_DEFERS, HANDLER_DEFER_COUNT_KEY, hasDeferBudgetLeft, isJobDeferral, priorDeferCountOf, readTraceContext, resolveJobTz, tenantFailureMessageKey, } from "./job-runner-helpers.js";
10
+ import { DEFAULT_MAX_DEFERS, HANDLER_DEFER_COUNT_KEY, hasDeferBudgetLeft, isJobDeferral, isQueuedRun, priorDeferCountOf, readTraceContext, resolveJobTz, tenantFailureMessageKey, } from "./job-runner-helpers.js";
11
11
  import { laneForJob, logFailedAttempt } from "./job-runner-scope.js";
12
12
  function buildOutcomeMeta(run, messageKey, unrecoverable = false) {
13
13
  const { jobDef, subjects } = run;
@@ -140,7 +140,7 @@ export async function executeJobInSpan(scope, run) {
140
140
  }, () => runInSystemRowLevelSecurityScope("job execution span reads job rows of every tenant", () => runAndRecordJob(scope, run, { requestId, correlationId }))));
141
141
  }
142
142
  export async function applyHandlerDeferral(scope, run, bullJob, deferral, token) {
143
- if (!deferral || token === undefined || !bullJob.moveToDelayed)
143
+ if (!deferral || !isQueuedRun(bullJob, token))
144
144
  return "not-deferred";
145
145
  // Run-log bookkeeping must not turn a defer into a failure.
146
146
  try {
@@ -0,0 +1,48 @@
1
+ /// <reference types="temporal-polyfill/global" preserve="true" />
2
+ import type { ConfigAccessor, JobDefinition } from "@cosmicdrift/kumiko-types/config";
3
+ import type { WriteOrigin } from "@cosmicdrift/kumiko-types/event-store-types";
4
+ import type { JobContext } from "@cosmicdrift/kumiko-types/handlers";
5
+ import type { DbRow } from "../db/connection.ts";
6
+ import { createCrossTenantReads } from "../db/cross-tenant-reads.ts";
7
+ import type { TenantDb } from "../db/tenant-db.ts";
8
+ import { createUncheckedSystemDb } from "../db/tenant-db.ts";
9
+ import type { JobDispatch, SessionUser } from "../engine/types/index.ts";
10
+ import { createEscapeHatchReporter } from "../observability/escape-hatch-report.ts";
11
+ import type { JobRunnerScope } from "./job-runner-scope.ts";
12
+ import type { JobInvocation, JobLogEntry } from "./job-runner-types.ts";
13
+ export type JobContextInput = {
14
+ readonly jobName: string;
15
+ readonly jobDef: JobDefinition;
16
+ readonly bullJob: JobInvocation;
17
+ readonly token: string | undefined;
18
+ readonly rawData: DbRow;
19
+ readonly tenantId: string;
20
+ readonly triggeredById: string | null;
21
+ readonly writeOrigin: WriteOrigin | undefined;
22
+ readonly attempt: number;
23
+ readonly finalAttempt: boolean;
24
+ readonly logs: JobLogEntry[];
25
+ };
26
+ type EscapeHatchReport = ReturnType<typeof createEscapeHatchReporter>;
27
+ export type JobFacetInput = {
28
+ readonly input: JobContextInput;
29
+ readonly systemUser: SessionUser;
30
+ readonly isSystemJob: boolean;
31
+ readonly reportEscapeHatch: EscapeHatchReport;
32
+ };
33
+ export declare function createJobEscapeHatchReporter(scope: JobRunnerScope, input: JobContextInput, systemUser: SessionUser): EscapeHatchReport;
34
+ export declare function buildJobDbFacets(scope: JobRunnerScope, facetInput: JobFacetInput): {
35
+ tenantScopedDb: TenantDb | undefined;
36
+ jobDb: TenantDb | undefined;
37
+ systemDb: ReturnType<typeof createUncheckedSystemDb> | undefined;
38
+ crossTenantReads: ReturnType<typeof createCrossTenantReads> | undefined;
39
+ };
40
+ export declare function buildJobServiceFacets(scope: JobRunnerScope, facetInput: JobFacetInput, tenantScopedDb: TenantDb | undefined): {
41
+ files: JobContext["services"]["files"];
42
+ notify: ReturnType<NonNullable<JobRunnerScope["context"]["_notifyFactory"]>> | undefined;
43
+ config: ConfigAccessor | undefined;
44
+ derivatives: JobContext["services"]["derivatives"];
45
+ };
46
+ export declare function buildJobDispatchFacets(scope: JobRunnerScope, facetInput: JobFacetInput): JobDispatch;
47
+ export declare function createJobDefer(jobName: string, bullJob: JobInvocation, token: string | undefined): JobContext["defer"];
48
+ export {};
@@ -0,0 +1,156 @@
1
+ /// <reference types="temporal-polyfill/global" preserve="true" />
2
+ import { crossTenantReadsGrantFor, escapeHatchFor } from "@cosmicdrift/kumiko-types/handlers";
3
+ import { createCrossTenantReads } from "../db/cross-tenant-reads.js";
4
+ import { createTenantDb, createUncheckedSystemDb } from "../db/tenant-db.js";
5
+ import { createDerivativesContext } from "../derivatives/derivatives-context.js";
6
+ import { InternalError } from "../errors/index.js";
7
+ import { createTenantFileContext } from "../files/file-handle.js";
8
+ import { createEscapeHatchReporter } from "../observability/escape-hatch-report.js";
9
+ import { configAccessorFactoryOf } from "../pipeline/config-accessor-factory.js";
10
+ import { createGatedIdentitySwitch } from "../pipeline/system-identity-switch.js";
11
+ import { buildPersonalDataGate } from "../pipeline/write-origin.js";
12
+ import { isScheduledTrigger } from "./cron-repeat-options.js";
13
+ import { isQueuedRun } from "./job-runner-helpers.js";
14
+ export function createJobEscapeHatchReporter(scope, input, systemUser) {
15
+ const { jobName, jobDef, tenantId, triggeredById } = input;
16
+ // One reporter for ctx.systemDb and ctx.db.unsafeRaw() so both dedupe in the same window.
17
+ const isSystemCronRun = triggeredById === null &&
18
+ jobDef.escapeHatch !== undefined &&
19
+ isScheduledTrigger(jobDef.trigger);
20
+ return createEscapeHatchReporter({
21
+ handler: jobName,
22
+ tenantId,
23
+ actor: systemUser.id,
24
+ sink: scope.context._escapeHatchAuditSink,
25
+ log: scope.errorLogger,
26
+ window: scope.escapeHatchReportWindow,
27
+ ...(triggeredById !== null && { caller: triggeredById }),
28
+ ...(isSystemCronRun && { processDedup: scope.systemCronEscapeHatchDedup }),
29
+ ...(scope.context.meter && { meter: scope.context.meter }),
30
+ });
31
+ }
32
+ export function buildJobDbFacets(scope, facetInput) {
33
+ const { context, registry } = scope;
34
+ const { input, isSystemJob, reportEscapeHatch } = facetInput;
35
+ const { jobDef, tenantId, writeOrigin } = input;
36
+ const personalDataGate = writeOrigin ? buildPersonalDataGate(registry, writeOrigin) : undefined;
37
+ const configDb = context.db; // @cast-boundary db-operator
38
+ // Shared by the config accessor and ctx.services.derivatives below — both need the
39
+ // same tenant-scoped db, and building it twice would let the two calls
40
+ // drift apart. Always "system" mode regardless of the job's own
41
+ // systemScope() status (pre-existing, not something this change alters)
42
+ // — isSystemJob below is what actually keeps ctx.systemDb off a
43
+ // non-system job; it is the only thing standing between this db and an
44
+ // unchecked cross-tenant escape hatch for such a job. Gated like jobDb so
45
+ // ctx.systemDb, built from it, is gated too.
46
+ const tenantScopedDb = configDb
47
+ ? createTenantDb({
48
+ db: configDb,
49
+ tenantId,
50
+ mode: "system",
51
+ reason: "job context db for cross-tenant jobs, ctx.systemDb exposure is gated by isSystemJob",
52
+ grants: {
53
+ projectionRegistry: registry,
54
+ ...(personalDataGate && { personalDataGate }),
55
+ },
56
+ })
57
+ : undefined;
58
+ const systemDb = isSystemJob && tenantScopedDb
59
+ ? createUncheckedSystemDb(tenantScopedDb, undefined, reportEscapeHatch)
60
+ : undefined;
61
+ const jobDb = configDb
62
+ ? createTenantDb({
63
+ db: configDb,
64
+ tenantId,
65
+ mode: "tenant",
66
+ tracer: context.tracer,
67
+ meter: context.meter,
68
+ grants: {
69
+ unsafeRaw: escapeHatchFor(jobDef.escapeHatch, "unsafeRaw"),
70
+ globalWrites: escapeHatchFor(jobDef.escapeHatch, "globalWrites"),
71
+ report: reportEscapeHatch,
72
+ projectionRegistry: registry,
73
+ ...(personalDataGate && { personalDataGate }),
74
+ },
75
+ })
76
+ : undefined;
77
+ const crossTenantReadsReason = crossTenantReadsGrantFor(jobDef.escapeHatch)?.reason;
78
+ const crossTenantReads = tenantScopedDb && crossTenantReadsReason !== undefined
79
+ ? createCrossTenantReads(tenantScopedDb, crossTenantReadsReason, reportEscapeHatch)
80
+ : undefined;
81
+ return { tenantScopedDb, jobDb, systemDb, crossTenantReads };
82
+ }
83
+ export function buildJobServiceFacets(scope, facetInput, tenantScopedDb) {
84
+ const { context, registry } = scope;
85
+ const { input, systemUser } = facetInput;
86
+ const { tenantId } = input;
87
+ // Mirror dispatch-shared.ts buildHandlerContext: ctx.services.files must resolve
88
+ // through the same _fileProviderResolver for jobs as for write-handlers,
89
+ // otherwise event-triggered jobs silently get an unresolved ctx.services.files.
90
+ const fileResolver = context._fileProviderResolver;
91
+ const files = fileResolver ? createTenantFileContext(fileResolver, tenantId) : context.files;
92
+ // Same buildHandlerContext parity as ctx.services.files above: ctx.notify/ctx.config
93
+ // must resolve for jobs the same way they do for write-handlers, or an
94
+ // app-author job calling ctx.notify(...)/ctx.config(...) hits a TypeError
95
+ // at runtime the write-handler path never would.
96
+ const notify = context._notifyFactory?.(systemUser, tenantId, scope.getSelfRunner(), undefined, context._fileProviderResolver);
97
+ const configFactory = configAccessorFactoryOf(context);
98
+ const config = configFactory && tenantScopedDb
99
+ ? configFactory({
100
+ user: { id: systemUser.id, tenantId },
101
+ db: tenantScopedDb,
102
+ secrets: context.secrets,
103
+ })
104
+ : undefined;
105
+ // Mirror dispatch-shared.ts: ctx.services.derivatives needs files+db, same
106
+ // tenant-scoped db the config accessor above uses.
107
+ const derivatives = files && tenantScopedDb
108
+ ? createDerivativesContext({ files, registry, db: tenantScopedDb, tenantId })
109
+ : context.derivatives;
110
+ return { files, notify, config, derivatives };
111
+ }
112
+ function requireDispatchRef(scope, method) {
113
+ const ref = scope.getDispatchWriteRef();
114
+ if (!ref) {
115
+ throw new Error(`JobContext.${method} called before dispatcher attached — call attachDispatcher() first`);
116
+ }
117
+ return ref;
118
+ }
119
+ export function buildJobDispatchFacets(scope, facetInput) {
120
+ const { input, systemUser, isSystemJob, reportEscapeHatch } = facetInput;
121
+ const { jobName, jobDef, tenantId, writeOrigin } = input;
122
+ // Per-job-run reader, created lazily on queryAsMember's first call and
123
+ // cached for the rest of this run.
124
+ let memberReader;
125
+ const identitySwitchHatch = escapeHatchFor(jobDef.escapeHatch, "systemIdentity");
126
+ const identitySwitchGrantReason = identitySwitchHatch?.reason ??
127
+ (isSystemJob ? `r.systemScope() feature of job "${jobName}"` : undefined);
128
+ const gatedIdentitySwitch = createGatedIdentitySwitch(`job "${jobName}"`, systemUser, isSystemJob || identitySwitchHatch !== undefined, {
129
+ queryAs: (user, qn, payload) => requireDispatchRef(scope, "queryAs").queryAs(user, qn, payload, writeOrigin),
130
+ writeAs: async (user, qn, payload) => requireDispatchRef(scope, "writeAs").write(user, qn, payload, writeOrigin),
131
+ }, { reason: identitySwitchGrantReason, report: reportEscapeHatch });
132
+ return {
133
+ write: (qn, payload) => requireDispatchRef(scope, "write").write(systemUser, qn, payload, writeOrigin),
134
+ writeAs: gatedIdentitySwitch.writeAs,
135
+ queryAs: gatedIdentitySwitch.queryAs,
136
+ queryAsMember: (userId, qn, payload) => {
137
+ const ref = requireDispatchRef(scope, "queryAsMember");
138
+ // Lazy per-run reader, mirroring the handler-context reader.
139
+ memberReader ??= ref.createMemberReader(tenantId);
140
+ return memberReader(userId, qn, payload);
141
+ },
142
+ };
143
+ }
144
+ export function createJobDefer(jobName, bullJob, token) {
145
+ return (delayMs) => {
146
+ if (!Number.isInteger(delayMs) || delayMs <= 0) {
147
+ throw new RangeError(`Job "${jobName}": ctx.defer needs a positive integer delay in ms (got ${delayMs})`);
148
+ }
149
+ if (!isQueuedRun(bullJob, token)) {
150
+ throw new InternalError({
151
+ message: `Job "${jobName}": ctx.defer needs a queued run; it is not available inline (boot gate).`,
152
+ });
153
+ }
154
+ return { kind: "job-deferral", delayMs };
155
+ };
156
+ }
@@ -1,6 +1,7 @@
1
1
  import { SYSTEM_TENANT_ID } from "../engine/types/index.js";
2
+ import { scrubLogText } from "../logging/index.js";
2
3
  import { prepareJobRun } from "./job-runner-context.js";
3
- import { attemptNumberOf, buildRetryBullOpts, DEFER_COUNT_KEY, deferDelayMs, isFinalAttempt, priorAttemptsOf, priorDeferCountOf, } from "./job-runner-helpers.js";
4
+ import { attemptNumberOf, buildRetryBullOpts, DEFER_COUNT_KEY, deferDelayMs, isFinalAttempt, isQueuedRun, priorAttemptsOf, priorDeferCountOf, } from "./job-runner-helpers.js";
4
5
  import { ACTIVE_TENANT_IDS_QUERY_NAME, perTenantChildJobId } from "./job-runner-schedulers.js";
5
6
  import { announceDropped, announceQueued, isOverPerTenantLimit, laneForJob, logFailedAttempt, } from "./job-runner-scope.js";
6
7
  import { resolveMaxPerTenant } from "./max-per-tenant.js";
@@ -65,7 +66,7 @@ async function enqueuePerTenantChildren(scope, bullJob, actualName) {
65
66
  // the _perTenant wrapper itself always lives in the consumer-lane
66
67
  // (it's picked up by this runner's own worker).
67
68
  export async function fanOutPerTenantJob(scope, bullJob, actualName) {
68
- // These throws happen before runInSpan, so its onJobFailed never sees them
69
+ // These throws happen before executeJobInSpan, so recordJobFailure never sees them
69
70
  // and a drained test stack would stay green over a fan-out that never ran.
70
71
  try {
71
72
  await enqueuePerTenantChildren(scope, bullJob, actualName);
@@ -73,12 +74,11 @@ export async function fanOutPerTenantJob(scope, bullJob, actualName) {
73
74
  catch (err) {
74
75
  // A retry may still succeed, and a succeeding wrapper reports no completion
75
76
  // that could clear an earlier failure, so only the final attempt is reported.
76
- const retries = scope.allJobs.get(actualName)?.retries ?? 0;
77
- const finalAttempt = bullJob.attemptsMade + 1 >= retries + 1;
77
+ const finalAttempt = isFinalAttempt(bullJob, scope.allJobs.get(actualName) ?? { retries: 0 });
78
78
  logFailedAttempt(scope, {
79
79
  job: bullJob.name,
80
80
  jobId: bullJob.id ?? "unknown",
81
- attempt: bullJob.attemptsMade + 1,
81
+ attempt: attemptNumberOf(bullJob),
82
82
  finalAttempt,
83
83
  err,
84
84
  });
@@ -90,9 +90,18 @@ export async function fanOutPerTenantJob(scope, bullJob, actualName) {
90
90
  }
91
91
  async function reportPreRunFailure(scope, jobName, bullJob, err) {
92
92
  const message = err instanceof Error ? err.message : String(err);
93
- await scope.options.onJobFailed?.(jobName, bullJob.id ?? "unknown", message, [
94
- { level: "error", message, timestamp: Temporal.Now.instant() },
95
- ]);
93
+ try {
94
+ await scope.options.onJobFailed?.(jobName, bullJob.id ?? "unknown", message, [
95
+ { level: "error", message, timestamp: Temporal.Now.instant() },
96
+ ]);
97
+ }
98
+ catch (hookErr) {
99
+ // The caller rethrows the original error; a failing hook (often the same unreachable store) must not replace it as BullMQ's failedReason.
100
+ scope.errorLogger.warn("onJobFailed hook threw while reporting a pre-run failure", {
101
+ job: jobName,
102
+ error: scrubLogText(hookErr instanceof Error ? hookErr.message : String(hookErr)),
103
+ });
104
+ }
96
105
  }
97
106
  // prepareJobRun and onJobStart throw before the handler span exists, so the
98
107
  // span's own failure recording never sees them.
@@ -127,7 +136,7 @@ export async function resolveJobDefinitionOrFail(scope, bullJob) {
127
136
  logFailedAttempt(scope, {
128
137
  job: jobName,
129
138
  jobId: bullJob.id ?? "unknown",
130
- attempt: bullJob.attemptsMade + 1,
139
+ attempt: attemptNumberOf(bullJob),
131
140
  finalAttempt: true,
132
141
  err,
133
142
  });
@@ -142,8 +151,7 @@ export async function deferOverTenantLimit(scope, jobDef, bullJob, token) {
142
151
  const deferTenantId = bullJob.data["_tenantId"];
143
152
  if (maxPerTenant?.onLimit === "defer" &&
144
153
  typeof deferTenantId === "string" &&
145
- token !== undefined &&
146
- bullJob.moveToDelayed &&
154
+ isQueuedRun(bullJob, token) &&
147
155
  (await isOverPerTenantLimit(scope, bullJob.name, deferTenantId, maxPerTenant.limit, {
148
156
  activeOnly: true,
149
157
  self: { id: bullJob.id, processedOn: bullJob.processedOn },
@@ -16,8 +16,12 @@ export declare function jobSubjectKey(jobName: string, payload: Record<string, u
16
16
  export declare function resolveJobTz(config: ConfigAccessor | undefined, context: Pick<AppContext, "geoTzProvider" | "clock">, logger: Pick<Logger, "warn">): Promise<TzContext>;
17
17
  export declare function missingDbProxy(jobName: string): TenantDb;
18
18
  export declare function priorAttemptsOf(data: Record<string, unknown>): number;
19
+ type DeferrableInvocation = JobInvocation & {
20
+ readonly moveToDelayed: NonNullable<JobInvocation["moveToDelayed"]>;
21
+ };
22
+ export declare function isQueuedRun(bullJob: JobInvocation, token: string | undefined): bullJob is DeferrableInvocation;
19
23
  export declare function attemptNumberOf(bullJob: JobInvocation): number;
20
- export declare function isFinalAttempt(bullJob: JobInvocation, jobDef: JobDefinition): boolean;
24
+ export declare function isFinalAttempt(bullJob: JobInvocation, jobDef: Pick<JobDefinition, "retries">): boolean;
21
25
  export declare function tenantFailureMessageKey(err: unknown, declaration: JobDefinition["tenantVisibleFailure"]): string | null;
22
26
  export declare const TRACE_CONTEXT_KEY = "_traceContext";
23
27
  export declare const DEFER_COUNT_KEY = "_deferCount";