@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,200 +1,157 @@
1
- # Arc Testing Utilities (2.11)
1
+ # Testing (`@classytic/arc/testing`)
2
2
 
3
- Three primary entry points — pick by what you're testing. Everything else composes with one of them.
3
+ | Need | Use |
4
+ |---|---|
5
+ | Auto CRUD + permission + validation coverage for one resource | `createHttpTestHarness` |
6
+ | Custom scenarios, one app with auth and fixtures | `createTestApp` + `expectArc` |
7
+ | Real app around modules (boots green means it composes) | `bootModuleApp` |
8
+ | Prove an adapter or store satisfies a contract | `runStorageContract`, `runOutboxStoreContract` (`/testing/outbox`), `runCleanupRunStoreContract` (`/testing/cleanup`) |
4
9
 
5
- | Entry point | Use when | Tests in scope |
6
- |---|---|---|
7
- | `createHttpTestHarness(resource, ctxFn)` | You want auto-generated CRUD + permission + validation coverage per resource | ~16 tests / resource, zero boilerplate |
8
- | `createTestApp({ resources, authMode, db })` | Custom scenarios, end-to-end flows, integration across resources | You write assertions with `expectArc(res)` |
9
- | `runStorageContract(setup)` | You're building an adapter and want to prove it satisfies arc's Storage contract | DB-agnostic adapter conformance |
10
-
11
- ---
12
-
13
- ## `createTestApp()` — turnkey Fastify + in-memory Mongo + auth + fixtures
10
+ ## createTestApp
14
11
 
15
12
  ```typescript
16
13
  import { createTestApp, expectArc } from '@classytic/arc/testing';
17
14
  import type { TestAppContext } from '@classytic/arc/testing';
18
15
 
19
- describe('Product API', () => {
20
- let ctx: TestAppContext;
21
-
22
- beforeAll(async () => {
23
- ctx = await createTestApp({
24
- resources: [productResource],
25
- authMode: 'jwt', // 'jwt' | 'better-auth' | 'none'
26
- db: 'in-memory', // default; or { uri } | false
27
- connectMongoose: true, // optional — one-liner for Mongoose apps
28
- });
29
-
30
- ctx.auth.register('admin', {
31
- user: { id: '1', roles: ['admin'] },
32
- orgId: 'org-1',
33
- });
34
- });
35
-
36
- afterAll(() => ctx.close());
37
-
38
- it('GET /products — public', async () => {
39
- const res = await ctx.app.inject({ method: 'GET', url: '/products' });
40
- expectArc(res).ok().paginated();
16
+ let ctx: TestAppContext;
17
+ beforeAll(async () => {
18
+ ctx = await createTestApp({
19
+ resources: [productResource],
20
+ authMode: 'jwt', // 'jwt' (default) | 'better-auth' | 'none'
21
+ db: 'in-memory', // default | { uri } | false
22
+ connectMongoose: true, // mongoose.connect(dbUri) for Mongoose apps
41
23
  });
24
+ ctx.auth!.register('admin', { user: { id: '1', roles: ['admin'] }, orgId: 'org-1' });
25
+ });
26
+ afterAll(() => ctx.close());
42
27
 
43
- it('POST /products — admin required', async () => {
44
- const res = await ctx.app.inject({
45
- method: 'POST',
46
- url: '/products',
47
- headers: ctx.auth.as('admin').headers,
48
- payload: { name: 'Widget', price: 99 },
49
- });
50
- expectArc(res).ok();
28
+ it('POST /products as admin', async () => {
29
+ const res = await ctx.app.inject({
30
+ method: 'POST', url: '/products',
31
+ headers: ctx.auth!.as('admin').headers,
32
+ payload: { name: 'Widget', price: 99 },
51
33
  });
34
+ expectArc(res).ok(201);
52
35
  });
53
36
  ```
54
37
 
55
- **`TestAppContext` shape**: `{ app, auth, fixtures, dbUri, close }`. Auth is `undefined` when `authMode: 'none'`; `dbUri` is present when `db: 'in-memory'` or `{ uri }`.
56
-
57
- **`db` modes**:
58
- - `'in-memory'` (default) — boots `MongoMemoryServer`, exposes `dbUri`, stops on `close()`. Needs `npm i -D mongodb-memory-server`.
59
- - `{ uri }` — external Mongo URI; caller owns lifecycle.
60
- - `false` — no DB wiring (pure Fastify unit tests).
61
-
62
- **`authMode: 'better-auth'`** requires the caller to also pass `auth: { type: 'better-auth', ... }`. Mismatched config fails fast at setup.
38
+ - `TestAppContext`: `{ app, auth, fixtures, dbUri, close }`. `auth` is `undefined` when `authMode: 'none'`.
39
+ - Other `createApp` options pass through (`plugins`, `auth`, `ports` ...). Defaults: `preset: 'testing'`, no logger, helmet, cors, rate limit.
40
+ - `db: 'in-memory'` needs `mongodb-memory-server` (dev dependency). `dbUri` is NOT wired into your adapters: connect them yourself.
41
+ - `authMode: 'better-auth'` requires you to pass `auth: { type: 'better-auth', ... }`; it throws otherwise.
42
+ - `ok()` defaults to 200, so pass the exact status (`ok(201)`).
63
43
 
64
- ---
65
-
66
- ## `TestAuthProvider` — unified session primitive
67
-
68
- One `register()` → `.as(role).headers` flow across JWT, Better Auth, and custom providers.
69
-
70
- ```typescript
71
- // JWT — provider signs on-the-fly via app.jwt.sign()
72
- ctx.auth.register('admin', { user: { id: '1', roles: ['admin'] }, orgId: 'org-1' });
73
- ctx.auth.register('user', { user: { id: '2', roles: ['user'] } });
74
-
75
- // Better Auth / custom — pre-signed tokens
76
- ctx.auth.register('admin', { token: existingToken, orgId: 'org-1' });
77
-
78
- // Use
79
- const headers = ctx.auth.as('admin').headers; // { authorization, x-organization-id }
80
- const withExtra = ctx.auth.as('admin').withExtra({ 'x-request-id': 'r-1' }).headers;
81
- ```
44
+ ## Auth sessions
82
45
 
83
- Directly construct without `createTestApp`:
46
+ `ctx.auth.register(role, { user | token, orgId?, extraHeaders? })`, then `ctx.auth.as(role).headers` (`authorization`, `x-organization-id`), `.withExtra({...})`, `ctx.auth.anonymous()` for 401 tests, `ctx.auth.roles`.
84
47
 
85
48
  ```typescript
86
- import { createJwtAuthProvider, createBetterAuthProvider } from '@classytic/arc/testing';
87
- const auth = createJwtAuthProvider(app, { defaultOrgId: 'org-1' });
49
+ import { createJwtAuthProvider, createBetterAuthProvider, createCustomAuthProvider } from '@classytic/arc/testing';
50
+ const auth = createJwtAuthProvider(app, { defaultOrgId: 'org-1' }); // signs via app.jwt.sign
88
51
  ```
89
52
 
90
- ---
53
+ `user` is signed by the JWT provider; Better Auth and custom providers need a pre-minted `token`.
91
54
 
92
- ## `createHttpTestHarness(resource, ctxFn)` — auto-generated resource coverage
55
+ ## expectArc
93
56
 
94
- ~16 tests per resource (CRUD + permission + validation + error envelope) from a single factory call. Reads `defineResource()` config and probes every route.
57
+ Success bodies have no envelope, failures are `{ code, message, status }`.
95
58
 
96
59
  ```typescript
97
- import { createTestApp, createHttpTestHarness } from '@classytic/arc/testing';
98
-
99
- describe('Product resource — full coverage', () => {
100
- const ctx = await createTestApp({ resources: [productResource] });
101
- ctx.auth.register('admin', { user: { id: '1', roles: ['admin'] } });
102
-
103
- createHttpTestHarness(productResource, () => ({
104
- app: ctx.app,
105
- auth: ctx.auth,
106
- adminRole: 'admin',
107
- fixtures: { product: (i) => ({ name: `P${i}`, price: 10 + i }) },
108
- })).runAll();
109
- });
60
+ expectArc(res).ok(201);
61
+ expectArc(res).forbidden(); // also unauthorized(), notFound(), validationError(), conflict(), failed(status?)
62
+ expectArc(res).notFound().hasError(/not exist/);
63
+ expectArc(res).paginated({ total: 10 }); // docs[] plus pagination fields
64
+ expectArc(res).hidesField('password'); // also showsField, hasData(), hasMeta(key, value?)
110
65
  ```
111
66
 
112
- ---
113
-
114
- ## `expectArc(response)` — fluent envelope matchers
67
+ ## createHttpTestHarness
115
68
 
116
69
  ```typescript
117
- expectArc(res).ok(); // 200/201 with data envelope
118
- expectArc(res).forbidden(); // 403, arc error envelope
119
- expectArc(res).notFound().hasError(/not exist/);
120
- expectArc(res).validationError().hasData({ fields: ['email'] });
121
- expectArc(res).paginated({ total: 10 }); // meta.pagination present
122
- expectArc(res).hidesField('password'); // field stripped from response
123
- expectArc(res).hasMeta('traceId');
70
+ createHttpTestHarness(productResource, () => ({
71
+ app: ctx.app,
72
+ auth: ctx.auth!,
73
+ adminRole: 'admin',
74
+ fixtures: { valid: { name: 'P', price: 10 }, update: { price: 20 }, invalid: { price: 'x' } },
75
+ apiPrefix: '/api', // optional
76
+ })).runAll(); // or runCrud() / runPermissions() / runValidation()
124
77
  ```
125
78
 
126
- Available: `.ok`, `.failed`, `.unauthorized`, `.forbidden`, `.notFound`, `.validationError`, `.conflict`, `.hasData`, `.hidesField`, `.showsField`, `.paginated`, `.hasError`, `.hasMeta`.
79
+ Reads the resource config (`disabledRoutes`, `updateMethod`) and probes each enabled route. Pass a getter when the app is built in `beforeAll`.
127
80
 
128
- ---
129
-
130
- ## `createTestFixtures()` — DB-agnostic seeding
81
+ ## Fixtures
131
82
 
132
83
  ```typescript
133
84
  import { createTestFixtures } from '@classytic/arc/testing';
134
-
135
85
  const fixtures = createTestFixtures();
136
- fixtures.register('product', async (data) => {
137
- const doc = await Product.create(data);
138
- return { record: doc, destroy: () => Product.deleteOne({ _id: doc._id }) };
86
+ fixtures.register('product', {
87
+ create: (data) => Product.create(data),
88
+ destroy: (doc) => Product.deleteOne({ _id: doc._id }).then(() => undefined),
139
89
  });
140
-
141
- const widget = await fixtures.create('product', { name: 'Widget' });
142
- await fixtures.clear(); // runs destroyers newest-first
90
+ await fixtures.create('product', { name: 'Widget' });
91
+ await fixtures.createMany('product', 3);
92
+ await fixtures.clear(); // destroyers run newest first
143
93
  ```
144
94
 
145
- Destroyers bind at create time — no global cleanup registry. Works with any backend (Mongoose, sqlitekit, Prisma, in-memory).
146
-
147
- ---
95
+ `register` also accepts a bare factory function (no cleanup). `ctx.fixtures` is the same tracker.
148
96
 
149
- ## Better Auth orchestration — `setupBetterAuthTestApp`
150
-
151
- Composes `createTestApp` with Better Auth sign-up + org creation. Use when you need real Better Auth tokens rather than pre-signed stubs:
97
+ ## bootModuleApp
152
98
 
153
99
  ```typescript
154
- import { setupBetterAuthTestApp, createBetterAuthTestHelpers } from '@classytic/arc/testing';
100
+ import { bootModuleApp, testActorHeaders } from '@classytic/arc/testing';
155
101
 
156
- const { ctx, helpers } = await setupBetterAuthTestApp({ resources: [orderResource], auth });
157
- const { user, token, orgId } = await helpers.signUpWithOrg({ email: 'a@x.co', name: 'A' });
158
- ctx.auth.register('admin', { token, orgId });
102
+ const t = await bootModuleApp((ctx) => [catalogModule(ctx.connection)], {
103
+ replset: false, // true for transactions
104
+ actor: { roles: ['manager'], organizationId: 'org-1' }, // default actor
105
+ ports: { /* host ports */ },
106
+ app: { /* extra createApp options */ },
107
+ });
108
+ const engine = t.exports<CatalogEngine>('catalog');
109
+ await t.app.inject({ url: '/x', headers: testActorHeaders('cashier', 'org-1') });
110
+ await t.close();
159
111
  ```
160
112
 
161
- ---
113
+ - Database is a seam: `database` (default `mongoMemoryDatabase`) returns `{ uri, connection, teardown }`; kits inject their own.
114
+ - Identity comes from the `x-test-actor` header (`testActorHeaders(actor | roleString | null, orgId?)`). `null` stays public. Only `bootModuleApp` installs it; `createApp` never does.
115
+ - Gate routes with arc primitives (`requireRoles`, `requireOrgMembership`), not test-only gates.
116
+ - `assertModuleBootsAlone(modules, name, { probe })` boots a module with its dependency closure only.
117
+ - `assertRequiresPorts(module, ports, { with, ports })` proves declared required ports.
118
+ - `createTestModuleSetup({ ports })` gives `{ context, deferred, dispose }` to unit-test module phases.
119
+ - `runAuthorizationConformance`, `scopeRoleGate(...roles)` exist for authorization suites.
162
120
 
163
- ## Mocks (non-Fastify unit tests)
121
+ ## Better Auth
164
122
 
165
123
  ```typescript
166
- import {
167
- createMockRepository,
168
- createDataFactory,
169
- createMockUser,
170
- createMockRequest,
171
- createMockReply,
172
- waitFor,
173
- createSpy,
174
- createTestTimer,
175
- } from '@classytic/arc/testing';
124
+ import { setupBetterAuthTestApp } from '@classytic/arc/testing';
125
+
126
+ const r = await setupBetterAuthTestApp({
127
+ app, // built app with Better Auth registered
128
+ org: { name: 'Acme', slug: 'acme' },
129
+ users: [
130
+ { key: 'admin', email: 'a@x.co', password: 'pw', name: 'A', role: 'owner', isCreator: true },
131
+ ],
132
+ addMember, // required for non-creator users
133
+ });
134
+ r.auth.as('admin').headers; r.orgId; r.users.admin.token; await r.teardown();
176
135
  ```
177
136
 
178
- ---
179
-
180
- ## `runStorageContract(setup)` — adapter conformance
137
+ Exactly one user has `isCreator: true`. Lower level: `createBetterAuthTestHelpers()` gives `signUp`, `signIn`, `createOrg`, `setActiveOrg`, `authHeaders`.
181
138
 
182
- DB-agnostic Storage contract check. Build a setup that returns your adapter factory + a cleanup fn; arc runs the full contract suite against it.
139
+ ## Contracts
183
140
 
184
141
  ```typescript
185
- import { runStorageContract } from '@classytic/arc/testing';
186
- runStorageContract(async () => {
187
- const storage = createMyAdapter();
188
- return { storage, cleanup: async () => storage.close() };
189
- });
142
+ runStorageContract('my-storage', async () => ({ storage, teardown: async () => storage.close() }));
143
+ runOutboxStoreContract('my-store', async () => ({ store, reset: async () => { /* empty it */ }, teardown }));
190
144
  ```
191
145
 
192
- ---
146
+ `reset` is required for the outbox contract and runs before every test.
147
+
148
+ ## Unit-test mocks
149
+
150
+ `createMockRepository`, `createMockController`, `createMockUser`, `createMockRequest`, `createMockReply`, `createDataFactory`, `createSpy`, `createTestTimer`, `waitFor`.
193
151
 
194
152
  ## Tips
195
153
 
196
- 1. **`app.inject()` over real HTTP** — same server, zero network.
197
- 2. **Register auth sessions once per role** — not per test.
198
- 3. **Use `ctx.fixtures.clear()` in `afterEach`** — destroyers handle dependency order.
199
- 4. **Test permission denials explicitly** — `expectArc(res).forbidden()` beats status-code assertions.
200
- 5. **Reach for `createHttpTestHarness` first** — 16 tests for one function call.
154
+ - Use `app.inject()`, never a real port.
155
+ - Register one auth session per role in `beforeAll`.
156
+ - Call `ctx.fixtures.clear()` in `afterEach`.
157
+ - Assert denials with `expectArc(res).forbidden()`, not raw status codes.
@@ -0,0 +1,45 @@
1
+ # Usage counters, tenant cleanup, runtime capabilities
2
+
3
+ ## Usage counters and plan limits
4
+
5
+ `usagePlugin` (`@classytic/arc/usage`) decorates `fastify.usage` with per-actor, per-UTC-month counters: `record`, `summary`, `period`, `actorOf` (actor chain: org, user, client, ip). It tracks `api.requests` by default and `api.egress.bytes` on request; recording is fail-safe (a throwing store never fails a request).
6
+
7
+ | Store | Use |
8
+ |---|---|
9
+ | `MemoryUsageStore` | single process (default) |
10
+ | `RedisUsageStore` | distributed; retention is opt-in (`retentionSeconds`), counters are kept forever otherwise |
11
+ | a kit's `usage` store | counters beside domain data |
12
+
13
+ Quota gate: `requireQuota({ kind: 'ai.tokens', limit })` (number, `false` = unlimited, or a plan-aware resolver); denies with 429 `quota.exceeded` carrying `{ kind, used, limit, period, resetsAt }`. Fail-open on store errors unless `onStoreError: 'deny'`. Per-plan request ceilings: `createApp({ rateLimit: { plan } })` (the limiter runs before auth, so `resolve` sees the raw request).
14
+
15
+ ## Tenant cleanup (GDPR / SOX / HIPAA)
16
+
17
+ ```typescript
18
+ defineResource({ name: 'invoice', tenantField: 'organizationId',
19
+ onTenantDelete: { strategy: { type: 'anonymize', fields: { customerName: '[REDACTED]', email: null } },
20
+ priority: 50, batchSize: 1000 } });
21
+ defineResource({ name: 'event', onTenantDelete: { strategy: { type: 'hard' } } });
22
+ defineResource({ name: 'ledger', onTenantDelete: { strategy: { type: 'skip', reason: 'SOX retention' } } });
23
+
24
+ import { assertNoTenantData, cascadeDeleteForOrganization } from '@classytic/arc/registry';
25
+ const report = await cascadeDeleteForOrganization(fastify.arc.registry, { organizationId, concurrency: 4, logger: fastify.log });
26
+ ```
27
+
28
+ Strategies: `hard`, `soft`, `anonymize` (`fields` static or `(doc) => value`), `skip` (`reason` mandatory). Resources without `onTenantDelete` are never touched. Index `tenantField` on every cascading resource. Smoke check: `assertNoTenantData(registry, { organizationId })`.
29
+
30
+ ## Runtime capability registry
31
+
32
+ Under `runtime: 'distributed'`, a subsystem holding process-local state must declare it, or the end-of-boot audit fails naming every violator.
33
+
34
+ ```typescript
35
+ import { declareRuntimeCapability } from '@classytic/arc/utils';
36
+
37
+ declareRuntimeCapability(fastify, {
38
+ subsystem: 'billing.sequence-cache',
39
+ durability: 'memory', // 'memory' | 'shared'
40
+ detail: 'invoice numbering cached per process',
41
+ // accepted: true, // only when per-process is intended by design; never inferred
42
+ });
43
+ ```
44
+
45
+ Arc's own memory defaults declare themselves (`auth.sessions`, `usage.store`, `audit.store`, `cache.query`, `permissions.dynamic-cache`, `websocket.adapter`, `webhooks.store`); a distributed app must replace each with a shared store or accept it explicitly. See the production references for the store-by-store table.
@@ -0,0 +1,91 @@
1
+ # Validation: declare a zod schema once
2
+
3
+ Zod v4 is accepted in every schema slot. Arc converts it once at registration (`draft-7` for AJV, `openapi-3.0` for docs); plain JSON Schema passes through. Zod stays an optional peer.
4
+
5
+ ## Slots
6
+
7
+ | Where | Slot | Direction |
8
+ |---|---|---|
9
+ | `routes[].schema` | `body`, `querystring`, `params`, `headers` | input |
10
+ | `routes[].schema.response` | `{ 200: schema }` | output |
11
+ | `customSchemas.{list,get,create,update,delete}` | same parts, replaces the generated part wholesale | input / output |
12
+ | `actions.<name>.schema` | the body schema itself | input |
13
+ | `openApiSchemas` | docs only (`createBody`, `updateBody`, `listQuery`, ...) | input |
14
+
15
+ Input direction keeps `.default()` optional on the wire and keeps `.transform()` representable. A plain `z.object()` strips unknown keys, so it does not emit `additionalProperties: false` on input; use `z.strictObject()` to reject them. A `z.object` response doubles as a field-stripping contract. `.meta({ description, examples })` flows into OpenAPI and MCP.
16
+
17
+ ## routeInput: AJV + parsed handler input
18
+
19
+ AJV validates what JSON Schema can express. JSON Schema cannot trim, refine across fields or fill nested defaults, so `routeInput` adds a `preHandler` that runs the same zod schema and replaces `request.body|query|params` with its OUTPUT.
20
+
21
+ ```typescript
22
+ import { parsed, routeInput } from '@classytic/arc/core';
23
+ import { allowPublic } from '@classytic/arc/permissions';
24
+ import { z } from 'zod';
25
+
26
+ const createNote = z.object({ title: z.string().trim().min(2), tags: z.array(z.string()).default([]) });
27
+ const listQuery = z.object({ limit: z.coerce.number().int().min(1).default(20) });
28
+
29
+ routes: [{
30
+ method: 'POST', path: '/notes', permissions: allowPublic(),
31
+ ...routeInput({ body: createNote, querystring: listQuery, response: { 200: z.object({ id: z.string() }) } }),
32
+ rawHandler: async (req, reply) => {
33
+ const body = parsed(createNote, req.body); // typed z.output, trimmed, defaulted
34
+ return reply.send({ id: await notes.create(body) });
35
+ },
36
+ }]
37
+ ```
38
+
39
+ - A failed parse is `400 arc.validation_error` with `details[]` (`path`, `message`), the same wire as an AJV failure.
40
+ - A plain JSON Schema slot is AJV-only (no preHandler is added for it).
41
+ - `parsed(schema, value)` is a typing helper: it does not parse again.
42
+ - `headers` and `response` are schema-only.
43
+
44
+ ## CRUD verbs: crudInput
45
+
46
+ ```typescript
47
+ import { crudInput } from '@classytic/arc/core';
48
+
49
+ defineResource({
50
+ name: 'course', adapter,
51
+ ...crudInput({ create: courseCreate, update: courseUpdate, parse: true }),
52
+ });
53
+ ```
54
+
55
+ Returns `customSchemas` (what AJV enforces) and `openApiSchemas` (what docs show, instead of the stored model). `parse: true` also returns `middlewares.create|update` that hand the repository the zod output; merge it with your own `middlewares` instead of overwriting.
56
+
57
+ ## Actions
58
+
59
+ ```typescript
60
+ import { defineAction, noPayloadSchema } from '@classytic/arc/core';
61
+
62
+ actions: {
63
+ close: defineAction({
64
+ schema: z.object({ note: z.string().trim().min(2) }),
65
+ parse: true, // handler's data is the zod output; default false = what AJV accepted
66
+ permissions: requireRoles(['admin']),
67
+ handler: async (id, data) => tickets.close(id, data.note),
68
+ }),
69
+ touch: { schema: noPayloadSchema, permissions: requireAuth(), handler: async (id) => touch(id) },
70
+ }
71
+ ```
72
+
73
+ `noPayloadSchema` is plain JSON Schema (`additionalProperties: false`): any stray field is a 400.
74
+
75
+ ## The wrapper pitfall
76
+
77
+ An action's `schema` IS the body schema. `schema: { body: X }` has no `type` or `properties`, arc reads it as empty, and the action accepts anything with no error.
78
+
79
+ ```typescript
80
+ schema: { body: z.object({ note: z.string() }) } // WRONG: validates nothing
81
+ schema: z.object({ note: z.string() }) // right
82
+ ```
83
+
84
+ `defineResource()` records a `schema.slot_wrapper` diagnostic (logged at registration) for this shape in action schemas and in route or `customSchemas` slots (`body: { body: X }`). Make it fatal: `strictSchemas: true` on the resource or `ARC_STRICT_SCHEMAS=true`.
85
+
86
+ ## Other rules
87
+
88
+ - `customSchemas` parts replace generated parts; untouched parts keep auto-generation. Model-required fields the server fills: `schemaOptions.fieldRules: { f: { systemManaged: true } }`.
89
+ - Unconvertible zod in a validation slot (`z.date()`, `z.bigint()`, custom checks) fails boot: use the wire form (`z.iso.datetime()`, `z.string()`) and convert in the handler.
90
+ - A `.refine()` is not enforced by AJV: it needs `routeInput` / `parse: true`, or do it in the handler.
91
+ - A thrown raw `ZodError` from your own `.parse()` is not mapped to a 400 by arc; use `routeInput` or throw `ValidationError`.
@@ -0,0 +1,80 @@
1
+ # Writes, hooks, errors, audit
2
+
3
+ ## Write verbs and transactions
4
+
5
+ `writes` binds a domain command to a CRUD slot. `transactional: true` runs the persistence step inside the kit's `withTransaction`; the verb receives the tx-bound repository and `ctx.uow`.
6
+
7
+ ```typescript
8
+ defineResource({
9
+ name: 'order', adapter, transactional: true,
10
+ writes: {
11
+ create: async (data, ctx) => {
12
+ const order = await ctx.repository.create(data); // tx-bound
13
+ await outbox.store(event, { session: ctx.uow?.session }); // same transaction
14
+ return order;
15
+ },
16
+ },
17
+ });
18
+ ```
19
+
20
+ - Hooks run once, outside the retry; only persistence re-runs on a transient conflict. `VersionConflictError` surfaces as 409, never retried.
21
+ - Retry belongs to the kit (`transactionRetry`); arc never stacks a second policy.
22
+ - Boot fails without `withTransaction`, and at registration when `capabilities.transactions !== true` (standalone Mongo, D1).
23
+ - `ctx.uow.session` is empty on connection-bound backends (SQLite): use the tx-bound repository.
24
+
25
+ ## Hooks
26
+
27
+ ```typescript
28
+ hooks: {
29
+ beforeCreate: async (ctx) => { ctx.data.slug = slugify(ctx.data.name); },
30
+ afterCreate: async (ctx) => { analytics.track('created', { id: ctx.data._id }); },
31
+ beforeUpdate: async (ctx) => { /* ctx.meta.existing is the pre-image */ },
32
+ beforeDelete: async (ctx) => { if (ctx.data.isProtected) throw new Error('locked'); },
33
+ }
34
+ ```
35
+
36
+ `ctx = { data, user?, meta? }`; `meta` carries `id` and `existing`. Cross-resource: `createHookSystem()` and `beforeCreate(hooks, 'product', fn)` from `@classytic/arc/hooks`.
37
+
38
+ ## Errors
39
+
40
+ ```typescript
41
+ import { createDomainError, NotFoundError } from '@classytic/arc';
42
+
43
+ throw new NotFoundError('Product'); // 404 arc.not_found
44
+ throw createDomainError('SELF_REFERRAL', 'Cannot self-refer', 422, { field });
45
+ ```
46
+
47
+ Wire (repo-core `ErrorContract`, no envelope, HTTP status discriminates): `{ code, message, status, details?, meta?, correlationId? }`. AJV and zod failures are `400 arc.validation_error` with `details[]`. Unknown routes are `404 arc.not_found`.
48
+
49
+ ```typescript
50
+ errorHandler: { errorMappers: [{ type: AccountingError,
51
+ toResponse: (e) => ({ status: e.status, code: e.code, message: e.message }) }] }
52
+ ```
53
+
54
+ Modules ship mappers with `defineModule({ errorMappers })`; host mappers keep priority. A raw `ZodError` from your own `.parse()` is not mapped (use `routeInput`). Driver duplicate-key errors become 409 `arc.conflict`.
55
+
56
+ ## Audit and history
57
+
58
+ ```typescript
59
+ await fastify.register(auditPlugin, { autoAudit: { perResource: true } });
60
+
61
+ defineResource({ name: 'order', audit: true });
62
+ defineResource({ name: 'invoice', history: true }); // adds GET /:id/history from audit rows; implies audit
63
+ defineResource({ name: 'payment', audit: { operations: ['delete'] } });
64
+ await app.audit.custom('order', id, 'refund', { reason }, { user }); // manual, e.g. read auditing
65
+ ```
66
+
67
+ History is gated update -> get -> `requireAuth` unless you pass `{ permissions, limit }`.
68
+
69
+ ## Refusing from your own hook
70
+
71
+ A hook that refuses must end the lifecycle itself. `reply.sent` stays false while 2+ async `preSerialization`/`onSend` hooks defer the write, so Fastify runs the handler after a `reply.send(...)` that returned nothing (the write happened, so did the side effects).
72
+
73
+ ```typescript
74
+ fastify.addHook('preHandler', async (req, reply) => {
75
+ if (!allowed(req)) return reply.code(403).send({ code: 'arc.forbidden', message: 'No', status: 403 }); // return the reply
76
+ });
77
+ // or throw: createError(403, 'No') from @classytic/arc/utils; the error handler serializes it
78
+ ```
79
+
80
+ Arc's own gates (permissions, auth, org scope, rate limit, cache hit) return the reply. `defineGuard` and a custom `auth.authenticate` that reply without returning are detected and ended for you. Pinned by `tests/core/refusal-ends-lifecycle.test.ts`; guard a host app with `checkRefusalDoesNoWork` from `@classytic/arc-testkit/conformance`.