@classytic/arc 2.45.2 → 2.47.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 (333) hide show
  1. package/README.md +1 -1
  2. package/dist/{EventTransport-DHb1tpu-.mjs → EventTransport-BHKy4_Bi.mjs} +5 -6
  3. package/dist/{EventTransport-CiicKz2Z.d.mts → EventTransport-CYEoCJGe.d.mts} +0 -2
  4. package/dist/{HookSystem-C1u0EUnt.mjs → HookSystem-CAIDVoKC.mjs} +3 -4
  5. package/dist/{QueryCache--5uAuYPW.d.mts → QueryCache-DdvrGG8Q.d.mts} +1 -3
  6. package/dist/{ResourceRegistry-D2jXWVN_.mjs → ResourceRegistry-23Ml6FNe.mjs} +15 -4
  7. package/dist/{acquire-DTkA8Lme.mjs → acquire-DoFX06fm.mjs} +2 -3
  8. package/dist/{actionPermissions-DRVk6m7x.mjs → actionPermissions-DXrlWHHK.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-DYiubkYw.mjs} +5 -6
  18. package/dist/{base-CZyixEQR.d.mts → base-HXNgPQww.d.mts} +1 -7
  19. package/dist/{boundedMap-DkKiPifd.mjs → boundedMap-CtdzpJ3X.mjs} +2 -3
  20. package/dist/{buildHandler-BiZ4VATS.mjs → buildHandler-CARdmPNo.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-QRiryDLs.mjs} +3 -4
  24. package/dist/{claimed-ChI13rUR.mjs → claimed-BLecr1j3.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-Cx7BcnHT.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-0WyMuo0f.mjs} +9 -12
  47. package/dist/{createActionRouter-CvH84dyx.mjs → createActionRouter-mLAGbpDV.mjs} +7 -8
  48. package/dist/{createAggregationRouter-DGyK2Hp6.mjs → createAggregationRouter-BEAjn3dA.mjs} +9 -10
  49. package/dist/{createApp-CKjZpmq9.mjs → createApp-QDP4vYWH.mjs} +49 -62
  50. package/dist/{createMcpServer-DSztofa9.d.mts → createMcpServer-DzXHX0SO.d.mts} +1 -3
  51. package/dist/{defineAggregation-BLza7Ca4.mjs → defineAggregation-CFNfvz-C.mjs} +2 -3
  52. package/dist/{defineResource-CEo0gDCb.mjs → defineResource-BROJmhzJ.mjs} +80 -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-BW2J3tNj.d.mts → elevation-DPD0hcU-.d.mts} +0 -2
  58. package/dist/{elevation-BJTsSnke.mjs → elevation-DrXeEWWk.mjs} +9 -10
  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-BiBXtxj4.mjs} +16 -6
  63. package/dist/{errors-JYc9vwqE.d.mts → errors-DTo0me1o.d.mts} +0 -2
  64. package/dist/{errors-grZkIA8N.mjs → errors-DnrUChAy.mjs} +2 -3
  65. package/dist/{eventPlugin-BtmA4-3P.d.mts → eventPlugin-BY38F6yK.d.mts} +1 -7
  66. package/dist/{eventPlugin-ItcYBGUs.mjs → eventPlugin-BhKLUe7H.mjs} +10 -12
  67. package/dist/{eventTypes-Ck6fD3ne.mjs → eventTypes-CCIRGakw.mjs} +5 -8
  68. package/dist/events/index.d.mts +5 -17
  69. package/dist/events/index.mjs +9 -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-bzkWPt1f.d.mts} +4 -10
  78. package/dist/{fields-BRX0Krcj.mjs → fields-CYdpcV73.mjs} +2 -3
  79. package/dist/{fields-BBSpf8pS.d.mts → fields-JTkrtO-r.d.mts} +0 -2
  80. package/dist/{filter-merge-CDc7YMwX.mjs → filter-merge-6kasezRH.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-DUkcbc4r.mjs} +7 -12
  83. package/dist/{headers-Cqkg4LzI.mjs → headers-KxhrKevA.mjs} +3 -4
  84. package/dist/{health-PVt0VjOx.mjs → health-CRJg3IIq.mjs} +2 -3
  85. package/dist/{health-DyeP3mTW.mjs → health-jkYNdobJ.mjs} +4 -7
  86. package/dist/hooks/index.d.mts +1 -1
  87. package/dist/hooks/index.mjs +2 -2
  88. package/dist/http-cache/index.d.mts +211 -0
  89. package/dist/http-cache/index.mjs +605 -0
  90. package/dist/http-cache/purgers/cloudflare.d.mts +13 -0
  91. package/dist/http-cache/purgers/cloudflare.mjs +46 -0
  92. package/dist/http-cache/purgers/fastly.d.mts +12 -0
  93. package/dist/http-cache/purgers/fastly.mjs +47 -0
  94. package/dist/http-cache/testing/index.d.mts +68 -0
  95. package/dist/http-cache/testing/index.mjs +168 -0
  96. package/dist/idempotency/index.d.mts +3 -9
  97. package/dist/idempotency/index.mjs +11 -14
  98. package/dist/idempotency/redis.d.mts +1 -1
  99. package/dist/idempotency/redis.mjs +3 -4
  100. package/dist/{index-Bxriq3so.d.mts → index-B5i9-vuP.d.mts} +4 -26
  101. package/dist/{index-Chgz3d0i.d.mts → index-BAXDo5eE.d.mts} +1 -7
  102. package/dist/{index-Beg3aNnK.d.mts → index-BxZS-8So.d.mts} +67 -25
  103. package/dist/{index-WH7xgvxS.d.mts → index-Cy2-QffW.d.mts} +40 -92
  104. package/dist/{index-uhkUA5-U.d.mts → index-D1X_C_qz.d.mts} +13 -23
  105. package/dist/{index-CUJvoyw3.d.mts → index-DFCCQ9AE.d.mts} +2 -24
  106. package/dist/index.d.mts +7 -9
  107. package/dist/index.mjs +12 -13
  108. package/dist/{init-jC3rMPzb.mjs → init-CACwpktI.mjs} +18 -35
  109. package/dist/{init-Cscs4lab.d.mts → init-CV2_Fw3H.d.mts} +0 -4
  110. package/dist/integrations/event-gateway.d.mts +3 -5
  111. package/dist/integrations/event-gateway.mjs +3 -4
  112. package/dist/integrations/index.d.mts +3 -3
  113. package/dist/integrations/index.mjs +1 -1
  114. package/dist/integrations/jobs/index.d.mts +1 -1
  115. package/dist/integrations/jobs/index.mjs +7 -11
  116. package/dist/integrations/mcp/index.d.mts +7 -39
  117. package/dist/integrations/mcp/index.mjs +8 -14
  118. package/dist/integrations/mcp/testing.d.mts +3 -5
  119. package/dist/integrations/mcp/testing.mjs +3 -4
  120. package/dist/integrations/streamline.d.mts +1 -3
  121. package/dist/integrations/streamline.mjs +4 -5
  122. package/dist/integrations/webhooks.d.mts +2 -4
  123. package/dist/integrations/webhooks.mjs +5 -5
  124. package/dist/integrations/websocket-pushref-redis.d.mts +2 -4
  125. package/dist/integrations/websocket-pushref-redis.mjs +2 -3
  126. package/dist/integrations/websocket-redis.d.mts +2 -4
  127. package/dist/integrations/websocket-redis.mjs +2 -3
  128. package/dist/integrations/websocket.d.mts +2 -2
  129. package/dist/integrations/websocket.mjs +13 -24
  130. package/dist/{interface-JJzwH4Ro.d.mts → interface-BmExzQRD.d.mts} +0 -2
  131. package/dist/{interface-BOk3YnTz.d.mts → interface-WR1U0K7t.d.mts} +0 -2
  132. package/dist/{jsonBody-ptwyzZQ-.mjs → jsonBody-CzDBkCme.mjs} +3 -4
  133. package/dist/{keys-C1vFuSbv.mjs → keys-Cbwf6r1B.mjs} +2 -3
  134. package/dist/{loadResources-CHPDyIPn.mjs → loadResources-Kr6vuljv.mjs} +4 -5
  135. package/dist/{loadResourcesFromEntry-BkHHTu_B.mjs → loadResourcesFromEntry-D2e0qoDR.mjs} +3 -4
  136. package/dist/logger/index.d.mts +1 -3
  137. package/dist/logger/index.mjs +2 -2
  138. package/dist/{logger-C5bvCiAK.mjs → logger-C110X5Yz.mjs} +3 -5
  139. package/dist/{mcpPlugin-C9qohJCF.mjs → mcpPlugin-4lIPr9OJ.mjs} +41 -60
  140. package/dist/{memory-CxiTwT0j.mjs → memory-D9qkhXiB.mjs} +4 -5
  141. package/dist/{metrics-Ckp2zRy-.mjs → metrics-B-qrrWfI.mjs} +4 -5
  142. package/dist/middleware/index.d.mts +1 -5
  143. package/dist/middleware/index.mjs +4 -5
  144. package/dist/migrations/index.d.mts +0 -2
  145. package/dist/migrations/index.mjs +3 -4
  146. package/dist/{module-CfnKuIuH.mjs → module-BD8xHgrz.mjs} +2 -3
  147. package/dist/{multiTenant-CAtYlW6H.d.mts → multiTenant-KZj8j1uJ.d.mts} +1 -5
  148. package/dist/{multipartBody-BFasGtP9.mjs → multipartBody-qU7KCn1l.mjs} +2 -3
  149. package/dist/observeSend-BnPtTotW.mjs +20 -0
  150. package/dist/{openapi-DAPxjYHX.mjs → openapi-DoVa5SVP.mjs} +18 -28
  151. package/dist/outbox-admin/index.d.mts +2 -4
  152. package/dist/outbox-admin/index.mjs +6 -7
  153. package/dist/{outbox-module-gZCHoE4H.d.mts → outbox-module-5Mnwcycy.d.mts} +3 -9
  154. package/dist/outbox-module-DyITEIop.mjs +297 -0
  155. package/dist/permissions/index.d.mts +4 -4
  156. package/dist/permissions/index.mjs +7 -7
  157. package/dist/{permissions-B14c3OMp.mjs → permissions-BBy4bOGi.mjs} +19 -29
  158. package/dist/{pipe-CQv7PsAK.mjs → pipe-BOm2o4UA.mjs} +3 -4
  159. package/dist/pipeline/index.d.mts +1 -9
  160. package/dist/pipeline/index.mjs +5 -8
  161. package/dist/{plan-CpnTykjb.mjs → plan-DDIGwuxr.mjs} +5 -9
  162. package/dist/{plugin-DXTjVg_Q.mjs → plugin-Bn4D_0XK.mjs} +156 -64
  163. package/dist/plugins/index.d.mts +8 -16
  164. package/dist/plugins/index.mjs +22 -26
  165. package/dist/plugins/response-cache.d.mts +2 -4
  166. package/dist/plugins/response-cache.mjs +10 -10
  167. package/dist/plugins/tracing-entry.d.mts +1 -1
  168. package/dist/plugins/tracing-entry.mjs +3 -4
  169. package/dist/{pluralize-C3VJKRGp.mjs → pluralize-ClEjcKlG.mjs} +2 -3
  170. package/dist/policy.types-DPqToKG1.d.mts +50 -0
  171. package/dist/presets/filesUpload.d.mts +4 -6
  172. package/dist/presets/filesUpload.mjs +6 -7
  173. package/dist/presets/index.d.mts +3 -19
  174. package/dist/presets/index.mjs +2 -2
  175. package/dist/presets/multiTenant.d.mts +1 -1
  176. package/dist/presets/multiTenant.mjs +7 -7
  177. package/dist/presets/search.d.mts +3 -5
  178. package/dist/presets/search.mjs +3 -4
  179. package/dist/{presets-CquqYJPy.mjs → presets-DK2jh5YR.mjs} +11 -18
  180. package/dist/{projection-CgfSLOSM.mjs → projection-BHH-sXyS.mjs} +3 -4
  181. package/dist/purger.types-2wNJK_89.mjs +24 -0
  182. package/dist/purger.types-DvPp4-yd.d.mts +26 -0
  183. package/dist/{pushref-registry-UxCkoA4C.d.mts → pushref-registry-d86QUaSq.d.mts} +0 -6
  184. package/dist/{queryCachePlugin-D0HUISHJ.mjs → queryCachePlugin-Ckqe98AM.mjs} +8 -10
  185. package/dist/{queryCachePlugin-C2lZjTxk.d.mts → queryCachePlugin-DYQUyeJ9.d.mts} +2 -4
  186. package/dist/{rateLimitKey-AvkBOMkl.mjs → rateLimitKey-CWAjlqcN.mjs} +2 -3
  187. package/dist/{realtime-CbWtVbqK.mjs → realtime-BIJi9USY.mjs} +17 -19
  188. package/dist/{redis-BDgv9Glw.d.mts → redis-RpDMemdm.d.mts} +2 -4
  189. package/dist/{redis-stream-BMk-bpQS.d.mts → redis-stream-CS1N9dwM.d.mts} +1 -3
  190. package/dist/{redisShapes-CQksY67q.d.mts → redisShapes-CqBXTn_s.d.mts} +0 -2
  191. package/dist/registry/index.d.mts +2 -12
  192. package/dist/registry/index.mjs +3 -3
  193. package/dist/{registry-BVwpAuFI.mjs → registry-y9ZA-R_J.mjs} +7 -12
  194. package/dist/{outbox-module-B4FAkx3A.mjs → relay-BNrC1CEP.mjs} +8 -306
  195. package/dist/{renewingLease-CykpeNcQ.mjs → renewingLease-CS43br5E.mjs} +2 -3
  196. package/dist/{replyHelpers-DA51IZio.mjs → replyHelpers-oZDzakGb.mjs} +3 -4
  197. package/dist/{requestContext-DIWHKDtQ.mjs → requestContext-fWb_YaV2.mjs} +2 -3
  198. package/dist/{requirement-Cp_fsMDL.mjs → requirement--2hWyyHi.mjs} +2 -3
  199. package/dist/{requirement-CbiLdQ1n.d.mts → requirement-CTRQjjQx.d.mts} +0 -2
  200. package/dist/{resourceRateLimit-BFuluodF.mjs → resourceRateLimit-1WbcyMZY.mjs} +3 -4
  201. package/dist/{resourceRateLimit-Wf6d6FL9.d.mts → resourceRateLimit-DCWglD7V.d.mts} +1 -3
  202. package/dist/{rolldown-runtime-D_lMdYOd.mjs → rolldown-runtime-yH2lHMo_.mjs} +2 -3
  203. package/dist/{routeValidator-DuLonYwr.mjs → routeValidator-BSlRIA5c.mjs} +2 -3
  204. package/dist/{runtimeCapabilities-CydRfm0i.mjs → runtimeCapabilities-CYCEtU1W.mjs} +2 -3
  205. package/dist/{schedules-B693KXxa.mjs → schedules-B5WGlYIT.mjs} +132 -9
  206. package/dist/{schemaConverter-DNvZWTV6.mjs → schemaConverter-DtNvts-6.mjs} +3 -4
  207. package/dist/{schemaIR-REV2y7Wd.mjs → schemaIR-uS_RHqa3.mjs} +3 -4
  208. package/dist/schemas/index.d.mts +0 -2
  209. package/dist/schemas/index.mjs +2 -3
  210. package/dist/scim/index.d.mts +0 -12
  211. package/dist/scim/index.mjs +10 -18
  212. package/dist/scope/index.d.mts +2 -6
  213. package/dist/scope/index.mjs +5 -5
  214. package/dist/{scope-Bevxy_ST.mjs → scope-BwVLSyNG.mjs} +5 -6
  215. package/dist/{sessionManager-qimlKV0P.d.mts → sessionManager-CdvDF04x.d.mts} +2 -4
  216. package/dist/{shutdown-CfrqPR7A.mjs → shutdown-BJiJN7FT.mjs} +2 -3
  217. package/dist/{simpleEqualityMatcher-BJwfuRKP.mjs → simpleEqualityMatcher-DGRLq-1k.mjs} +2 -3
  218. package/dist/{sse-CuNNWr2z.mjs → sse-B_50llZu.mjs} +8 -9
  219. package/dist/{sseStream-C_2ujAVY.mjs → sseStream-BjSo9Ult.mjs} +3 -4
  220. package/dist/{storage-Cx9Sz3Ou.d.mts → storage-odC5MNKN.d.mts} +0 -2
  221. package/dist/{store-helpers-C8uBGCbb.mjs → store-helpers-D-n5cwy5.mjs} +2 -3
  222. package/dist/{streaming-Bdq_M4d5.mjs → streaming-Dcgqa-hH.mjs} +2 -3
  223. package/dist/{subscriberIdentity-B-KpZkdl.mjs → subscriberIdentity-C9KhIXTF.mjs} +2 -3
  224. package/dist/{tenancy-C5PCvm1h.mjs → tenancy-COrhjPRZ.mjs} +3 -4
  225. package/dist/{tenantPreparation-dYvWrgNa.mjs → tenantPreparation-BElWHytd.mjs} +5 -6
  226. package/dist/testing/cleanupStoreContract.d.mts +2 -4
  227. package/dist/testing/cleanupStoreContract.mjs +2 -3
  228. package/dist/testing/index.d.mts +6 -32
  229. package/dist/testing/index.mjs +24 -37
  230. package/dist/testing/outboxStoreContract.d.mts +1 -3
  231. package/dist/testing/outboxStoreContract.mjs +3 -4
  232. package/dist/testing/requiredPorts.d.mts +2 -4
  233. package/dist/testing/requiredPorts.mjs +3 -4
  234. package/dist/testing/storageContract.d.mts +2 -4
  235. package/dist/testing/storageContract.mjs +2 -3
  236. package/dist/{timing-DCqsezX8.mjs → timing-CaxKbRk_.mjs} +3 -5
  237. package/dist/{tracing-Dro5eH6j.d.mts → tracing-JSFiBl5r.d.mts} +0 -2
  238. package/dist/{transactionContext-DrcNyjpv.mjs → transactionContext-8qKON0Nk.mjs} +2 -3
  239. package/dist/{typeGuards-CEl10KPy.mjs → typeGuards-DVjVSsXO.mjs} +2 -3
  240. package/dist/types/index.d.mts +4 -4
  241. package/dist/types/index.mjs +1 -1
  242. package/dist/types/storage.d.mts +1 -1
  243. package/dist/types/storage.mjs +1 -1
  244. package/dist/{types-ByHn9rEO.d.mts → types-0Dqlbgn8.d.mts} +0 -2
  245. package/dist/{types-BJ-2XqVF.d.mts → types-BeEJm-DV.d.mts} +114 -14
  246. package/dist/{types-DVLddu2q.d.mts → types-C0YJAiL0.d.mts} +0 -2
  247. package/dist/{types-D9NWjpYc.mjs → types-DZHqOuJE.mjs} +5 -6
  248. package/dist/{types-D3Ixsh00.d.mts → types-DeLiuaNv.d.mts} +2 -4
  249. package/dist/{types-Ddl9OjmE.d.mts → types-DnkIALZ8.d.mts} +0 -4
  250. package/dist/usage/index.d.mts +2 -10
  251. package/dist/usage/index.mjs +8 -12
  252. package/dist/{userHelpers-BHig1kHq.mjs → userHelpers-_eGj6kf0.mjs} +2 -3
  253. package/dist/utils/index.d.mts +5 -39
  254. package/dist/utils/index.mjs +12 -12
  255. package/dist/{utils-BG5P7_Vb.mjs → utils-Dd6MWpye.mjs} +20 -30
  256. package/dist/{validate-D_mdOCir.mjs → validate-BaF5wd0x.mjs} +5 -7
  257. package/dist/{versioning-DBGHjPh7.mjs → versioning-DyV7mwtK.mjs} +4 -5
  258. package/dist/{versioning-Bqm_57Qt.d.mts → versioning-S18y2-0C.d.mts} +1 -15
  259. package/dist/{websocket-Cs4awVyD.d.mts → websocket-BGuc-WVZ.d.mts} +1 -15
  260. package/dist/{workScope-DPPfM4m6.mjs → workScope-CmCBUmPR.mjs} +3 -4
  261. package/llms.txt +37 -30
  262. package/package.json +51 -22
  263. package/skills/arc/SKILL.md +65 -844
  264. package/skills/arc/references/agent-auth.md +82 -193
  265. package/skills/arc/references/api-reference.md +41 -245
  266. package/skills/arc/references/auth-api-keys.md +99 -0
  267. package/skills/arc/references/auth-better-auth-overlay.md +87 -0
  268. package/skills/arc/references/auth-better-auth.md +78 -0
  269. package/skills/arc/references/auth-permissions.md +100 -0
  270. package/skills/arc/references/auth-strategies.md +122 -0
  271. package/skills/arc/references/boot.md +80 -0
  272. package/skills/arc/references/enterprise-auth.md +65 -81
  273. package/skills/arc/references/events-outbox.md +90 -0
  274. package/skills/arc/references/events.md +75 -440
  275. package/skills/arc/references/integrations-jobs.md +74 -0
  276. package/skills/arc/references/integrations-realtime.md +84 -0
  277. package/skills/arc/references/integrations-webhooks.md +71 -0
  278. package/skills/arc/references/integrations-workflows.md +47 -0
  279. package/skills/arc/references/mcp-auth.md +83 -0
  280. package/skills/arc/references/mcp-custom-tools.md +125 -0
  281. package/skills/arc/references/mcp-setup.md +115 -0
  282. package/skills/arc/references/mcp-testing.md +63 -0
  283. package/skills/arc/references/multi-tenancy.md +56 -230
  284. package/skills/arc/references/permissions-scope.md +81 -0
  285. package/skills/arc/references/production-api.md +119 -0
  286. package/skills/arc/references/production-audit.md +101 -0
  287. package/skills/arc/references/production-boot.md +91 -0
  288. package/skills/arc/references/production-caching.md +63 -0
  289. package/skills/arc/references/production-distributed.md +75 -0
  290. package/skills/arc/references/production-idempotency.md +83 -0
  291. package/skills/arc/references/production-observability.md +83 -0
  292. package/skills/arc/references/production-realtime.md +70 -0
  293. package/skills/arc/references/production-reliability.md +100 -0
  294. package/skills/arc/references/production-shutdown.md +43 -0
  295. package/skills/arc/references/querying.md +76 -0
  296. package/skills/arc/references/resources.md +97 -0
  297. package/skills/arc/references/schedules.md +79 -0
  298. package/skills/arc/references/scim.md +61 -208
  299. package/skills/arc/references/tenancy-scope-install.md +82 -0
  300. package/skills/arc/references/testing.md +101 -144
  301. package/skills/arc/references/usage-cleanup-capabilities.md +45 -0
  302. package/skills/arc/references/validation.md +91 -0
  303. package/skills/arc/references/writes-hooks-errors.md +80 -0
  304. package/skills/arc-code-review/SKILL.md +67 -114
  305. package/skills/arc-code-review/references/arc-cheatsheet.md +68 -167
  306. package/skills/arc-code-review/references/mongokit-repositories.md +104 -0
  307. package/skills/arc-code-review/references/recipe-events-cache-jobs.md +112 -0
  308. package/skills/arc-code-review/references/recipe-resource.md +100 -0
  309. package/skills/arc-code-review/references/recipe-schemas-fields.md +93 -0
  310. package/skills/arc-code-review/references/recipe-scope-permissions.md +82 -0
  311. package/skills/arc-code-review/references/scaffolding.md +61 -198
  312. package/skills/arc-code-review/references/severity.md +49 -102
  313. package/skills/arc-code-review/references/smells-auth-scope.md +80 -0
  314. package/skills/arc-code-review/references/smells-data-events.md +66 -0
  315. package/skills/arc-code-review/references/smells-imports-style.md +59 -0
  316. package/skills/arc-code-review/references/smells-platform.md +89 -0
  317. package/skills/arc-code-review/references/smells-routes-schemas.md +66 -0
  318. package/skills/arc-module-publishing/SKILL.md +82 -208
  319. package/skills/arc-module-publishing/references/action-presets-and-plugins.md +87 -0
  320. package/skills/arc-module-publishing/references/build-and-types.md +73 -0
  321. package/skills/arc-module-publishing/references/module-lifecycle.md +101 -0
  322. package/skills/arc-module-publishing/references/package-manifest.md +34 -122
  323. package/skills/arc-module-publishing/references/publishing-workflow.md +44 -140
  324. package/skills/arc-module-publishing/references/resource-assembly.md +102 -0
  325. package/skills/arc-module-publishing/references/testing-packages.md +82 -0
  326. package/skills/arc/references/auth.md +0 -729
  327. package/skills/arc/references/integrations.md +0 -452
  328. package/skills/arc/references/mcp.md +0 -691
  329. package/skills/arc/references/production.md +0 -835
  330. package/skills/arc-code-review/references/anti-patterns.md +0 -1008
  331. package/skills/arc-code-review/references/migration-recipes.md +0 -649
  332. package/skills/arc-code-review/references/mongokit-migration.md +0 -360
  333. package/skills/arc-module-publishing/references/authoring-modules.md +0 -327
@@ -0,0 +1,91 @@
1
+ # Production: boot, runtime, roles, deployment
2
+
3
+ ## Production createApp
4
+
5
+ ```typescript
6
+ import { createApp } from '@classytic/arc/factory';
7
+
8
+ if (!process.env.JWT_SECRET || process.env.JWT_SECRET.length < 32) throw new Error('JWT_SECRET');
9
+ if (!process.env.ALLOWED_ORIGINS) throw new Error('ALLOWED_ORIGINS');
10
+
11
+ const app = await createApp({
12
+ preset: 'production',
13
+ runtime: 'memory', // REQUIRED with preset 'production': 'memory' | 'distributed'
14
+ auth: { type: 'jwt', jwt: { secret: process.env.JWT_SECRET } },
15
+ cors: { origin: process.env.ALLOWED_ORIGINS.split(','), credentials: true },
16
+ rateLimit: { max: 100, timeWindow: '1 minute' },
17
+ trustProxy: '10.0.0.0/8', // name the proxies; default false; a hop count is not accepted
18
+ arcPlugins: { queryCache: true, gracefulShutdown: { drainDelayMs: 10_000 } },
19
+ });
20
+ await app.listen({ port: 3000, host: '0.0.0.0' });
21
+ ```
22
+
23
+ | Option | Notes |
24
+ |---|---|
25
+ | `runtime` | `'memory'` = exactly one instance. `'distributed'` = more than one replica; audited at boot (production-distributed.md) |
26
+ | `trustProxy` | `true`, CIDR string/array, or `'loopback'`. Unset behind a proxy makes `request.ip` the proxy |
27
+ | `keepAliveTimeout` | Default 72000; keep above the LB idle timeout or you get intermittent 502 |
28
+ | `requestTimeout`, `connectionTimeout`, `bodyLimit`, `maxParamLength` | Fastify pass-through (body 1 MiB, param 400) |
29
+ | `underPressure` | Production preset sets `maxEventLoopDelay: 3000`; override `{ maxEventLoopDelay: 500 }`, disable `false` |
30
+ | `strictResourceDir`, `strictResources` | Throw on empty discovery or duplicate resource names; turn on in production |
31
+ | `resourceDir: import.meta.url` | Works from `src/` and `dist/`; a path string resolves against `process.cwd()` |
32
+
33
+ Response compression is not included: use the reverse proxy or CDN.
34
+
35
+ ## Roles
36
+
37
+ `role` decides which async machinery mounts (default `'all'`).
38
+
39
+ | Role | Behavior |
40
+ |---|---|
41
+ | `api`, `worker` | No module schedule arms run (outbox relay included) |
42
+ | `relay` | Only `kind: 'relay'` arms run; declaring `resources` or `resourceDir` throws |
43
+ | `scheduler` | Every arm runs; declaring HTTP resources throws |
44
+ | `all` | Everything |
45
+
46
+ `createWorker` (from `@classytic/arc/factory`) and `preset: 'worker'` build headless processes: resources register without mounting routes (`mountRoutes: false`).
47
+
48
+ ## Deployment
49
+
50
+ | Target | Preset | Entry |
51
+ |---|---|---|
52
+ | Docker/K8s, Cloud Run, Railway, Render, Fly | `production` | `app.listen()` |
53
+ | AWS Lambda, Vercel Serverless, Cloudflare Workers (`nodejs_compat`) | `edge` | `toFetchHandler(app)` |
54
+
55
+ ```typescript
56
+ import { createApp, toFetchHandler } from '@classytic/arc/factory';
57
+ const app = await createApp({ preset: 'edge', auth: { type: 'jwt', jwt: { secret } } });
58
+ export default { fetch: toFetchHandler(app) };
59
+ ```
60
+
61
+ `toFetchHandler` buffers both directions: no SSE, streaming or WebSocket. Publish events to a dedicated edge tier for realtime.
62
+
63
+ ## CORS
64
+
65
+ - Production without `cors.origin` warns. `origin: '*'` with `credentials: true` throws at boot; use an allow-list.
66
+ - Arc merges its headers (`x-organization-id`, `x-arc-scope`, `x-request-id`) into a declared `allowedHeaders` list and always exposes its own response headers.
67
+ - Mobile webviews (Capacitor, Ionic): add webview origins and expose the Better Auth bearer header.
68
+
69
+ ```typescript
70
+ cors: {
71
+ origin: [...webOrigins, 'https://localhost', 'capacitor://localhost'],
72
+ credentials: true,
73
+ exposedHeaders: ['set-auth-token'], // Better Auth bearer plugin; without it JS cannot read the token
74
+ },
75
+ trustProxy: true,
76
+ ```
77
+
78
+ Add the same origins to Better Auth `trustedOrigins`. Native HTTP clients send no `Origin`; CORS does not apply.
79
+
80
+ ## Security defaults
81
+
82
+ - Field-write permission denial rejects with 403 listing denied fields; `onFieldWriteDenied: 'strip'` per resource silently drops instead.
83
+ - Scope elevation always emits `arc.scope.elevated`: `fastify.events.subscribe('arc.scope.elevated', handler)`.
84
+ - `multiTenant` injects the caller's org on update, overwriting a body-supplied `organizationId`.
85
+ - `verifySignature(body, secret, sig)` throws `TypeError` unless body is a string or Buffer: register `@fastify/raw-body` and pass `req.rawBody`.
86
+ - Upload preset `sanitizeFilename` is strict by default; relax per adapter with `false`, `'*'` or a function.
87
+ - Logger redaction defaults to `DEFAULT_LOGGER_REDACT_PATHS` when you pass an object logger without `redact`.
88
+
89
+ ## Multi-domain deployments
90
+
91
+ Arc owns no domain routing, certificates or wildcard hosts. Resolve a custom tenant domain at a gateway or early plugin, then authorize through the normal permission path. Never treat `Host` or `X-Forwarded-Host` as tenant authorization: it only selects a candidate, membership resolution authorizes it (same rule as `resolveOrgFromHeader`).
@@ -0,0 +1,63 @@
1
+ # Production: caching
2
+
3
+ Three independent layers. Pick one per concern.
4
+
5
+ | Layer | Enable | Scope |
6
+ |---|---|---|
7
+ | QueryCache | `arcPlugins.queryCache` plus per-resource `cache` | Server data cache with stale-while-revalidate and mutation invalidation |
8
+ | HTTP caching headers | `arcPlugins.caching` | ETag, `Cache-Control`, 304 |
9
+ | Response cache | `responseCachePlugin` | In-process LRU of GET responses, per replica |
10
+
11
+ ## QueryCache
12
+
13
+ ```typescript
14
+ const app = await createApp({
15
+ arcPlugins: { queryCache: true }, // memory store
16
+ // distributed: stores: { queryCache: new RedisCacheStore({ client: redis }) }
17
+ });
18
+
19
+ defineResource({
20
+ name: 'product',
21
+ cache: {
22
+ staleTime: 30, // seconds fresh, no revalidation (default 0)
23
+ gcTime: 300, // seconds stale data is kept, the SWR window (default 60)
24
+ tags: ['catalog'], // cross-resource group
25
+ invalidateOn: { 'category.*': ['catalog'] }, // event pattern to tag invalidation
26
+ jitter: 0.1, // spread revalidation across keys
27
+ },
28
+ });
29
+ ```
30
+
31
+ - GET responses carry `x-cache: HIT | STALE | MISS`.
32
+ - POST, PATCH, DELETE bump the resource version and invalidate its cached queries; tags invalidate across resources.
33
+ - Keys are scoped by user and org, so tenants never share entries.
34
+ - `invalidateOn` needs `queryCachePlugin` (enabled by `arcPlugins.queryCache`); without it boot only warns and the rules are ignored.
35
+ - `RedisCacheStore` options: `client`, `prefix` (`arc:cache:`), `defaultTtlSeconds` (60), `maxEntryBytes`. Adapt clients with `ioredisAsCacheClient` / `upstashAsCacheClient`.
36
+ - Under `runtime: 'distributed'` a memory store fails the boot (production-distributed.md).
37
+
38
+ ## HTTP caching headers
39
+
40
+ ```typescript
41
+ createApp({ arcPlugins: { caching: { maxAge: 0, etag: true, conditional: true, methods: ['GET', 'HEAD'], exclude: ['/api/auth'], rules: [] } } });
42
+ ```
43
+
44
+ Requires `stores.cache` under `runtime: 'distributed'`.
45
+
46
+ ## Response cache
47
+
48
+ ```typescript
49
+ import { responseCachePlugin } from '@classytic/arc/plugins/response-cache';
50
+
51
+ await fastify.register(responseCachePlugin, {
52
+ maxEntries: 500, defaultTTL: 30,
53
+ rules: [{ match: '/api/products', ttl: 120 }, { match: '/api/users', ttl: 0 }],
54
+ exclude: ['/api/me'],
55
+ eventInvalidation: { patterns: { 'order.*': ['/api/products'] } },
56
+ xCacheHeader: true,
57
+ });
58
+ fastify.responseCache.invalidate('/api/products');
59
+ ```
60
+
61
+ - Per replica by design: correctness comes from short TTLs. Declared `accepted` in the capability audit.
62
+ - `responseCache.middleware` must run after authentication; the default key includes user and org.
63
+ - Prefer QueryCache when a resource needs shared, tagged invalidation.
@@ -0,0 +1,75 @@
1
+ # Production: distributed runtime
2
+
3
+ `runtime: 'distributed'` is the "more than one replica" switch. Boot fails when any subsystem holds state that exists only in this process. Two checks, one policy.
4
+
5
+ ## 1. Constructor guard (what `createApp` can see)
6
+
7
+ | Requirement | Applies when |
8
+ |---|---|
9
+ | `stores.events` durable transport | always |
10
+ | `stores.cache` | `arcPlugins.caching` enabled |
11
+ | `stores.queryCache` | `arcPlugins.queryCache` enabled |
12
+ | `stores.idempotency` | memory store is rejected; a missing one only warns |
13
+ | `rateLimit: { redis: client }` or `{ store }` | rate limiting on; `rateLimit: false` opts out |
14
+ | `arcPlugins.schedules.lock` (`LockAdapter`) or `singleReplica: true` | schedules object enabled; `singleReplica` claims exactly one replica arms schedules (the pinned `role: 'scheduler'` deployment) |
15
+
16
+ ## 2. Capability audit (end of boot)
17
+
18
+ Covers everything wired in `plugins()`, `bootstrap[]` or module phases. Subsystems declare themselves; undeclared-shared memory defaults fail the boot in one error naming every violator.
19
+
20
+ | Subsystem | Memory default | Shared fix |
21
+ |---|---|---|
22
+ | `auth.sessions` | `MemorySessionStore` | `RedisSessionStore` (`@classytic/arc/auth/redis`) |
23
+ | `usage.store` | `MemoryUsageStore` | `RedisUsageStore` (`@classytic/arc/usage`) |
24
+ | `audit.store` | `MemoryAuditStore` | `auditPlugin` `repository` or `customStores` |
25
+ | `cache.query` | `MemoryCacheStore` | `stores.queryCache: new RedisCacheStore({ client })` (`@classytic/arc/cache`) |
26
+ | `permissions.dynamic-cache` | internal memory | `cacheStore` option, and pass `fastify` so the audit sees it |
27
+ | `websocket.adapter` | `LocalWebSocketAdapter` | `RedisWebSocketAdapter` (`@classytic/arc/integrations/websocket-redis`) |
28
+ | `websocket.pushref-store` | memory | `RedisPushRefStore` (`@classytic/arc/integrations/websocket-pushref-redis`) via `pushRefStore` |
29
+ | `webhooks.store` | `MemoryWebhookStore` | pass `store`, or `createDurableWebhookModule` |
30
+ | `mcp.resource-rate-limit` | memory limiter | shared `rateLimit` backend, when resources declare `rateLimit` |
31
+ | `http.response-cache` | memory | none: declared `accepted` (per replica by design, short TTLs). Logged, never a failure |
32
+
33
+ Events: `stores.events` with `RedisEventTransport` (`@classytic/arc/events/redis`) or `RedisStreamTransport` (`@classytic/arc/events/redis-stream`).
34
+
35
+ ## Declare your own state
36
+
37
+ A replica-local cache built in `plugins()` belongs in the audit. Declare from anywhere a registration reaches, including your own encapsulated `fastify.register()`.
38
+
39
+ ```typescript
40
+ import { declareRuntimeCapability } from '@classytic/arc/utils';
41
+
42
+ declareRuntimeCapability(fastify, {
43
+ subsystem: 'billing.sequence-cache',
44
+ durability: 'memory', // 'memory' | 'shared'
45
+ detail: 'invoice numbering cached per process',
46
+ // accepted: true, // only when per-process is intended
47
+ });
48
+ ```
49
+
50
+ `accepted: true` must be stated by the declarant, never inferred.
51
+
52
+ ## Circuit breakers count per replica
53
+
54
+ `CircuitBreaker` state is in-process: with 50 pods and `failureThreshold: 5`, a dead downstream absorbs 250 real requests. Share the failure window:
55
+
56
+ ```typescript
57
+ import { CircuitBreaker, RedisCircuitBreakerState } from '@classytic/arc/utils';
58
+
59
+ const shared = new RedisCircuitBreakerState({ redis, windowMs: 60_000, prefix: 'arc:circuit:' });
60
+
61
+ const payments = new CircuitBreaker(charge, {
62
+ name: 'stripe.charges', // REQUIRED with sharedState: the key every replica counts under
63
+ failureThreshold: 5,
64
+ sharedState: shared,
65
+ });
66
+ ```
67
+
68
+ - Shares the failure signal, not the state machine: each replica still owns its own OPEN/HALF_OPEN probing.
69
+ - The success path never touches the network; a throwing store degrades to local counting.
70
+ - `windowMs` must be positive (fixed window, default 60s).
71
+
72
+ ## Gotchas
73
+
74
+ - Run migrations from one owner (deploy job) or pass a `lock`; see production-reliability.md.
75
+ - Relay, scheduler and worker processes: `role` in production-boot.md.
@@ -0,0 +1,83 @@
1
+ # Production: idempotency
2
+
3
+ Replays the stored response for a repeated mutation. Disabled unless `enabled: true`. Register it after authentication so the principal and tenant isolate keys.
4
+
5
+ ```typescript
6
+ import { idempotencyPlugin } from '@classytic/arc/idempotency';
7
+
8
+ await fastify.register(idempotencyPlugin, {
9
+ enabled: true,
10
+ headerName: 'idempotency-key', // default
11
+ ttlMs: 86_400_000, // cached response lifetime, default 24h
12
+ lockTimeoutMs: 30_000, // in-flight lease, default 30s
13
+ methods: ['POST', 'PUT', 'PATCH'],
14
+ include: [/\/orders/], // regex allowlist (optional)
15
+ exclude: [/\/health/], // wins over include
16
+ retryAfterSeconds: 1,
17
+ namespace: 'api', // fold into the fingerprint when deployments share one store
18
+ });
19
+ ```
20
+
21
+ | Case | Result |
22
+ |---|---|
23
+ | First request | Runs, stores the response |
24
+ | Retry, same key and body | Stored response, header `x-idempotency-replayed: true` |
25
+ | Same key, different body | 422 (fingerprint mismatch) |
26
+ | Concurrent, first still running | 409 with `Retry-After` |
27
+ | Key required but missing | 400 `arc.idempotency_key_required` |
28
+
29
+ ```typescript
30
+ fetch('/api/orders', { method: 'POST', headers: { 'Idempotency-Key': crypto.randomUUID() }, body });
31
+ ```
32
+
33
+ ## Require a key
34
+
35
+ ```typescript
36
+ defineResource({ name: 'order', idempotency: { required: ['create', 'update'] } }); // built-in write routes
37
+ ```
38
+
39
+ Boot fails when a listed op is not mounted or the plugin is disabled. Custom routes:
40
+
41
+ ```typescript
42
+ routes: [{
43
+ method: 'POST', path: '/:id/charge', handler: 'charge',
44
+ config: { idempotency: { required: true } }, // any method, DELETE included
45
+ }]
46
+ // action routes: { requiredActions: ['refund'] }
47
+ // handler owns at-most-once: { required: true, dedup: 'handler', owner: 'payments-runner' }
48
+ ```
49
+
50
+ `dedup: 'handler'` still demands the key and exposes `request.idempotencyKey`, but stores and replays nothing. A custom route using `fastify.idempotency.middleware` in its own `preHandler` must place it after `fastify.authenticate`.
51
+
52
+ ## Stores
53
+
54
+ ```typescript
55
+ // Memory (default; dev, single instance): omit repository and store.
56
+
57
+ // Redis (multi-instance)
58
+ import { RedisIdempotencyStore } from '@classytic/arc/idempotency/redis';
59
+ store: new RedisIdempotencyStore({ client: redis, prefix: 'idem:', ttlMs: 86_400_000 })
60
+ // ioredisAsIdempotencyClient / upstashAsIdempotencyClient adapt other clients
61
+
62
+ // Database via any RepositoryLike (needs getOne, deleteMany, findOneAndUpdate)
63
+ import { Repository, methodRegistryPlugin, batchOperationsPlugin, mongoOperationsPlugin } from '@classytic/mongokit';
64
+ const IdempotencyModel = mongoose.model(
65
+ 'IdempotencyKey',
66
+ new Schema({ _id: String }, { strict: false, strictQuery: false, timestamps: false }),
67
+ );
68
+ repository: new Repository(IdempotencyModel, [methodRegistryPlugin(), batchOperationsPlugin(), mongoOperationsPlugin()])
69
+ ```
70
+
71
+ - The schema must declare `_id: String` and `strictQuery: false`. A pathless schema under global `strictQuery: true` strips the key filter and replays one cached response to every key and user. A boot self-check (`selfCheck`, default on) refuses such a store.
72
+ - `repository` takes precedence over `store`. Arc closes only stores it built.
73
+ - With `createApp({ runtime: 'distributed' })`, pass `stores.idempotency`; a memory store is rejected.
74
+
75
+ ## IdempotencyStore contract
76
+
77
+ Required: `name`, `get`, `set`, `tryLock`, `unlock`, `isLocked`, `delete`, `deleteByPrefix`, `findByPrefix`. Optional: `acquire` (atomic check-and-lock), `setIfLocked` (fenced completion), `supportsFencedCompletion`, `completionReleasesLock`, `close`. A custom store without fencing needs `allowUnfencedCompletion: true`.
78
+
79
+ ## Gotchas
80
+
81
+ - A crash between the business write and completion, or a handler outliving its lease, can repeat effects: use `dedup: 'handler'` with a shared transaction or a unique constraint when replay protection alone is not enough.
82
+ - Utilities: `fastify.idempotency.invalidate(key)`, `.has(key)`, `.store`.
83
+ - MCP mutating tools accept `_idempotencyKey` against the same store (mcp-setup.md).
@@ -0,0 +1,83 @@
1
+ # Production: health, request id, metrics, tracing
2
+
3
+ `createApp` registers request id, health and graceful shutdown by default; metrics and versioning are opt-in under `arcPlugins`.
4
+
5
+ ## Health
6
+
7
+ ```typescript
8
+ const app = await createApp({
9
+ arcPlugins: {
10
+ health: {
11
+ prefix: '/_health',
12
+ version: '1.0.0',
13
+ checks: [
14
+ { name: 'mongo', check: () => mongoose.connection.readyState === 1 },
15
+ { name: 'redis', check: async () => (await redis.ping()) === 'PONG', timeout: 3000 },
16
+ { name: 'search', check: async () => search.isReady(), critical: false },
17
+ ],
18
+ },
19
+ },
20
+ });
21
+ ```
22
+
23
+ Manual: `fastify.register(healthPlugin, opts)` from `@classytic/arc/plugins`; `checks` run with an `AbortSignal`.
24
+
25
+ | Route | Response |
26
+ |---|---|
27
+ | `GET /_health` and `/_health/live` | 200 `{ status: 'ok', timestamp, version? }` |
28
+ | `GET /_health/ready` | 200 `{ status: 'ready', timestamp, checks: [{ name, healthy, duration, error? }] }` |
29
+ | ready, critical check failed | 503 `status: 'not_ready'` |
30
+ | ready, shutdown draining | 503 `status: 'draining'` (liveness stays 200) |
31
+
32
+ - `critical` defaults to true; only critical failures return 503.
33
+ - Health-check names must be unique across the app (duplicates throw at boot).
34
+ - `metrics: true` adds `/_health/metrics` with process metrics; `metricsCollector` replaces the body.
35
+
36
+ ## Request id
37
+
38
+ ```typescript
39
+ import { requestIdPlugin } from '@classytic/arc/plugins';
40
+ await fastify.register(requestIdPlugin, { header: 'x-request-id', setResponseHeader: true, generator: () => crypto.randomUUID() });
41
+ ```
42
+
43
+ Incoming ids are sanitized (max 128 chars, safe charset; repeated headers rejected). The id is echoed on the response and carried in logs.
44
+
45
+ ## Metrics
46
+
47
+ ```typescript
48
+ const app = await createApp({ arcPlugins: { metrics: { path: '/_metrics', prefix: 'arc', maxSeries: 1000, onCollect: (m) => pushToOtlp(m) } } });
49
+ // GET /_metrics: Prometheus text
50
+ ```
51
+
52
+ | Series (prefix `arc`) | Type |
53
+ |---|---|
54
+ | `arc_http_requests_total`, `arc_http_request_duration_seconds` | HTTP by method, route, status |
55
+ | `arc_crud_operations_total`, `arc_crud_operation_duration_seconds` | CRUD |
56
+ | `arc_cache_hits_total`, `arc_cache_misses_total` | cache |
57
+ | `arc_events_published_total`, `arc_events_consumed_total` | events |
58
+ | `arc_circuit_breaker_state` | breakers |
59
+
60
+ Programmatic: `fastify.metrics.recordOperation(resource, op, status, durationMs)`, `.recordCacheHit(resource)`, `.recordEventPublish(type)`, `.collect()`, `.reset()`. `maxSeries` bounds label cardinality per metric.
61
+
62
+ ## Tracing (OpenTelemetry)
63
+
64
+ Needs `@opentelemetry/api` plus the SDK and OTLP exporter packages; without them tracing is a no-op (`isTracingAvailable()`).
65
+
66
+ ```typescript
67
+ import { tracingPlugin, createSpan, traced } from '@classytic/arc/plugins/tracing';
68
+
69
+ await fastify.register(tracingPlugin, {
70
+ serviceName: 'my-api',
71
+ exporterUrl: 'http://localhost:4318/v1/traces', // default
72
+ sampleRate: 0.1, // default 1.0
73
+ autoInstrumentation: true,
74
+ });
75
+
76
+ // Custom span; span is null when tracing is off
77
+ return createSpan(req, 'processPayment', async (span) => {
78
+ span?.setAttribute('orderId', order.id);
79
+ return processPayment(order);
80
+ });
81
+ ```
82
+
83
+ `traced(spanName?)` decorates a method that receives the request as an argument. Use `getTraceHeaders` from `@classytic/arc/context` to propagate trace context into outbox rows.
@@ -0,0 +1,70 @@
1
+ # Production: SSE, realtime change feed, streaming routes
2
+
3
+ Pick by need:
4
+
5
+ | Need | Use |
6
+ |---|---|
7
+ | Per-user live views of a resource (list permission, row filter, field masking) | `arcPlugins.realtime` |
8
+ | Raw domain-event firehose | `arcPlugins.sse` |
9
+ | Bidirectional or geo rooms | `integrations/websocket` (its CRUD bridge is org-coarse: never expose row-permissioned resources through it) |
10
+ | Massive fan-out (viral feeds, live scores) | Publish once via `app.events.subscribe(...)` to a dedicated edge fan-out tier |
11
+
12
+ Both feeds need the event plugin (on by default).
13
+
14
+ ## Realtime change feed
15
+
16
+ ```typescript
17
+ const app = await createApp({
18
+ arcPlugins: { realtime: { path: '/realtime/:resource', heartbeat: 30_000, resources: ['order'], maxConnectionMs: 30 * 60_000 } },
19
+ });
20
+ ```
21
+
22
+ - `GET /realtime/:resource` (resource name) and multiplexed `GET /realtime?resources=a,b,c` (max 20).
23
+ - Gated by the resource's own `list` permission; per-event row filtering, tenant guard, field masking.
24
+ - Client: plain `EventSource` with `?token=` (`tokenQueryParam`, default `token`, `null` disables).
25
+ - No replay: on reconnect, refetch the list.
26
+ - Permission filters are snapshotted at connect. The feed closes at token `exp` and at `maxConnectionMs` (default 30 min) to bound staleness.
27
+
28
+ ## SSE plugin
29
+
30
+ ```typescript
31
+ const app = await createApp({
32
+ arcPlugins: {
33
+ sse: {
34
+ path: '/events/stream', // default
35
+ requireAuth: true, // default; throws at registration if fastify.authenticate is missing
36
+ patterns: ['order.*', 'product.*'],// default ['*']
37
+ orgScoped: true, // default: events with organizationId reach only that org
38
+ heartbeat: 30_000,
39
+ filter: (event, request) => true,
40
+ audience: (event) => [(event.payload as { ownerId: string }).ownerId], // keyed delivery; connections key on scope user id
41
+ },
42
+ },
43
+ });
44
+ // Manual: import { ssePlugin } from '@classytic/arc/plugins';
45
+ ```
46
+
47
+ - Events without `organizationId` reach every caller. An elevated admin with no active org sees all tenants.
48
+ - `orgScoped: false` only for a deliberately cross-tenant stream; keep `requireAuth` and add a `filter`.
49
+ - `fastify.sseStats()` returns `{ connections, keys }`.
50
+
51
+ ## Streaming custom routes
52
+
53
+ ```typescript
54
+ import { requireAuth } from '@classytic/arc/permissions';
55
+ import { pipeUIMessageStreamToReply } from '@classytic/arc/utils';
56
+
57
+ routes: [{
58
+ method: 'POST', path: '/chat',
59
+ streamResponse: true, // SSE headers, bypasses response serialization
60
+ permissions: requireAuth(),
61
+ preAuth: [(req) => { const t = (req.query as { token?: string }).token; if (t) req.headers.authorization = `Bearer ${t}`; }],
62
+ handler: async (req, reply) => {
63
+ await pipeUIMessageStreamToReply(reply, result.toUIMessageStream());
64
+ },
65
+ }]
66
+ ```
67
+
68
+ - `preAuth` handlers run before authentication; use them to promote `?token=` because `EventSource` cannot set headers. `promoteStreamTokenToHeader(request, 'token')` from `@classytic/arc/utils` does this safely (no-op when `Authorization` exists, token still fully authenticated).
69
+ - `openSseStream` (utils) takes over the socket after every gate has passed; no JSON error can be sent afterwards.
70
+ - Edge `toFetchHandler` cannot stream.
@@ -0,0 +1,100 @@
1
+ # Production: outbox, compensation, migrations
2
+
3
+ ## Event outbox
4
+
5
+ At-least-once delivery even when the transport is down. Prefer the module form: it owns the relay schedule, shutdown and a readiness check.
6
+
7
+ ```typescript
8
+ import { createOutboxModule, exponentialBackoff, repositoryAsOutboxStore } from '@classytic/arc/events';
9
+ import { Repository } from '@classytic/mongokit';
10
+
11
+ const outbox = createOutboxModule({
12
+ store: repositoryAsOutboxStore(new Repository(OutboxModel)),
13
+ relayEveryMs: 5000, // default
14
+ failurePolicy: ({ attempts }) =>
15
+ attempts >= 5 ? { deadLetter: true } : { retryAt: exponentialBackoff({ attempt: attempts }) },
16
+ health: { relayLagUnhealthyMs: 5 * 60_000, probeCacheMs: 5000 },
17
+ });
18
+
19
+ const app = await createApp({ modules: [outbox, orderModule] }); // consumers declare dependsOn: ['outbox']
20
+ ```
21
+
22
+ Writers use the module exports (`getModuleExports<OutboxModuleExports>(f, 'outbox')` from `@classytic/arc/factory`):
23
+
24
+ | Export | Use |
25
+ |---|---|
26
+ | `store` | Write events: `await store.save(event)`. Joins the active transaction automatically (`sessionProvider` defaults to `transactionContext.get()`), so the row commits with the domain write |
27
+ | `requestDrain()` | Nudge a relay pass after commit (milliseconds, not `relayEveryMs`); coalesced; never throws |
28
+ | `drain({ maxPasses })` | Await delivery including cascades; for tests and shutdown |
29
+ | `health()` | Same reading as the readiness check |
30
+ | `relay` | The `EventOutbox` |
31
+
32
+ - Always set a `failurePolicy`. Without one a failing row stays pending and is retried every poll forever, logging per event. `attempts` is the durable count and survives restarts.
33
+ - Readiness check `<name>.relay` is non-critical (pulling a pod does not drain the relay). Unhealthy on any dead letter or pending lag past `relayLagUnhealthyMs`; `alertEveryMs` also logs `OUTBOX_RELAY_LAG` / `OUTBOX_DEAD_LETTER`.
34
+ - `transport` defaults to the app's own event transport; `consumerId` defaults to a per-instance id and must stay unique per relay.
35
+ - Under `role: 'api'` or `'worker'` the relay arm does not run; run it in a `role: 'relay'` process.
36
+ - Store contract (`@classytic/primitives/outbox`): required `save`, `getPending`, `acknowledge`; optional `claimPending`, `claimPendingFenced`, `fail`, `getDeadLettered`, `requeue`, `purge`, `countByStatus`, `oldestPendingAgeMs`. Prove a custom store with `runOutboxStoreContract` from `@classytic/arc/testing/outbox`.
37
+
38
+ Hand-wired form (tests, custom scheduling):
39
+
40
+ ```typescript
41
+ import { EventOutbox, MemoryOutboxStore } from '@classytic/arc/events';
42
+
43
+ const relay = new EventOutbox({ store: new MemoryOutboxStore(), transport, batchSize: 100, failurePolicy });
44
+ // or { repository: new Repository(OutboxModel), transport }
45
+ await relay.store(event, { session });
46
+ await relay.relay(); // publishes pending to the transport
47
+ ```
48
+
49
+ ## Compensating transactions
50
+
51
+ In-process rollback: steps run in order, completed steps compensate in reverse on failure. A process crash skips compensation; for durable distributed workflows use `@classytic/streamline` or a workflow engine.
52
+
53
+ ```typescript
54
+ import { withCompensation, defineCompensation } from '@classytic/arc/utils';
55
+
56
+ const result = await withCompensation('place-order', [
57
+ {
58
+ name: 'reserve-inventory',
59
+ execute: async (ctx) => { const r = await inventory.reserve(ctx.items); ctx.reservationId = r.id; return r; },
60
+ compensate: async (_ctx, r) => { await inventory.release(r.id); },
61
+ },
62
+ { name: 'charge', execute: async (ctx) => payments.charge(ctx.total), compensate: async (_c, r) => payments.refund(r.chargeId) },
63
+ { name: 'email', execute: async (ctx) => mailer.send(ctx.email), fireAndForget: true },
64
+ ], { items, total, email }, {
65
+ onStepComplete: (step, res) => {}, onStepFailed: (step, err) => {}, onCompensate: (step) => {}, onHookError: (hook, err) => {},
66
+ });
67
+
68
+ if (!result.success) { /* result.failedStep, result.error, result.compensationErrors */ }
69
+ const placeOrder = defineCompensation('place-order', steps); // reusable: placeOrder.execute(ctx, hooks)
70
+ ```
71
+
72
+ - The context is a mutable copy shared by all steps.
73
+ - `fireAndForget` steps do not block, are not compensated, and appear only via `onStepFailed` on error; put must-survive side effects in the outbox.
74
+ - Compensation errors are collected in `result.compensationErrors` and never stop the rollback.
75
+ - Result is a union: `success: true` has `completedSteps` and `results`; `success: false` adds `failedStep`, `error`.
76
+
77
+ ## Migrations
78
+
79
+ ```typescript
80
+ import { defineMigration, MigrationRunner, MongoMigrationStore } from '@classytic/arc/migrations';
81
+
82
+ const v2 = defineMigration({
83
+ version: 2,
84
+ resource: 'product',
85
+ description: 'rename oldField',
86
+ up: async (db) => { await (db as mongo.Db).collection('products').updateMany({}, { $rename: { oldField: 'newField' } }); },
87
+ down: async (db) => { await (db as mongo.Db).collection('products').updateMany({}, { $rename: { newField: 'oldField' } }); },
88
+ });
89
+
90
+ const runner = new MigrationRunner(mongoose.connection.db, {
91
+ store: new MongoMigrationStore(mongoose.connection.db), // required
92
+ lock, // LockAdapter: concurrent runners fail fast
93
+ checksumMismatch: 'error', // default 'warn'
94
+ });
95
+ await runner.up([v2]);
96
+ ```
97
+
98
+ - Run migrations from one owner (deploy job or leader), not every replica at startup.
99
+ - Write migrations idempotently: a crash between `up()` and recording re-runs that migration.
100
+ - `runner.down(...)` and `runner.downTo(...)` roll back; `computeMigrationChecksum` detects edits to applied migrations.
@@ -0,0 +1,43 @@
1
+ # Production: graceful shutdown
2
+
3
+ Registered by default (`arcPlugins.gracefulShutdown`). Configure inline from `createApp`, or register `gracefulShutdownPlugin` from `@classytic/arc/plugins`.
4
+
5
+ ```typescript
6
+ const app = await createApp({
7
+ arcPlugins: {
8
+ gracefulShutdown: {
9
+ timeout: 30_000, // hard cap; drainDelayMs counts against it
10
+ drainDelayMs: 10_000, // lame-duck window, default 0
11
+ signals: ['SIGTERM', 'SIGINT'],
12
+ logEvents: true,
13
+ onShutdown: async () => {
14
+ await mongoose.disconnect();
15
+ await redis.quit();
16
+ },
17
+ onForceExit: (reason) => process.exit(1), // reason: 'timeout' | 'error'; stub it in tests
18
+ },
19
+ },
20
+ });
21
+ ```
22
+
23
+ ## Sequence
24
+
25
+ 1. Signal arrives: `fastify.shutdownState.draining = true`; `/_health/ready` returns 503 `draining`.
26
+ 2. Wait `drainDelayMs`, still serving everything routed here. `/_health/live` stays 200.
27
+ 3. `fastify.close()`: stop accepting, drain in-flight requests.
28
+ 4. `onShutdown()`: release what arc does not own (DB connections, your Redis client).
29
+ 5. Exit naturally; `onForceExit` fires if `timeout` elapses or a step throws.
30
+
31
+ ## Rolling-deploy 502
32
+
33
+ With `drainDelayMs: 0` the instance closes the moment SIGTERM arrives, while the load balancer keeps routing to it until its readiness probe has failed for several intervals.
34
+
35
+ - Set `drainDelayMs` above the LB deregistration window, typically 5000 to 15000 ms.
36
+ - Kubernetes: keep `terminationGracePeriodSeconds` greater than `drainDelayMs + timeout`, or the kubelet SIGKILLs mid-drain.
37
+ - Liveness must not fail while draining: a 503 there gets the pod killed instead of drained.
38
+
39
+ ## Gotchas
40
+
41
+ - `fastify.close()` runs before `onShutdown`: do not close anything an in-flight request still needs from `onShutdown`.
42
+ - Do not add `process.on('SIGTERM', () => app.close())`. The plugin owns the signals; a second handler closes immediately and skips the drain.
43
+ - Stores and clients you pass into arc are yours to close (in `onShutdown`).