@classytic/arc 2.45.1 → 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-4b0noGwa.mjs → EventTransport-DNgD9NP4.mjs} +3 -4
  4. package/dist/{HookSystem-4pABQnGn.mjs → HookSystem-DRbPzEcP.mjs} +3 -4
  5. package/dist/{QueryCache--5uAuYPW.d.mts → QueryCache-DdvrGG8Q.d.mts} +1 -3
  6. package/dist/{ResourceRegistry-BBaN_Ne-.mjs → ResourceRegistry-Douk51fa.mjs} +15 -4
  7. package/dist/{acquire-kiZzy5bX.mjs → acquire-RbtvDg9s.mjs} +2 -3
  8. package/dist/{actionPermissions-BLnbDA6g.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-CVlaTjAX.mjs → authorizationDecision-DeZMrHcm.mjs} +5 -6
  18. package/dist/{base-CZyixEQR.d.mts → base-HXNgPQww.d.mts} +1 -7
  19. package/dist/{boundedMap-DSy7KkeX.mjs → boundedMap-2WBh3gM9.mjs} +2 -3
  20. package/dist/{buildHandler-B4IhILv9.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-DqakP2vY.mjs → caching-BYRwYrUo.mjs} +3 -4
  24. package/dist/{claimed-XoiVrWZ2.mjs → claimed-DYlELdnm.mjs} +2 -3
  25. package/dist/cleanup/index.d.mts +9 -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-CtWkmWn3.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-Cro2v5a7.mjs → core-D9rS2BxO.mjs} +9 -12
  47. package/dist/{createActionRouter-k-gwiPv6.mjs → createActionRouter-0qkCRzTL.mjs} +7 -8
  48. package/dist/{createAggregationRouter-BqWqhAPG.mjs → createAggregationRouter-CUf5Esd9.mjs} +9 -10
  49. package/dist/{createApp-Dw7L72Hz.mjs → createApp-DZIXfDKD.mjs} +49 -62
  50. package/dist/{createMcpServer-DSztofa9.d.mts → createMcpServer-DeVpqQF-.d.mts} +1 -3
  51. package/dist/{defineAggregation-pxbd7BBK.mjs → defineAggregation-bmKQ4NmC.mjs} +2 -3
  52. package/dist/{defineResource-DwgEjLCO.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-B9wF2Z1F.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-Dr2nG0Ui.mjs → errorHandler-dFyGOEoB.mjs} +16 -6
  63. package/dist/{errors-BtHzrSA6.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-Dvs7OBw8.mjs → eventPlugin-eMhAPtQA.mjs} +10 -12
  67. package/dist/{eventTypes-BVoCTG5c.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-C1e_7Fwi.mjs → fields-LnbCcvsw.mjs} +2 -3
  80. package/dist/{filter-merge-xaiEKtz8.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-DJiJMaXN.mjs → generate-oXoDnpJf.mjs} +7 -12
  83. package/dist/{headers-Dr-wt6Tr.mjs → headers-DBd3Qheo.mjs} +3 -4
  84. package/dist/{health-DkkWbJtQ.mjs → health-BlJu9GXS.mjs} +2 -3
  85. package/dist/{health-BLYn_Hds.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-CW3kJqNW.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-DPU8yYwA.mjs → jsonBody-DpRpKR_K.mjs} +3 -4
  125. package/dist/{keys-Dgn6OYhl.mjs → keys-FBz6Ull-.mjs} +2 -3
  126. package/dist/{loadResources-BtKj6P1P.mjs → loadResources-Bx1sKPnF.mjs} +4 -5
  127. package/dist/{loadResourcesFromEntry-Bmq6TnB7.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-qQNLlOAU.mjs → logger-CbFcIEBZ.mjs} +3 -5
  131. package/dist/{mcpPlugin-DDfe8jAP.mjs → mcpPlugin-yix548XX.mjs} +41 -60
  132. package/dist/{memory-C0Blueoh.mjs → memory-Bgw5dn8N.mjs} +4 -5
  133. package/dist/{metrics-DYka72iN.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-BszSyWbd.mjs → module-Dsc_nKL5.mjs} +2 -3
  139. package/dist/{multiTenant-CAtYlW6H.d.mts → multiTenant-XCxAUlru.d.mts} +1 -5
  140. package/dist/{multipartBody-RHvIkNmc.mjs → multipartBody-B85ek8Kj.mjs} +2 -3
  141. package/dist/observeSend-BK-JN1jK.mjs +20 -0
  142. package/dist/{openapi-BrFPc3Ny.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-DF4Bu_Qa.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-DN1CWH56.mjs → permissions-A1oKtpiC.mjs} +19 -29
  150. package/dist/{pipe-B8uq865o.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-DUGfynNg.mjs → plan-KVseuBCL.mjs} +5 -9
  154. package/dist/{plugin-ByU3h-bR.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-Cdya8zYt.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-CCOlKTZw.mjs → presets-qKCehiJM.mjs} +11 -18
  171. package/dist/{projection-BGty6ie4.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-B7itTkWu.mjs → queryCachePlugin-3gJj5Rbz.mjs} +8 -10
  174. package/dist/{queryCachePlugin-C2lZjTxk.d.mts → queryCachePlugin-DYQUyeJ9.d.mts} +2 -4
  175. package/dist/{rateLimitKey-DBWO59H9.mjs → rateLimitKey-Kro---xl.mjs} +2 -3
  176. package/dist/{realtime-_59Rlje8.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-uG4wr541.mjs → registry-BA-_vFYk.mjs} +7 -12
  183. package/dist/{renewingLease-CiU3ZynH.mjs → renewingLease-CMY8YOcc.mjs} +2 -3
  184. package/dist/{replyHelpers-Dr2pnXZg.mjs → replyHelpers-DK9P_XSz.mjs} +3 -4
  185. package/dist/{requestContext-DBKIdmDi.mjs → requestContext-GYO_0gEw.mjs} +2 -3
  186. package/dist/{requirement-CbiLdQ1n.d.mts → requirement-CTRQjjQx.d.mts} +0 -2
  187. package/dist/{requirement-DxOaghWD.mjs → requirement-DeNjZIH3.mjs} +2 -3
  188. package/dist/{resourceRateLimit-Wf6d6FL9.d.mts → resourceRateLimit-DCWglD7V.d.mts} +1 -3
  189. package/dist/{resourceRateLimit-BBdj5yRq.mjs → resourceRateLimit-tHLbrtWc.mjs} +3 -4
  190. package/dist/{rolldown-runtime-DpVPUeXF.mjs → rolldown-runtime-Kv1fZdLg.mjs} +2 -3
  191. package/dist/{routeValidator-BNTqM1Eh.mjs → routeValidator-C_H5NanI.mjs} +2 -3
  192. package/dist/{runtimeCapabilities-D_3eUO6V.mjs → runtimeCapabilities-DWqbxkyw.mjs} +2 -3
  193. package/dist/{schedules-CVS7c1nv.mjs → schedules-eO_RzhCU.mjs} +132 -9
  194. package/dist/{schemaConverter-BQbg7loK.mjs → schemaConverter-DBJrPZN4.mjs} +3 -4
  195. package/dist/{schemaIR-CUI3hPQR.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-DFXngazv.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-BCXCwghd.mjs → shutdown-DzLFbe27.mjs} +2 -3
  205. package/dist/{simpleEqualityMatcher-5jOzYQ_L.mjs → simpleEqualityMatcher-DOJhwQ8g.mjs} +2 -3
  206. package/dist/{sse-BilBz766.mjs → sse-2972pVwV.mjs} +8 -9
  207. package/dist/{sseStream-BG_uJL6J.mjs → sseStream-AWLEeNV-.mjs} +3 -4
  208. package/dist/{storage-Cx9Sz3Ou.d.mts → storage-odC5MNKN.d.mts} +0 -2
  209. package/dist/{store-helpers-CzLZdVa1.mjs → store-helpers-VzjgVTkM.mjs} +2 -3
  210. package/dist/{streaming-DgUvMWlv.mjs → streaming-DvraWW6x.mjs} +2 -3
  211. package/dist/{subscriberIdentity-EWnIZ-U8.mjs → subscriberIdentity-Bya56jsg.mjs} +2 -3
  212. package/dist/{tenancy-CVMvO5DH.mjs → tenancy-DSa_0hhw.mjs} +3 -4
  213. package/dist/{tenantPreparation-DIH-GX4g.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-q9NITK04.mjs → timing-6rQTuCwg.mjs} +3 -5
  225. package/dist/{tracing-Dro5eH6j.d.mts → tracing-JSFiBl5r.d.mts} +0 -2
  226. package/dist/{transactionContext-NHmhDIOF.mjs → transactionContext-DaxYUEgH.mjs} +2 -3
  227. package/dist/{typeGuards-CPYR9RCg.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-BI4sbUJ3.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-oBTU3a_k.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-BmE8zRrh.mjs → utils-CjjGOT4E.mjs} +20 -30
  244. package/dist/{validate-Dby08LhR.mjs → validate-4RlTKOJb.mjs} +5 -7
  245. package/dist/{versioning-P6JMNcJr.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-BcMLKa3G.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,1008 +0,0 @@
1
- # Arc Anti-Pattern Detection Catalog
2
-
3
- Every entry below has: **detection** (greppable regex / file pattern), **severity**, **why it matters**, and **fix** (with arc API citation). Run each detection against `src/` (excluding `node_modules`, `dist`, `coverage`, `*.test.*`).
4
-
5
- Severity legend: 🔴 Critical · 🟠 High · 🟡 Medium · 🟢 Low
6
-
7
- ---
8
-
9
- ## §1. Manual query parsing 🟡
10
-
11
- **Detection (Grep):**
12
- ```
13
- pattern: "req\\.query\\.(filter|sort|page|limit|search|q)\\b"
14
- glob: "**/*.{ts,js}"
15
- output_mode: content
16
- ```
17
- Also: `\\$or\\s*:\\s*\\[`, `\\$and\\s*:\\s*\\[`, `\\$regex`, `Number\\(req\\.query\\.`, `parseInt\\(req\\.query\\.`.
18
-
19
- **Anti-pattern:**
20
- ```typescript
21
- const filters: any = {};
22
- if (req.query.status) filters.status = req.query.status;
23
- if (req.query.minPrice) filters.price = { $gte: Number(req.query.minPrice) };
24
- if (req.query.q) {
25
- filters.$or = [
26
- { name: { $regex: req.query.q, $options: 'i' } },
27
- { description: { $regex: req.query.q, $options: 'i' } },
28
- ];
29
- }
30
- const items = await Product.find(filters)
31
- .skip((Number(req.query.page) - 1) * 20)
32
- .limit(20);
33
- ```
34
-
35
- **Why critical-adjacent:** ad-hoc parsing is a ReDoS vector (no regex bounds), bypasses field whitelists, and silently diverges across resources.
36
-
37
- **Fix:** Arc's built-in parser handles filters, operators, sort, pagination, populate, select.
38
- ```typescript
39
- defineResource({
40
- name: 'product',
41
- schemaOptions: {
42
- query: {
43
- filterableFields: { status: { type: 'string' }, price: { type: 'number' } },
44
- allowedPopulate: ['category'],
45
- },
46
- },
47
- });
48
- // GET /products?status=active&price[gte]=100&sort=-createdAt&page=2&limit=20&populate=category
49
- ```
50
- For MongoDB-specific operators (`$lookup`, geo): use `QueryParser` from `@classytic/mongokit`:
51
- ```typescript
52
- import { QueryParser } from '@classytic/mongokit';
53
- defineResource({
54
- queryParser: new QueryParser({
55
- allowedFilterFields: ['status', 'category'],
56
- allowedSortFields: ['createdAt', 'price'],
57
- allowedOperators: ['eq', 'gte', 'lte', 'in'],
58
- }),
59
- });
60
- ```
61
- ReDoS protection, max-depth, max-limit are enforced.
62
-
63
- ---
64
-
65
- ## §2. Hand-written Fastify route schemas 🟡
66
-
67
- **Detection:**
68
- ```
69
- pattern: "fastify\\.(get|post|patch|put|delete)\\([^,]+,\\s*\\{\\s*schema\\s*:"
70
- multiline: true
71
- ```
72
- Or: `properties\\s*:\\s*\\{` near `route\\(|fastify\\.(get|post|patch)`.
73
-
74
- **Anti-pattern:**
75
- ```typescript
76
- fastify.post('/products', {
77
- schema: {
78
- body: {
79
- type: 'object',
80
- properties: {
81
- name: { type: 'string', minLength: 1 },
82
- price: { type: 'number', minimum: 0 },
83
- },
84
- required: ['name', 'price'],
85
- },
86
- response: { 200: { type: 'object', properties: { id: {...}, name: {...} } } },
87
- },
88
- handler: async (req) => Product.create(req.body),
89
- });
90
- ```
91
-
92
- **Why:** Schema duplicates Mongoose model + diverges over time. No OpenAPI sync.
93
-
94
- **Fix:**
95
- ```typescript
96
- defineResource({
97
- name: 'product',
98
- schemaOptions: {
99
- fieldRules: {
100
- name: { type: 'string', minLength: 1, required: true },
101
- price: { type: 'number', minimum: 0, required: true },
102
- },
103
- },
104
- });
105
- ```
106
- Body, response, and OpenAPI auto-derive. Mongoose model constraints take precedence; `fieldRules` supplements.
107
-
108
- ---
109
-
110
- ## §3. Manual CRUD routes 🟠
111
-
112
- **Detection:** Multiple `fastify.(get|post|patch|delete)` calls for the same path stem.
113
- ```
114
- pattern: "fastify\\.(get|post|patch|put|delete)\\(['\"]\\/(\\w+)"
115
- output_mode: content
116
- ```
117
- Group hits by capture group 2 (path stem). Three or more methods on the same stem ⇒ candidate for `defineResource`.
118
-
119
- **Anti-pattern:** A `routes/products.ts` file with `GET /products`, `GET /products/:id`, `POST /products`, `PATCH /products/:id`, `DELETE /products/:id` each implemented inline.
120
-
121
- **Why high:** One resource gets a fix (e.g., pagination, error handling) and the others drift. Arc generates all five identically.
122
-
123
- **Fix:** Replace the whole file with one `defineResource`. See [migration-recipes.md §1](migration-recipes.md).
124
-
125
- ---
126
-
127
- ## §4. Manual permission checks inside handlers 🔴
128
-
129
- **Detection:**
130
- ```
131
- pattern: "(req|request)\\.user\\.(role|roles)\\b|user\\.role\\s*[!=]==|roles\\.includes\\("
132
- output_mode: content
133
- ```
134
- Also: `if\\s*\\(\\s*!\\s*req\\.user\\s*\\)`, `throw\\s+new\\s+Error\\(['\"](Unauthorized|Forbidden)`.
135
-
136
- **Anti-pattern:**
137
- ```typescript
138
- fastify.post('/products', async (req, reply) => {
139
- if (!req.user) throw new Error('Unauthorized'); // 401 hand-rolled
140
- if (!req.user.roles.includes('admin')) throw new Error('Forbidden'); // 403 hand-rolled
141
- if (product.createdBy !== req.user.id) throw new Error('Not yours'); // ownership
142
- // proceed
143
- });
144
- ```
145
-
146
- **Why critical:**
147
- - Inconsistent error shape (Error vs ArcError). Frontend gets unpredictable bodies.
148
- - `req.user.id` vs `req.user._id` mismatches between routes silently bypass ownership.
149
- - No row-level filter — admin sees `Product.find()` with no tenant scope.
150
-
151
- **Fix:** Declarative permission combinators. Permissions run at framework level, `filters` propagate into the repo query (row-level ABAC):
152
- ```typescript
153
- import {
154
- allowPublic, requireAuth, requireRoles, requireOwnership,
155
- requireOrgMembership, requireOrgRole, requireServiceScope,
156
- allOf, anyOf,
157
- } from '@classytic/arc';
158
-
159
- defineResource({
160
- permissions: {
161
- list: allowPublic(),
162
- get: allowPublic(),
163
- create: requireRoles(['admin', 'editor']),
164
- update: anyOf(requireRoles(['admin']), requireOwnership('createdBy')),
165
- delete: requireRoles(['admin']),
166
- },
167
- });
168
- ```
169
- For mixed human + service: `anyOf(requireOrgRole('admin'), requireServiceScope('jobs:bulk-write'))`.
170
-
171
- ---
172
-
173
- ## §5. Manual `toJSON` transforms / response field stripping 🔴
174
-
175
- **Detection:**
176
- ```
177
- pattern: "schema\\.set\\(['\"]toJSON['\"]|toJSON\\s*=\\s*function|delete\\s+(ret|obj|doc)\\.(password|__v|secret)"
178
- output_mode: content
179
- ```
180
- Also: `onSerialization` Fastify hook bodies that delete fields.
181
-
182
- **Anti-pattern:**
183
- ```typescript
184
- userSchema.set('toJSON', {
185
- transform: (_doc, ret) => {
186
- delete ret.password;
187
- delete ret.__v;
188
- delete ret.secretToken;
189
- return ret;
190
- },
191
- });
192
- ```
193
-
194
- **Why critical:** Easy to forget on a new field; password leaks happen this way. Also breaks lean reads (the transform doesn't fire on `.lean()` results).
195
-
196
- **Fix:** `fieldRules.hidden` (or field-level read permission) — applies at framework serialization for both REST and MCP, and works with lean reads:
197
- ```typescript
198
- import { fields } from '@classytic/arc';
199
-
200
- defineResource({
201
- schemaOptions: {
202
- fieldRules: {
203
- password: { hidden: true },
204
- __v: { hidden: true },
205
- secretToken: { hidden: true },
206
- salary: fields.visibleTo(['admin', 'hr']),
207
- email: fields.redactFor(['viewer'], '***'),
208
- },
209
- },
210
- });
211
- ```
212
-
213
- ---
214
-
215
- ## §6. Hand-maintained OpenAPI / Swagger 🟡
216
-
217
- **Detection:**
218
- - Files: `openapi.yaml`, `openapi.json`, `swagger.yaml`, `swagger.json`, `api-spec.*` checked into the repo.
219
- - `@fastify/swagger` registered with hand-written `swagger.definitions`.
220
-
221
- **Why medium:** Spec drifts from code; consumers integrate against stale docs.
222
-
223
- **Fix:** `arc docs ./openapi.json --entry ./dist/index.js` — emits OpenAPI from registered resources. Wire into `prebuild` or CI.
224
- ```typescript
225
- import { SpecGenerator } from '@classytic/arc/docs';
226
- const spec = await app.arc.docs.getSpec({ title: 'My API', version: '1.0.0' });
227
- ```
228
-
229
- ---
230
-
231
- ## §7. Manual event emission 🟠
232
-
233
- **Detection:**
234
- ```
235
- pattern: "(eventBus|emitter|events|pubsub)\\.(emit|publish)\\(['\"](\\w+)\\.(created|updated|deleted)"
236
- output_mode: content
237
- ```
238
-
239
- **Anti-pattern:**
240
- ```typescript
241
- const product = await Product.create(req.body);
242
- await eventBus.emit('product.created', { id: product._id });
243
- // ... and somebody forgets it on PATCH
244
- ```
245
-
246
- **Why high:** Inconsistent emission breaks downstream consumers (search index, audit log, cache invalidation). Test coverage rarely catches missing emits.
247
-
248
- **Fix:** Arc auto-emits `{resource}.created` / `.updated` / `.deleted` on every CRUD. Custom events go through hooks:
249
- ```typescript
250
- defineResource({
251
- name: 'product',
252
- events: {
253
- created: { description: 'Product created' },
254
- priceChanged: { description: 'Price updated', schema: { oldPrice, newPrice } },
255
- },
256
- hooks: {
257
- afterUpdate: async (ctx) => {
258
- if (ctx.data.price !== ctx.meta?.existing?.price) {
259
- await ctx.fastify.events.publish('product.priceChanged', {
260
- id: ctx.data._id,
261
- oldPrice: ctx.meta.existing.price,
262
- newPrice: ctx.data.price,
263
- });
264
- }
265
- },
266
- },
267
- });
268
- ```
269
- For guaranteed delivery, use `EventOutbox` (transactional outbox pattern).
270
-
271
- ---
272
-
273
- ## §8. Manual cache invalidation 🟡
274
-
275
- **Detection:**
276
- ```
277
- pattern: "(redis|cache)\\.(del|invalidate|set)\\(['\"](\\w+)[-:_]"
278
- output_mode: content
279
- ```
280
- Also: hand-rolled cache key strings.
281
-
282
- **Anti-pattern:**
283
- ```typescript
284
- const product = await Product.create(req.body);
285
- await cache.del(`product-${product._id}`);
286
- await cache.del('products-list'); // forgot the org-scoped key
287
- ```
288
-
289
- **Fix:** Arc's `QueryCache` invalidates by tag on every mutation. Enable via `arcPlugins.queryCache: true` and declare tags per resource:
290
- ```typescript
291
- defineResource({
292
- cache: {
293
- staleTime: 30,
294
- gcTime: 300,
295
- tags: ['catalog'],
296
- invalidateOn: { 'category.*': ['catalog'] }, // cross-resource
297
- },
298
- });
299
- ```
300
- Modes: `memory` (default) / `distributed` (requires `stores.queryCache: RedisCacheStore`). Response header: `x-cache: HIT | STALE | MISS`.
301
-
302
- ---
303
-
304
- ## §9. Bypassing RequestScope 🔴
305
-
306
- **Detection:**
307
- ```
308
- pattern: "req(uest)?\\.user\\.(_id|id|orgId|organizationId|tenantId|parentOrgId|teamId)"
309
- output_mode: content
310
- ```
311
-
312
- **Anti-pattern:**
313
- ```typescript
314
- const userId = req.user._id; // crashes on public route
315
- const orgId = req.user.orgId; // undefined for service tokens
316
- const parent = req.user.parentOrgId; // not real — fragile custom field
317
- ```
318
-
319
- **Why critical:**
320
- - Crashes on public routes (`request.user` is `Record<string, unknown> | undefined`).
321
- - Doesn't differentiate `member` vs `service` vs `elevated` scope kinds.
322
- - Org hierarchy not honored (no ancestor lookup).
323
- - Inconsistent across routes.
324
-
325
- **Fix:** Always use accessors from `@classytic/arc/scope`:
326
- ```typescript
327
- import {
328
- getUserId, getOrgId, getOrgRoles, getServiceScopes,
329
- getScopeContext, getAncestorOrgIds,
330
- isMember, isService, isElevated, isAuthenticated, hasOrgAccess,
331
- isOrgInScope,
332
- } from '@classytic/arc/scope';
333
-
334
- if (!isAuthenticated(req.scope)) return reply.unauthorized();
335
- const userId = getUserId(req.scope); // typed, undefined-safe
336
- const orgId = getOrgId(req.scope);
337
- const branch = getScopeContext(req.scope, 'branchId');
338
- const inOrg = isOrgInScope(req.scope, 'acme-eu');
339
- ```
340
- For permissions, prefer combinators (`requireOrgRole`, `requireScopeContext`, `requireOrgInScope`) over accessor logic in handlers.
341
-
342
- ---
343
-
344
- ## §10. Mongoose/Prisma imports outside adapters 🟠
345
-
346
- **Detection:**
347
- ```
348
- pattern: "^import\\s+.*\\b(mongoose|@prisma/client|drizzle-orm)\\b"
349
- glob: "src/**/*.{ts,js}"
350
- output_mode: content
351
- ```
352
- Then exclude allowed paths: `src/**/adapter*.ts` (host-side adapter file), `src/db/**` (depending on convention), and `src/**/*.model.ts` (model definition is OK).
353
-
354
- **Anti-pattern:** `import mongoose from 'mongoose'` in `src/services/`, `src/hooks/`, `src/routes/`, or any `.resource.ts`.
355
-
356
- **Why high:** Defeats arc's DB-agnostic boundary. Forces every consumer of that file to pull a database driver. Migration to a different DB becomes a multi-thousand-LOC rewrite instead of swapping one adapter file.
357
-
358
- **Fix:** Mongoose calls go in:
359
- 1. `*.model.ts` — schema definition only.
360
- 2. `*.repository.ts` — extends `Repository<TDoc>` from `@classytic/mongokit` (or implements `MinimalRepo`).
361
- 3. `*.adapter.ts` — `createMongooseAdapter({ model, repository })`.
362
-
363
- Resources, hooks, and services consume `RepositoryLike<TDoc>` — never the model directly.
364
-
365
- ---
366
-
367
- ## §11. `console.log` in `src/` 🟢
368
-
369
- **Detection:**
370
- ```
371
- pattern: "console\\.(log|warn|error|info|debug)\\("
372
- glob: "src/**/*.{ts,js}"
373
- output_mode: content
374
- ```
375
- Allowed: `src/cli/**`, scripts, examples.
376
-
377
- **Fix:** Use Fastify's logger via `request.log` / `app.log`, or arc's logger if exposed.
378
-
379
- ---
380
-
381
- ## §12. `any` and `@ts-ignore` 🟢
382
-
383
- **Detection:**
384
- ```
385
- pattern: ":\\s*any\\b|<any>|as\\s+any\\b|@ts-ignore|@ts-expect-error"
386
- glob: "src/**/*.ts"
387
- ```
388
-
389
- **Fix:** Use `unknown` + type narrowing. `as unknown as X` is a last resort, not a shortcut. Never `@ts-ignore` — fix the type. For repo casts, prefer `RepositoryLike<TDoc>` from `@classytic/arc`.
390
-
391
- ---
392
-
393
- ## §13. Default exports 🟢
394
-
395
- **Detection:**
396
- ```
397
- pattern: "^export\\s+default\\b"
398
- glob: "src/**/*.ts"
399
- ```
400
-
401
- **Fix:** Named exports only. `export const productResource = defineResource({...})`. Knip enforces in arc itself; client projects should follow.
402
-
403
- **Exception:** `*.resource.ts` files used by `loadResources()` may use `export default` because the loader recognizes both `default` export AND `export const resource`. Prefer named for grep-ability.
404
-
405
- ---
406
-
407
- ## §14. Reimplementing presets manually 🟡
408
-
409
- **Detection:** Look for handler names + route paths that match preset signatures:
410
-
411
- | Preset | Handler / route fingerprint |
412
- |---|---|
413
- | `softDelete` | `getDeleted`, `restore`, `GET /deleted`, `POST /:id/restore`, field `deletedAt` with manual filtering on every read |
414
- | `slugLookup` | `getBySlug`, `GET /slug/:slug`, `GET /by-slug/:slug` |
415
- | `tree` | `getChildren`, `getTree`, `GET /tree`, `GET /:id/children`, manual `parentId` field |
416
- | `bulk` | `bulkCreate`, `bulkUpdate`, `bulkDelete`, `POST /bulk`, `PATCH /bulk`, `DELETE /bulk` |
417
- | `multiTenant` | Every find call appended with `organizationId: req.user.orgId` |
418
- | `ownedByUser` | Every find call appended with `userId: req.user.id` |
419
- | `audited` | Manual write to an audit collection on every mutation |
420
- | `filesUpload` | `multer`, `@fastify/multipart` ad-hoc routes per resource |
421
- | `search` | `POST /search`, `/search-similar`, `/embed` hand-rolled |
422
-
423
- **Fix:**
424
- ```typescript
425
- defineResource({
426
- presets: [
427
- 'softDelete',
428
- { name: 'multiTenant', tenantField: 'organizationId' },
429
- { name: 'slugLookup', slugField: 'slug' },
430
- 'bulk',
431
- { name: 'filesUpload', storage: s3Storage, allowedMimeTypes: ['image/*'] },
432
- ],
433
- });
434
- ```
435
- Multi-level tenancy (branch/project/region) — use `multiTenantPreset({ tenantFields: TenantFieldSpec[] })`.
436
-
437
- ---
438
-
439
- ## §15. Hand-written MCP tools 🟡
440
-
441
- **Detection:**
442
- ```
443
- pattern: "CallToolRequestSchema|setRequestHandler\\(\\s*Call|inputSchema\\s*:\\s*\\{\\s*type\\s*:\\s*['\"]object"
444
- output_mode: content
445
- ```
446
- Or: a file pattern of `tools.ts`/`mcp.ts` defining `name`, `description`, `inputSchema`, `handler` objects manually.
447
-
448
- **Fix:** Resources auto-generate MCP tools (5 CRUD + custom routes + actions). Permissions and field rules carry over.
449
- ```typescript
450
- import { mcpPlugin } from '@classytic/arc/mcp';
451
-
452
- await app.register(mcpPlugin, {
453
- resources: [productResource, orderResource],
454
- auth: false, // or getAuth() / custom
455
- exclude: ['credential'],
456
- overrides: { product: { operations: ['list', 'get'] } },
457
- });
458
- ```
459
- For domain-specific tools, use `extraTools` + `buildMcpToolsFromBridges([...])` instead of hand-rolling MCP server plumbing.
460
-
461
- ---
462
-
463
- ## §16. Custom search routes / query language 🟡
464
-
465
- **Detection:** `GET /search`, `GET /:resource/search`, `/find`, `/lookup` with custom param parsing.
466
-
467
- **Fix:** Either use arc's standard `QueryParser` syntax (`?search=...&filter=...`), or `searchPreset` for full-text/vector backends:
468
- ```typescript
469
- import { searchPreset } from '@classytic/arc/presets/search';
470
-
471
- defineResource({
472
- presets: [searchPreset({
473
- search: { handler: (req) => elastic.search({ index: 'products', q: req.body.q }) },
474
- similar: { handler: (req) => pinecone.query({ vector: req.body.vector, topK: 10 }) },
475
- })],
476
- });
477
- ```
478
-
479
- ---
480
-
481
- ## §17. `request.user` access without guard on public routes 🔴
482
-
483
- **Detection:**
484
- ```
485
- pattern: "(req|request)\\.user\\.\\w+"
486
- output_mode: content
487
- ```
488
- Then for each hit, check whether the enclosing route is `allowPublic()` or has no `permissions`. Crashes happen on public routes.
489
-
490
- **Fix:** Always guard:
491
- ```typescript
492
- if (req.user) {
493
- const userId = req.user.id;
494
- // ...
495
- }
496
- // or: use scope accessors which return undefined safely
497
- ```
498
- Arc rule: `request.user: Record<string, unknown> | undefined`. The property is required (not optional `?:`), but the value is union-with-undefined.
499
-
500
- ---
501
-
502
- ## §18. Custom controller without forwarding `tenantField`/`schemaOptions`/`idField` 🟠
503
-
504
- **Detection:** A `class FooController extends BaseController` where the constructor doesn't forward `tenantField`, `idField`, `schemaOptions`, `cache`, `onFieldWriteDenied`.
505
-
506
- **Why:** When you pass your own controller to `defineResource({ controller })`, arc CANNOT thread these into it. They must be forwarded through `super(repo, opts)` AND mirrored on the `defineResource` call.
507
-
508
- **Fix:**
509
- ```typescript
510
- class ProductController extends BaseController<Product> {
511
- constructor(opts: { tenantField?: string | false; idField?: string } = {}) {
512
- super(productRepo, { resourceName: 'product', ...opts });
513
- }
514
- }
515
-
516
- defineResource({
517
- name: 'product',
518
- controller: new ProductController({ tenantField: 'organizationId', idField: '_id' }),
519
- tenantField: 'organizationId', // mirror!
520
- idField: '_id', // mirror!
521
- });
522
- ```
523
- Or skip the custom controller entirely — arc's auto-built `BaseController` handles 90% of cases. Use `BaseCrudController` + `SoftDeleteMixin`/`BulkMixin`/etc. for slim CRUD-only.
524
-
525
- ---
526
-
527
- ## §19. `tenantField` left at default for company-wide tables 🟠
528
-
529
- **Detection:** Resources for lookup tables, platform settings, or cross-org reports that don't set `tenantField: false`.
530
-
531
- **Why:** Default `tenantField: 'organizationId'` silently scopes queries to caller's org. For an `account-type` lookup table or `currency` table, this returns empty results forever.
532
-
533
- **Fix:**
534
- ```typescript
535
- defineResource({ name: 'account-type', tenantField: false }); // company-wide
536
- defineResource({ name: 'workspace-item', tenantField: 'workspaceId' }); // different scope
537
- ```
538
-
539
- ---
540
-
541
- ## §20. Wrong lifecycle slot for async-booted engines 🟠
542
-
543
- **Detection:** A resource adapter that depends on an engine initialized inside the same module (e.g., `await ensureCatalogEngine()`) is exported as a static `defineResource()` at module top — which runs before `bootstrap[]`.
544
-
545
- **Anti-pattern:**
546
- ```typescript
547
- // product.resource.ts — runs at IMPORT time, before bootstrap
548
- const engine = await ensureCatalogEngine(); // top-level await
549
- export const productResource = defineResource({ adapter: engine.adapter() });
550
- ```
551
-
552
- **Fix:** Use the factory form for `resources` so it runs *after* `bootstrap[]`:
553
- ```typescript
554
- const app = await createApp({
555
- bootstrap: [async () => { await ensureCatalogEngine(); }],
556
- resources: async () => {
557
- const engine = await getCatalogEngine();
558
- return [buildProductResource(engine), buildCategoryResource(engine)];
559
- },
560
- });
561
- ```
562
- Or via `loadResources` with `context`:
563
- ```typescript
564
- resources: async () => loadResources(import.meta.url, { context: { engine } }),
565
- // Each *.resource.ts then exports: (ctx) => defineResource({ adapter: ctx.engine.adapter() })
566
- ```
567
-
568
- For the DB **connection** itself (as opposed to engines), arc 2.21 adds `createApp({ beforeBoot: async () => connectDatabase() })` — awaited before Fastify exists, before module thunks resolve, and before any resource file imports. A composition root that connects the DB then dynamic-imports the app to control evaluation order is the pre-2.21 workaround; flag it and move the connect into `beforeBoot`.
569
-
570
- ---
571
-
572
- ## §21. Field-write denied as silent strip when reject is needed (or vice versa) 🟡
573
-
574
- **Detection:** Resources with sensitive fields (`role`, `permissions`, `tenantId`, `organizationId`) that don't declare `onFieldWriteDenied`. Default is `reject` (403 with denied list) — usually correct. If client set `'strip'`, sensitive denied writes silently disappear.
575
-
576
- **Fix:** Explicit choice per resource:
577
- ```typescript
578
- defineResource({ onFieldWriteDenied: 'reject' }); // default — explicit
579
- defineResource({ onFieldWriteDenied: 'strip' }); // only for low-stakes UX flows
580
- ```
581
- Tests should assert 403 on protected-field write attempts.
582
-
583
- ---
584
-
585
- ## §22. Manual idempotency 🟠
586
-
587
- **Detection:** Hand-rolled deduplication via `Idempotency-Key` header reads, custom Redis/Mongo lookup, retry tables.
588
-
589
- **Fix:** Arc ships `idempotencyPlugin`:
590
- ```typescript
591
- import { idempotencyPlugin } from '@classytic/arc/idempotency';
592
- await app.register(idempotencyPlugin, { repository: idempotencyRepo, ttlMs: 24 * 3600_000 });
593
- ```
594
- Requires `getOne`, `deleteMany`, `findOneAndUpdate` on the repo (mongokit + sqlitekit conform).
595
-
596
- ---
597
-
598
- ## §23. Manual audit log 🟡
599
-
600
- **Detection:** Every mutation handler appends to an `audit_logs` / `events` / `history` collection inline.
601
-
602
- **Fix:** Per-resource opt-in via `auditPlugin`:
603
- ```typescript
604
- await fastify.register(auditPlugin, { autoAudit: { perResource: true } });
605
- defineResource({ name: 'order', audit: true });
606
- defineResource({ name: 'payment', audit: { operations: ['delete'] } });
607
- ```
608
- Or `presets: ['audited']`.
609
-
610
- ---
611
-
612
- ## §24. Manual rate limiting per route 🟡
613
-
614
- **Detection:** `@fastify/rate-limit` registered per-route with hand-tuned configs.
615
-
616
- **Fix:** Per-resource `rateLimit: RateLimitConfig` on `defineResource`, or global at `createApp({ rateLimit })`.
617
-
618
- ---
619
-
620
- ## §25. Webhook signature verification on parsed body 🔴
621
-
622
- **Detection:**
623
- ```
624
- pattern: "verifySignature\\(.*req\\.body"
625
- output_mode: content
626
- ```
627
-
628
- **Why critical:** `verifySignature(body, ...)` throws `TypeError` if body isn't string/Buffer. Parsed body silently fails verification → forged webhooks accepted.
629
-
630
- **Fix:** `verifySignature(req.rawBody, ...)`. Declare webhook routes via `rawHandler` and ensure `@fastify/raw-body` is registered (arc registers it automatically when needed).
631
-
632
- ---
633
-
634
- ## §26. Multipart/file upload handled with multer or ad-hoc parsing 🟡
635
-
636
- **Detection:** `multer`, `formidable`, `busboy` used directly; or `req.body` consumed without `multipartBody` middleware.
637
-
638
- **Fix:**
639
- ```typescript
640
- import { multipartBody } from '@classytic/arc/middleware';
641
- defineResource({
642
- middlewares: { create: [multipartBody({ allowedMimeTypes: ['image/png'], maxFileSize: 5 * 1024 * 1024 })] },
643
- });
644
- ```
645
- Or `presets: [{ name: 'filesUpload', storage, allowedMimeTypes, maxFileSize }]`.
646
- `multipartBody()` is a no-op for JSON requests — safe to always add to create/update.
647
-
648
- ---
649
-
650
- ## §27. SSE auth via query string without `preAuth` 🔴
651
-
652
- **Detection:** SSE/EventSource routes that read `req.query.token` and call `verify()` inline.
653
-
654
- **Fix:** EventSource can't set headers, so arc's `preAuth` slot copies `?token=` into the `Authorization` header before auth runs:
655
- ```typescript
656
- routes: [
657
- {
658
- method: 'GET', path: '/stream',
659
- preAuth: [(req) => { req.headers.authorization = `Bearer ${req.query.token}`; }],
660
- permissions: requireAuth(),
661
- rawHandler: async (req, reply) => reply.send(stream),
662
- },
663
- ],
664
- ```
665
-
666
- ---
667
-
668
- ## §28. Mongoose without mongokit 🟠
669
-
670
- **Detection:** `package.json` has `mongoose` but not `@classytic/mongokit`. Or `import { Schema, model } from 'mongoose'` paired with hand-rolled repository classes (`class FooRepository`).
671
-
672
- **Why high:** Every Mongoose model + repo class is duplicating mongokit's hook engine, plugin system, pagination, multi-tenant scoping, soft-delete, audit trail, transaction helpers. A 150 LOC repo class typically reduces to ~30 LOC with mongokit.
673
-
674
- **Fix:** Full migration recipe → [mongokit-migration.md](mongokit-migration.md).
675
-
676
- ---
677
-
678
- ## §29. `app.register(authPlugin)` instead of `createApp({ auth })` 🟢
679
-
680
- **Detection:** Manual JWT plugin registration with `@fastify/jwt`, hand-rolled `app.authenticate` decorator.
681
-
682
- **Fix:** `createApp({ auth: { type: 'jwt', jwt: { secret, ... } } })` decorates `app.authenticate`, `app.optionalAuthenticate`, `app.authorize` and wires permission checks. For Better Auth, `createApp({ auth: { type: 'betterAuth', betterAuth: createBetterAuthAdapter({ auth, orgContext: true }) } })`.
683
-
684
- ---
685
-
686
- ## §30. Missing `arc-discovered` resources because of tsconfig path aliases 🟢
687
-
688
- **Detection:** Resources defined under `import.meta.url`-discovered directories don't appear in routes; resource files import other resource files via `@/foo` aliases.
689
-
690
- **Why:** `loadResources()` uses Node's resolver. `@/*` path aliases are compile-time only, not Node-resolvable. Auto-discovery silently misses these files.
691
-
692
- **Fix:** Use relative imports OR Node's `#` subpath imports (`"imports": { "#foo/*": "./src/foo/*.js" }` in `package.json`) for files that participate in `loadResources`. Path aliases work fine for type-only imports.
693
-
694
- ---
695
-
696
- ## §31. `select` field manipulated client-side 🟢
697
-
698
- **Detection:** Code post-processing `select` value from query (normalizing case, splitting, building projection objects).
699
-
700
- **Why:** Arc preserves `select` as-is for DB-agnosticism (Mongo `'name email'` vs SQL `['name', 'email']`). Client normalization is wasted work and divergent across resources.
701
-
702
- **Fix:** Pass through. The repository / adapter handles its native shape.
703
-
704
- ---
705
-
706
- ## §32a. Importing pagination types from primitives or mongokit 🟠
707
-
708
- **Detection:**
709
- ```
710
- pattern: "from\\s+['\"]@classytic/(primitives/pagination|mongokit)['\"][^\\n]*\\b(OffsetPaginationResult|KeysetPaginationResult|AggregatePaginationResult|PaginationResult|toCanonicalList)\\b"
711
- output_mode: content
712
- ```
713
- Also `@classytic/arc-next/api` for `OffsetPaginationResponse` / `KeysetPaginationResponse` / `AggregatePaginationResponse` / `PaginatedResponse`.
714
-
715
- **Why high:** Pagination types and the `toCanonicalList()` helper now live in `@classytic/repo-core/pagination` as the single source of truth (primitives' duplicate dropped, mongokit's local declarations dropped, arc-next's response types removed). Importing from any other package risks drift between the type the host believes and the one the kit actually returns.
716
-
717
- **Fix:**
718
- ```typescript
719
- import type {
720
- OffsetPaginationResult, KeysetPaginationResult,
721
- AggregatePaginationResult, PaginationResult,
722
- } from '@classytic/repo-core/pagination';
723
- import { toCanonicalList } from '@classytic/repo-core/pagination';
724
- ```
725
- The wire envelope carries `method` ('offset' | 'keyset' | 'aggregate') as the discriminant; arc's `reply.sendList()` calls `toCanonicalList` internally.
726
-
727
- ---
728
-
729
- ## §32b. Importing event types from arc 🟠
730
-
731
- **Detection:**
732
- ```
733
- pattern: "from\\s+['\"]@classytic/arc/events['\"][^\\n]*\\b(EventMeta|DomainEvent|EventHandler|EventLogger|EventTransport|DeadLetteredEvent|PublishManyResult|createEvent|createChildEvent|matchEventPattern)\\b"
734
- output_mode: content
735
- ```
736
-
737
- **Why high:** Event types now live in `@classytic/primitives/events` as the single source of truth. Arc only re-exports the runtime `MemoryEventTransport`. Hosts importing event types from arc lock themselves to arc's version even when the type lives in primitives.
738
-
739
- **Fix:**
740
- ```typescript
741
- import type {
742
- EventMeta, DomainEvent, EventHandler, EventLogger, EventTransport,
743
- DeadLetteredEvent, PublishManyResult,
744
- } from '@classytic/primitives/events';
745
- import { createEvent, createChildEvent, matchEventPattern } from '@classytic/primitives/events';
746
- import { MemoryEventTransport } from '@classytic/arc/events'; // runtime stays at arc
747
- ```
748
-
749
- ---
750
-
751
- ## §32c. Importing tenant config from primitives 🟡
752
-
753
- **Detection:**
754
- ```
755
- pattern: "from\\s+['\"]@classytic/primitives/tenant['\"]"
756
- output_mode: content
757
- ```
758
-
759
- **Why medium:** `TenantConfig`, `TenantStrategy`, `TenantFieldType`, `resolveTenantConfig`, `DEFAULT_TENANT_CONFIG`, `ResolvedTenantConfig` now live in `@classytic/repo-core/tenant`. Mongokit and sqlitekit both `extends Pick<TenantConfig, ...>` from repo-core.
760
-
761
- **Fix:**
762
- ```typescript
763
- import type { TenantConfig, ResolvedTenantConfig } from '@classytic/repo-core/tenant';
764
- import { resolveTenantConfig, DEFAULT_TENANT_CONFIG } from '@classytic/repo-core/tenant';
765
- ```
766
-
767
- ---
768
-
769
- ## §32d. Importing error types from primitives or mongokit 🟠
770
-
771
- **Detection:**
772
- ```
773
- pattern: "from\\s+['\"]@classytic/(primitives/errors|mongokit)['\"][^\\n]*\\bHttpError\\b"
774
- output_mode: content
775
- ```
776
-
777
- **Why high:** `HttpError` (throwable contract), `ErrorContract` (wire shape), `ErrorDetail`, `ErrorCode`, `ERROR_CODES`, `toErrorContract()`, `statusToErrorCode()` all live in `@classytic/repo-core/errors`. `ArcError implements HttpError` from repo-core. Mongokit no longer publishes its own `HttpError`.
778
-
779
- **Fix:**
780
- ```typescript
781
- import type { HttpError, ErrorContract, ErrorDetail, ErrorCode } from '@classytic/repo-core/errors';
782
- import { toErrorContract, statusToErrorCode, ERROR_CODES } from '@classytic/repo-core/errors';
783
- ```
784
-
785
- ---
786
-
787
- ## §32e. Hand-rolled `if (!getOrgId(scope)) throw …` 🟡
788
-
789
- **Detection:**
790
- ```
791
- pattern: "if\\s*\\(\\s*!\\s*getOrgId\\s*\\("
792
- output_mode: content
793
- ```
794
- Also: `if (!getUserId(...))`, `if (!getClientId(...))`, `if (!getTeamId(...))` followed by a manual throw.
795
-
796
- **Why medium:** Arc 2.12 ships `requireOrgId(scope, hint?)` / `requireUserId(scope, hint?)` / `requireClientId(scope, hint?)` / `requireTeamId(scope, hint?)` which return the value or throw a 403 `ArcError`. Hand-rolled guards usually throw a generic `Error` (wrong status), forget the optional hint, or duplicate the same boilerplate at every call site.
797
-
798
- **Fix:**
799
- ```typescript
800
- import { requireOrgId, requireUserId } from '@classytic/arc/scope';
801
-
802
- const orgId = requireOrgId(scope); // throws 403 if missing
803
- const userId = requireUserId(scope, 'finalize-checkout'); // hint surfaces in error.details
804
- ```
805
-
806
- ---
807
-
808
- ## §32f. Missing / dodged `schemaGenerator` 🟠
809
-
810
- **Detection:**
811
- ```
812
- pattern: "createMongooseAdapter\\s*\\(\\s*\\{[^}]*\\}\\s*\\)"
813
- multiline: true
814
- ```
815
- Then check the `schemaGenerator:` key — what to flag depends on the kit version:
816
-
817
- - **mongokit >=3.21**: `schemaGenerator` DEFAULTS to `buildCrudSchemasFromModel` — omitting it is now correct. Flag the opposite: `schemaGenerator: false` used to dodge a wire-vs-model shape mismatch (minor-unit integers vs Money objects, enums, etc.). That opt-out silently kills OpenAPI bodies AND MCP tool input schemas for the whole resource. The right fix is a real wire contract: `customSchemas: { create: { body }, update: { body } }` with the generator ON — in arc 2.21 a custom part REPLACES the generated part wholesale (no `required[]` union), so wire and model shapes can differ cleanly.
818
- - **mongokit <3.21**: omitted `schemaGenerator` emits `null` OpenAPI bodies (arc 2.12 deleted the built-in fallback). Fix: upgrade the kit, or wire `schemaGenerator: buildCrudSchemasFromModel` explicitly.
819
-
820
- For drizzle: `createDrizzleAdapter` still wants `schemaGenerator: buildCrudSchemasFromTable` from `@classytic/sqlitekit` — check the kit's own version before flagging.
821
-
822
- ---
823
-
824
- ## §32g. Importing kit-specific adapters from `@classytic/arc` (any subpath) 🔴
825
-
826
- **Detection:**
827
- ```
828
- pattern: "from\\s+['\"]@classytic/arc(/adapters)?['\"][^\\n]*\\b(createMongooseAdapter|MongooseAdapter|createDrizzleAdapter|DrizzleAdapter|createPrismaAdapter|PrismaAdapter|PrismaQueryParser|InferMongooseDoc|MongooseDocument|isMongooseModel|MongooseAdapterOptions|DrizzleAdapterOptions|DrizzleColumnLike|DrizzleTableLike)\\b"
829
- output_mode: content
830
- ```
831
-
832
- Also: adapter contract types imported from arc — `import type { DataAdapter, AdapterRepositoryInput, AdapterFactory, OpenApiSchemas, SchemaMetadata, FieldMetadata, RelationMetadata, AdapterValidationResult, AdapterSchemaContext } from '@classytic/arc'` (any subpath). And: `mergeFieldRuleConstraints` from `@classytic/arc/adapters`. Any `from '@classytic/arc/adapters'` import — the entire subpath was removed in arc 2.12.
833
-
834
- **Why critical:** `@classytic/arc/adapters` does not exist. Kit-specific adapters (Mongoose, Drizzle, Prisma) live in their kit; the cross-framework contract lives in `@classytic/repo-core/adapter`. Importing these names from arc fails to resolve — the build breaks at install time. The rule is **strict**: kit-specific things come from the kit, the contract comes from repo-core.
835
-
836
- **Fix:**
837
- ```typescript
838
- // Mongoose
839
- import {
840
- createMongooseAdapter, MongooseAdapter,
841
- type MongooseAdapterOptions, type InferMongooseDoc,
842
- type MongooseDocument, isMongooseModel,
843
- } from '@classytic/mongokit/adapter';
844
-
845
- // Drizzle
846
- import {
847
- createDrizzleAdapter, DrizzleAdapter,
848
- type DrizzleAdapterOptions, type DrizzleColumnLike, type DrizzleTableLike,
849
- } from '@classytic/sqlitekit/adapter';
850
-
851
- // Prisma
852
- import {
853
- createPrismaAdapter, PrismaAdapter, PrismaQueryParser,
854
- } from '@classytic/prismakit/adapter';
855
-
856
- // Cross-framework adapter contract
857
- import type {
858
- DataAdapter, RepositoryLike, AdapterRepositoryInput,
859
- AdapterFactory, AdapterValidationResult, AdapterSchemaContext,
860
- OpenApiSchemas, SchemaMetadata, FieldMetadata, RelationMetadata,
861
- } from '@classytic/repo-core/adapter';
862
- import { asRepositoryLike, isRepository } from '@classytic/repo-core/adapter';
863
-
864
- // Schema helpers
865
- import { mergeFieldRuleConstraints, applyNullable } from '@classytic/repo-core/schema';
866
- ```
867
-
868
- The `@classytic/arc/adapters` subpath has been **removed** in arc 2.12 — no symbols ship there anymore. `RepositoryLike` is re-exported from `@classytic/arc` for convenience, but importing from `@classytic/repo-core/adapter` is canonical. Custom kits implementing `DataAdapter<TDoc>` from `@classytic/repo-core/adapter` plug in identically.
869
-
870
- ---
871
-
872
- ## §32. Headers set in `onSend` hook 🔴
873
-
874
- **Detection:**
875
- ```
876
- pattern: "addHook\\(['\"]onSend"
877
- output_mode: content
878
- ```
879
- Then check whether the hook body sets headers (`reply.header(`, `reply.headers[`).
880
-
881
- **Why critical:** Async `onSend` races with Fastify's `onSendEnd → safeWriteHead` flush path and produces `ERR_HTTP_HEADERS_SENT` under slow responses. Intermittent prod failures, hard to reproduce.
882
-
883
- **Fix:** Set headers in `onRequest` (before handler) or `preSerialization` (before flush). Never `onSend`.
884
-
885
- ---
886
-
887
- ## §33. Hand-rolled aggregation routes when `aggregations: { … }` would do 🟠
888
-
889
- **Detection:**
890
- ```
891
- pattern: "Model\\.aggregate\\(\\["
892
- output_mode: content
893
- ```
894
- Also: `\\.aggregate\\(\\s*\\[`, `\\$group\\b`, `\\$match\\b` inside resource handler files. Plus inline mongoose pipeline imports inside route handlers (vs. inside the kit's repository).
895
-
896
- **Anti-pattern:**
897
- ```typescript
898
- // In a custom GET /aggregate/byPaymentMethod route:
899
- const orgId = getOrgId(getScope(req));
900
- const rows = await Transaction.aggregate([
901
- { $match: { organizationId: new mongoose.Types.ObjectId(orgId), status: 'verified' } },
902
- { $group: { _id: '$method', total: { $sum: '$amount' }, count: { $sum: 1 } } },
903
- { $sort: { total: -1 } },
904
- ]);
905
- return reply.send({ rows });
906
- ```
907
-
908
- **Why high:** loses every cross-cutting feature arc's aggregation router gives for free — per-aggregation permissions, OpenAPI schema, MCP tool export, SWR cache + tag invalidation, `requireFilters` / `requireDateRange` safety guards, `maxGroups` cap, multi-tenant scope without manual `ObjectId` casting. The hand-rolled version also drifts: every new bucket needs a new route, no central declaration, no unified shape across kits.
909
-
910
- **Fix:** declare `aggregations: { name: defineAggregation({ groupBy, measures, sort, cache, permissions }) }` on the resource. Arc registers `GET /:prefix/aggregations/:name` per entry, threads `tenantOptions` to `repo.aggregate(req, options)`, and the kit's multi-tenant plugin handles type-coercion. Type-coercion (string → ObjectId / UUID / text) is **the kit's responsibility, not the framework's** — never inject the tenant key into `aggReq.filter` from arc-host code.
911
-
912
- ```typescript
913
- import { defineAggregation } from '@classytic/arc';
914
-
915
- aggregations: {
916
- byPaymentMethod: defineAggregation({
917
- groupBy: 'method',
918
- measures: { total: 'sum:amount', count: 'count' },
919
- sort: { total: -1 },
920
- cache: { staleTime: 60, swr: true, tags: ['revenue'] },
921
- permissions: canViewRevenue(),
922
- }),
923
- }
924
- ```
925
-
926
- For backends without `repo.aggregate`, declare a `materialized` hook on the aggregation — the router calls it instead of the kit and keeps the same `{ rows }` envelope, permission gate, and cache contract.
927
-
928
- ---
929
-
930
- ## §34. `as never` / `as unknown as` casts on engine bags in module packages 🟠
931
-
932
- **Detection:**
933
- ```
934
- pattern: "as never|as unknown as"
935
- ```
936
- Concentrated hits in `@classytic/arc-*` (or `@scope/arc-*`) module packages — especially around `defineResource(...)` assembly, adapter construction from an engine, or hand-rolled config spread-merges.
937
-
938
- **Anti-pattern (pre-2.21 module-author tax):**
939
- ```typescript
940
- interface EngineLike { models: Record<string, unknown>; repositories: Record<string, unknown> }
941
- adapter: createMongooseAdapter(engine.models.Party as never, repo as never),
942
- ...(cfg.extraRoutes ? { routes: [...base.routes, ...cfg.extraRoutes] as never } : {}),
943
- ```
944
-
945
- **Why high:** every cast is a hole where the kernel's real types (optional sub-module members, role unions, doc shapes) stop flowing — typos compile, wrong repos pair with wrong models, and hand-rolled spread-merges clobber host arrays.
946
-
947
- **Fix (arc 2.21):** type the engine port with the KERNEL's own bags and assemble via `mergeResourceConfig`:
948
- ```typescript
949
- import { mergeResourceConfig, type ResourceSeams, type AdapterLike } from '@classytic/arc';
950
-
951
- interface CatalogEngineLike { // kernel is already a peer — no new coupling
952
- models: CatalogEngine['models'];
953
- repositories: CatalogEngine['repositories'];
954
- }
955
- defineResource(mergeResourceConfig(
956
- { name: 'product', adapter: createMongooseAdapter({ model: models.Product, repository: repositories.product }), ... },
957
- hostSeams, // typed ResourceSeams — arrays concat, objects deep-merge,
958
- )); // instances last-win, undefined never clobbers
959
- ```
960
- Remaining honest boundaries (hydrated-vs-lean id widening at a kernel bridge, wire-body narrowing in action handlers) get a comment, not a blanket `as never`.
961
-
962
- ---
963
-
964
- ## §35. Hand-rolled recurring jobs (`setInterval` / cron + DB lock) 🟠
965
-
966
- **Detection:**
967
- ```
968
- pattern: "setInterval\\s*\\(|node-cron|cron\\.schedule|new CronJob"
969
- ```
970
- Plus home-grown "job registry" / "leader lock" / "acquireLock" modules paired with timers.
971
-
972
- **Why high:** every host regrows the same layer — overlap prevention, multi-replica leader lock, shutdown timer cleanup, failure counters — and gets at least one of them wrong (stacking `setInterval` runs, timers holding the process open, no lease recovery after a crashed leader).
973
-
974
- **Fix (arc 2.21):** `schedulesPlugin` from `@classytic/arc/plugins` — interval jobs with no-overlap by construction (timeout chain), optional `lock` (any `LockAdapter`: `@classytic/mongokit/lock`, sqlitekit, memory) for multi-replica lease safety, `jitterMs`, `runOnStart`, `getScheduleStats()`, clean `onClose` drain. Calendar cron-expressions / durable retries stay in the BullMQ tier (`@classytic/arc/integrations/jobs`) — don't flag hosts that need real cron semantics for using it.
975
-
976
- ---
977
-
978
- ## §36. Wrong tenant config key — `{ field }` instead of `{ tenantField }` 🔴
979
-
980
- **Detection:**
981
- ```
982
- pattern: "tenant:\\s*\\{\\s*field\\s*:"
983
- ```
984
- Also any object passed as tenant config whose keys aren't in repo-core's `TenantConfig`.
985
-
986
- **Why critical:** unknown keys are **silently ignored** — `{ tenant: { field: 'branchId' } }` compiles (loose host types), the resource falls back to the default tenant field, and cross-tenant reads/writes go unscoped for hosts on a custom field name. Found live in published spine packages (arc-assets / arc-pricelist 0.1.x).
987
-
988
- **Fix:** the key is `tenantField` (repo-core `TenantConfig`). In arc resources prefer the top-level `tenantField: 'branchId'` shorthand or the `multiTenant` preset; when passing a tenant object through a module seam, type it as `TenantConfig` so unknown keys fail the build.
989
-
990
- ---
991
-
992
- ## Detection checklist (run-order)
993
-
994
- Run sweeps in this order — early hits often invalidate later context:
995
-
996
- 1. §10 — driver imports outside adapters (most architecturally significant)
997
- 2. §28 — mongoose without mongokit (scope of mongokit migration)
998
- 3. §3 — manual CRUD route count (scope of defineResource migration)
999
- 4. §4 + §9 + §17 — auth/scope (security-critical)
1000
- 5. §5 — toJSON / response stripping (security-critical)
1001
- 6. §25, §27, §32 — webhook/SSE/header gotchas (security-critical)
1002
- 7. §1, §2, §6, §16 — query/schema/openapi/search (style + drift)
1003
- 8. §7, §8, §22, §23 — events/cache/idempotency/audit (silent inconsistency)
1004
- 9. §14, §18, §19 — preset adoption + custom controller wiring
1005
- 10. §11, §12, §13, §29, §30, §31 — style and edges
1006
- 11. §32a–§32g — canonical-contract drift (pagination / events / tenant / errors / adapter imports), missing `requireOrgId` accessors, missing/dodged `schemaGenerator`, kit-specific adapter imports from arc (3.0 break)
1007
- 12. §33 — hand-rolled `Model.aggregate([...])` in resource routes vs declarative `aggregations: { … }`
1008
- 13. §36 — tenant config `{ field }` key (security: silent unscoped queries), then §34–§35 — module-package `as never` casts vs 2.21 seams; hand-rolled recurring jobs vs `schedulesPlugin`