@cosmicdrift/kumiko-framework 0.413.0 → 0.414.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (467) hide show
  1. package/AGENTS.md +5 -2
  2. package/agents/api/framework-db.md +14 -3
  3. package/agents/api/framework-engine.md +64 -13
  4. package/agents/api/framework-event-store.md +14 -0
  5. package/agents/api/framework-ui-types.md +149 -21
  6. package/agents/api/renderer-web.md +93 -9
  7. package/agents/api/testing-helpers.md +3 -2
  8. package/agents/api/testing-stack.md +3 -0
  9. package/agents/api/types.md +205 -14
  10. package/agents/api.md +7 -7
  11. package/agents/boot-rules.md +63 -9
  12. package/agents/examples/api-docs.md +2 -6
  13. package/agents/examples/auth-mfa.md +57 -10
  14. package/agents/examples/chat-channels.md +2 -0
  15. package/agents/examples/currencies-global.md +1 -0
  16. package/agents/examples/env-composition.md +7 -11
  17. package/agents/examples/helpdesk.md +15 -8
  18. package/agents/examples/managed-pages.md +90 -1
  19. package/agents/examples/pwa-shell.md +210 -0
  20. package/agents/examples/rate-limiting.md +3 -3
  21. package/agents/examples/record-detail-layout.md +1537 -67
  22. package/agents/examples/workflow-engine.md +16 -12
  23. package/agents/examples.md +1 -0
  24. package/agents/features-index.md +4 -2
  25. package/agents/features.md +22 -7
  26. package/agents/widgets.md +19 -1
  27. package/dist/api/api-constants.d.ts +1 -0
  28. package/dist/api/api-constants.js +4 -0
  29. package/dist/api/auth-middleware.js +4 -3
  30. package/dist/api/auth-routes-shared.js +2 -1
  31. package/dist/api/entity-read-access.d.ts +1 -0
  32. package/dist/api/entity-read-access.js +18 -0
  33. package/dist/api/export/export-route.d.ts +6 -1
  34. package/dist/api/export/export-route.js +27 -1
  35. package/dist/api/export/export-rows.js +19 -3
  36. package/dist/api/routes.d.ts +2 -0
  37. package/dist/api/routes.js +9 -1
  38. package/dist/api/server-extra-routes.js +2 -1
  39. package/dist/api/server-feature-http-routes.d.ts +9 -0
  40. package/dist/api/server-feature-http-routes.js +109 -0
  41. package/dist/api/server-middleware.js +2 -19
  42. package/dist/api/server-pat-rate-limit-guard.d.ts +3 -0
  43. package/dist/api/server-pat-rate-limit-guard.js +19 -0
  44. package/dist/api/server-rate-limit-wiring.d.ts +10 -0
  45. package/dist/api/server-rate-limit-wiring.js +37 -0
  46. package/dist/api/server-routes.d.ts +4 -12
  47. package/dist/api/server-routes.js +12 -171
  48. package/dist/api/server-schema-route.d.ts +3 -0
  49. package/dist/api/server-schema-route.js +58 -0
  50. package/dist/api/server-wiring.js +2 -37
  51. package/dist/api/server.js +3 -1
  52. package/dist/compliance/override-schema.js +5 -5
  53. package/dist/compliance/sub-processors.js +10 -1
  54. package/dist/crypto/index.d.ts +1 -1
  55. package/dist/crypto/index.js +1 -1
  56. package/dist/crypto/pii-field-encryption.d.ts +2 -0
  57. package/dist/crypto/pii-field-encryption.js +16 -1
  58. package/dist/db/apply-entity-event.js +4 -0
  59. package/dist/db/bun-sql-connection-codes.d.ts +1 -0
  60. package/dist/db/bun-sql-connection-codes.js +7 -0
  61. package/dist/db/collect-table-metas.js +4 -1
  62. package/dist/db/config-seed.js +1 -1
  63. package/dist/db/derived-field-sql.js +15 -13
  64. package/dist/db/derived-related-sql.d.ts +2 -2
  65. package/dist/db/derived-related-sql.js +4 -2
  66. package/dist/db/dialect.d.ts +3 -0
  67. package/dist/db/dialect.js +1 -3
  68. package/dist/db/driver-row-coercion.js +2 -2
  69. package/dist/db/driver-value-preparation.js +1 -1
  70. package/dist/db/eagerload.js +15 -12
  71. package/dist/db/entity-table-meta.d.ts +2 -0
  72. package/dist/db/entity-table-meta.js +7 -0
  73. package/dist/db/event-store-executor-context.js +13 -8
  74. package/dist/db/event-store-executor-read-aggregate-currencies.js +2 -2
  75. package/dist/db/event-store-executor-read-aggregate.js +2 -2
  76. package/dist/db/event-store-executor-read-filter.d.ts +4 -0
  77. package/dist/db/event-store-executor-read-filter.js +28 -11
  78. package/dist/db/event-store-executor-read-search.d.ts +1 -0
  79. package/dist/db/event-store-executor-read-search.js +6 -6
  80. package/dist/db/event-store-executor-read-sort.js +3 -3
  81. package/dist/db/event-store-executor-read-where.js +14 -5
  82. package/dist/db/event-store-executor-read.js +7 -7
  83. package/dist/db/event-store-executor-write.js +50 -95
  84. package/dist/db/executor-managed-tables.js +4 -1
  85. package/dist/db/index.d.ts +4 -2
  86. package/dist/db/index.js +4 -2
  87. package/dist/db/known-table-names.d.ts +1 -0
  88. package/dist/db/known-table-names.js +7 -5
  89. package/dist/db/list-aggregate-labels.d.ts +1 -0
  90. package/dist/db/list-aggregate-labels.js +9 -1
  91. package/dist/db/migrate-generator.js +23 -4
  92. package/dist/db/migrate-rls-diff.d.ts +1 -0
  93. package/dist/db/migrate-rls-diff.js +15 -1
  94. package/dist/db/migrate-runner.js +2 -2
  95. package/dist/db/money.d.ts +1 -1
  96. package/dist/db/money.js +1 -4
  97. package/dist/db/parent-ref-clause.d.ts +6 -2
  98. package/dist/db/parent-ref-clause.js +76 -23
  99. package/dist/db/parent-ref-global-hosts.d.ts +20 -0
  100. package/dist/db/parent-ref-global-hosts.js +47 -0
  101. package/dist/db/production-schema-command-hint.d.ts +1 -0
  102. package/dist/db/production-schema-command-hint.js +3 -0
  103. package/dist/db/queries/backfill-pii.js +55 -29
  104. package/dist/db/queries/ddl.js +13 -2
  105. package/dist/db/queries/event-store-open-streams.d.ts +15 -0
  106. package/dist/db/queries/event-store-open-streams.js +33 -0
  107. package/dist/db/queries/event-store-payload-scrub.d.ts +5 -0
  108. package/dist/db/queries/event-store-payload-scrub.js +11 -0
  109. package/dist/db/queries/event-store.js +0 -1
  110. package/dist/db/queries/raw-sql.js +0 -1
  111. package/dist/db/queries/rebuild-rls-guard.d.ts +2 -1
  112. package/dist/db/queries/rebuild-rls-guard.js +24 -11
  113. package/dist/db/queries/rls-boot-catalog.d.ts +1 -0
  114. package/dist/db/queries/rls-boot-catalog.js +13 -8
  115. package/dist/db/queries/rls-shape.d.ts +2 -1
  116. package/dist/db/queries/rls-shape.js +10 -0
  117. package/dist/db/queries/session-advisory-lock.js +2 -1
  118. package/dist/db/queries/test-stack.js +7 -7
  119. package/dist/db/query.js +16 -11
  120. package/dist/db/rebuild-marker.js +11 -2
  121. package/dist/db/render-rls-ddl.d.ts +2 -0
  122. package/dist/db/render-rls-ddl.js +16 -11
  123. package/dist/db/replay-migration-sql.js +1 -1
  124. package/dist/db/row-level-security-boot-check.js +18 -5
  125. package/dist/db/row-level-security-connection.js +25 -12
  126. package/dist/db/row-level-security-scope.d.ts +2 -1
  127. package/dist/db/row-level-security-scope.js +9 -5
  128. package/dist/db/sql-identifier.d.ts +1 -0
  129. package/dist/db/sql-identifier.js +3 -0
  130. package/dist/db/system-tenant-read-db.d.ts +5 -0
  131. package/dist/db/system-tenant-read-db.js +28 -0
  132. package/dist/db/table-builder.d.ts +3 -1
  133. package/dist/db/table-builder.js +18 -8
  134. package/dist/db/table-info.d.ts +1 -2
  135. package/dist/db/table-introspection.d.ts +3 -0
  136. package/dist/db/table-introspection.js +6 -0
  137. package/dist/db/table-push.d.ts +1 -0
  138. package/dist/db/table-push.js +7 -1
  139. package/dist/db/tenant-db-runner.d.ts +3 -0
  140. package/dist/db/tenant-db-runner.js +19 -1
  141. package/dist/db/transaction-serialization.d.ts +1 -0
  142. package/dist/db/transaction-serialization.js +20 -3
  143. package/dist/db/where-clause.js +11 -2
  144. package/dist/db/write-ownership-failures.d.ts +25 -0
  145. package/dist/db/write-ownership-failures.js +82 -0
  146. package/dist/engine/boot-validator/boot-check.js +7 -1
  147. package/dist/engine/boot-validator/boot-phases-app.js +5 -5
  148. package/dist/engine/boot-validator/boot-phases.js +3 -2
  149. package/dist/engine/boot-validator/boot-rules.d.ts +293 -26
  150. package/dist/engine/boot-validator/boot-rules.js +4 -0
  151. package/dist/engine/boot-validator/bundled-lists-table.js +2 -2
  152. package/dist/engine/boot-validator/card-meta-overflow.js +1 -0
  153. package/dist/engine/boot-validator/config-deps.d.ts +0 -1
  154. package/dist/engine/boot-validator/config-deps.js +0 -28
  155. package/dist/engine/boot-validator/config-key-rules.d.ts +0 -15
  156. package/dist/engine/boot-validator/config-key-rules.js +0 -15
  157. package/dist/engine/boot-validator/dashboard-screen-target.d.ts +22 -0
  158. package/dist/engine/boot-validator/dashboard-screen-target.js +20 -0
  159. package/dist/engine/boot-validator/dashboard-stat-navigate.d.ts +1 -0
  160. package/dist/engine/boot-validator/dashboard-stat-navigate.js +25 -17
  161. package/dist/engine/boot-validator/definition-webhook-events-rules.d.ts +5 -0
  162. package/dist/engine/boot-validator/definition-webhook-events-rules.js +5 -0
  163. package/dist/engine/boot-validator/derived-sql-fields.js +1 -2
  164. package/dist/engine/boot-validator/entity-declaration-rules.d.ts +5 -0
  165. package/dist/engine/boot-validator/entity-declaration-rules.js +5 -0
  166. package/dist/engine/boot-validator/entity-list-screens.d.ts +1 -0
  167. package/dist/engine/boot-validator/entity-list-screens.js +33 -6
  168. package/dist/engine/boot-validator/entity-structure-rules.d.ts +5 -0
  169. package/dist/engine/boot-validator/entity-structure-rules.js +5 -0
  170. package/dist/engine/boot-validator/list-column-layout.js +10 -6
  171. package/dist/engine/boot-validator/list-row-guidance-rules.d.ts +67 -0
  172. package/dist/engine/boot-validator/list-row-guidance-rules.js +67 -0
  173. package/dist/engine/boot-validator/list-row-guidance.d.ts +20 -0
  174. package/dist/engine/boot-validator/list-row-guidance.js +129 -0
  175. package/dist/engine/boot-validator/list-sort-summary-rules.d.ts +42 -0
  176. package/dist/engine/boot-validator/list-sort-summary-rules.js +42 -0
  177. package/dist/engine/boot-validator/list-sort-summary.d.ts +5 -0
  178. package/dist/engine/boot-validator/list-sort-summary.js +149 -0
  179. package/dist/engine/boot-validator/list-table-options.js +15 -1
  180. package/dist/engine/boot-validator/list-table-rules.d.ts +10 -5
  181. package/dist/engine/boot-validator/list-table-rules.js +10 -5
  182. package/dist/engine/boot-validator/list-toolbar-options.d.ts +10 -0
  183. package/dist/engine/boot-validator/list-toolbar-options.js +31 -0
  184. package/dist/engine/boot-validator/named-filter-rules.d.ts +32 -2
  185. package/dist/engine/boot-validator/named-filter-rules.js +32 -2
  186. package/dist/engine/boot-validator/ownership.js +10 -1
  187. package/dist/engine/boot-validator/parent-ref.js +87 -50
  188. package/dist/engine/boot-validator/projection-list-screens.d.ts +1 -0
  189. package/dist/engine/boot-validator/projection-list-screens.js +31 -1
  190. package/dist/engine/boot-validator/query-output-columns.js +62 -9
  191. package/dist/engine/boot-validator/query-output-guidance.d.ts +7 -0
  192. package/dist/engine/boot-validator/query-output-guidance.js +39 -0
  193. package/dist/engine/boot-validator/query-refs.js +24 -1
  194. package/dist/engine/boot-validator/row-decoration.d.ts +11 -0
  195. package/dist/engine/boot-validator/row-decoration.js +16 -0
  196. package/dist/engine/boot-validator/screens-dashboard-links.d.ts +10 -0
  197. package/dist/engine/boot-validator/screens-dashboard-links.js +36 -0
  198. package/dist/engine/boot-validator/screens-dashboard-narrow.d.ts +4 -0
  199. package/dist/engine/boot-validator/screens-dashboard-narrow.js +211 -0
  200. package/dist/engine/boot-validator/screens-dashboard-rules.d.ts +84 -4
  201. package/dist/engine/boot-validator/screens-dashboard-rules.js +84 -4
  202. package/dist/engine/boot-validator/screens-dashboard.js +29 -7
  203. package/dist/engine/boot-validator/screens-kind-entity-list.js +32 -27
  204. package/dist/engine/boot-validator/screens-kind-projection-detail-guidance.d.ts +3 -0
  205. package/dist/engine/boot-validator/screens-kind-projection-detail-guidance.js +46 -0
  206. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +20 -0
  207. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +20 -0
  208. package/dist/engine/boot-validator/screens-kind-projection-detail.js +2 -0
  209. package/dist/engine/boot-validator/screens-kind-projection-list.js +4 -0
  210. package/dist/engine/boot-validator/screens-kind-rules.d.ts +25 -0
  211. package/dist/engine/boot-validator/screens-kind-rules.js +25 -0
  212. package/dist/engine/boot-validator/screens-lists.d.ts +8 -2
  213. package/dist/engine/boot-validator/screens-lists.js +19 -3
  214. package/dist/engine/boot-validator/screens.js +1 -1
  215. package/dist/engine/boot-validator/sort-nulls.d.ts +2 -0
  216. package/dist/engine/boot-validator/sort-nulls.js +15 -0
  217. package/dist/engine/boot-validator/zod-shape.d.ts +2 -1
  218. package/dist/engine/boot-validator/zod-shape.js +19 -1
  219. package/dist/engine/build-app-schema.js +4 -0
  220. package/dist/engine/config-helpers.d.ts +1 -2
  221. package/dist/engine/config-helpers.js +6 -7
  222. package/dist/engine/define-feature.js +1 -0
  223. package/dist/engine/define-handler.d.ts +1 -0
  224. package/dist/engine/define-handler.js +4 -2
  225. package/dist/engine/definition-violations.js +2 -2
  226. package/dist/engine/entity-handlers.js +3 -8
  227. package/dist/engine/entity-list-runtime-options.js +9 -8
  228. package/dist/engine/factories.d.ts +2 -0
  229. package/dist/engine/feature-config-events-jobs.js +1 -0
  230. package/dist/engine/feature-entity-handlers.js +5 -2
  231. package/dist/engine/field-access.d.ts +1 -1
  232. package/dist/engine/field-access.js +7 -10
  233. package/dist/engine/find-entity.js +3 -3
  234. package/dist/engine/form-derivations.js +3 -3
  235. package/dist/engine/index.d.ts +3 -3
  236. package/dist/engine/index.js +2 -2
  237. package/dist/engine/named-filter-roles.d.ts +3 -0
  238. package/dist/engine/named-filter-roles.js +23 -0
  239. package/dist/engine/pipeline.js +0 -1
  240. package/dist/engine/project-app-schema-for-roles.js +17 -2
  241. package/dist/engine/qualified-name.js +0 -1
  242. package/dist/engine/registry-facade.js +1 -2
  243. package/dist/engine/registry-state.d.ts +1 -1
  244. package/dist/engine/registry-state.js +5 -2
  245. package/dist/engine/registry-validate.d.ts +1 -0
  246. package/dist/engine/registry-validate.js +9 -1
  247. package/dist/engine/registry.js +2 -1
  248. package/dist/engine/resolve-named-list-filters.js +5 -2
  249. package/dist/engine/schema-builder.js +6 -10
  250. package/dist/engine/screen-helpers.d.ts +12 -0
  251. package/dist/engine/screen-helpers.js +17 -1
  252. package/dist/engine/soft-delete-cleanup.js +5 -8
  253. package/dist/engine/state-machine.js +0 -1
  254. package/dist/engine/steps/_database-clock.d.ts +2 -0
  255. package/dist/engine/steps/_database-clock.js +6 -0
  256. package/dist/engine/steps/compute.js +1 -1
  257. package/dist/engine/steps/retry.js +5 -1
  258. package/dist/engine/steps/return.js +0 -1
  259. package/dist/engine/steps/wait-for-event.js +2 -1
  260. package/dist/engine/steps/wait.js +2 -1
  261. package/dist/engine/system-user.d.ts +2 -2
  262. package/dist/engine/system-user.js +2 -2
  263. package/dist/engine/types/handlers.d.ts +1 -1
  264. package/dist/engine/types/handlers.js +1 -1
  265. package/dist/engine/types/screen.d.ts +1 -1
  266. package/dist/engine/types/screen.js +1 -1
  267. package/dist/engine/webhook-contracts.d.ts +2 -3
  268. package/dist/engine/webhook-contracts.js +2 -25
  269. package/dist/engine/webhook-events.js +48 -29
  270. package/dist/engine/webhook-payload-strictness.d.ts +7 -0
  271. package/dist/engine/webhook-payload-strictness.js +53 -0
  272. package/dist/env/_zod-introspect.d.ts +1 -0
  273. package/dist/env/dry-run.d.ts +1 -1
  274. package/dist/env/dry-run.js +1 -1
  275. package/dist/env/field-meta.d.ts +4 -0
  276. package/dist/env/field-meta.js +67 -0
  277. package/dist/env/field-rules.d.ts +9 -0
  278. package/dist/env/field-rules.js +46 -0
  279. package/dist/env/index.d.ts +3 -3
  280. package/dist/env/index.js +16 -71
  281. package/dist/env/internals.d.ts +3 -0
  282. package/dist/env/internals.js +1 -2
  283. package/dist/env/required-env.d.ts +3 -1
  284. package/dist/env/required-env.js +5 -2
  285. package/dist/errors/serialize.js +2 -2
  286. package/dist/errors/write-error-info.js +0 -2
  287. package/dist/es-ops/operations-schema.js +18 -7
  288. package/dist/event-store/admin-api.js +3 -3
  289. package/dist/event-store/event-store.js +0 -3
  290. package/dist/event-store/index.d.ts +1 -0
  291. package/dist/event-store/index.js +1 -0
  292. package/dist/event-store/transfer.js +1 -1
  293. package/dist/files/assert-file-refs-belong-to-tenant.d.ts +2 -1
  294. package/dist/files/assert-file-refs-belong-to-tenant.js +15 -13
  295. package/dist/files/bind-pending-file-refs.d.ts +3 -1
  296. package/dist/files/bind-pending-file-refs.js +54 -27
  297. package/dist/files/copy-pending-file-refs-to-tenant.js +7 -3
  298. package/dist/files/create-file-ref.d.ts +4 -1
  299. package/dist/files/create-file-ref.js +14 -3
  300. package/dist/files/default-file-guard.js +4 -1
  301. package/dist/files/feature.js +1 -0
  302. package/dist/files/file-claim.d.ts +6 -0
  303. package/dist/files/file-claim.js +17 -0
  304. package/dist/files/file-field-slots.d.ts +2 -0
  305. package/dist/files/file-field-slots.js +28 -0
  306. package/dist/files/file-ref-entity.d.ts +3 -0
  307. package/dist/files/file-ref-entity.js +2 -0
  308. package/dist/files/file-ref-table.d.ts +3 -0
  309. package/dist/files/file-routes.d.ts +4 -1
  310. package/dist/files/file-routes.js +80 -16
  311. package/dist/files/in-memory-provider.d.ts +1 -1
  312. package/dist/files/in-memory-provider.js +2 -1
  313. package/dist/files/index.d.ts +1 -1
  314. package/dist/files/index.js +1 -1
  315. package/dist/files/invalid-file-ref-error.d.ts +2 -0
  316. package/dist/files/invalid-file-ref-error.js +15 -0
  317. package/dist/files/local-provider.js +9 -2
  318. package/dist/files/provider-resolver.js +1 -1
  319. package/dist/files/rebind-file-ref.d.ts +3 -2
  320. package/dist/files/rebind-file-ref.js +24 -18
  321. package/dist/files/resolve-file-handles.d.ts +13 -0
  322. package/dist/files/resolve-file-handles.js +57 -0
  323. package/dist/files/storage-tracking.d.ts +1 -1
  324. package/dist/files/storage-tracking.js +5 -2
  325. package/dist/files/sweep-stale-pending-file-refs.js +10 -4
  326. package/dist/files/types.d.ts +4 -0
  327. package/dist/files/types.js +10 -0
  328. package/dist/files/upload-field-resolution.d.ts +1 -0
  329. package/dist/files/upload-field-resolution.js +16 -2
  330. package/dist/files/upload-ledger.js +1 -1
  331. package/dist/i18n/required-surface-guidance-keys.d.ts +3 -0
  332. package/dist/i18n/required-surface-guidance-keys.js +9 -0
  333. package/dist/i18n/required-surface-keys.js +19 -4
  334. package/dist/internal/boot-rule-table-expectations.d.ts +2 -0
  335. package/dist/internal/boot-rule-table-expectations.js +29 -0
  336. package/dist/internal/row-level-security.d.ts +1 -0
  337. package/dist/internal/row-level-security.js +1 -0
  338. package/dist/internal/testing.d.ts +1 -0
  339. package/dist/internal/testing.js +1 -0
  340. package/dist/jobs/index.d.ts +1 -0
  341. package/dist/jobs/index.js +1 -0
  342. package/dist/jobs/job-load-events.d.ts +10 -0
  343. package/dist/jobs/job-load-events.js +12 -0
  344. package/dist/jobs/job-runner-context.js +6 -158
  345. package/dist/jobs/job-runner-dispatch.d.ts +7 -0
  346. package/dist/jobs/job-runner-dispatch.js +57 -0
  347. package/dist/jobs/job-runner-event-triggers.js +18 -9
  348. package/dist/jobs/job-runner-execution.js +2 -2
  349. package/dist/jobs/job-runner-facets.d.ts +48 -0
  350. package/dist/jobs/job-runner-facets.js +156 -0
  351. package/dist/jobs/job-runner-gates.js +24 -12
  352. package/dist/jobs/job-runner-helpers.d.ts +5 -1
  353. package/dist/jobs/job-runner-helpers.js +18 -3
  354. package/dist/jobs/job-runner-scope.d.ts +1 -0
  355. package/dist/jobs/job-runner-scope.js +2 -0
  356. package/dist/jobs/job-runner-tenant-cap-lock.d.ts +2 -0
  357. package/dist/jobs/job-runner-tenant-cap-lock.js +30 -0
  358. package/dist/jobs/job-runner.js +31 -70
  359. package/dist/jobs/obliterate-job-queues.d.ts +6 -0
  360. package/dist/jobs/obliterate-job-queues.js +23 -0
  361. package/dist/lifecycle/lifecycle.js +1 -1
  362. package/dist/migrations/event-header-scrub.d.ts +11 -0
  363. package/dist/migrations/event-header-scrub.js +33 -0
  364. package/dist/migrations/event-payload-scrub.d.ts +1 -1
  365. package/dist/migrations/event-payload-scrub.js +36 -4
  366. package/dist/migrations/index.d.ts +1 -0
  367. package/dist/migrations/index.js +2 -0
  368. package/dist/migrations/kumiko-drift.d.ts +5 -2
  369. package/dist/migrations/kumiko-drift.js +51 -14
  370. package/dist/migrations/pending-rebuilds.js +4 -5
  371. package/dist/observability/sensitive-filter.js +0 -12
  372. package/dist/pipeline/aggregate-type-removal.js +17 -4
  373. package/dist/pipeline/context-services.d.ts +2 -0
  374. package/dist/pipeline/context-services.js +5 -2
  375. package/dist/pipeline/dispatch-batch.js +4 -3
  376. package/dist/pipeline/dispatch-context-helpers.d.ts +11 -0
  377. package/dist/pipeline/dispatch-context-helpers.js +58 -0
  378. package/dist/pipeline/dispatch-nested-write.d.ts +7 -0
  379. package/dist/pipeline/dispatch-nested-write.js +119 -0
  380. package/dist/pipeline/dispatch-query.js +10 -3
  381. package/dist/pipeline/dispatch-scope.js +4 -3
  382. package/dist/pipeline/dispatch-shared.d.ts +2 -6
  383. package/dist/pipeline/dispatch-shared.js +6 -38
  384. package/dist/pipeline/dispatch-write.d.ts +0 -1
  385. package/dist/pipeline/dispatch-write.js +3 -302
  386. package/dist/pipeline/dispatcher-utils.js +6 -0
  387. package/dist/pipeline/effective-system-scope.d.ts +3 -0
  388. package/dist/pipeline/effective-system-scope.js +22 -0
  389. package/dist/pipeline/event-dispatcher-delivery.d.ts +1 -0
  390. package/dist/pipeline/event-dispatcher-delivery.js +17 -9
  391. package/dist/pipeline/event-dispatcher.d.ts +4 -1
  392. package/dist/pipeline/event-dispatcher.js +6 -7
  393. package/dist/pipeline/handler-context-auth.d.ts +3 -2
  394. package/dist/pipeline/handler-context-auth.js +3 -4
  395. package/dist/pipeline/handler-context-db.js +11 -4
  396. package/dist/pipeline/handler-context-dispatch.js +2 -2
  397. package/dist/pipeline/handler-context-events.d.ts +8 -3
  398. package/dist/pipeline/handler-context-events.js +20 -65
  399. package/dist/pipeline/handler-context-member-resolution.js +16 -8
  400. package/dist/pipeline/handler-context-notify.d.ts +1 -0
  401. package/dist/pipeline/handler-context-notify.js +2 -0
  402. package/dist/pipeline/handler-context-phase-denials.js +3 -2
  403. package/dist/pipeline/handler-context-projection.d.ts +3 -0
  404. package/dist/pipeline/handler-context-projection.js +39 -0
  405. package/dist/pipeline/handler-context-scope.d.ts +1 -1
  406. package/dist/pipeline/handler-context-scope.js +14 -2
  407. package/dist/pipeline/index.d.ts +1 -1
  408. package/dist/pipeline/index.js +1 -1
  409. package/dist/pipeline/lifecycle-pipeline.d.ts +1 -0
  410. package/dist/pipeline/lifecycle-pipeline.js +7 -4
  411. package/dist/pipeline/member-reader.js +4 -2
  412. package/dist/pipeline/msp-rebuild.js +1 -1
  413. package/dist/pipeline/nested-write-parent-guard.d.ts +5 -0
  414. package/dist/pipeline/nested-write-parent-guard.js +81 -0
  415. package/dist/pipeline/projection-rebuild.d.ts +2 -0
  416. package/dist/pipeline/projection-rebuild.js +16 -7
  417. package/dist/pipeline/projection-state.js +4 -6
  418. package/dist/pipeline/system-hooks.js +36 -6
  419. package/dist/pipeline/write-result-masking.js +31 -3
  420. package/dist/pipeline/write-transition-guard.d.ts +7 -0
  421. package/dist/pipeline/write-transition-guard.js +95 -0
  422. package/dist/schema-cli/shared.d.ts +2 -0
  423. package/dist/schema-cli/shared.js +4 -2
  424. package/dist/schema-cli/validate-command.js +43 -28
  425. package/dist/search/meilisearch-adapter.js +14 -9
  426. package/dist/search/reindex-entity.d.ts +2 -0
  427. package/dist/search/reindex-entity.js +32 -4
  428. package/dist/search/reindex-tenants-search.js +20 -4
  429. package/dist/time/tz-context.js +1 -1
  430. package/dist/ui-types/card-column-roles.d.ts +4 -0
  431. package/dist/ui-types/card-column-roles.js +6 -3
  432. package/dist/ui-types/index.d.ts +2 -2
  433. package/dist/ui-types/index.js +1 -1
  434. package/dist/utils/ids.js +0 -1
  435. package/dist/utils/index.d.ts +1 -0
  436. package/dist/utils/index.js +1 -0
  437. package/dist/utils/return-path-limit.d.ts +1 -0
  438. package/dist/utils/return-path-limit.js +1 -0
  439. package/package.json +5 -3
  440. package/presets/biome-app.json +39 -21
  441. package/presets/biome-plugins/admin-api.grit +10 -0
  442. package/presets/biome-plugins/error-reasons.grit +53 -0
  443. package/presets/biome-plugins/es-literal-writes-tests.grit +18 -0
  444. package/presets/biome-plugins/es-literal-writes.grit +22 -0
  445. package/presets/biome-plugins/i18n-locale-terminology-de.grit +15 -0
  446. package/presets/biome-plugins/i18n-locale-terminology-romance.grit +10 -0
  447. package/presets/biome-plugins/no-create-test-dispatcher.grit +5 -0
  448. package/presets/biome-plugins/no-css-properties-type.grit +7 -0
  449. package/presets/biome-plugins/no-date-api.grit +9 -0
  450. package/presets/biome-plugins/no-direct-fetch.grit +16 -0
  451. package/presets/biome-plugins/no-direct-fs.grit +16 -0
  452. package/presets/biome-plugins/no-external-font-cdn-css.grit +9 -0
  453. package/presets/biome-plugins/no-external-font-cdn.grit +12 -0
  454. package/presets/biome-plugins/no-raw-hooks.grit +10 -0
  455. package/presets/biome-plugins/no-same-folder-barrel-import.grit +11 -0
  456. package/presets/biome-plugins/no-screen-container-classes.grit +7 -0
  457. package/presets/biome-plugins/no-skipped-or-retried-tests.grit +34 -0
  458. package/presets/biome-plugins/no-temporal-polyfill-require.grit +10 -0
  459. package/presets/biome-plugins/raw-html-in-web.grit +40 -0
  460. package/presets/biome-plugins/raw-ui-in-app.grit +142 -0
  461. package/presets/biome-plugins/restricted-event-store-symbols.grit +18 -0
  462. package/presets/biome-plugins/test-title.grit +20 -0
  463. package/presets/biome-plugins/unsafe-json-parse.grit +6 -0
  464. package/presets/biome-rules.json +465 -0
  465. package/src/changes.json +309 -0
  466. package/dist/engine/minor-units.d.ts +0 -2
  467. package/dist/engine/minor-units.js +0 -8
@@ -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
  }
@@ -117,8 +117,20 @@ function searchOperationKey(op) {
117
117
  // delete-then-restore ⇒ index wins.
118
118
  async function resolveSearchOperationsByTenant(events, ctx, registry) {
119
119
  const byKey = new Map();
120
+ const unresolved = new Map();
120
121
  for (const event of events) {
121
- const op = await resolveSearchOperation(event, ctx, registry);
122
+ let op;
123
+ try {
124
+ op = await resolveSearchOperation(event, ctx, registry);
125
+ }
126
+ catch (error) {
127
+ const previous = unresolved.get(event.tenantId);
128
+ unresolved.set(event.tenantId, {
129
+ eventIds: [...(previous?.eventIds ?? []), event.id],
130
+ error: previous?.error ?? error,
131
+ });
132
+ continue;
133
+ }
122
134
  if (!op)
123
135
  continue;
124
136
  const key = searchOperationKey(op);
@@ -140,7 +152,7 @@ async function resolveSearchOperationsByTenant(events, ctx, registry) {
140
152
  else
141
153
  bucket.toRemove.push({ entityType: op.entityType, entityId: op.entityId });
142
154
  }
143
- return perTenant;
155
+ return { perTenant, unresolved };
144
156
  }
145
157
  // Flushes one tenant's collapsed ops — indexBatch/removeBatch when the
146
158
  // adapter implements them, otherwise falls back to looping the single-doc
@@ -239,14 +251,32 @@ export function createSearchEventConsumer(searchAdapter, registry, options = {})
239
251
  // One tenant's failing index must not stall the others: its failing ops are held for a later
240
252
  // turn, and while it backs off all of its ops wait, so per-entity order survives.
241
253
  batchHandler: async (events, ctx, turn) => {
242
- const perTenant = await resolveSearchOperationsByTenant(events, ctx, registry);
243
- for (const [tenantId, bucket] of perTenant) {
254
+ const { perTenant, unresolved } = await resolveSearchOperationsByTenant(events, ctx, registry);
255
+ const tenantIds = new Set([...perTenant.keys(), ...unresolved.keys()]);
256
+ for (const tenantId of tenantIds) {
257
+ const bucket = perTenant.get(tenantId);
258
+ const unresolvedOps = unresolved.get(tenantId);
244
259
  const retry = tenantRetries.get(tenantId);
245
260
  if (retry && retry.retryAtMs > now()) {
246
- turn.holdForRetry(bucket.sourcedOps.map((s) => s.sourceEventId), retry.reason);
261
+ turn.holdForRetry([
262
+ ...(bucket?.sourcedOps.map((s) => s.sourceEventId) ?? []),
263
+ ...(unresolvedOps?.eventIds ?? []),
264
+ ], retry.reason, { stillBackingOff: true });
247
265
  continue;
248
266
  }
249
- const held = await flushTenantHoldingFailedOperations(searchAdapter, tenantId, bucket);
267
+ // An unresolved event may carry an earlier op for an entity a later resolved op targets
268
+ // (update fails, delete resolves); writing the later op now would let the retry resurrect it.
269
+ const held = unresolvedOps
270
+ ? {
271
+ eventIds: [
272
+ ...unresolvedOps.eventIds,
273
+ ...(bucket?.sourcedOps.map((s) => s.sourceEventId) ?? []),
274
+ ],
275
+ error: unresolvedOps.error,
276
+ }
277
+ : bucket
278
+ ? await flushTenantHoldingFailedOperations(searchAdapter, tenantId, bucket)
279
+ : null;
250
280
  if (held) {
251
281
  turn.holdForRetry(held.eventIds, recordTenantFailure(tenantId, held));
252
282
  continue;
@@ -1,11 +1,39 @@
1
+ import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
1
2
  import { maskWriteOnlyFields } from "../engine/field-access.js";
2
3
  import { isLifecycleResult } from "./dispatcher-utils.js";
4
+ const MAX_NESTED_EVENT_STRIP_DEPTH = 8;
5
+ // A handler may nest an executor result in its own data (`{ created: inner.data }`); the
6
+ // echoed event inside it carries plaintext PII and must not reach the response either.
7
+ // Returns the input unchanged when nothing was stripped.
8
+ function stripNestedEchoedEvents(value, depth = 0) {
9
+ if (depth > MAX_NESTED_EVENT_STRIP_DEPTH)
10
+ return value;
11
+ if (Array.isArray(value)) {
12
+ const items = value.map((item) => stripNestedEchoedEvents(item, depth + 1));
13
+ return items.some((item, index) => item !== value[index]) ? items : value;
14
+ }
15
+ if (!isPlainObject(value))
16
+ return value;
17
+ const isNestedLifecycle = isLifecycleResult(value) && "event" in value;
18
+ let changed = isNestedLifecycle;
19
+ const entries = Object.entries(value).flatMap(([key, child]) => {
20
+ if (isNestedLifecycle && key === "event")
21
+ return [];
22
+ const stripped = stripNestedEchoedEvents(child, depth + 1);
23
+ if (stripped !== child)
24
+ changed = true;
25
+ return [[key, stripped]];
26
+ });
27
+ return changed ? Object.fromEntries(entries) : value;
28
+ }
3
29
  // The echoed event carries plaintext entity data; only hooks and projections may read it.
4
30
  function maskLifecycleOrRow(entity, data) {
5
- if (typeof data !== "object" || data === null || Array.isArray(data))
6
- return data;
31
+ if (typeof data !== "object" || data === null || Array.isArray(data)) {
32
+ return stripNestedEchoedEvents(data);
33
+ }
7
34
  if (!isLifecycleResult(data)) {
8
- return entity ? maskWriteOnlyFields(entity, data) : data; // @cast-boundary engine-payload
35
+ const row = stripNestedEchoedEvents(data);
36
+ return entity && isPlainObject(row) ? maskWriteOnlyFields(entity, row) : row;
9
37
  }
10
38
  const { event: _event, ...lifecycle } = data;
11
39
  if (!entity)
@@ -0,0 +1,7 @@
1
+ import type { WriteHandlerDef } from "@cosmicdrift/kumiko-types/handlers";
2
+ import type { DbTx } from "../db/connection.ts";
3
+ import type { HandlerContext } from "../engine/types/index.ts";
4
+ import type { DispatchContext } from "./dispatch-shared.ts";
5
+ export declare function resolveTransitionGuardDb(handlerContext: HandlerContext, type: string): import("@cosmicdrift/kumiko-types/tenant-db-types").TenantDb;
6
+ export type TransitionGuardDb = ReturnType<typeof resolveTransitionGuardDb>;
7
+ export declare function guardAutoTransitions(ctx: DispatchContext, handler: WriteHandlerDef, type: string, parsedPayload: unknown, transitionGuardDb: TransitionGuardDb, tx: DbTx | undefined): Promise<void>;
@@ -0,0 +1,95 @@
1
+ import { selectRowForUpdateById } from "../db/queries/entity-read.js";
2
+ import { asEntityTableMeta, selectMany } from "../db/query.js";
3
+ import { toSnakeCase } from "../db/table-builder.js";
4
+ import { tenantDbRunner } from "../db/tenant-db-runner.js";
5
+ import { defineTransitions, guardTransition } from "../engine/state-machine.js";
6
+ import { getTable } from "./dispatch-context-helpers.js";
7
+ function getTransitions(ctx, args) {
8
+ const { transitionCache } = ctx;
9
+ // Scope by entity — `fieldName` alone collides across entities (e.g. both
10
+ // `invoice.status` and `driverOrder.status` exist with different maps),
11
+ // which would apply the wrong transition rules to whichever entity arrives
12
+ // second.
13
+ const key = `${args.entityName}:${args.fieldName}`;
14
+ const cached = transitionCache.get(key);
15
+ if (cached)
16
+ return cached;
17
+ const transitions = defineTransitions(args.map);
18
+ transitionCache.set(key, transitions);
19
+ return transitions;
20
+ }
21
+ // Reads via the guard's own db handle — for r.systemScope() handlers
22
+ // handlerContext.db is fail-closed, so this reaches for
23
+ // systemDb.acknowledgeCrossTenant like any other framework-internal
24
+ // mechanism that touches a system-scoped handler's data.
25
+ export function resolveTransitionGuardDb(handlerContext, type) {
26
+ return handlerContext.systemDb
27
+ ? handlerContext.systemDb.acknowledgeCrossTenant(`auto transition guard for r.systemScope() write handler (${type})`)
28
+ : handlerContext.db;
29
+ }
30
+ // Auto transition guard: if entity has transitions and handler doesn't skip it.
31
+ export async function guardAutoTransitions(ctx, handler, type, parsedPayload, transitionGuardDb, tx) {
32
+ const entityName = ctx.registry.getHandlerEntity(type);
33
+ // skip: handler has no entity or opted out of the transition guard
34
+ if (!entityName || handler.unsafeSkipTransitionGuard)
35
+ return;
36
+ const entity = ctx.registry.getEntity(entityName);
37
+ // skip: entity declares no transitions, or there is no db to read the current value from
38
+ if (!entity?.transitions || !transitionGuardDb)
39
+ return;
40
+ const parsedData = parsedPayload; // @cast-boundary engine-payload
41
+ const changes = parsedData["changes"] ?? parsedData; // @cast-boundary engine-payload
42
+ const id = parsedData["id"] ?? undefined; // @cast-boundary engine-payload
43
+ for (const [fieldName, transitionMap] of Object.entries(entity.transitions)) {
44
+ await guardFieldTransition(ctx, {
45
+ entityName,
46
+ entity,
47
+ fieldName,
48
+ transitionMap,
49
+ changes,
50
+ id,
51
+ transitionGuardDb,
52
+ tx,
53
+ });
54
+ }
55
+ }
56
+ async function guardFieldTransition(ctx, args) {
57
+ const { entityName, entity, fieldName, transitionMap, changes, id, transitionGuardDb, tx } = args;
58
+ const newValue = changes[fieldName]; // @cast-boundary engine-bridge
59
+ // skip: field is not part of this write
60
+ if (!newValue || !id)
61
+ return;
62
+ const table = getTable(ctx, entityName);
63
+ // skip: entity has no table to read the current value from
64
+ if (!table)
65
+ return;
66
+ // SELECT FOR UPDATE inside the surrounding transaction — locks the
67
+ // row so a concurrent handler can't mutate `status` between our
68
+ // guard check and the handler's UPDATE. Without this lock the guard
69
+ // can false-pass; optimistic locking would catch it later, but with
70
+ // a less specific error. Falls back to a plain SELECT if no tx is
71
+ // active (tests without a DB connection).
72
+ const tableName = asEntityTableMeta(table)?.tableName ?? "";
73
+ const rows = tx
74
+ ? await selectRowForUpdateById(tenantDbRunner(transitionGuardDb), tableName, id)
75
+ : await selectMany(transitionGuardDb, table, { id });
76
+ const row = rows[0];
77
+ // skip: no stored row to transition from
78
+ if (!row)
79
+ return;
80
+ // Skip guard for soft-deleted rows — they shouldn't be transitioning
81
+ // at all; a handler that wants to move a deleted row should use
82
+ // unsafeSkipTransitionGuard or restore first.
83
+ const rowAsRow = row; // @cast-boundary engine-payload
84
+ const isDeleted = rowAsRow["isDeleted"] ?? rowAsRow["is_deleted"];
85
+ // skip: soft-deleted row
86
+ if (entity.softDelete && isDeleted === true) {
87
+ return;
88
+ }
89
+ const currentValue = row[fieldName] ??
90
+ row[toSnakeCase(fieldName)]; // @cast-boundary engine-bridge
91
+ // skip: an unchanged value is no transition (an edit form resends the current status)
92
+ if (currentValue === newValue)
93
+ return;
94
+ guardTransition(getTransitions(ctx, { entityName, fieldName, map: transitionMap }), currentValue, newValue);
95
+ }
@@ -49,6 +49,8 @@ export type CollectedSchemaLoad = {
49
49
  } | {
50
50
  readonly kind: "violations";
51
51
  readonly violations: readonly BootViolation[];
52
+ /** A runtime crash stopped the import, so later features were never evaluated. */
53
+ readonly importAborted?: true;
52
54
  } | {
53
55
  readonly kind: "failed";
54
56
  };
@@ -97,9 +97,11 @@ export async function loadSchemaModCollectingDefinitionViolations(ctx) {
97
97
  }
98
98
  const { thrown } = outcome;
99
99
  if (isRuntimeCrash(thrown)) {
100
+ out.err(violations.length > 0
101
+ ? ` schema.ts import stopped early: ${describeThrown(thrown)}; further violations may be missing.`
102
+ : ` ${describeThrown(thrown)}`);
100
103
  if (violations.length > 0)
101
- return { kind: "violations", violations };
102
- out.err(` ${describeThrown(thrown)}`);
104
+ return { kind: "violations", violations, importAborted: true };
103
105
  return { kind: "failed" };
104
106
  }
105
107
  if (thrown instanceof Error) {
@@ -33,7 +33,7 @@ function checkSchemaDrift(ctx, schemaMod, prevSnapshot) {
33
33
  out.err(" ✗ schema drift: entity definitions are ahead of kumiko/migrations.");
34
34
  out.err(` pending — new: ${drift.diff.newTables.length}, changed: ${drift.diff.changedTables.length}, dropped: ${drift.diff.droppedTables.length}, row level security: ${drift.rowLevelSecurityChanges.length}`);
35
35
  out.err(` tables: ${pendingTables.join(", ")}`);
36
- out.err(" Fix: `kumiko-schema generate <name>`, then commit the migration.");
36
+ out.err(" Fix: `bun kumiko-schema generate <name>`, then commit the migration.");
37
37
  return false;
38
38
  }
39
39
  function unclassifiedViolation(check, e) {
@@ -82,7 +82,13 @@ function checkBootValidity(out, schemaMod) {
82
82
  }
83
83
  function declaredTablesOf(schemaMod) {
84
84
  const names = new Set(schemaMod.entityMetas.map((meta) => meta.tableName));
85
- return { has: (tableName) => names.has(tableName) || isLiveFrameworkTable(tableName) };
85
+ const systemReadable = new Set(schemaMod.entityMetas
86
+ .filter((meta) => meta.systemRowsReadable === true)
87
+ .map((meta) => meta.tableName));
88
+ return {
89
+ has: (tableName) => names.has(tableName) || isLiveFrameworkTable(tableName),
90
+ readsSystemRows: (tableName) => systemReadable.has(tableName),
91
+ };
86
92
  }
87
93
  // 4. Live row-level security table state — the table half of the boot check. Only with a DATABASE_URL;
88
94
  // without one the command stays database-free. Scoped to the tables kumiko/schema.ts declares plus the
@@ -125,7 +131,7 @@ function reportMigrationContentMismatches(out, mismatches) {
125
131
  out.err(" Fix (unexpected-table): build a meta via `defineUnmanagedTable()` " +
126
132
  "from `@cosmicdrift/kumiko-framework/db`, then `r.storeTable(meta, { reason: ... })` " +
127
133
  "inside a feature — this adds it to ENTITY_METAS immediately; the .snapshot.json " +
128
- "only picks it up on the NEXT `kumiko-schema generate` run, which you still need " +
134
+ "only picks it up on the NEXT `bun kumiko-schema generate` run, which you still need " +
129
135
  "to run and commit. `table()` returns a query handle, not a storeTable()-compatible " +
130
136
  "meta — don't pass its result to storeTable(). See the bundled `jobs` feature's " +
131
137
  "job-run-log store table for the pattern.");
@@ -162,27 +168,28 @@ function checkMigrationContentDrift(ctx, prevSnapshot) {
162
168
  return false;
163
169
  }
164
170
  }
165
- // Static, DB-free boot-blocking checks for CI — catches "this won't boot"
166
- // before deploy. Three layers, no database:
167
- // 1. schema drift: would `generate` write a migration? (= an entity was
168
- // added/changed but never generated → missing table → prod 500)
169
- // 2. boot validity: validateBoot over the composed FEATURES (QN/screen/
170
- // nav/role refs). Runs only if kumiko/schema.ts exports FEATURES;
171
- // honours its optional VALIDATE_BOOT_OPTIONS export. `--json` prints
172
- // this result as one JSON document on stdout.
173
- // 3. migration-content drift: replay every committed *.sql file and
174
- // diff the result against .snapshot.json — catches a migration
175
- // file whose SQL body doesn't match what its own snapshot entry
176
- // claims (e.g. an accidental copy-paste from an earlier file).
177
- // Layer 1 alone misses this: it only compares ENTITY_METAS to the
178
- // snapshot, never the snapshot to the SQL that's supposed to have
179
- // produced it.
180
- // 4. live row-level security (only with DATABASE_URL): the boot's
181
- // table-state check against the real database (not the role: that is a boot-time property).
182
- // The DB-level gate (assertKumikoSchemaCurrent) stays at boot/deploy.
183
- function printBootJson(ctx, boot) {
171
+ // `ok` mirrors the exit code; `boot` stays the violation list for machine consumers.
172
+ function printValidateJson(ctx, boot, extras = {}) {
184
173
  const { ok, skipped, violations } = boot;
185
- ctx.out.log(JSON.stringify({ boot: { ok, ...(skipped ? { skipped } : {}), violations } }));
174
+ const { importAborted, checks } = extras;
175
+ const allOk = ok &&
176
+ (checks === undefined || (checks.schemaDrift && checks.migrations && checks.rowLevelSecurity));
177
+ ctx.out.log(JSON.stringify({
178
+ ok: allOk,
179
+ boot: {
180
+ ok,
181
+ ...(skipped ? { skipped } : {}),
182
+ ...(importAborted ? { importAborted } : {}),
183
+ violations,
184
+ },
185
+ ...(checks === undefined
186
+ ? {}
187
+ : {
188
+ schemaDrift: { ok: checks.schemaDrift },
189
+ migrations: { ok: checks.migrations },
190
+ rowLevelSecurity: { ok: checks.rowLevelSecurity },
191
+ }),
192
+ }));
186
193
  }
187
194
  export async function runValidateCommand(ctx) {
188
195
  const jsonMode = ctx.argv.includes("--json");
@@ -192,14 +199,15 @@ export async function runValidateCommand(ctx) {
192
199
  const loaded = await loadSchemaModCollectingDefinitionViolations(humanCtx);
193
200
  if (loaded.kind === "violations") {
194
201
  reportBootViolations(out, loaded.violations);
195
- if (jsonMode)
196
- printBootJson(ctx, { ok: false, violations: loaded.violations });
202
+ if (jsonMode) {
203
+ printValidateJson(ctx, { ok: false, violations: loaded.violations }, { ...(loaded.importAborted ? { importAborted: loaded.importAborted } : {}) });
204
+ }
197
205
  return 1;
198
206
  }
199
207
  if (loaded.kind === "failed") {
200
208
  if (jsonMode) {
201
209
  const message = "kumiko/schema.ts could not be loaded";
202
- printBootJson(ctx, {
210
+ printValidateJson(ctx, {
203
211
  ok: false,
204
212
  violations: [{ ruleId: "unclassified/loadSchemaMod", check: "loadSchemaMod", message }],
205
213
  });
@@ -212,7 +220,14 @@ export async function runValidateCommand(ctx) {
212
220
  const boot = checkBootValidity(out, schemaMod);
213
221
  const migrationsOk = checkMigrationContentDrift(humanCtx, prevSnapshot);
214
222
  const rowLevelSecurityOk = await checkLiveRowLevelSecurity(out, schemaMod);
215
- if (jsonMode)
216
- printBootJson(ctx, boot);
223
+ if (jsonMode) {
224
+ printValidateJson(ctx, boot, {
225
+ checks: {
226
+ schemaDrift: schemaOk,
227
+ migrations: migrationsOk,
228
+ rowLevelSecurity: rowLevelSecurityOk,
229
+ },
230
+ });
231
+ }
217
232
  return schemaOk && boot.ok && migrationsOk && rowLevelSecurityOk ? 0 : 1;
218
233
  }
@@ -41,6 +41,9 @@ const DEFAULT_FILTERABLE_ATTRIBUTES = [
41
41
  "_chunk",
42
42
  ];
43
43
  const DEFAULT_SORTABLE_ATTRIBUTES = ["_weight"];
44
+ // Meilisearch has no free-form index metadata, so an explicit configure() leaves this foreign
45
+ // filterable attribute behind; a later lazy default then sees a foreign attribute and keeps it.
46
+ const EXPLICIT_CONFIG_MARKER = "_explicitConfig";
44
47
  // Filters per deleteDocuments call: one task per call, and the filter string stays short.
45
48
  const DELETE_FILTER_BATCH = 100;
46
49
  function defaultSearchableAttributes(config) {
@@ -51,9 +54,8 @@ function isSubsetOf(stored, wanted) {
51
54
  return stored.every((attribute) => typeof attribute === "string" && wanted.includes(attribute));
52
55
  }
53
56
  // A stored list that lies inside the current default and misses attributes is an
54
- // older default that gained fields since; anything with a foreign attribute is
55
- // an explicit configure() and stays untouched. Known limit: an explicit configure() that
56
- // narrowed to a strict subset of the default is indistinguishable and gets widened again.
57
+ // older default that gained fields since; anything with a foreign attribute (including the
58
+ // explicit-config marker) is an explicit configure() and stays untouched.
57
59
  function isOutdatedDefault(stored, wanted, distinctMissing) {
58
60
  const pairs = [
59
61
  [stored.searchable, wanted.searchable],
@@ -137,10 +139,12 @@ export function createMeilisearchAdapter(options) {
137
139
  function isOwnTenantIndex(uid) {
138
140
  return uid.startsWith(prefix) && /^t[0-9A-Za-z-]+$/.test(uid.slice(prefix.length));
139
141
  }
140
- async function applyConfig(tenantId, config) {
142
+ async function applyConfig(tenantId, config, explicit) {
141
143
  const index = client.index(meilisearchTenantIndex(prefix, tenantId));
142
144
  await awaitSucceededTask(index.updateSearchableAttributes([...defaultSearchableAttributes(config)]));
143
- await awaitSucceededTask(index.updateFilterableAttributes([...DEFAULT_FILTERABLE_ATTRIBUTES]));
145
+ await awaitSucceededTask(index.updateFilterableAttributes(explicit
146
+ ? [...DEFAULT_FILTERABLE_ATTRIBUTES, EXPLICIT_CONFIG_MARKER]
147
+ : [...DEFAULT_FILTERABLE_ATTRIBUTES]));
144
148
  await awaitSucceededTask(index.updateSortableAttributes([...DEFAULT_SORTABLE_ATTRIBUTES]));
145
149
  await awaitSucceededTask(index.updateDistinctAttribute(DISTINCT_ATTRIBUTE));
146
150
  }
@@ -188,7 +192,8 @@ export function createMeilisearchAdapter(options) {
188
192
  // The configured-tenants map is process memory only: after a restart a stored explicit
189
193
  // configure() must not be overwritten by the registry default, so the default is applied only
190
194
  // to an index that is missing, carries Meilisearch's factory settings, or holds an older
191
- // default that is a strict subset of the current one (fields were added by a deploy).
195
+ // default that is a strict subset of the current one (fields were added by a deploy); an
196
+ // explicit configure() is told apart by EXPLICIT_CONFIG_MARKER.
192
197
  // A kept index still gets the default filterable attributes merged in: remove, purge and the
193
198
  // stale-piece delete filter on them, and an index without them rejects every delete.
194
199
  async function configActionFor(tenantId, config) {
@@ -223,7 +228,7 @@ export function createMeilisearchAdapter(options) {
223
228
  if (!defaultConfig)
224
229
  return;
225
230
  const existing = configuredTenants.get(tenantId);
226
- if (existing) {
231
+ if (existing !== undefined) {
227
232
  await existing;
228
233
  // skip: configured (or in flight) already for this tenant.
229
234
  return;
@@ -232,7 +237,7 @@ export function createMeilisearchAdapter(options) {
232
237
  await trackConfigure(tenantId, async () => {
233
238
  const action = await configActionFor(tenantId, config);
234
239
  if (action.kind === "apply-default")
235
- await applyConfig(tenantId, config);
240
+ await applyConfig(tenantId, config, false);
236
241
  if (action.kind === "add-filterable") {
237
242
  await awaitSucceededTask(client
238
243
  .index(meilisearchTenantIndex(prefix, tenantId))
@@ -269,7 +274,7 @@ export function createMeilisearchAdapter(options) {
269
274
  defaultConfig = config;
270
275
  },
271
276
  async configure(tenantId, config) {
272
- await trackConfigure(tenantId, () => applyConfig(tenantId, config));
277
+ await trackConfigure(tenantId, () => applyConfig(tenantId, config, true));
273
278
  },
274
279
  async index(tenantId, doc) {
275
280
  await ensureConfigured(tenantId);
@@ -14,6 +14,8 @@ export type ReindexEntityResult = {
14
14
  export type ReindexEntityOptions = {
15
15
  readonly batchSize?: number;
16
16
  readonly dryRun?: boolean;
17
+ readonly onlyEntityId?: string;
17
18
  readonly afterBatchRead?: () => Promise<void>;
19
+ readonly signal?: AbortSignal;
18
20
  };
19
21
  export declare function reindexEntity(db: DbRunner, registry: Registry, searchAdapter: SearchAdapter, entityName: string, tenantId: TenantId, options?: ReindexEntityOptions): Promise<ReindexEntityResult>;