@classytic/arc 2.45.2 → 2.46.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 (321) hide show
  1. package/README.md +1 -1
  2. package/dist/{EventTransport-CiicKz2Z.d.mts → EventTransport-CYEoCJGe.d.mts} +0 -2
  3. package/dist/{EventTransport-DHb1tpu-.mjs → EventTransport-DNgD9NP4.mjs} +3 -4
  4. package/dist/{HookSystem-C1u0EUnt.mjs → HookSystem-DRbPzEcP.mjs} +3 -4
  5. package/dist/{QueryCache--5uAuYPW.d.mts → QueryCache-DdvrGG8Q.d.mts} +1 -3
  6. package/dist/{ResourceRegistry-D2jXWVN_.mjs → ResourceRegistry-Douk51fa.mjs} +15 -4
  7. package/dist/{acquire-DTkA8Lme.mjs → acquire-RbtvDg9s.mjs} +2 -3
  8. package/dist/{actionPermissions-DRVk6m7x.mjs → actionPermissions-De0AJ7hm.mjs} +37 -42
  9. package/dist/audit/index.d.mts +2 -10
  10. package/dist/audit/index.mjs +8 -12
  11. package/dist/auth/audit.d.mts +0 -2
  12. package/dist/auth/audit.mjs +2 -3
  13. package/dist/auth/index.d.mts +9 -17
  14. package/dist/auth/index.mjs +26 -29
  15. package/dist/auth/redis-session.d.mts +2 -4
  16. package/dist/auth/redis-session.mjs +2 -3
  17. package/dist/{authorizationDecision-D48fUJv1.mjs → authorizationDecision-DeZMrHcm.mjs} +5 -6
  18. package/dist/{base-CZyixEQR.d.mts → base-HXNgPQww.d.mts} +1 -7
  19. package/dist/{boundedMap-DkKiPifd.mjs → boundedMap-2WBh3gM9.mjs} +2 -3
  20. package/dist/{buildHandler-BiZ4VATS.mjs → buildHandler-DxVOOBpw.mjs} +5 -6
  21. package/dist/cache/index.d.mts +4 -10
  22. package/dist/cache/index.mjs +5 -6
  23. package/dist/{caching-Cj0as-P1.mjs → caching-BYRwYrUo.mjs} +3 -4
  24. package/dist/{claimed-ChI13rUR.mjs → claimed-DYlELdnm.mjs} +2 -3
  25. package/dist/cleanup/index.d.mts +4 -18
  26. package/dist/cleanup/index.mjs +12 -20
  27. package/dist/cli/commands/describe.d.mts +1 -3
  28. package/dist/cli/commands/describe.mjs +4 -5
  29. package/dist/cli/commands/docs.d.mts +1 -3
  30. package/dist/cli/commands/docs.mjs +4 -5
  31. package/dist/cli/commands/doctor.d.mts +1 -3
  32. package/dist/cli/commands/doctor.mjs +2 -3
  33. package/dist/cli/commands/generate.d.mts +1 -1
  34. package/dist/cli/commands/generate.mjs +2 -2
  35. package/dist/cli/commands/init.d.mts +1 -1
  36. package/dist/cli/commands/init.mjs +2 -2
  37. package/dist/cli/commands/introspect.d.mts +1 -3
  38. package/dist/cli/commands/introspect.mjs +3 -4
  39. package/dist/cli/index.d.mts +2 -2
  40. package/dist/cli/index.mjs +3 -3
  41. package/dist/{constants-D_aiew34.mjs → constants-CHZMUwBW.mjs} +2 -3
  42. package/dist/context/index.d.mts +0 -8
  43. package/dist/context/index.mjs +6 -7
  44. package/dist/core/index.d.mts +3 -3
  45. package/dist/core/index.mjs +8 -8
  46. package/dist/{core-QIZ2560Y.mjs → core-D9rS2BxO.mjs} +9 -12
  47. package/dist/{createActionRouter-CvH84dyx.mjs → createActionRouter-0qkCRzTL.mjs} +7 -8
  48. package/dist/{createAggregationRouter-DGyK2Hp6.mjs → createAggregationRouter-CUf5Esd9.mjs} +9 -10
  49. package/dist/{createApp-CKjZpmq9.mjs → createApp-DZIXfDKD.mjs} +49 -62
  50. package/dist/{createMcpServer-DSztofa9.d.mts → createMcpServer-DeVpqQF-.d.mts} +1 -3
  51. package/dist/{defineAggregation-BLza7Ca4.mjs → defineAggregation-bmKQ4NmC.mjs} +2 -3
  52. package/dist/{defineResource-CEo0gDCb.mjs → defineResource-CGmdmGwh.mjs} +78 -29
  53. package/dist/discovery/index.d.mts +1 -3
  54. package/dist/discovery/index.mjs +2 -3
  55. package/dist/docs/index.d.mts +8 -8
  56. package/dist/docs/index.mjs +4 -5
  57. package/dist/{elevation-BJTsSnke.mjs → elevation-CzhqAyVN.mjs} +9 -10
  58. package/dist/{elevation-BW2J3tNj.d.mts → elevation-DPD0hcU-.d.mts} +0 -2
  59. package/dist/encryption/index.d.mts +1 -7
  60. package/dist/encryption/index.mjs +8 -13
  61. package/dist/{errorHandler--4rSMMvq.d.mts → errorHandler-B9r88jZV.d.mts} +8 -3
  62. package/dist/{errorHandler-2p4SL5zm.mjs → errorHandler-dFyGOEoB.mjs} +16 -6
  63. package/dist/{errors-grZkIA8N.mjs → errors-BY8vzlP4.mjs} +2 -3
  64. package/dist/{errors-JYc9vwqE.d.mts → errors-DTo0me1o.d.mts} +0 -2
  65. package/dist/{eventPlugin-BtmA4-3P.d.mts → eventPlugin-BY38F6yK.d.mts} +1 -7
  66. package/dist/{eventPlugin-ItcYBGUs.mjs → eventPlugin-eMhAPtQA.mjs} +10 -12
  67. package/dist/{eventTypes-Ck6fD3ne.mjs → eventTypes-Do2KYeJx.mjs} +5 -8
  68. package/dist/events/index.d.mts +4 -16
  69. package/dist/events/index.mjs +8 -9
  70. package/dist/events/transports/redis-stream-entry.d.mts +1 -1
  71. package/dist/events/transports/redis-stream-entry.mjs +5 -6
  72. package/dist/events/transports/redis.d.mts +2 -4
  73. package/dist/events/transports/redis.mjs +3 -4
  74. package/dist/{externalPaths-CmGOxOtD.d.mts → externalPaths-BOqdq5wr.d.mts} +0 -2
  75. package/dist/factory/index.d.mts +4 -14
  76. package/dist/factory/index.mjs +12 -18
  77. package/dist/{fastify-augmentation-DRlCIWE9.d.mts → fastify-augmentation-Dtn0IIRn.d.mts} +4 -10
  78. package/dist/{fields-BBSpf8pS.d.mts → fields-JTkrtO-r.d.mts} +0 -2
  79. package/dist/{fields-BRX0Krcj.mjs → fields-LnbCcvsw.mjs} +2 -3
  80. package/dist/{filter-merge-CDc7YMwX.mjs → filter-merge-BAWi019Q.mjs} +2 -3
  81. package/dist/{generate-DCGuEbqI.d.mts → generate-C-g_KOkV.d.mts} +0 -4
  82. package/dist/{generate-hvg7V2g1.mjs → generate-oXoDnpJf.mjs} +7 -12
  83. package/dist/{headers-Cqkg4LzI.mjs → headers-DBd3Qheo.mjs} +3 -4
  84. package/dist/{health-PVt0VjOx.mjs → health-BlJu9GXS.mjs} +2 -3
  85. package/dist/{health-DyeP3mTW.mjs → health-Dp-3EC9o.mjs} +4 -7
  86. package/dist/hooks/index.d.mts +1 -1
  87. package/dist/hooks/index.mjs +2 -2
  88. package/dist/idempotency/index.d.mts +3 -9
  89. package/dist/idempotency/index.mjs +10 -13
  90. package/dist/idempotency/redis.d.mts +1 -1
  91. package/dist/idempotency/redis.mjs +3 -4
  92. package/dist/{index-Bxriq3so.d.mts → index-B5i9-vuP.d.mts} +4 -26
  93. package/dist/{index-Chgz3d0i.d.mts → index-BAXDo5eE.d.mts} +1 -7
  94. package/dist/{index-Beg3aNnK.d.mts → index-BTxzJ_MN.d.mts} +67 -25
  95. package/dist/{index-CUJvoyw3.d.mts → index-Bqfo8hLz.d.mts} +2 -24
  96. package/dist/{index-uhkUA5-U.d.mts → index-CUdaoCYt.d.mts} +13 -23
  97. package/dist/{index-WH7xgvxS.d.mts → index-DyJFTJLA.d.mts} +31 -92
  98. package/dist/index.d.mts +7 -9
  99. package/dist/index.mjs +12 -13
  100. package/dist/{init-jC3rMPzb.mjs → init-BOaNkLYb.mjs} +18 -35
  101. package/dist/{init-Cscs4lab.d.mts → init-CV2_Fw3H.d.mts} +0 -4
  102. package/dist/integrations/event-gateway.d.mts +3 -5
  103. package/dist/integrations/event-gateway.mjs +3 -4
  104. package/dist/integrations/index.d.mts +3 -3
  105. package/dist/integrations/index.mjs +1 -1
  106. package/dist/integrations/jobs/index.d.mts +1 -1
  107. package/dist/integrations/jobs/index.mjs +7 -11
  108. package/dist/integrations/mcp/index.d.mts +7 -39
  109. package/dist/integrations/mcp/index.mjs +8 -14
  110. package/dist/integrations/mcp/testing.d.mts +3 -5
  111. package/dist/integrations/mcp/testing.mjs +3 -4
  112. package/dist/integrations/streamline.d.mts +1 -3
  113. package/dist/integrations/streamline.mjs +4 -5
  114. package/dist/integrations/webhooks.d.mts +2 -4
  115. package/dist/integrations/webhooks.mjs +4 -5
  116. package/dist/integrations/websocket-pushref-redis.d.mts +2 -4
  117. package/dist/integrations/websocket-pushref-redis.mjs +2 -3
  118. package/dist/integrations/websocket-redis.d.mts +2 -4
  119. package/dist/integrations/websocket-redis.mjs +2 -3
  120. package/dist/integrations/websocket.d.mts +2 -2
  121. package/dist/integrations/websocket.mjs +13 -24
  122. package/dist/{interface-JJzwH4Ro.d.mts → interface-BmExzQRD.d.mts} +0 -2
  123. package/dist/{interface-BOk3YnTz.d.mts → interface-WR1U0K7t.d.mts} +0 -2
  124. package/dist/{jsonBody-ptwyzZQ-.mjs → jsonBody-DpRpKR_K.mjs} +3 -4
  125. package/dist/{keys-C1vFuSbv.mjs → keys-FBz6Ull-.mjs} +2 -3
  126. package/dist/{loadResources-CHPDyIPn.mjs → loadResources-Bx1sKPnF.mjs} +4 -5
  127. package/dist/{loadResourcesFromEntry-BkHHTu_B.mjs → loadResourcesFromEntry-b_jcqbxh.mjs} +3 -4
  128. package/dist/logger/index.d.mts +1 -3
  129. package/dist/logger/index.mjs +2 -2
  130. package/dist/{logger-C5bvCiAK.mjs → logger-CbFcIEBZ.mjs} +3 -5
  131. package/dist/{mcpPlugin-C9qohJCF.mjs → mcpPlugin-yix548XX.mjs} +41 -60
  132. package/dist/{memory-CxiTwT0j.mjs → memory-Bgw5dn8N.mjs} +4 -5
  133. package/dist/{metrics-Ckp2zRy-.mjs → metrics-CZDQWVjS.mjs} +4 -5
  134. package/dist/middleware/index.d.mts +1 -5
  135. package/dist/middleware/index.mjs +4 -5
  136. package/dist/migrations/index.d.mts +0 -2
  137. package/dist/migrations/index.mjs +3 -4
  138. package/dist/{module-CfnKuIuH.mjs → module-Dsc_nKL5.mjs} +2 -3
  139. package/dist/{multiTenant-CAtYlW6H.d.mts → multiTenant-XCxAUlru.d.mts} +1 -5
  140. package/dist/{multipartBody-BFasGtP9.mjs → multipartBody-B85ek8Kj.mjs} +2 -3
  141. package/dist/observeSend-BK-JN1jK.mjs +20 -0
  142. package/dist/{openapi-DAPxjYHX.mjs → openapi-Co7hl073.mjs} +18 -28
  143. package/dist/outbox-admin/index.d.mts +2 -4
  144. package/dist/outbox-admin/index.mjs +6 -7
  145. package/dist/{outbox-module-gZCHoE4H.d.mts → outbox-module-XvUThpqn.d.mts} +2 -8
  146. package/dist/{outbox-module-B4FAkx3A.mjs → outbox-module-mg9kDYkd.mjs} +13 -17
  147. package/dist/permissions/index.d.mts +4 -4
  148. package/dist/permissions/index.mjs +7 -7
  149. package/dist/{permissions-B14c3OMp.mjs → permissions-A1oKtpiC.mjs} +19 -29
  150. package/dist/{pipe-CQv7PsAK.mjs → pipe-Czpw9U2n.mjs} +3 -4
  151. package/dist/pipeline/index.d.mts +1 -9
  152. package/dist/pipeline/index.mjs +5 -8
  153. package/dist/{plan-CpnTykjb.mjs → plan-KVseuBCL.mjs} +5 -9
  154. package/dist/{plugin-DXTjVg_Q.mjs → plugin-DTWt_8C3.mjs} +130 -62
  155. package/dist/plugins/index.d.mts +8 -16
  156. package/dist/plugins/index.mjs +22 -26
  157. package/dist/plugins/response-cache.d.mts +2 -4
  158. package/dist/plugins/response-cache.mjs +10 -10
  159. package/dist/plugins/tracing-entry.d.mts +1 -1
  160. package/dist/plugins/tracing-entry.mjs +3 -4
  161. package/dist/{pluralize-C3VJKRGp.mjs → pluralize-msB9X3yw.mjs} +2 -3
  162. package/dist/presets/filesUpload.d.mts +4 -6
  163. package/dist/presets/filesUpload.mjs +6 -7
  164. package/dist/presets/index.d.mts +3 -19
  165. package/dist/presets/index.mjs +2 -2
  166. package/dist/presets/multiTenant.d.mts +1 -1
  167. package/dist/presets/multiTenant.mjs +7 -7
  168. package/dist/presets/search.d.mts +3 -5
  169. package/dist/presets/search.mjs +3 -4
  170. package/dist/{presets-CquqYJPy.mjs → presets-qKCehiJM.mjs} +11 -18
  171. package/dist/{projection-CgfSLOSM.mjs → projection-ClBqtsIw.mjs} +3 -4
  172. package/dist/{pushref-registry-UxCkoA4C.d.mts → pushref-registry-d86QUaSq.d.mts} +0 -6
  173. package/dist/{queryCachePlugin-D0HUISHJ.mjs → queryCachePlugin-3gJj5Rbz.mjs} +8 -10
  174. package/dist/{queryCachePlugin-C2lZjTxk.d.mts → queryCachePlugin-DYQUyeJ9.d.mts} +2 -4
  175. package/dist/{rateLimitKey-AvkBOMkl.mjs → rateLimitKey-Kro---xl.mjs} +2 -3
  176. package/dist/{realtime-CbWtVbqK.mjs → realtime-Ber8uJN2.mjs} +17 -19
  177. package/dist/{redis-BDgv9Glw.d.mts → redis-RpDMemdm.d.mts} +2 -4
  178. package/dist/{redis-stream-BMk-bpQS.d.mts → redis-stream-CS1N9dwM.d.mts} +1 -3
  179. package/dist/{redisShapes-CQksY67q.d.mts → redisShapes-CqBXTn_s.d.mts} +0 -2
  180. package/dist/registry/index.d.mts +2 -12
  181. package/dist/registry/index.mjs +3 -3
  182. package/dist/{registry-BVwpAuFI.mjs → registry-BA-_vFYk.mjs} +7 -12
  183. package/dist/{renewingLease-CykpeNcQ.mjs → renewingLease-CMY8YOcc.mjs} +2 -3
  184. package/dist/{replyHelpers-DA51IZio.mjs → replyHelpers-DK9P_XSz.mjs} +3 -4
  185. package/dist/{requestContext-DIWHKDtQ.mjs → requestContext-GYO_0gEw.mjs} +2 -3
  186. package/dist/{requirement-CbiLdQ1n.d.mts → requirement-CTRQjjQx.d.mts} +0 -2
  187. package/dist/{requirement-Cp_fsMDL.mjs → requirement-DeNjZIH3.mjs} +2 -3
  188. package/dist/{resourceRateLimit-Wf6d6FL9.d.mts → resourceRateLimit-DCWglD7V.d.mts} +1 -3
  189. package/dist/{resourceRateLimit-BFuluodF.mjs → resourceRateLimit-tHLbrtWc.mjs} +3 -4
  190. package/dist/{rolldown-runtime-D_lMdYOd.mjs → rolldown-runtime-Kv1fZdLg.mjs} +2 -3
  191. package/dist/{routeValidator-DuLonYwr.mjs → routeValidator-C_H5NanI.mjs} +2 -3
  192. package/dist/{runtimeCapabilities-CydRfm0i.mjs → runtimeCapabilities-DWqbxkyw.mjs} +2 -3
  193. package/dist/{schedules-B693KXxa.mjs → schedules-eO_RzhCU.mjs} +132 -9
  194. package/dist/{schemaConverter-DNvZWTV6.mjs → schemaConverter-DBJrPZN4.mjs} +3 -4
  195. package/dist/{schemaIR-REV2y7Wd.mjs → schemaIR-CEScKT2v.mjs} +3 -4
  196. package/dist/schemas/index.d.mts +0 -2
  197. package/dist/schemas/index.mjs +2 -3
  198. package/dist/scim/index.d.mts +0 -12
  199. package/dist/scim/index.mjs +10 -18
  200. package/dist/scope/index.d.mts +2 -6
  201. package/dist/scope/index.mjs +5 -5
  202. package/dist/{scope-Bevxy_ST.mjs → scope-B-Sm9m_E.mjs} +5 -6
  203. package/dist/{sessionManager-qimlKV0P.d.mts → sessionManager-CdvDF04x.d.mts} +2 -4
  204. package/dist/{shutdown-CfrqPR7A.mjs → shutdown-DzLFbe27.mjs} +2 -3
  205. package/dist/{simpleEqualityMatcher-BJwfuRKP.mjs → simpleEqualityMatcher-DOJhwQ8g.mjs} +2 -3
  206. package/dist/{sse-CuNNWr2z.mjs → sse-2972pVwV.mjs} +8 -9
  207. package/dist/{sseStream-C_2ujAVY.mjs → sseStream-AWLEeNV-.mjs} +3 -4
  208. package/dist/{storage-Cx9Sz3Ou.d.mts → storage-odC5MNKN.d.mts} +0 -2
  209. package/dist/{store-helpers-C8uBGCbb.mjs → store-helpers-VzjgVTkM.mjs} +2 -3
  210. package/dist/{streaming-Bdq_M4d5.mjs → streaming-DvraWW6x.mjs} +2 -3
  211. package/dist/{subscriberIdentity-B-KpZkdl.mjs → subscriberIdentity-Bya56jsg.mjs} +2 -3
  212. package/dist/{tenancy-C5PCvm1h.mjs → tenancy-DSa_0hhw.mjs} +3 -4
  213. package/dist/{tenantPreparation-dYvWrgNa.mjs → tenantPreparation-BrpkQre3.mjs} +5 -6
  214. package/dist/testing/cleanupStoreContract.d.mts +2 -4
  215. package/dist/testing/cleanupStoreContract.mjs +2 -3
  216. package/dist/testing/index.d.mts +6 -32
  217. package/dist/testing/index.mjs +24 -37
  218. package/dist/testing/outboxStoreContract.d.mts +1 -3
  219. package/dist/testing/outboxStoreContract.mjs +3 -4
  220. package/dist/testing/requiredPorts.d.mts +2 -4
  221. package/dist/testing/requiredPorts.mjs +3 -4
  222. package/dist/testing/storageContract.d.mts +2 -4
  223. package/dist/testing/storageContract.mjs +2 -3
  224. package/dist/{timing-DCqsezX8.mjs → timing-6rQTuCwg.mjs} +3 -5
  225. package/dist/{tracing-Dro5eH6j.d.mts → tracing-JSFiBl5r.d.mts} +0 -2
  226. package/dist/{transactionContext-DrcNyjpv.mjs → transactionContext-DaxYUEgH.mjs} +2 -3
  227. package/dist/{typeGuards-CEl10KPy.mjs → typeGuards-UKnX8wPX.mjs} +2 -3
  228. package/dist/types/index.d.mts +4 -4
  229. package/dist/types/index.mjs +1 -1
  230. package/dist/types/storage.d.mts +1 -1
  231. package/dist/types/storage.mjs +1 -1
  232. package/dist/{types-ByHn9rEO.d.mts → types-0Dqlbgn8.d.mts} +0 -2
  233. package/dist/{types-D3Ixsh00.d.mts → types-BYEb_dLW.d.mts} +2 -4
  234. package/dist/{types-BJ-2XqVF.d.mts → types-BeEJm-DV.d.mts} +114 -14
  235. package/dist/{types-DVLddu2q.d.mts → types-C0YJAiL0.d.mts} +0 -2
  236. package/dist/{types-D9NWjpYc.mjs → types-CuGjhn83.mjs} +5 -6
  237. package/dist/{types-Ddl9OjmE.d.mts → types-DnkIALZ8.d.mts} +0 -4
  238. package/dist/usage/index.d.mts +2 -10
  239. package/dist/usage/index.mjs +8 -12
  240. package/dist/{userHelpers-BHig1kHq.mjs → userHelpers-oX5_mOVs.mjs} +2 -3
  241. package/dist/utils/index.d.mts +5 -39
  242. package/dist/utils/index.mjs +12 -12
  243. package/dist/{utils-BG5P7_Vb.mjs → utils-CjjGOT4E.mjs} +20 -30
  244. package/dist/{validate-D_mdOCir.mjs → validate-4RlTKOJb.mjs} +5 -7
  245. package/dist/{versioning-DBGHjPh7.mjs → versioning-Dk2-19La.mjs} +4 -5
  246. package/dist/{versioning-Bqm_57Qt.d.mts → versioning-S18y2-0C.d.mts} +1 -15
  247. package/dist/{websocket-Cs4awVyD.d.mts → websocket-BGuc-WVZ.d.mts} +1 -15
  248. package/dist/{workScope-DPPfM4m6.mjs → workScope-DoBsoVo4.mjs} +3 -4
  249. package/llms.txt +37 -30
  250. package/package.json +9 -8
  251. package/skills/arc/SKILL.md +65 -844
  252. package/skills/arc/references/agent-auth.md +82 -193
  253. package/skills/arc/references/api-reference.md +41 -245
  254. package/skills/arc/references/auth-api-keys.md +99 -0
  255. package/skills/arc/references/auth-better-auth-overlay.md +87 -0
  256. package/skills/arc/references/auth-better-auth.md +78 -0
  257. package/skills/arc/references/auth-permissions.md +100 -0
  258. package/skills/arc/references/auth-strategies.md +122 -0
  259. package/skills/arc/references/boot.md +80 -0
  260. package/skills/arc/references/enterprise-auth.md +65 -81
  261. package/skills/arc/references/events-outbox.md +90 -0
  262. package/skills/arc/references/events.md +75 -440
  263. package/skills/arc/references/integrations-jobs.md +74 -0
  264. package/skills/arc/references/integrations-realtime.md +84 -0
  265. package/skills/arc/references/integrations-webhooks.md +71 -0
  266. package/skills/arc/references/integrations-workflows.md +47 -0
  267. package/skills/arc/references/mcp-auth.md +83 -0
  268. package/skills/arc/references/mcp-custom-tools.md +125 -0
  269. package/skills/arc/references/mcp-setup.md +115 -0
  270. package/skills/arc/references/mcp-testing.md +63 -0
  271. package/skills/arc/references/multi-tenancy.md +56 -230
  272. package/skills/arc/references/permissions-scope.md +81 -0
  273. package/skills/arc/references/production-api.md +119 -0
  274. package/skills/arc/references/production-audit.md +101 -0
  275. package/skills/arc/references/production-boot.md +91 -0
  276. package/skills/arc/references/production-caching.md +63 -0
  277. package/skills/arc/references/production-distributed.md +75 -0
  278. package/skills/arc/references/production-idempotency.md +83 -0
  279. package/skills/arc/references/production-observability.md +83 -0
  280. package/skills/arc/references/production-realtime.md +70 -0
  281. package/skills/arc/references/production-reliability.md +100 -0
  282. package/skills/arc/references/production-shutdown.md +43 -0
  283. package/skills/arc/references/querying.md +76 -0
  284. package/skills/arc/references/resources.md +97 -0
  285. package/skills/arc/references/schedules.md +79 -0
  286. package/skills/arc/references/scim.md +61 -208
  287. package/skills/arc/references/tenancy-scope-install.md +82 -0
  288. package/skills/arc/references/testing.md +101 -144
  289. package/skills/arc/references/usage-cleanup-capabilities.md +45 -0
  290. package/skills/arc/references/validation.md +91 -0
  291. package/skills/arc/references/writes-hooks-errors.md +80 -0
  292. package/skills/arc-code-review/SKILL.md +67 -114
  293. package/skills/arc-code-review/references/arc-cheatsheet.md +68 -167
  294. package/skills/arc-code-review/references/mongokit-repositories.md +104 -0
  295. package/skills/arc-code-review/references/recipe-events-cache-jobs.md +112 -0
  296. package/skills/arc-code-review/references/recipe-resource.md +100 -0
  297. package/skills/arc-code-review/references/recipe-schemas-fields.md +93 -0
  298. package/skills/arc-code-review/references/recipe-scope-permissions.md +82 -0
  299. package/skills/arc-code-review/references/scaffolding.md +61 -198
  300. package/skills/arc-code-review/references/severity.md +49 -102
  301. package/skills/arc-code-review/references/smells-auth-scope.md +80 -0
  302. package/skills/arc-code-review/references/smells-data-events.md +66 -0
  303. package/skills/arc-code-review/references/smells-imports-style.md +59 -0
  304. package/skills/arc-code-review/references/smells-platform.md +89 -0
  305. package/skills/arc-code-review/references/smells-routes-schemas.md +66 -0
  306. package/skills/arc-module-publishing/SKILL.md +82 -208
  307. package/skills/arc-module-publishing/references/action-presets-and-plugins.md +87 -0
  308. package/skills/arc-module-publishing/references/build-and-types.md +73 -0
  309. package/skills/arc-module-publishing/references/module-lifecycle.md +101 -0
  310. package/skills/arc-module-publishing/references/package-manifest.md +34 -122
  311. package/skills/arc-module-publishing/references/publishing-workflow.md +44 -140
  312. package/skills/arc-module-publishing/references/resource-assembly.md +102 -0
  313. package/skills/arc-module-publishing/references/testing-packages.md +82 -0
  314. package/skills/arc/references/auth.md +0 -729
  315. package/skills/arc/references/integrations.md +0 -452
  316. package/skills/arc/references/mcp.md +0 -691
  317. package/skills/arc/references/production.md +0 -835
  318. package/skills/arc-code-review/references/anti-patterns.md +0 -1008
  319. package/skills/arc-code-review/references/migration-recipes.md +0 -649
  320. package/skills/arc-code-review/references/mongokit-migration.md +0 -360
  321. package/skills/arc-module-publishing/references/authoring-modules.md +0 -327
@@ -1,491 +1,126 @@
1
- # Arc Events System
1
+ # Events: bus, transports, handlers
2
2
 
3
- Domain event pub/sub with pluggable transports. Auto-emits events on CRUD operations.
3
+ `createApp()` registers `eventPlugin` and decorates `app.events`. Event contract types and helpers come from `@classytic/primitives/events`; arc ships the runtime.
4
4
 
5
- ## Hooks vs Events
6
-
7
- | Aspect | Hooks | Events |
8
- |--------|-------|--------|
9
- | Purpose | Internal lifecycle callbacks | External integration |
10
- | Scope | Same process, synchronous flow | Cross-service, async |
11
- | Use when | Validating, transforming, auditing | Notifying services, event-driven systems |
12
- | Transport | In-process only | Pluggable (Memory → Redis → Kafka) |
13
- | Pattern | `beforeCreate`, `afterUpdate` | `product.created`, `order.updated` |
5
+ ```typescript
6
+ import type { EventMeta, DomainEvent, EventHandler, EventTransport, DeadLetteredEvent } from '@classytic/primitives/events';
7
+ import { createEvent, createChildEvent, matchEventPattern } from '@classytic/primitives/events';
8
+ ```
14
9
 
15
10
  ## Setup
16
11
 
17
- The `createApp()` factory auto-registers `eventPlugin` — no manual registration needed:
18
-
19
12
  ```typescript
20
13
  import { createApp } from '@classytic/arc/factory';
21
-
22
- // Development (in-memory, default — zero config)
23
- const app = await createApp({ preset: 'development' });
24
- // app.events is ready to use
25
-
26
- // Production (Redis transport, with retry)
27
- import { RedisEventTransport } from '@classytic/arc/events/redis';
14
+ import { RedisStreamTransport } from '@classytic/arc/events/redis-stream';
28
15
 
29
16
  const app = await createApp({
30
- stores: { events: new RedisEventTransport(redis) },
17
+ stores: { events: new RedisStreamTransport(redis, { stream: 'arc:events', group: 'api', consumer: 'api-1' }) },
31
18
  arcPlugins: {
32
19
  events: {
33
- logEvents: true,
34
- failOpen: true, // default: suppress transport failures
20
+ failOpen: true, // default: publish errors are logged, not thrown
35
21
  retry: { maxRetries: 3, backoffMs: 1000 },
22
+ logEvents: true,
36
23
  },
37
24
  },
38
25
  });
39
-
40
- // Disable event plugin entirely
41
- const app = await createApp({ arcPlugins: { events: false } });
42
- ```
43
-
44
- **Manual registration** (for apps not using `createApp`):
45
-
46
- ```typescript
47
- import { eventPlugin } from '@classytic/arc/events';
48
-
49
- await fastify.register(eventPlugin); // Memory transport
50
-
51
- // Redis Pub/Sub
52
- import { RedisEventTransport } from '@classytic/arc/events/redis';
53
- await fastify.register(eventPlugin, {
54
- transport: new RedisEventTransport(redisClient, { channel: 'arc-events' }),
55
- logEvents: true,
56
- });
57
-
58
- // Redis Streams (ordered, persistent, consumer groups)
59
- import { RedisStreamTransport } from '@classytic/arc/events/redis-stream';
60
- await fastify.register(eventPlugin, {
61
- transport: new RedisStreamTransport(redisClient, {
62
- stream: 'arc:events',
63
- group: 'api-service',
64
- consumer: 'worker-1',
65
- }),
66
- });
26
+ await createApp({ arcPlugins: { events: false } }); // disable
67
27
  ```
68
28
 
69
- `failOpen` behavior:
70
- - `true` (default): publish/subscribe/close transport errors are logged and suppressed.
71
- - `false`: transport errors are thrown to caller.
72
-
73
- ## Auto-Emitted Events
74
-
75
- BaseController automatically emits events when eventPlugin is registered:
29
+ Without `createApp`: `await fastify.register(eventPlugin, { transport })` from `@classytic/arc/events`.
76
30
 
77
- | Operation | Event Type | Payload |
78
- |-----------|------------|---------|
79
- | `create()` | `{resource}.created` | Created document |
80
- | `update()` | `{resource}.updated` | Updated document |
81
- | `delete()` | `{resource}.deleted` | Deleted document |
82
- | `restore()` | `{resource}.restored` | Restored document |
31
+ | `eventPlugin` option | Meaning |
32
+ |---|---|
33
+ | `transport` | Default `MemoryEventTransport`. arc closes only a transport it built |
34
+ | `memoryTransport` | `{ logger, onHandlerError: 'log'\|'throw', handlerDispatch: 'sequential'\|'parallel' }` for the default transport |
35
+ | `singleProcess` | Declare one-process topology on purpose (silences the memory-transport warning) |
36
+ | `failOpen` | `true` (default) suppress transport errors; `false` throw to caller |
37
+ | `retry` / `deadLetterQueue` | Auto-wrap subscribers with `withRetry`; DLQ needs `retry`, default sink publishes `$deadLetter` |
38
+ | `registry`, `validateMode` | Payload validation on publish: `'warn'` (default with registry) \| `'reject'` \| `'off'` |
39
+ | `onPublish`, `onPublishError` | Telemetry callbacks (isolated, never affect delivery) |
40
+ | `warnOnDuplicate` | Dual-publish detector, on outside production |
41
+ | `wal` | Low-level hook; not at-least-once. Use the outbox |
83
42
 
84
- Disable per-controller: `super({ disableEvents: true })`
43
+ CRUD events auto-emit on `arcPlugins.emitEvents` (default true) as `<resource>.created|updated|deleted` with payload `{ resource, operation, data, userId?, organizationId?, timestamp }`. Build names with `crudEventType('product', 'created')`. Lifecycle names: `ARC_LIFECYCLE_EVENTS`.
85
44
 
86
- ## Publishing & Subscribing
45
+ ## Publish and subscribe
87
46
 
88
47
  ```typescript
89
- // Publish
90
- await fastify.events.publish('order.created', {
91
- orderId: 'order-123',
92
- total: 99.99,
93
- }, {
94
- userId: request.user._id,
95
- organizationId: getOrgId(request.scope),
96
- correlationId: request.id,
97
- });
98
-
99
- // Subscribe to specific event
100
- await fastify.events.subscribe('order.created', async (event) => {
101
- await sendConfirmation(event.payload);
48
+ await app.events.publish('order.placed', { orderId: 'o1' }, {
49
+ correlationId: req.id, organizationId: getOrgId(req.scope),
102
50
  });
103
-
104
- // Subscribe to pattern (wildcard)
105
- await fastify.events.subscribe('order.*', async (event) => {
106
- await updateAnalytics(event.type, event.payload);
107
- });
108
-
109
- // Subscribe to all
110
- await fastify.events.subscribe('*', async (event) => {
111
- await auditLog.create(event);
112
- });
113
-
114
- // Unsubscribe
115
- const unsub = await fastify.events.subscribe('order.created', handler);
116
- unsub();
51
+ const unsub = await app.events.subscribe('order.*', async (event) => { /* event.type, payload, meta */ });
52
+ await app.events.subscribe('*', audit);
53
+ const stop = app.events.observe((event) => metrics.inc(event.type)); // read-only tap, also sees outbox relays
117
54
  ```
118
55
 
119
- ## Event Structure
56
+ Patterns: exact, prefix `order.*`, global `*`. `app.events.registry?.catalog()` lists registered definitions.
120
57
 
121
- Event types live in `@classytic/primitives/events` (canonical source). Arc re-exports the runtime `MemoryEventTransport` only — every type below is imported from primitives.
58
+ `EventMeta`: `id`, `timestamp`, `schemaVersion?`, `correlationId?`, `causationId?`, `partitionKey?`, `source?`, `idempotencyKey?`, `resource?`, `resourceId?`, `userId?`, `organizationId?`, `aggregate?: { type, id }`.
122
59
 
123
60
  ```typescript
124
- interface EventMeta {
125
- id: string; // UUID v4 (fresh per emit; a retry gets a new id)
126
- timestamp: Date;
127
- schemaVersion?: number; // bump on payload breaking change
128
- correlationId?: string; // stable across causal chain
129
- causationId?: string; // direct parent event id
130
- partitionKey?: string; // ordering hint (Kafka/Kinesis/Streams)
131
- source?: string; // originating service/package ('commerce', 'billing')
132
- idempotencyKey?: string; // cross-transport dedupe hint — stable per operation
133
- resource?: string;
134
- resourceId?: string;
135
- userId?: string;
136
- organizationId?: string;
137
- aggregate?: { type: string; id: string }; // DDD aggregate marker
138
- }
139
-
140
- interface DomainEvent<T> {
141
- type: string; // e.g., 'order.created'
142
- payload: T;
143
- meta: EventMeta;
144
- }
145
- ```
146
-
147
- **`@classytic/primitives/events` is source of truth** — `EventMeta`, `DomainEvent`, `EventHandler`, `EventLogger`, `EventTransport`, `DeadLetteredEvent`, `PublishManyResult`, `createEvent`, `createChildEvent`, `matchEventPattern` all live there. Arc consumes them and re-exports the runtime `MemoryEventTransport`.
148
-
149
- ### DDD aggregate narrowing
150
-
151
- `aggregate.type` is `string` in arc's base contract so it stays framework-neutral. Domain packages narrow it to a closed union via interface extension:
152
-
153
- ```typescript
154
- // @classytic/cart
155
- type CartAggregateType = 'cart' | 'cart-item';
156
-
157
- interface CartEventMeta extends EventMeta {
158
- aggregate?: { type: CartAggregateType; id: string };
159
- }
160
- ```
161
-
162
- Unlike `correlationId` / `causationId`, `aggregate` is **not inherited** by `createChildEvent`. Child events usually belong to a different aggregate (e.g. an `order.placed` event emitted by the order aggregate spawns `inventory.reserved` owned by the inventory aggregate). Each event names its own aggregate explicitly.
163
-
164
- ### Causation chains
165
-
166
- ```typescript
167
- import { createEvent, createChildEvent } from '@classytic/primitives/events';
168
-
169
- const placed = createEvent('order.placed', { orderId: 'o1' }, {
170
- correlationId: req.id, userId: user.id,
171
- });
172
-
173
- // Downstream handler emits child — causation linked, correlation inherited:
61
+ const placed = createEvent('order.placed', { orderId: 'o1' }, { correlationId: req.id });
174
62
  const reserved = createChildEvent(placed, 'inventory.reserved', { sku: 'a' });
175
- // reserved.meta.causationId === placed.meta.id
176
- // reserved.meta.correlationId === placed.meta.correlationId
177
- ```
178
-
179
- ### Dead-letter contract
180
-
181
- ```typescript
182
- import type { DeadLetteredEvent, EventTransport } from '@classytic/primitives/events';
183
-
184
- class KafkaTransport implements EventTransport {
185
- async deadLetter(dlq: DeadLetteredEvent) {
186
- await producer.send({ topic: `${dlq.event.type}.DLQ`, messages: [{ value: JSON.stringify(dlq) }] });
187
- }
188
- }
189
- ```
190
-
191
- ## Custom Transport
192
-
193
- Implement `EventTransport` for RabbitMQ, Kafka, etc.:
194
-
195
- ```typescript
196
- import type { EventTransport, DomainEvent } from '@classytic/primitives/events';
197
-
198
- class KafkaTransport implements EventTransport {
199
- readonly name = 'kafka';
200
-
201
- async publish(event: DomainEvent): Promise<void> {
202
- await this.producer.send({ topic: event.type, messages: [{ value: JSON.stringify(event) }] });
203
- }
204
-
205
- async subscribe(pattern: string, handler: EventHandler): Promise<() => void> {
206
- // Subscribe to Kafka topic matching pattern
207
- return () => { /* unsubscribe */ };
208
- }
209
-
210
- async close(): Promise<void> {
211
- await this.producer.disconnect();
212
- }
213
- }
214
- ```
215
-
216
- ## Built-in Transports
217
-
218
- | Transport | Import | Use Case |
219
- |-----------|--------|----------|
220
- | Memory | `@classytic/arc/events` (default) | Development, testing, single-instance |
221
- | Redis Pub/Sub | `@classytic/arc/events/redis` | Multi-instance, real-time |
222
- | Redis Streams | `@classytic/arc/events/redis-stream` | Ordered, persistent, consumer groups |
223
-
224
- ### Streams vs Pub/Sub — pick the right one
225
-
226
- Choosing wrong loses messages silently. Default to **Streams** for anything business-critical.
227
-
228
- | Requirement | Use |
229
- |---|---|
230
- | Message MUST NOT be lost (billing, payments, audit) | **Streams** |
231
- | Real-time notifications, OK to miss when no subscriber is up | Pub/Sub |
232
- | Need to replay/reprocess past events | **Streams** |
233
- | Multiple workers processing the same queue | **Streams** (consumer groups) |
234
- | Simple broadcast to live WebSocket clients | Pub/Sub |
235
- | Event sourcing or audit trail | **Streams** |
236
- | Single-instance dev | Memory |
237
- | At-least-once delivery with durable WAL | **Streams** + outbox pattern |
238
-
239
- **Why it matters:** Pub/Sub is fire-and-forget. If no subscriber is connected when you publish, the message is gone. Streams persist until every consumer group acknowledges them — crashes, restarts, and network blips are survivable.
240
-
241
- **Defense-in-depth:** pair `eventPlugin` with the transactional outbox (`EventOutbox` + `MemoryOutboxStore` or your own persistent store) for guaranteed delivery even if Redis is unreachable at publish time.
242
-
243
- ### Redis eviction policy — required for queues and idempotency
244
-
245
- When you back events (Streams), jobs (BullMQ), idempotency, or cache with Redis, your Redis instance **must** be configured with `maxmemory-policy: noeviction`. Any other policy can silently evict in-flight stream entries or pending jobs.
246
-
247
- - **Self-hosted Redis:** `redis-cli CONFIG SET maxmemory-policy noeviction` (or set in `redis.conf`).
248
- - **Upstash:** free/paid DBs default to `optimistic-volatile`. You'll see `IMPORTANT! Eviction policy is optimistic-volatile. It should be "noeviction"` in BullMQ logs. **Do one of:** open a support ticket to request `noeviction`, use a dedicated DB for queues, or accept that long-idle jobs may be evicted.
249
- - **ElastiCache / Redis Cloud:** set the parameter group's `maxmemory-policy` to `noeviction` before pointing arc at it.
250
-
251
- For a pure cache DB (no queues, no idempotency), `allkeys-lru` is correct and what you want.
252
-
253
- ## Injectable Logger
254
-
255
- All transports and retry accept a `logger` option — defaults to `console`, compatible with pino/fastify.log:
256
-
257
- ```typescript
258
- import type { EventLogger } from '@classytic/primitives/events';
259
-
260
- // Interface: { warn(msg, ...args): void; error(msg, ...args): void }
261
-
262
- // Use Fastify's logger
263
- await fastify.register(eventPlugin, {
264
- transport: new RedisEventTransport(redisClient, {
265
- logger: fastify.log, // pino logger
266
- }),
267
- });
268
-
269
- // Use with Memory transport
270
- new MemoryEventTransport({ logger: fastify.log });
271
-
272
- // Use with Redis Streams
273
- new RedisStreamTransport(redisClient, { logger: fastify.log });
274
-
275
- // Use with retry wrapper
276
- import { withRetry } from '@classytic/arc/events';
277
- const retried = withRetry(handler, { maxRetries: 3, logger: fastify.log });
63
+ // reserved.meta.causationId === placed.meta.id; correlationId inherited; aggregate is NOT inherited
278
64
  ```
279
65
 
280
- | Component | File | `logger` option |
281
- |-----------|------|-----------------|
282
- | `MemoryEventTransport` | `EventTransport.ts` | `MemoryEventTransportOptions.logger` |
283
- | `withRetry()` | `retry.ts` | `RetryOptions.logger` |
284
- | `RedisEventTransport` | `transports/redis.ts` | `RedisEventTransportOptions.logger` |
285
- | `RedisStreamTransport` | `transports/redis-stream.ts` | `RedisStreamTransportOptions.logger` |
286
-
287
- ## Typed Events — defineEvent & Event Registry
288
-
289
- Declare events with schemas for runtime validation and introspection:
66
+ ## Typed events and registry
290
67
 
291
68
  ```typescript
69
+ import { z } from 'zod';
292
70
  import { defineEvent, createEventRegistry } from '@classytic/arc/events';
293
71
 
294
- const OrderCreated = defineEvent({
295
- name: 'order.created',
296
- version: 1,
297
- description: 'Emitted when an order is placed',
298
- schema: {
299
- type: 'object',
300
- properties: {
301
- orderId: { type: 'string' },
302
- total: { type: 'number' },
303
- },
304
- required: ['orderId', 'total'],
305
- },
72
+ const OrderPlaced = defineEvent({
73
+ name: 'order.placed', version: 1,
74
+ payload: z.object({ orderId: z.string(), total: z.number() }), // zod v4; or raw `schema` (JSON Schema)
306
75
  });
307
-
308
- // Type-safe event creation
309
- const event = OrderCreated.create({ orderId: 'o-1', total: 100 }, { userId: 'user-1' });
76
+ const event = OrderPlaced.create({ orderId: 'o1', total: 10 }, { userId: 'u1' });
310
77
  await app.events.publish(event.type, event.payload, event.meta);
311
- ```
312
78
 
313
- **Event Registry** — catalog + auto-validation on publish:
314
-
315
- ```typescript
316
- const registry = createEventRegistry();
317
- registry.register(OrderCreated);
318
-
319
- const app = await createApp({
320
- arcPlugins: {
321
- events: { registry, validateMode: 'warn' },
322
- // 'warn' (default): log warning, still publish
323
- // 'reject': throw error, do NOT publish
324
- // 'off': registry is introspection-only
325
- },
326
- });
327
-
328
- // Introspect at runtime
329
- app.events.registry?.catalog();
330
- // → [{ name: 'order.created', version: 1, schema: {...} }, ...]
79
+ const registry = createEventRegistry(); // optional { validate } to plug a full validator
80
+ registry.register(OrderPlaced);
81
+ createApp({ arcPlugins: { events: { registry, validateMode: 'reject' } } });
331
82
  ```
332
83
 
333
- ## QueryCache Integration
84
+ - Declare `payload` or `schema`, never both.
85
+ - Money or stock events: `durability: 'durable'` plus `occurrence(payload)` (fixed id). `app.events.publish` refuses them with `NonDurablePublishError`; write them to the outbox (see events-outbox.md).
334
86
 
335
- QueryCache uses events for auto-invalidation. When `arcPlugins.queryCache` is enabled, all CRUD events automatically bump resource versions, invalidating cached queries — zero config required.
336
-
337
- ## Retry Logic
338
-
339
- Events module includes retry with exponential backoff for failed handlers:
87
+ ## Handler wrappers
340
88
 
341
89
  ```typescript
342
- import { withRetry } from '@classytic/arc/events';
343
-
344
- const retriedHandler = withRetry(async (event) => {
345
- await processEvent(event);
346
- }, {
347
- maxRetries: 3, // default: 3
348
- backoffMs: 1000, // initial delay, doubles each retry (default: 1000)
349
- maxBackoffMs: 30000, // cap (default: 30000)
350
- logger: fastify.log, // default: console
351
- });
352
-
353
- await fastify.events.subscribe('order.created', retriedHandler);
90
+ import { withRetry, wrapWithSchema, subscribeWithSchema, wrapWithBoundary, subscribeWithBoundary,
91
+ withSubscriberId, withInbox, createDeadLetterPublisher } from '@classytic/arc/events';
92
+
93
+ await app.events.subscribe('order.placed', withRetry(handler, {
94
+ maxRetries: 3, backoffMs: 1000, maxBackoffMs: 30000, jitter: 0.1,
95
+ transport, // your EventTransport: exhausted events go to transport.deadLetter()
96
+ name: 'emailer', // DeadLetteredEvent.handlerName
97
+ onDead: (event, errors) => alert(event), // observability only, errors swallowed
98
+ dlqFailureMode: 'rethrow', // default; 'log-and-drop' acknowledges losses
99
+ }));
100
+ await subscribeWithSchema(app, OrderPlaced, handler); // typed payload, invalid events skipped
101
+ await subscribeWithBoundary(app, 'cache.*', invalidate); // log and swallow, no retry
354
102
  ```
355
103
 
356
- ### Auto-route exhausted events to transport.deadLetter() (v2.9)
357
-
358
- For transports with a native DLQ (Kafka DLQ topic, SQS DLQ queue, etc.), pass
359
- `transport` to skip custom `$deadLetter` plumbing:
360
-
361
- ```typescript
362
- await fastify.events.subscribe(
363
- 'order.created',
364
- withRetry(handler, {
365
- maxRetries: 3,
366
- transport: fastify.events.transport, // any EventTransport with deadLetter()
367
- name: 'emailProcessor', // populates DeadLetteredEvent.handlerName
368
- }),
369
- );
370
- ```
371
-
372
- On exhaustion, a typed `DeadLetteredEvent` envelope (original event + error +
373
- attempts + first/last failure timestamps) is handed to `transport.deadLetter()`.
374
- `onDead` still works — both fire when both are configured.
375
-
376
- ## Transactional Outbox (v2.9)
377
-
378
- **Why the outbox exists:** you write a row + publish an event in the same user
379
- request. If the transport (Redis/Kafka) is down at that moment, the row
380
- commits but the event vanishes — silent data divergence. The outbox persists
381
- the event in the **same DB transaction** as the row, then a background relayer
382
- guarantees at-least-once delivery to the transport. Multi-worker claim +
383
- retry/DLQ policy + dedupe make it scale.
384
-
385
- `EventOutbox` now offers centralised retry/DLQ and typed DLQ query:
386
-
387
- ```typescript
388
- import { EventOutbox, MemoryOutboxStore, exponentialBackoff } from '@classytic/arc/events';
389
-
390
- const outbox = new EventOutbox({
391
- store: new MemoryOutboxStore(), // swap for durable store in prod
392
- transport: fastify.events.transport,
393
-
394
- // Centralised retry/DLQ — no more hand-rolled exponentialBackoff at every fail site
395
- failurePolicy: ({ attempts, error }) => {
396
- if (attempts >= 5) return { deadLetter: true };
397
- return { retryAt: exponentialBackoff({ attempt: attempts }) };
398
- },
399
- });
400
-
401
- // meta.idempotencyKey auto-maps to OutboxWriteOptions.dedupeKey — duplicate
402
- // saves with the same key are silently absorbed.
403
- await outbox.store(
404
- createEvent('order.placed', payload, { idempotencyKey: `order:${id}:placed` }),
405
- );
406
-
407
- // Rich per-batch outcome — deadLettered is new in v2.9
408
- const result = await outbox.relayBatch();
409
- // { relayed, attempted, publishFailed, ackFailed, ownershipMismatches,
410
- // malformed, failHookErrors, deadLettered, usedPublishMany }
104
+ | Helper | Use |
105
+ |---|---|
106
+ | `withSubscriberId(id, handler)` | Stable per-handler identity for durable per-handler progress (never an index) |
107
+ | `withInbox(name, handler, { store, leaseMs?, transaction? })` | Run a handler once per event id; `store` is a repo-core `IdempotencyClaimStore`; handler gets `{ session, eventId }` |
108
+ | `createDeadLetterPublisher(app.events)` | Handler that publishes exhausted events to `$deadLetter`; pass as `onDead` or `deadLetter` |
411
109
 
412
- // Read DLQ state as typed DeadLetteredEvent[]
413
- const dlq = await outbox.getDeadLettered(100);
414
- for (const envelope of dlq) {
415
- await alertOps(envelope); // event, error, attempts, firstFailedAt, lastFailedAt
416
- }
417
- ```
110
+ Dead-letter contract: a transport may implement `deadLetter(dlq: DeadLetteredEvent)`.
418
111
 
419
- **Store capability tiers:**
112
+ ## Transports
420
113
 
421
- | Method | Required | What you lose without it |
114
+ | Transport | Import | Use |
422
115
  |---|---|---|
423
- | `save`, `getPending`, `acknowledge` | ✅ | — |
424
- | `claimPending` | — | Multi-worker relay safety |
425
- | `fail` | — | Retry / DLQ / per-event failure reporting |
426
- | `getDeadLettered` | — | `outbox.getDeadLettered()` returns `[]` |
427
- | `purge` | — | App owns retention (TTL index, cron DELETE, etc.) |
428
-
429
- `MemoryOutboxStore` implements all capabilities — use it as a reference when
430
- writing a durable store for Postgres / DynamoDB / your DB of choice.
431
-
432
- ### Durable store — pass a `RepositoryLike`
433
-
434
- Arc adapts any `Repository` (mongokit / prismakit / your own kit) to the
435
- `OutboxStore` contract — no dedicated subpath, no store class to
436
- instantiate:
437
-
438
- ```typescript
439
- import mongoose from 'mongoose';
440
- import { Repository } from '@classytic/mongokit';
441
- import { EventOutbox, exponentialBackoff, createEvent } from '@classytic/arc/events';
442
-
443
- const OutboxModel = mongoose.model('ArcOutbox', OutboxSchema, 'arc_outbox_events');
444
-
445
- const outbox = new EventOutbox({
446
- repository: new Repository(OutboxModel),
447
- transport: redisTransport,
448
- failurePolicy: ({ attempts }) =>
449
- attempts >= 5 ? { deadLetter: true } : { retryAt: exponentialBackoff({ attempt: attempts }) },
450
- });
451
-
452
- // Persist event in the same DB transaction as the row
453
- await mongoose.connection.transaction(async (session) => {
454
- await Order.create([orderDoc], { session });
455
- await outbox.store(
456
- createEvent('order.placed', { orderId }, { idempotencyKey: `order:${orderId}:placed` }),
457
- { session },
458
- );
459
- });
460
-
461
- // Background relayer
462
- setInterval(async () => {
463
- const r = await outbox.relayBatch();
464
- metrics.gauge('outbox.deadLettered', r.deadLettered);
465
- }, 1000);
466
-
467
- // Ops: read dead-letter envelopes for alerting / replay
468
- const dlq = await outbox.getDeadLettered(100);
469
- ```
470
-
471
- **What you get:**
116
+ | `MemoryEventTransport` | `@classytic/arc/events` | Dev, tests, one process |
117
+ | `RedisEventTransport(redis, { channel, externalLifecycle, logger })` | `@classytic/arc/events/redis` | Pub/Sub, fire-and-forget, live fan-out |
118
+ | `RedisStreamTransport(redis, opts)` | `@classytic/arc/events/redis-stream` | Persistent, consumer groups, replay, DLQ stream |
472
119
 
473
- - **Atomic multi-worker claim** — arc's adapter uses `findOneAndUpdate`
474
- on `{ status: 'pending', visibleAt ≤ now, lease free }`. Two racing
475
- relayers never see the same event; expired leases auto-recover.
476
- - **Session threading** — `outbox.store(event, { session })` flows
477
- through `Repository.create(doc, { session })` so the event commits
478
- with your business write.
479
- - **Dedupe** — `meta.idempotencyKey` maps to `dedupeKey`; your kit's
480
- unique index (or equivalent) enforces idempotency.
481
- - **DLQ** — `getDeadLettered(limit)` returns typed `DeadLetteredEvent[]`.
482
- `RelayResult.deadLettered` counts per-batch transitions.
483
- - **Purge** — `outbox.purge(olderThanMs)` deletes delivered rows; define
484
- retention via a TTL index (`deliveredAt`), a cron, or a scheduler —
485
- your kit's choice.
120
+ Streams options: `stream` ('arc:events'), `group` ('default'), `consumer`, `blockTimeMs` (5000), `batchSize` (10), `processingConcurrency` (1, keeps order), `maxRetries` (5), `claimTimeoutMs` (30000), `deadLetterStream` ('arc:events:dlq' or `false`), `maxLen` (0), `groupStart` ('latest' | 'beginning'), `maxPayloadBytes` (1 MB), `externalLifecycle`.
486
121
 
487
- You own the schema and indexes. Recommended shape:
488
- `{ eventId (unique), type, payload, meta, status, attempts, leaseOwner,
489
- leaseExpiresAt, visibleAt, dedupeKey (unique sparse), lastError,
490
- createdAt, deliveredAt }` with indexes on `{ status, visibleAt }` and
491
- `{ deliveredAt }` (TTL).
122
+ - Pub/Sub loses events when no subscriber is connected. Use Streams for billing, payments, audit, replay.
123
+ - Redis backing events, BullMQ jobs, or idempotency needs `maxmemory-policy noeviction`. Pure caches use `allkeys-lru`.
124
+ - Custom transport: implement `EventTransport` (`name`, `publish`, `subscribe(pattern, handler)` returning unsubscribe, `close`, optional `deadLetter`, `publishMany`).
125
+ - Every transport and wrapper takes `logger` (`fastify.log` works).
126
+ - Multi-instance deployments must not rely on the default memory transport.
@@ -0,0 +1,74 @@
1
+ # Jobs (BullMQ)
2
+
3
+ ```typescript
4
+ import { jobsPlugin, defineJob } from '@classytic/arc/integrations/jobs';
5
+ ```
6
+
7
+ Peers: `bullmq`, Redis (with `maxmemory-policy noeviction`).
8
+
9
+ ## Define
10
+
11
+ ```typescript
12
+ const sendEmail = defineJob({
13
+ name: 'send-email', // unique; also the queue name
14
+ handler: async (data: { to: string; subject: string }, meta) => {
15
+ await mailer.send(data.to, data.subject, { signal: meta.signal });
16
+ return { sent: true };
17
+ },
18
+ retries: 3, // default 3
19
+ backoff: { type: 'exponential', delay: 1000 },
20
+ timeout: 30000, // default 30000; aborts meta.signal
21
+ concurrency: 5, // BullMQ concurrency per worker
22
+ maxConcurrent: 2, // arc semaphore for a downstream limit
23
+ cancelGraceMs: 30000, // max time a timed-out handler holds its slot
24
+ rateLimit: { max: 100, duration: 60000 },
25
+ deadLetterQueue: 'send-email:dead', // default '<name>-dead'
26
+ repeat: { pattern: '0 9 * * *', tz: 'UTC' }, // cron needs tz; or { every: ms }, plus endDate, limit
27
+ });
28
+ ```
29
+
30
+ - `meta`: `{ jobId, attemptsMade, timestamp, signal }`. Pass `signal` to fetch and DB calls, or a timed-out handler keeps running and a retry can overlap it. Make handlers idempotent.
31
+
32
+ ## Register
33
+
34
+ ```typescript
35
+ await app.register(jobsPlugin, {
36
+ connection: { host: 'localhost', port: 6379 },
37
+ jobs: [sendEmail],
38
+ mode: 'both', // 'producer' (queues only, API fleets) | 'worker' | 'both'
39
+ bridgeEvents: true, // default
40
+ defaults: { retries: 3, backoff: { type: 'exponential', delay: 1000 }, removeOnComplete: 100, removeOnFail: 500 },
41
+ });
42
+ ```
43
+
44
+ Repeat schedules are reconciled by the side that runs workers.
45
+
46
+ ## Dispatch
47
+
48
+ ```typescript
49
+ const { queue, jobId } = await app.jobs.dispatch('send-email', { to: 'a@b.co', subject: 'Hi' }, {
50
+ delay: 5000, priority: 1, jobId: 'dedupe-key', removeOnComplete: true,
51
+ });
52
+ const status = await app.jobs.getStatus(queue, jobId); // JobStatus | null; ids are queue-local
53
+ const stats = await app.jobs.getStats(); // { [queue]: { waiting, active, completed, failed, delayed } }
54
+ ```
55
+
56
+ `app.jobs` also has `getQueue(name)` and `close()`.
57
+
58
+ ## Management routes (off by default)
59
+
60
+ ```typescript
61
+ import { requirePlatformRole } from '@classytic/arc/permissions';
62
+
63
+ managementRoutes: {
64
+ operatorPermission: requirePlatformRole('platform-ops'), // required, platform-only
65
+ exposeResult: false, // default: hide returnValue
66
+ exposeFailureReason: false, // default: hide failedReason
67
+ }
68
+ ```
69
+
70
+ Mounts `GET <prefix>/stats` (prefix default `/jobs`) and `GET <prefix>/:queue/:id/status`. Both are global (a job carries no tenant), so org-role gates are refused at boot; `allowUnverifiedOperatorPermission: true` accepts a custom check you verified.
71
+
72
+ ## Event bridge
73
+
74
+ With `bridgeEvents`, the bus gets `job.<name>.completed` (`{ jobId, data, result }`), `job.<name>.failed` (`{ jobId, data, error, attemptsMade }`), `job.<name>.stalled` (`{ jobId }`). Publishing is best effort and never fails the worker.