@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,30 +1,14 @@
1
- import { runInSavepoint, selectMany } from "../db/query.js";
2
- import { runInSystemRowLevelSecurityScope } from "../db/row-level-security-scope.js";
3
- import { hasTenantColumn } from "../db/tenant-db.js";
1
+ import { runInSavepoint } from "../db/query.js";
4
2
  import { InternalError, VersionConflictError } from "../errors/index.js";
5
3
  import { memberResolutionReadOnlyDenied } from "../errors/member-resolution.js";
6
4
  import { archiveStream as archiveStreamHelper, isStreamArchived, restoreStream as restoreStreamHelper, } from "../event-store/archive.js";
7
5
  import { IdempotentAppendConflictError as EventStoreIdempotentAppendConflictError, VersionConflictError as EventStoreVersionConflictError, } from "../event-store/errors.js";
8
6
  import { loadAggregate, loadAggregateAsOf, loadAggregateForWriting, } from "../event-store/event-store.js";
9
7
  import { effectiveSnapshotGeneration, loadAggregateWithSnapshot, saveSnapshot, } from "../event-store/snapshot.js";
10
- import { upcastStoredEvent, upcastStoredEvents } from "../event-store/upcaster.js";
8
+ import { makeUpcastCtx, upcastStoredEvent, upcastStoredEvents } from "../event-store/upcaster.js";
11
9
  import { appendDomainEventCore } from "./append-event-core.js";
12
- import { isMemberResolutionPrincipal, resolveDbSource, } from "./dispatch-shared.js";
13
- import { createGatedProjectionReader } from "./system-identity-switch.js";
10
+ import { isMemberResolutionPrincipal, requireDbSource } from "./dispatch-context-helpers.js";
14
11
  import { asTypedAppendEventFn } from "./typed-append-event.js";
15
- function requireDbSource(ctx, tx, surfaceCall) {
16
- const dbSource = resolveDbSource(ctx, tx);
17
- if (!dbSource) {
18
- throw new InternalError({
19
- message: `${surfaceCall} requires a database connection — none is configured.`,
20
- });
21
- }
22
- return dbSource;
23
- }
24
- // ctx.events.append — append a domain event onto a specific aggregate stream
25
- // in the current tx, then fire matching inline projections. Core logic
26
- // lives in appendDomainEventCore; this wrapper just locates dbSource +
27
- // stringifies the SessionUser id for the shared helper.
28
12
  async function appendDomainEvent(ctx, args, user, tx, callerFeature) {
29
13
  // Sink behind every append surface, so a resolved member stays read-only even via fetchForWriting handles.
30
14
  if (isMemberResolutionPrincipal(user))
@@ -124,19 +108,23 @@ function buildFetchForWriting(scope) {
124
108
  };
125
109
  };
126
110
  }
111
+ /** Shared by handler and job `ctx.events.load`: tenant-scoped read through the upcaster chain. */
112
+ export async function loadUpcastedAggregate(source, aggregateId, loadOptions) {
113
+ const { db, registry, tenantId } = source;
114
+ const includeArchived = loadOptions?.includeArchived === true;
115
+ const events = loadOptions?.asOf
116
+ ? await loadAggregateAsOf(db, aggregateId, tenantId, loadOptions.asOf, { includeArchived })
117
+ : await loadAggregate(db, aggregateId, tenantId, {
118
+ includeArchived,
119
+ ...(loadOptions?.atVersion !== undefined && { atVersion: loadOptions.atVersion }),
120
+ });
121
+ return upcastStoredEvents(events, registry.getEventUpcasters(), makeUpcastCtx(db, tenantId));
122
+ }
127
123
  function buildLoadAggregate(scope) {
128
124
  const { ctx, user, tx, registry } = scope;
129
- return async (aggregateId, loadOptions) => {
130
- const dbSource = requireDbSource(ctx, tx, `ctx.events.load("${aggregateId}")`);
131
- const events = loadOptions?.asOf
132
- ? await loadAggregateAsOf(dbSource, aggregateId, user.tenantId, loadOptions.asOf)
133
- : await loadAggregate(dbSource, aggregateId, user.tenantId, {
134
- ...(loadOptions?.atVersion !== undefined && { atVersion: loadOptions.atVersion }),
135
- });
136
- return upcastStoredEvents(events, registry.getEventUpcasters(), {
137
- db: dbSource,
138
- tenantId: user.tenantId,
139
- });
125
+ return (aggregateId, loadOptions) => {
126
+ const db = requireDbSource(ctx, tx, `ctx.events.load("${aggregateId}")`);
127
+ return loadUpcastedAggregate({ db, registry, tenantId: user.tenantId }, aggregateId, loadOptions);
140
128
  };
141
129
  }
142
130
  function buildSnapshotAggregate(scope) {
@@ -167,43 +155,10 @@ function buildLoadAggregateWithSnapshot(scope) {
167
155
  return loadAggregateWithSnapshot(dbSource, aggregateId, user.tenantId, reducer, initial, {
168
156
  ...loadOptions,
169
157
  entityEventVersionOf: (aggregateType) => registry.getEntity(aggregateType)?.eventVersion,
170
- upcastEvent: (event) => upcastStoredEvent(event, upcasters, upcastCtx), // @wrapper-known semantic-alias
158
+ upcastEvent: (event) => upcastStoredEvent(event, upcasters, upcastCtx),
171
159
  });
172
160
  };
173
161
  }
174
- // queryProjection works against both single-stream and multi-stream
175
- // projections. MSPs without a table cannot be queried — those are
176
- // side-effect-only consumers (no state to read back).
177
- function buildHandlerProjectionReader(scope) {
178
- const { ctx, type, user, tx, registry, hasIdentitySwitchGrant, identitySwitchAudit } = scope;
179
- const findProjectionTable = (qualifiedName) => registry.getAllProjections().get(qualifiedName)?.table ??
180
- registry.getAllMultiStreamProjections().get(qualifiedName)?.table;
181
- const ungatedQueryProjection = async (qualifiedName, queryOptions) => {
182
- const projTable = findProjectionTable(qualifiedName);
183
- if (!projTable) {
184
- const singleNames = [...registry.getAllProjections().keys()];
185
- const mspNames = [...registry.getAllMultiStreamProjections().keys()].filter((n) => registry.getAllMultiStreamProjections().get(n)?.table);
186
- const all = [...singleNames, ...mspNames];
187
- throw new InternalError({
188
- message: `ctx.dispatch.queryProjection("${qualifiedName}") — projection not registered, or it is a ` +
189
- `table-less MSP (side-effect-only). Known queryable projections: ${all.join(", ") || "(none)"}`,
190
- });
191
- }
192
- const dbSource = requireDbSource(ctx, tx, `ctx.dispatch.queryProjection("${qualifiedName}")`);
193
- const allTenants = queryOptions?.unsafeAllTenants === true;
194
- const where = hasTenantColumn(projTable) && !allTenants ? { tenantId: user.tenantId } : undefined;
195
- const read = () => selectMany(dbSource, projTable, where);
196
- const rows = await (allTenants
197
- ? runInSystemRowLevelSecurityScope("handler projection read with allTenants spans every tenant", read)
198
- : read());
199
- return rows; // @cast-boundary engine-payload
200
- };
201
- return createGatedProjectionReader(`handler "${type}"`, hasIdentitySwitchGrant, ungatedQueryProjection, identitySwitchAudit, (qualifiedName) => {
202
- const projTable = findProjectionTable(qualifiedName);
203
- // Unknown projection: keep the grant check first, the ungated reader reports the real error.
204
- return projTable === undefined || hasTenantColumn(projTable);
205
- });
206
- }
207
162
  export function buildEventStoreFacet(scope) {
208
163
  const { ctx, type, user, tx, registry } = scope;
209
164
  const events = {
@@ -240,5 +195,5 @@ export function buildEventStoreFacet(scope) {
240
195
  snapshot: buildSnapshotAggregate(scope),
241
196
  loadWithSnapshot: buildLoadAggregateWithSnapshot(scope),
242
197
  };
243
- return { events, queryProjection: buildHandlerProjectionReader(scope) };
198
+ return { events };
244
199
  }
@@ -24,6 +24,7 @@ function allowlistedReadOnlyProxy(target, allowedMethods) {
24
24
  });
25
25
  }
26
26
  const MEMBER_READ_SEARCH_METHODS = new Set(["search"]);
27
+ const MEMBER_READ_SECRETS_METHODS = new Set(["get", "has"]);
27
28
  const MEMBER_READ_ENTITY_CACHE_METHODS = new Set(["get", "mget"]);
28
29
  const MEMBER_READ_REDIS_METHODS = new Set([
29
30
  "get",
@@ -48,10 +49,12 @@ const MEMBER_READ_REDIS_METHODS = new Set([
48
49
  "zrange",
49
50
  ]);
50
51
  function readOnlyServices(services) {
51
- const { searchAdapter, redis, entityCache, jobRunner } = services;
52
+ const { searchAdapter, redis, entityCache, jobRunner, secrets } = services;
52
53
  // A read as a member gets no file storage, no notify factory and no job runner; the read-only
53
54
  // proxies keep the rest. The resolver and factories would reopen what files/notify close.
54
- const { files: _files, derivatives: _derivatives, _fileProviderResolver: _resolver, ...kept } = withoutNotifyFactories(services);
55
+ // kms, masterKeyProvider and the audit sink write through their own connections, which the
56
+ // READ ONLY transaction does not cover.
57
+ const { files: _files, derivatives: _derivatives, _fileProviderResolver: _resolver, kms: _kms, masterKeyProvider: _masterKeyProvider, _escapeHatchAuditSink: _auditSink, secrets: _secrets, ...kept } = withoutNotifyFactories(services);
55
58
  const runner = jobRunner && denyingJobRunnerProxy();
56
59
  return {
57
60
  ...kept,
@@ -59,6 +62,9 @@ function readOnlyServices(services) {
59
62
  ...(searchAdapter && {
60
63
  searchAdapter: allowlistedReadOnlyProxy(searchAdapter, MEMBER_READ_SEARCH_METHODS),
61
64
  }),
65
+ ...(secrets && {
66
+ secrets: allowlistedReadOnlyProxy(secrets, MEMBER_READ_SECRETS_METHODS),
67
+ }),
62
68
  ...(redis && { redis: allowlistedReadOnlyProxy(redis, MEMBER_READ_REDIS_METHODS) }),
63
69
  ...(entityCache && {
64
70
  entityCache: allowlistedReadOnlyProxy(entityCache, MEMBER_READ_ENTITY_CACHE_METHODS),
@@ -67,13 +73,15 @@ function readOnlyServices(services) {
67
73
  }
68
74
  // Every write/side-effect surface throws, so "no writeAsMember" holds even
69
75
  // if a handler tries ctx.dispatch.write directly on a resolved member principal.
70
- // Deliberately open: `db` (guarded by the READ ONLY transaction + memberReadOnly grant),
71
- // and read-only methods of searchAdapter / redis / entityCache (allowlisted).
76
+ // Deliberately open: `db` and, for r.systemScope() handlers, `systemDb` (both ride the READ ONLY
77
+ // transaction; the systemDb is a view whose unsafeRaw follows db's memberReadOnly denial and that has
78
+ // no outside-transaction source), plus read-only methods of searchAdapter / redis / entityCache.
72
79
  export function applyMemberResolutionReadOnly(handlerContext) {
73
- // `db` stays open — executeQuery runs the whole handler in a Postgres READ ONLY
74
- // transaction, and its `memberReadOnly` grant denies every raw-runner handout.
80
+ // executeQuery runs the whole handler in a Postgres READ ONLY transaction, and `db`'s
81
+ // `memberReadOnly` grant denies every raw-runner handout. crossTenantReads and the
82
+ // outside-transaction door would escape that transaction, so they are dropped.
75
83
  dropOutsideTransaction(handlerContext);
76
- const { systemDb: _systemDb, crossTenantReads: _crossTenantReads, ...kept } = handlerContext;
84
+ const { crossTenantReads: _crossTenantReads, ...kept } = handlerContext;
77
85
  return {
78
86
  ...kept,
79
87
  dispatch: {
@@ -95,7 +103,7 @@ export function applyMemberResolutionReadOnly(handlerContext) {
95
103
  snapshot: denyMemberResolutionWrite,
96
104
  },
97
105
  auth: { ...handlerContext.auth, resolveActiveMembership: denyMemberResolutionWrite },
98
- // A read as a member gets no system-scope DB, preSave pipeline or file storage.
106
+ // A read as a member gets no preSave pipeline or file storage.
99
107
  lifecycle: {
100
108
  afterCommit: throwMemberResolutionDenied,
101
109
  afterRollback: throwMemberResolutionDenied,
@@ -9,5 +9,6 @@ export declare function buildNotifyFacet(scope: HandlerContextScope, sinks: Comm
9
9
  factoryServices: {
10
10
  _notifyInTransactionFactory?: ((notifyUser: SessionUser, notifyTenantId: TenantId) => NotifyFn) | undefined;
11
11
  _notifyAfterCommitFactory?: ((notifyUser: SessionUser, notifyTenantId: TenantId) => NotifyFn) | undefined;
12
+ _logOwnDeliveryAttempt?: import("@cosmicdrift/kumiko-types/handlers").DeliveryAttemptLogFn | undefined;
12
13
  };
13
14
  };
@@ -43,6 +43,7 @@ export function buildNotifyFacet(scope, sinks, outsideTxSource) {
43
43
  ? (notifyUser, notifyTenantId) => notifyFactory(notifyUser, notifyTenantId, notifyJobDispatcher, undefined, context._fileProviderResolver)
44
44
  : undefined;
45
45
  const notify = buildNotify(scope, sinks, notifyAfterCommitFactory, notifyInTransactionFactory);
46
+ const logOwnDeliveryAttempt = context._deliveryAttemptLogFactory?.(scope.user, scope.user.tenantId, outsideTxSource);
46
47
  return {
47
48
  notify,
48
49
  factoryServices: {
@@ -50,6 +51,7 @@ export function buildNotifyFacet(scope, sinks, outsideTxSource) {
50
51
  _notifyInTransactionFactory: notifyInTransactionFactory,
51
52
  }),
52
53
  ...(notifyAfterCommitFactory && { _notifyAfterCommitFactory: notifyAfterCommitFactory }),
54
+ ...(logOwnDeliveryAttempt && { _logOwnDeliveryAttempt: logOwnDeliveryAttempt }),
53
55
  },
54
56
  };
55
57
  }
@@ -84,9 +84,10 @@ export function denyTransactionBoundSurfaces(handlerContext) {
84
84
  },
85
85
  };
86
86
  }
87
- // A notify factory builds a working notify, so a phase that denies ctx.notify must drop them too.
87
+ // A notify factory builds a working notify, so a phase that denies ctx.notify must drop them too,
88
+ // along with the delivery attempt log that belongs to a delivery.
88
89
  export function withoutNotifyFactories(services) {
89
- const { _notifyFactory: _factory, _notifyInTransactionFactory: _inTransaction, _notifyAfterCommitFactory: _afterCommit, ...rest } = services;
90
+ const { _notifyFactory: _factory, _notifyInTransactionFactory: _inTransaction, _notifyAfterCommitFactory: _afterCommit, _deliveryAttemptLogFactory: _attemptLogFactory, _logOwnDeliveryAttempt: _ownAttemptLog, ...rest } = services;
90
91
  return rest;
91
92
  }
92
93
  // The beforeTransaction phase has no write need at all, so it also loses the outside-transaction
@@ -0,0 +1,3 @@
1
+ import type { HandlerContextScope } from "./handler-context-scope.ts";
2
+ import { type ProjectionReader } from "./system-identity-switch.ts";
3
+ export declare function buildHandlerProjectionReader(scope: HandlerContextScope): ProjectionReader;
@@ -0,0 +1,39 @@
1
+ import { selectMany } from "../db/query.js";
2
+ import { runInSystemRowLevelSecurityScope } from "../db/row-level-security-scope.js";
3
+ import { hasTenantColumn } from "../db/tenant-db.js";
4
+ import { InternalError } from "../errors/index.js";
5
+ import { requireDbSource } from "./dispatch-context-helpers.js";
6
+ import { createGatedProjectionReader } from "./system-identity-switch.js";
7
+ // queryProjection works against both single-stream and multi-stream
8
+ // projections. MSPs without a table cannot be queried — those are
9
+ // side-effect-only consumers (no state to read back).
10
+ export function buildHandlerProjectionReader(scope) {
11
+ const { ctx, type, user, tx, registry, hasIdentitySwitchGrant, identitySwitchAudit } = scope;
12
+ const findProjectionTable = (qualifiedName) => registry.getAllProjections().get(qualifiedName)?.table ??
13
+ registry.getAllMultiStreamProjections().get(qualifiedName)?.table;
14
+ const ungatedQueryProjection = async (qualifiedName, queryOptions) => {
15
+ const projTable = findProjectionTable(qualifiedName);
16
+ if (!projTable) {
17
+ const singleNames = [...registry.getAllProjections().keys()];
18
+ const mspNames = [...registry.getAllMultiStreamProjections().keys()].filter((n) => registry.getAllMultiStreamProjections().get(n)?.table);
19
+ const all = [...singleNames, ...mspNames];
20
+ throw new InternalError({
21
+ message: `ctx.dispatch.queryProjection("${qualifiedName}") — projection not registered, or it is a ` +
22
+ `table-less MSP (side-effect-only). Known queryable projections: ${all.join(", ") || "(none)"}`,
23
+ });
24
+ }
25
+ const dbSource = requireDbSource(ctx, tx, `ctx.dispatch.queryProjection("${qualifiedName}")`);
26
+ const allTenants = queryOptions?.unsafeAllTenants === true;
27
+ const where = hasTenantColumn(projTable) && !allTenants ? { tenantId: user.tenantId } : undefined;
28
+ const read = () => selectMany(dbSource, projTable, where);
29
+ const rows = await (allTenants
30
+ ? runInSystemRowLevelSecurityScope("handler projection read with allTenants spans every tenant", read)
31
+ : read());
32
+ return rows; // @cast-boundary engine-payload
33
+ };
34
+ return createGatedProjectionReader(`handler "${type}"`, hasIdentitySwitchGrant, ungatedQueryProjection, identitySwitchAudit, (qualifiedName) => {
35
+ const projTable = findProjectionTable(qualifiedName);
36
+ // Unknown projection: keep the grant check first, the ungated reader reports the real error.
37
+ return projTable === undefined || hasTenantColumn(projTable);
38
+ });
39
+ }
@@ -3,7 +3,7 @@ import type { RequestContextData } from "../api/request-context-internals.ts";
3
3
  import type { DbConnection, DbTx } from "../db/connection.ts";
4
4
  import type { AppContext, HandlerContext, HandlerLifecycle, Registry, SessionUser } from "../engine/types/index.ts";
5
5
  import type { ContextServiceOverrides } from "./context-services.ts";
6
- import { type DispatchContext, type HandlerTransactionScope } from "./dispatch-shared.ts";
6
+ import type { DispatchContext, HandlerTransactionScope } from "./dispatch-shared.ts";
7
7
  import type { WriteOrigin } from "./write-origin.ts";
8
8
  export type HandlerContextScope = {
9
9
  readonly ctx: DispatchContext;
@@ -1,13 +1,25 @@
1
1
  import { escapeHatchFor, } from "@cosmicdrift/kumiko-types/handlers";
2
2
  import { requestContext } from "../api/request-context.js";
3
+ import { isAgentToolCallScope } from "../api/request-context-scopes.js";
4
+ import { AccessDeniedError } from "../errors/index.js";
5
+ import { AgentReasons } from "../errors/reasons.js";
3
6
  import { createFallbackLogger } from "../logging/utils.js";
4
7
  import { createEscapeHatchReporter } from "../observability/escape-hatch-report.js";
5
- import { resolveDbSource, } from "./dispatch-shared.js";
8
+ import { resolveDbSource } from "./dispatch-context-helpers.js";
9
+ import { isEffectivelySystemScoped } from "./effective-system-scope.js";
6
10
  import { createUserLiveSignals } from "./user-live-signals.js";
7
11
  export function resolveHandlerContextScope(input) {
8
12
  const { ctx, type, user, origin, tx, transactionScope } = input;
9
13
  const { registry, appContext: context } = ctx;
10
- const isSystem = registry.isHandlerSystemScoped(type);
14
+ const isSystem = isEffectivelySystemScoped(registry, type);
15
+ // A system-scope handler reads and writes across tenants; an agent tool call carries the user's
16
+ // session into the LLM context, so it must never reach one.
17
+ if (isSystem && isAgentToolCallScope()) {
18
+ throw new AccessDeniedError({
19
+ message: `"${type}" is a system-scope handler and cannot run inside an agent tool call`,
20
+ details: { reason: AgentReasons.toolNotAllowed, handler: type },
21
+ });
22
+ }
11
23
  // The outer dispatcher receives a DbConnection from the server/stack;
12
24
  // AppContext's `db` union also allows TenantDb (for downstream hook calls),
13
25
  // but at this point we're the root of the pipeline — cast is safe.
@@ -13,7 +13,7 @@ export { ConsumerStatuses, createEventConsumerStateTable, eventConsumerStateTabl
13
13
  export type { EventDedup } from "./event-dedup.ts";
14
14
  export { createEventDedup } from "./event-dedup.ts";
15
15
  export type { ConsumerProgress, ConsumerRecoveryState, EventDispatcher, } from "./event-dispatcher.ts";
16
- export { ConsumerTransitionError, disableConsumer, enableConsumer, getAllConsumerProgress, getConsumerState, listConsumersWithState, restartConsumer, skipPoisonEvent, } from "./event-dispatcher.ts";
16
+ export { ConsumerTransitionError, DEFAULT_BATCH_SIZE as DEFAULT_EVENT_DISPATCHER_BATCH_SIZE, disableConsumer, enableConsumer, getAllConsumerProgress, getConsumerState, listConsumersWithState, restartConsumer, skipPoisonEvent, } from "./event-dispatcher.ts";
17
17
  export type { PruneEventsOptions } from "./event-retention.ts";
18
18
  export { ConsumerLagError, pruneEvents } from "./event-retention.ts";
19
19
  export type { IdempotencyGuard } from "./idempotency.ts";
@@ -9,7 +9,7 @@ export { createDistributedLock } from "./distributed-lock.js";
9
9
  export { createEntityCache } from "./entity-cache.js";
10
10
  export { ConsumerStatuses, createEventConsumerStateTable, eventConsumerStateTable, SHARED_INSTANCE_SENTINEL, } from "./event-consumer-state.js";
11
11
  export { createEventDedup } from "./event-dedup.js";
12
- export { ConsumerTransitionError, disableConsumer, enableConsumer, getAllConsumerProgress, getConsumerState, listConsumersWithState, restartConsumer, skipPoisonEvent, } from "./event-dispatcher.js";
12
+ export { ConsumerTransitionError, DEFAULT_BATCH_SIZE as DEFAULT_EVENT_DISPATCHER_BATCH_SIZE, disableConsumer, enableConsumer, getAllConsumerProgress, getConsumerState, listConsumersWithState, restartConsumer, skipPoisonEvent, } from "./event-dispatcher.js";
13
13
  export { ConsumerLagError, pruneEvents } from "./event-retention.js";
14
14
  export { createIdempotencyGuard } from "./idempotency.js";
15
15
  export { assertIrreversibleOperationAllowed } from "./irreversible-operation-gate.js";
@@ -22,6 +22,7 @@ export type LifecycleHooks = {
22
22
  runPostDelete(handlerName: string, payload: DeleteContext, context: HandlerContext, phase?: HookPhase): Promise<void>;
23
23
  runPostSaveBatch(results: readonly SaveContext[], context: HandlerContext): Promise<void>;
24
24
  runPostDeleteBatch(payloads: readonly DeleteContext[], context: HandlerContext): Promise<void>;
25
+ hasBatchHooks(): boolean;
25
26
  };
26
27
  export type LifecycleOptions = {
27
28
  eventDedup?: EventDedup;
@@ -149,8 +149,8 @@ export function createLifecycleHooks(registry, systemHooks = {}, options = {}) {
149
149
  payload: result,
150
150
  context,
151
151
  entityName: result.entityName,
152
- getHandlerHooks: (n) => registry.getPostSaveHooks(n, phase, eff), // @wrapper-known semantic-alias
153
- getEntityHooks: (n) => registry.getEntityPostSaveHooks(n, phase, eff), // @wrapper-known semantic-alias
152
+ getHandlerHooks: (n) => registry.getPostSaveHooks(n, phase, eff),
153
+ getEntityHooks: (n) => registry.getEntityPostSaveHooks(n, phase, eff),
154
154
  systemHookDefs: systemHooks.postSave,
155
155
  phaseLabel: `postSave:${phase}`,
156
156
  hookPhase: phase,
@@ -184,13 +184,16 @@ export function createLifecycleHooks(registry, systemHooks = {}, options = {}) {
184
184
  payload,
185
185
  context,
186
186
  entityName: payload.entityName,
187
- getHandlerHooks: (n) => registry.getPostDeleteHooks(n, phase, eff), // @wrapper-known semantic-alias
188
- getEntityHooks: (n) => registry.getEntityPostDeleteHooks(n, phase, eff), // @wrapper-known semantic-alias
187
+ getHandlerHooks: (n) => registry.getPostDeleteHooks(n, phase, eff),
188
+ getEntityHooks: (n) => registry.getEntityPostDeleteHooks(n, phase, eff),
189
189
  systemHookDefs: systemHooks.postDelete,
190
190
  phaseLabel: `postDelete:${phase}`,
191
191
  hookPhase: phase,
192
192
  });
193
193
  },
194
+ hasBatchHooks() {
195
+ return ((systemHooks.postSaveBatch?.length ?? 0) + (systemHooks.postDeleteBatch?.length ?? 0) > 0);
196
+ },
194
197
  async runPostSaveBatch(results, context) {
195
198
  await runBatchHooks({
196
199
  hooks: systemHooks.postSaveBatch,
@@ -1,5 +1,6 @@
1
1
  // ctx.dispatch.queryAsMember — reads a query handler as a stored tenant member. The
2
2
  // resolved SessionUser never leaves this module.
3
+ import { runInSystemRowLevelSecurityScope } from "../db/row-level-security-scope.js";
3
4
  import { buildSessionRoles } from "../engine/membership-roles.js";
4
5
  import { SYSTEM_TENANT_ID } from "../engine/types/index.js";
5
6
  import { AccessDeniedError, FrameworkReasons, InternalError } from "../errors/index.js";
@@ -37,7 +38,8 @@ async function resolveMember(ctx, tenantId, userId) {
37
38
  }
38
39
  // resolveDbSource(ctx, undefined) never returns a tx, only AppContext.db.
39
40
  const db = dbSource; // @cast-boundary db-operator
40
- const profile = await principalPlugin.resolveProfile(userId, { db });
41
+ // The user row lives on the system tenant, which a tenant scope no longer reads.
42
+ const profile = await runInSystemRowLevelSecurityScope("member resolution reads the stored user profile, a system tenant row", () => principalPlugin.resolveProfile(userId, { db }));
41
43
  if (!profile)
42
44
  throw memberResolutionDenied();
43
45
  // buildSessionRoles runs stripForbiddenMembershipRoles on the membership half (rebuild-resurrected roles).
@@ -71,7 +73,7 @@ export function createMemberReaderFn(ctx, tenantId, tx) {
71
73
  const cache = new Map();
72
74
  function resolve(userId) {
73
75
  const cached = cache.get(userId);
74
- if (cached)
76
+ if (cached !== undefined)
75
77
  return cached;
76
78
  const pending = resolveMember(ctx, tenantId, userId);
77
79
  cache.set(userId, pending);
@@ -64,7 +64,7 @@ async function replayMultiStreamProjectionIntoShadow(mspName, deps) {
64
64
  await createRebuildDeadLetterTable(db);
65
65
  const replayedIds = [];
66
66
  await db.begin(async (tx) => {
67
- await assertRebuildableRowLevelSecurity(tx, meta.tableName);
67
+ await assertRebuildableRowLevelSecurity(tx, meta);
68
68
  await resetConsumerForMspRebuild(tx, mspName, SHARED_INSTANCE_SENTINEL);
69
69
  await selectConsumerForUpdate(tx, mspName, SHARED_INSTANCE_SENTINEL);
70
70
  const { horizon, gaps: seededGaps } = await selectEventIdHorizonWithMissingRanges(tx);
@@ -0,0 +1,5 @@
1
+ import type { WriteResult } from "@cosmicdrift/kumiko-types/handlers";
2
+ import type { DbTx } from "../db/connection.ts";
3
+ import type { SessionUser } from "../engine/types/index.ts";
4
+ import type { DispatchContext } from "./dispatch-shared.ts";
5
+ export declare function rejectUnverifiedParent(ctx: DispatchContext, type: string, parentRow: Record<string, unknown>, parentId: string, user: SessionUser, tx: DbTx | undefined): Promise<WriteResult | undefined>;
@@ -0,0 +1,81 @@
1
+ import { createTenantDb, hasTenantColumn } from "../db/tenant-db.js";
2
+ import { checkWriteFieldOwnership } from "../engine/field-access.js";
3
+ import { AccessDeniedError, FrameworkReasons, writeFailure } from "../errors/index.js";
4
+ import { getTable, resolveDbSource } from "./dispatch-context-helpers.js";
5
+ function isForeignTenantParentRow(parentRow, user) {
6
+ const rowTenantId = parentRow["tenantId"];
7
+ return typeof rowTenantId === "string" && rowTenantId !== user.tenantId;
8
+ }
9
+ // A custom create handler may return a row without a string tenantId; the row's
10
+ // tenant is then unknown from the payload, so re-read it through the caller's tenant
11
+ // filter. Fail-closed: anything that cannot be verified counts as not visible.
12
+ // Tenant reads also return SYSTEM reference rows, so the row's own tenantId must match
13
+ // (same rule as the string path) unless the entity has no tenant column.
14
+ async function isParentRowHiddenFromCaller(ctx, parentEntityName, parentId, user, tx) {
15
+ if (parentEntityName === undefined)
16
+ return true;
17
+ const table = getTable(ctx, parentEntityName);
18
+ const source = resolveDbSource(ctx, tx);
19
+ if (!table || !source)
20
+ return true;
21
+ const callerDb = createTenantDb({ db: source, tenantId: user.tenantId, mode: "tenant" });
22
+ const visibleRow = await callerDb.fetchOne(table, { id: parentId });
23
+ if (visibleRow === undefined)
24
+ return true;
25
+ return hasTenantColumn(table) && visibleRow["tenantId"] !== user.tenantId;
26
+ }
27
+ // A custom create handler may return a partial row. The ownership check only
28
+ // inspects the keys it is given, so a row missing the ownership-bound field
29
+ // would be denied (rule evaluated against undefined) or skipped entirely.
30
+ // Complete it from the stored row, read through the caller's tenant filter.
31
+ async function completeParentRow(ctx, parentEntityName, parentEntity, parentRow, user, tx) {
32
+ if (Object.keys(parentEntity.fields).every((fieldName) => fieldName in parentRow)) {
33
+ return parentRow;
34
+ }
35
+ const table = getTable(ctx, parentEntityName);
36
+ const source = resolveDbSource(ctx, tx);
37
+ if (!table || !source || typeof parentRow["id"] !== "string")
38
+ return parentRow;
39
+ const stored = await createTenantDb({
40
+ db: source,
41
+ tenantId: user.tenantId,
42
+ mode: "tenant",
43
+ }).fetchOne(table, {
44
+ id: parentRow["id"],
45
+ });
46
+ return stored ? { ...stored, ...parentRow } : parentRow;
47
+ }
48
+ // A custom create handler may return an existing foreign row; verify it before attaching children.
49
+ export async function rejectUnverifiedParent(ctx, type, parentRow, parentId, user, tx) {
50
+ const { registry } = ctx;
51
+ const parentEntityName = registry.getHandlerEntity(type);
52
+ const isCallerScoped = !registry.isHandlerSystemScoped(type);
53
+ const isParentForeign = isCallerScoped &&
54
+ (typeof parentRow["tenantId"] === "string"
55
+ ? isForeignTenantParentRow(parentRow, user)
56
+ : await isParentRowHiddenFromCaller(ctx, parentEntityName, parentId, user, tx));
57
+ if (isParentForeign) {
58
+ return writeFailure(new AccessDeniedError({
59
+ message: `nested-write: parent row belongs to another tenant — refusing to attach children to "${type}"`,
60
+ details: { reason: FrameworkReasons.fieldAccessDenied, handler: type },
61
+ }));
62
+ }
63
+ if (!parentEntityName)
64
+ return undefined;
65
+ const parentEntity = registry.getEntity(parentEntityName);
66
+ if (!parentEntity)
67
+ return undefined;
68
+ const ownershipRow = await completeParentRow(ctx, parentEntityName, parentEntity, parentRow, user, tx);
69
+ const deniedField = checkWriteFieldOwnership(parentEntity, ownershipRow, user, undefined, ownershipRow, false);
70
+ if (!deniedField)
71
+ return undefined;
72
+ return writeFailure(new AccessDeniedError({
73
+ 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`,
74
+ i18nKey: "errors.access.fieldDenied",
75
+ details: {
76
+ reason: FrameworkReasons.fieldAccessDenied,
77
+ field: deniedField,
78
+ handler: type,
79
+ },
80
+ }));
81
+ }
@@ -1,5 +1,6 @@
1
1
  /// <reference types="temporal-polyfill/global" preserve="true" />
2
2
  import type { DbConnection } from "../db/connection.ts";
3
+ import { type ColumnDriftResult } from "../db/queries/shadow-swap.ts";
3
4
  import type { Registry } from "../engine/types/index.ts";
4
5
  import type { Meter } from "../observability/types/metric.ts";
5
6
  export declare const REBUILD_BATCH_SIZE = 1000;
@@ -24,6 +25,7 @@ type RebuildDeps = {
24
25
  readonly __test_onBeforeFence?: () => void | Promise<void>;
25
26
  readonly __test_onBuildShadowTable?: () => void;
26
27
  };
28
+ export declare function columnDriftLikelyCause(drift: ColumnDriftResult): string;
27
29
  export declare function rebuildProjection(projectionName: string, deps: RebuildDeps): Promise<RebuildResult>;
28
30
  export declare function getProjectionState(db: DbConnection, projectionName: string): Promise<{
29
31
  readonly name: string;
@@ -24,20 +24,29 @@ export const REBUILD_BATCH_SIZE = 1000;
24
24
  const MAX_UNLOCKED_BATCHES = 10_000;
25
25
  const DEFAULT_FENCE_LOCK_TIMEOUT_MS = 5_000;
26
26
  const TENANT_COLUMN_SUFFIX = ".tenant_id";
27
+ function sampledRowIds(drift) {
28
+ return new Set(drift.sample.map((s) => s.slice(0, s.lastIndexOf("."))));
29
+ }
30
+ export function columnDriftLikelyCause(drift) {
31
+ // A stream-tenant move (boot backfill) changes the stream's tenant, so the replayed row differs only in tenant_id.
32
+ // A truncated or empty sample proves nothing about the rows outside it.
33
+ const onlyTenantColumn = drift.sample.length > 0 &&
34
+ sampledRowIds(drift).size === drift.rowCount &&
35
+ drift.sample.every((s) => s.endsWith(TENANT_COLUMN_SUFFIX));
36
+ return onlyTenantColumn
37
+ ? "Expected cause: a stream-tenant move by the boot backfill (the replay carries the new stream tenant)."
38
+ : "Likely cause: a legacy direct-write predating the row's event history (#494), or a sensitive custom field pending #972. Investigate if unexpected.";
39
+ }
27
40
  // Ops-facing log line for countColumnDrift's result. No-op when clean.
28
41
  function warnOnColumnDrift(projectionName, tableName, drift) {
29
42
  // skip: no drift found — nothing to warn about
30
43
  if (drift.rowCount === 0)
31
44
  return;
32
- const sampledIds = new Set(drift.sample.map((s) => s.slice(0, s.lastIndexOf("."))));
45
+ const sampledIds = sampledRowIds(drift);
33
46
  const countLabel = sampledIds.size < drift.rowCount
34
47
  ? `${drift.rowCount} (sample truncated)`
35
48
  : String(drift.rowCount);
36
- // A stream-tenant move (boot backfill) changes the stream's tenant, so the replayed row differs only in tenant_id.
37
- const onlyTenantColumn = drift.sample.every((s) => s.endsWith(TENANT_COLUMN_SUFFIX));
38
- const likelyCause = onlyTenantColumn
39
- ? "Expected cause: a stream-tenant move by the boot backfill (the replay carries the new stream tenant)."
40
- : "Likely cause: a legacy direct-write predating the row's event history (#494), or a sensitive custom field pending #972. Investigate if unexpected.";
49
+ const likelyCause = columnDriftLikelyCause(drift);
41
50
  log.warn(`projection "${projectionName}": ${countLabel} live row(s) in "${tableName}" have ` +
42
51
  `column values that differ from the freshly-replayed shadow (sample: ${drift.sample.join(", ")}). ` +
43
52
  `Not blocking — replay wins on swap. ${likelyCause}`);
@@ -117,7 +126,7 @@ async function replayProjectionIntoShadow(projectionName, deps) {
117
126
  if (skipApplyErrors)
118
127
  await createRebuildDeadLetterTable(db);
119
128
  await db.begin(async (tx) => {
120
- await assertRebuildableRowLevelSecurity(tx, meta.tableName);
129
+ await assertRebuildableRowLevelSecurity(tx, meta);
121
130
  await markProjectionRebuilding(tx, projectionName);
122
131
  await assertLiveColumnsMatchMeta(tx, meta, projectionName);
123
132
  await buildShadowTable(tx, meta);
@@ -1,6 +1,5 @@
1
1
  import { bigint, index, instant, table as pgTable, sql, text } from "../db/dialect.js";
2
- import { tableExists } from "../db/schema-inspection.js";
3
- import { unsafePushTables } from "../db/table-push.js";
2
+ import { pushTableIfMissing } from "../db/table-push.js";
4
3
  // Framework-level state for every registered projection. One row per qualified
5
4
  // projection name. Written by the rebuild machinery; read by the CLI + any
6
5
  // status dashboard. Lives alongside the events table as framework infra —
@@ -39,8 +38,7 @@ export const projectionStateTable = pgTable("kumiko_projections", {
39
38
  // already there (second stack in same test DB, production boot after
40
39
  // migration), skip cleanly.
41
40
  export async function createProjectionStateTable(db) {
42
- // skip: table already exists — bootstrap is called from multiple paths
43
- if (await tableExists(db, "public.kumiko_projections"))
44
- return;
45
- await unsafePushTables(db, { kumikoProjections: projectionStateTable });
41
+ await pushTableIfMissing(db, "public.kumiko_projections", {
42
+ kumikoProjections: projectionStateTable,
43
+ });
46
44
  }