@classytic/arc 2.45.2 → 2.46.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (321) hide show
  1. package/README.md +1 -1
  2. package/dist/{EventTransport-CiicKz2Z.d.mts → EventTransport-CYEoCJGe.d.mts} +0 -2
  3. package/dist/{EventTransport-DHb1tpu-.mjs → EventTransport-DNgD9NP4.mjs} +3 -4
  4. package/dist/{HookSystem-C1u0EUnt.mjs → HookSystem-DRbPzEcP.mjs} +3 -4
  5. package/dist/{QueryCache--5uAuYPW.d.mts → QueryCache-DdvrGG8Q.d.mts} +1 -3
  6. package/dist/{ResourceRegistry-D2jXWVN_.mjs → ResourceRegistry-Douk51fa.mjs} +15 -4
  7. package/dist/{acquire-DTkA8Lme.mjs → acquire-RbtvDg9s.mjs} +2 -3
  8. package/dist/{actionPermissions-DRVk6m7x.mjs → actionPermissions-De0AJ7hm.mjs} +37 -42
  9. package/dist/audit/index.d.mts +2 -10
  10. package/dist/audit/index.mjs +8 -12
  11. package/dist/auth/audit.d.mts +0 -2
  12. package/dist/auth/audit.mjs +2 -3
  13. package/dist/auth/index.d.mts +9 -17
  14. package/dist/auth/index.mjs +26 -29
  15. package/dist/auth/redis-session.d.mts +2 -4
  16. package/dist/auth/redis-session.mjs +2 -3
  17. package/dist/{authorizationDecision-D48fUJv1.mjs → authorizationDecision-DeZMrHcm.mjs} +5 -6
  18. package/dist/{base-CZyixEQR.d.mts → base-HXNgPQww.d.mts} +1 -7
  19. package/dist/{boundedMap-DkKiPifd.mjs → boundedMap-2WBh3gM9.mjs} +2 -3
  20. package/dist/{buildHandler-BiZ4VATS.mjs → buildHandler-DxVOOBpw.mjs} +5 -6
  21. package/dist/cache/index.d.mts +4 -10
  22. package/dist/cache/index.mjs +5 -6
  23. package/dist/{caching-Cj0as-P1.mjs → caching-BYRwYrUo.mjs} +3 -4
  24. package/dist/{claimed-ChI13rUR.mjs → claimed-DYlELdnm.mjs} +2 -3
  25. package/dist/cleanup/index.d.mts +4 -18
  26. package/dist/cleanup/index.mjs +12 -20
  27. package/dist/cli/commands/describe.d.mts +1 -3
  28. package/dist/cli/commands/describe.mjs +4 -5
  29. package/dist/cli/commands/docs.d.mts +1 -3
  30. package/dist/cli/commands/docs.mjs +4 -5
  31. package/dist/cli/commands/doctor.d.mts +1 -3
  32. package/dist/cli/commands/doctor.mjs +2 -3
  33. package/dist/cli/commands/generate.d.mts +1 -1
  34. package/dist/cli/commands/generate.mjs +2 -2
  35. package/dist/cli/commands/init.d.mts +1 -1
  36. package/dist/cli/commands/init.mjs +2 -2
  37. package/dist/cli/commands/introspect.d.mts +1 -3
  38. package/dist/cli/commands/introspect.mjs +3 -4
  39. package/dist/cli/index.d.mts +2 -2
  40. package/dist/cli/index.mjs +3 -3
  41. package/dist/{constants-D_aiew34.mjs → constants-CHZMUwBW.mjs} +2 -3
  42. package/dist/context/index.d.mts +0 -8
  43. package/dist/context/index.mjs +6 -7
  44. package/dist/core/index.d.mts +3 -3
  45. package/dist/core/index.mjs +8 -8
  46. package/dist/{core-QIZ2560Y.mjs → core-D9rS2BxO.mjs} +9 -12
  47. package/dist/{createActionRouter-CvH84dyx.mjs → createActionRouter-0qkCRzTL.mjs} +7 -8
  48. package/dist/{createAggregationRouter-DGyK2Hp6.mjs → createAggregationRouter-CUf5Esd9.mjs} +9 -10
  49. package/dist/{createApp-CKjZpmq9.mjs → createApp-DZIXfDKD.mjs} +49 -62
  50. package/dist/{createMcpServer-DSztofa9.d.mts → createMcpServer-DeVpqQF-.d.mts} +1 -3
  51. package/dist/{defineAggregation-BLza7Ca4.mjs → defineAggregation-bmKQ4NmC.mjs} +2 -3
  52. package/dist/{defineResource-CEo0gDCb.mjs → defineResource-CGmdmGwh.mjs} +78 -29
  53. package/dist/discovery/index.d.mts +1 -3
  54. package/dist/discovery/index.mjs +2 -3
  55. package/dist/docs/index.d.mts +8 -8
  56. package/dist/docs/index.mjs +4 -5
  57. package/dist/{elevation-BJTsSnke.mjs → elevation-CzhqAyVN.mjs} +9 -10
  58. package/dist/{elevation-BW2J3tNj.d.mts → elevation-DPD0hcU-.d.mts} +0 -2
  59. package/dist/encryption/index.d.mts +1 -7
  60. package/dist/encryption/index.mjs +8 -13
  61. package/dist/{errorHandler--4rSMMvq.d.mts → errorHandler-B9r88jZV.d.mts} +8 -3
  62. package/dist/{errorHandler-2p4SL5zm.mjs → errorHandler-dFyGOEoB.mjs} +16 -6
  63. package/dist/{errors-grZkIA8N.mjs → errors-BY8vzlP4.mjs} +2 -3
  64. package/dist/{errors-JYc9vwqE.d.mts → errors-DTo0me1o.d.mts} +0 -2
  65. package/dist/{eventPlugin-BtmA4-3P.d.mts → eventPlugin-BY38F6yK.d.mts} +1 -7
  66. package/dist/{eventPlugin-ItcYBGUs.mjs → eventPlugin-eMhAPtQA.mjs} +10 -12
  67. package/dist/{eventTypes-Ck6fD3ne.mjs → eventTypes-Do2KYeJx.mjs} +5 -8
  68. package/dist/events/index.d.mts +4 -16
  69. package/dist/events/index.mjs +8 -9
  70. package/dist/events/transports/redis-stream-entry.d.mts +1 -1
  71. package/dist/events/transports/redis-stream-entry.mjs +5 -6
  72. package/dist/events/transports/redis.d.mts +2 -4
  73. package/dist/events/transports/redis.mjs +3 -4
  74. package/dist/{externalPaths-CmGOxOtD.d.mts → externalPaths-BOqdq5wr.d.mts} +0 -2
  75. package/dist/factory/index.d.mts +4 -14
  76. package/dist/factory/index.mjs +12 -18
  77. package/dist/{fastify-augmentation-DRlCIWE9.d.mts → fastify-augmentation-Dtn0IIRn.d.mts} +4 -10
  78. package/dist/{fields-BBSpf8pS.d.mts → fields-JTkrtO-r.d.mts} +0 -2
  79. package/dist/{fields-BRX0Krcj.mjs → fields-LnbCcvsw.mjs} +2 -3
  80. package/dist/{filter-merge-CDc7YMwX.mjs → filter-merge-BAWi019Q.mjs} +2 -3
  81. package/dist/{generate-DCGuEbqI.d.mts → generate-C-g_KOkV.d.mts} +0 -4
  82. package/dist/{generate-hvg7V2g1.mjs → generate-oXoDnpJf.mjs} +7 -12
  83. package/dist/{headers-Cqkg4LzI.mjs → headers-DBd3Qheo.mjs} +3 -4
  84. package/dist/{health-PVt0VjOx.mjs → health-BlJu9GXS.mjs} +2 -3
  85. package/dist/{health-DyeP3mTW.mjs → health-Dp-3EC9o.mjs} +4 -7
  86. package/dist/hooks/index.d.mts +1 -1
  87. package/dist/hooks/index.mjs +2 -2
  88. package/dist/idempotency/index.d.mts +3 -9
  89. package/dist/idempotency/index.mjs +10 -13
  90. package/dist/idempotency/redis.d.mts +1 -1
  91. package/dist/idempotency/redis.mjs +3 -4
  92. package/dist/{index-Bxriq3so.d.mts → index-B5i9-vuP.d.mts} +4 -26
  93. package/dist/{index-Chgz3d0i.d.mts → index-BAXDo5eE.d.mts} +1 -7
  94. package/dist/{index-Beg3aNnK.d.mts → index-BTxzJ_MN.d.mts} +67 -25
  95. package/dist/{index-CUJvoyw3.d.mts → index-Bqfo8hLz.d.mts} +2 -24
  96. package/dist/{index-uhkUA5-U.d.mts → index-CUdaoCYt.d.mts} +13 -23
  97. package/dist/{index-WH7xgvxS.d.mts → index-DyJFTJLA.d.mts} +31 -92
  98. package/dist/index.d.mts +7 -9
  99. package/dist/index.mjs +12 -13
  100. package/dist/{init-jC3rMPzb.mjs → init-BOaNkLYb.mjs} +18 -35
  101. package/dist/{init-Cscs4lab.d.mts → init-CV2_Fw3H.d.mts} +0 -4
  102. package/dist/integrations/event-gateway.d.mts +3 -5
  103. package/dist/integrations/event-gateway.mjs +3 -4
  104. package/dist/integrations/index.d.mts +3 -3
  105. package/dist/integrations/index.mjs +1 -1
  106. package/dist/integrations/jobs/index.d.mts +1 -1
  107. package/dist/integrations/jobs/index.mjs +7 -11
  108. package/dist/integrations/mcp/index.d.mts +7 -39
  109. package/dist/integrations/mcp/index.mjs +8 -14
  110. package/dist/integrations/mcp/testing.d.mts +3 -5
  111. package/dist/integrations/mcp/testing.mjs +3 -4
  112. package/dist/integrations/streamline.d.mts +1 -3
  113. package/dist/integrations/streamline.mjs +4 -5
  114. package/dist/integrations/webhooks.d.mts +2 -4
  115. package/dist/integrations/webhooks.mjs +4 -5
  116. package/dist/integrations/websocket-pushref-redis.d.mts +2 -4
  117. package/dist/integrations/websocket-pushref-redis.mjs +2 -3
  118. package/dist/integrations/websocket-redis.d.mts +2 -4
  119. package/dist/integrations/websocket-redis.mjs +2 -3
  120. package/dist/integrations/websocket.d.mts +2 -2
  121. package/dist/integrations/websocket.mjs +13 -24
  122. package/dist/{interface-JJzwH4Ro.d.mts → interface-BmExzQRD.d.mts} +0 -2
  123. package/dist/{interface-BOk3YnTz.d.mts → interface-WR1U0K7t.d.mts} +0 -2
  124. package/dist/{jsonBody-ptwyzZQ-.mjs → jsonBody-DpRpKR_K.mjs} +3 -4
  125. package/dist/{keys-C1vFuSbv.mjs → keys-FBz6Ull-.mjs} +2 -3
  126. package/dist/{loadResources-CHPDyIPn.mjs → loadResources-Bx1sKPnF.mjs} +4 -5
  127. package/dist/{loadResourcesFromEntry-BkHHTu_B.mjs → loadResourcesFromEntry-b_jcqbxh.mjs} +3 -4
  128. package/dist/logger/index.d.mts +1 -3
  129. package/dist/logger/index.mjs +2 -2
  130. package/dist/{logger-C5bvCiAK.mjs → logger-CbFcIEBZ.mjs} +3 -5
  131. package/dist/{mcpPlugin-C9qohJCF.mjs → mcpPlugin-yix548XX.mjs} +41 -60
  132. package/dist/{memory-CxiTwT0j.mjs → memory-Bgw5dn8N.mjs} +4 -5
  133. package/dist/{metrics-Ckp2zRy-.mjs → metrics-CZDQWVjS.mjs} +4 -5
  134. package/dist/middleware/index.d.mts +1 -5
  135. package/dist/middleware/index.mjs +4 -5
  136. package/dist/migrations/index.d.mts +0 -2
  137. package/dist/migrations/index.mjs +3 -4
  138. package/dist/{module-CfnKuIuH.mjs → module-Dsc_nKL5.mjs} +2 -3
  139. package/dist/{multiTenant-CAtYlW6H.d.mts → multiTenant-XCxAUlru.d.mts} +1 -5
  140. package/dist/{multipartBody-BFasGtP9.mjs → multipartBody-B85ek8Kj.mjs} +2 -3
  141. package/dist/observeSend-BK-JN1jK.mjs +20 -0
  142. package/dist/{openapi-DAPxjYHX.mjs → openapi-Co7hl073.mjs} +18 -28
  143. package/dist/outbox-admin/index.d.mts +2 -4
  144. package/dist/outbox-admin/index.mjs +6 -7
  145. package/dist/{outbox-module-gZCHoE4H.d.mts → outbox-module-XvUThpqn.d.mts} +2 -8
  146. package/dist/{outbox-module-B4FAkx3A.mjs → outbox-module-mg9kDYkd.mjs} +13 -17
  147. package/dist/permissions/index.d.mts +4 -4
  148. package/dist/permissions/index.mjs +7 -7
  149. package/dist/{permissions-B14c3OMp.mjs → permissions-A1oKtpiC.mjs} +19 -29
  150. package/dist/{pipe-CQv7PsAK.mjs → pipe-Czpw9U2n.mjs} +3 -4
  151. package/dist/pipeline/index.d.mts +1 -9
  152. package/dist/pipeline/index.mjs +5 -8
  153. package/dist/{plan-CpnTykjb.mjs → plan-KVseuBCL.mjs} +5 -9
  154. package/dist/{plugin-DXTjVg_Q.mjs → plugin-DTWt_8C3.mjs} +130 -62
  155. package/dist/plugins/index.d.mts +8 -16
  156. package/dist/plugins/index.mjs +22 -26
  157. package/dist/plugins/response-cache.d.mts +2 -4
  158. package/dist/plugins/response-cache.mjs +10 -10
  159. package/dist/plugins/tracing-entry.d.mts +1 -1
  160. package/dist/plugins/tracing-entry.mjs +3 -4
  161. package/dist/{pluralize-C3VJKRGp.mjs → pluralize-msB9X3yw.mjs} +2 -3
  162. package/dist/presets/filesUpload.d.mts +4 -6
  163. package/dist/presets/filesUpload.mjs +6 -7
  164. package/dist/presets/index.d.mts +3 -19
  165. package/dist/presets/index.mjs +2 -2
  166. package/dist/presets/multiTenant.d.mts +1 -1
  167. package/dist/presets/multiTenant.mjs +7 -7
  168. package/dist/presets/search.d.mts +3 -5
  169. package/dist/presets/search.mjs +3 -4
  170. package/dist/{presets-CquqYJPy.mjs → presets-qKCehiJM.mjs} +11 -18
  171. package/dist/{projection-CgfSLOSM.mjs → projection-ClBqtsIw.mjs} +3 -4
  172. package/dist/{pushref-registry-UxCkoA4C.d.mts → pushref-registry-d86QUaSq.d.mts} +0 -6
  173. package/dist/{queryCachePlugin-D0HUISHJ.mjs → queryCachePlugin-3gJj5Rbz.mjs} +8 -10
  174. package/dist/{queryCachePlugin-C2lZjTxk.d.mts → queryCachePlugin-DYQUyeJ9.d.mts} +2 -4
  175. package/dist/{rateLimitKey-AvkBOMkl.mjs → rateLimitKey-Kro---xl.mjs} +2 -3
  176. package/dist/{realtime-CbWtVbqK.mjs → realtime-Ber8uJN2.mjs} +17 -19
  177. package/dist/{redis-BDgv9Glw.d.mts → redis-RpDMemdm.d.mts} +2 -4
  178. package/dist/{redis-stream-BMk-bpQS.d.mts → redis-stream-CS1N9dwM.d.mts} +1 -3
  179. package/dist/{redisShapes-CQksY67q.d.mts → redisShapes-CqBXTn_s.d.mts} +0 -2
  180. package/dist/registry/index.d.mts +2 -12
  181. package/dist/registry/index.mjs +3 -3
  182. package/dist/{registry-BVwpAuFI.mjs → registry-BA-_vFYk.mjs} +7 -12
  183. package/dist/{renewingLease-CykpeNcQ.mjs → renewingLease-CMY8YOcc.mjs} +2 -3
  184. package/dist/{replyHelpers-DA51IZio.mjs → replyHelpers-DK9P_XSz.mjs} +3 -4
  185. package/dist/{requestContext-DIWHKDtQ.mjs → requestContext-GYO_0gEw.mjs} +2 -3
  186. package/dist/{requirement-CbiLdQ1n.d.mts → requirement-CTRQjjQx.d.mts} +0 -2
  187. package/dist/{requirement-Cp_fsMDL.mjs → requirement-DeNjZIH3.mjs} +2 -3
  188. package/dist/{resourceRateLimit-Wf6d6FL9.d.mts → resourceRateLimit-DCWglD7V.d.mts} +1 -3
  189. package/dist/{resourceRateLimit-BFuluodF.mjs → resourceRateLimit-tHLbrtWc.mjs} +3 -4
  190. package/dist/{rolldown-runtime-D_lMdYOd.mjs → rolldown-runtime-Kv1fZdLg.mjs} +2 -3
  191. package/dist/{routeValidator-DuLonYwr.mjs → routeValidator-C_H5NanI.mjs} +2 -3
  192. package/dist/{runtimeCapabilities-CydRfm0i.mjs → runtimeCapabilities-DWqbxkyw.mjs} +2 -3
  193. package/dist/{schedules-B693KXxa.mjs → schedules-eO_RzhCU.mjs} +132 -9
  194. package/dist/{schemaConverter-DNvZWTV6.mjs → schemaConverter-DBJrPZN4.mjs} +3 -4
  195. package/dist/{schemaIR-REV2y7Wd.mjs → schemaIR-CEScKT2v.mjs} +3 -4
  196. package/dist/schemas/index.d.mts +0 -2
  197. package/dist/schemas/index.mjs +2 -3
  198. package/dist/scim/index.d.mts +0 -12
  199. package/dist/scim/index.mjs +10 -18
  200. package/dist/scope/index.d.mts +2 -6
  201. package/dist/scope/index.mjs +5 -5
  202. package/dist/{scope-Bevxy_ST.mjs → scope-B-Sm9m_E.mjs} +5 -6
  203. package/dist/{sessionManager-qimlKV0P.d.mts → sessionManager-CdvDF04x.d.mts} +2 -4
  204. package/dist/{shutdown-CfrqPR7A.mjs → shutdown-DzLFbe27.mjs} +2 -3
  205. package/dist/{simpleEqualityMatcher-BJwfuRKP.mjs → simpleEqualityMatcher-DOJhwQ8g.mjs} +2 -3
  206. package/dist/{sse-CuNNWr2z.mjs → sse-2972pVwV.mjs} +8 -9
  207. package/dist/{sseStream-C_2ujAVY.mjs → sseStream-AWLEeNV-.mjs} +3 -4
  208. package/dist/{storage-Cx9Sz3Ou.d.mts → storage-odC5MNKN.d.mts} +0 -2
  209. package/dist/{store-helpers-C8uBGCbb.mjs → store-helpers-VzjgVTkM.mjs} +2 -3
  210. package/dist/{streaming-Bdq_M4d5.mjs → streaming-DvraWW6x.mjs} +2 -3
  211. package/dist/{subscriberIdentity-B-KpZkdl.mjs → subscriberIdentity-Bya56jsg.mjs} +2 -3
  212. package/dist/{tenancy-C5PCvm1h.mjs → tenancy-DSa_0hhw.mjs} +3 -4
  213. package/dist/{tenantPreparation-dYvWrgNa.mjs → tenantPreparation-BrpkQre3.mjs} +5 -6
  214. package/dist/testing/cleanupStoreContract.d.mts +2 -4
  215. package/dist/testing/cleanupStoreContract.mjs +2 -3
  216. package/dist/testing/index.d.mts +6 -32
  217. package/dist/testing/index.mjs +24 -37
  218. package/dist/testing/outboxStoreContract.d.mts +1 -3
  219. package/dist/testing/outboxStoreContract.mjs +3 -4
  220. package/dist/testing/requiredPorts.d.mts +2 -4
  221. package/dist/testing/requiredPorts.mjs +3 -4
  222. package/dist/testing/storageContract.d.mts +2 -4
  223. package/dist/testing/storageContract.mjs +2 -3
  224. package/dist/{timing-DCqsezX8.mjs → timing-6rQTuCwg.mjs} +3 -5
  225. package/dist/{tracing-Dro5eH6j.d.mts → tracing-JSFiBl5r.d.mts} +0 -2
  226. package/dist/{transactionContext-DrcNyjpv.mjs → transactionContext-DaxYUEgH.mjs} +2 -3
  227. package/dist/{typeGuards-CEl10KPy.mjs → typeGuards-UKnX8wPX.mjs} +2 -3
  228. package/dist/types/index.d.mts +4 -4
  229. package/dist/types/index.mjs +1 -1
  230. package/dist/types/storage.d.mts +1 -1
  231. package/dist/types/storage.mjs +1 -1
  232. package/dist/{types-ByHn9rEO.d.mts → types-0Dqlbgn8.d.mts} +0 -2
  233. package/dist/{types-D3Ixsh00.d.mts → types-BYEb_dLW.d.mts} +2 -4
  234. package/dist/{types-BJ-2XqVF.d.mts → types-BeEJm-DV.d.mts} +114 -14
  235. package/dist/{types-DVLddu2q.d.mts → types-C0YJAiL0.d.mts} +0 -2
  236. package/dist/{types-D9NWjpYc.mjs → types-CuGjhn83.mjs} +5 -6
  237. package/dist/{types-Ddl9OjmE.d.mts → types-DnkIALZ8.d.mts} +0 -4
  238. package/dist/usage/index.d.mts +2 -10
  239. package/dist/usage/index.mjs +8 -12
  240. package/dist/{userHelpers-BHig1kHq.mjs → userHelpers-oX5_mOVs.mjs} +2 -3
  241. package/dist/utils/index.d.mts +5 -39
  242. package/dist/utils/index.mjs +12 -12
  243. package/dist/{utils-BG5P7_Vb.mjs → utils-CjjGOT4E.mjs} +20 -30
  244. package/dist/{validate-D_mdOCir.mjs → validate-4RlTKOJb.mjs} +5 -7
  245. package/dist/{versioning-DBGHjPh7.mjs → versioning-Dk2-19La.mjs} +4 -5
  246. package/dist/{versioning-Bqm_57Qt.d.mts → versioning-S18y2-0C.d.mts} +1 -15
  247. package/dist/{websocket-Cs4awVyD.d.mts → websocket-BGuc-WVZ.d.mts} +1 -15
  248. package/dist/{workScope-DPPfM4m6.mjs → workScope-DoBsoVo4.mjs} +3 -4
  249. package/llms.txt +37 -30
  250. package/package.json +9 -8
  251. package/skills/arc/SKILL.md +65 -844
  252. package/skills/arc/references/agent-auth.md +82 -193
  253. package/skills/arc/references/api-reference.md +41 -245
  254. package/skills/arc/references/auth-api-keys.md +99 -0
  255. package/skills/arc/references/auth-better-auth-overlay.md +87 -0
  256. package/skills/arc/references/auth-better-auth.md +78 -0
  257. package/skills/arc/references/auth-permissions.md +100 -0
  258. package/skills/arc/references/auth-strategies.md +122 -0
  259. package/skills/arc/references/boot.md +80 -0
  260. package/skills/arc/references/enterprise-auth.md +65 -81
  261. package/skills/arc/references/events-outbox.md +90 -0
  262. package/skills/arc/references/events.md +75 -440
  263. package/skills/arc/references/integrations-jobs.md +74 -0
  264. package/skills/arc/references/integrations-realtime.md +84 -0
  265. package/skills/arc/references/integrations-webhooks.md +71 -0
  266. package/skills/arc/references/integrations-workflows.md +47 -0
  267. package/skills/arc/references/mcp-auth.md +83 -0
  268. package/skills/arc/references/mcp-custom-tools.md +125 -0
  269. package/skills/arc/references/mcp-setup.md +115 -0
  270. package/skills/arc/references/mcp-testing.md +63 -0
  271. package/skills/arc/references/multi-tenancy.md +56 -230
  272. package/skills/arc/references/permissions-scope.md +81 -0
  273. package/skills/arc/references/production-api.md +119 -0
  274. package/skills/arc/references/production-audit.md +101 -0
  275. package/skills/arc/references/production-boot.md +91 -0
  276. package/skills/arc/references/production-caching.md +63 -0
  277. package/skills/arc/references/production-distributed.md +75 -0
  278. package/skills/arc/references/production-idempotency.md +83 -0
  279. package/skills/arc/references/production-observability.md +83 -0
  280. package/skills/arc/references/production-realtime.md +70 -0
  281. package/skills/arc/references/production-reliability.md +100 -0
  282. package/skills/arc/references/production-shutdown.md +43 -0
  283. package/skills/arc/references/querying.md +76 -0
  284. package/skills/arc/references/resources.md +97 -0
  285. package/skills/arc/references/schedules.md +79 -0
  286. package/skills/arc/references/scim.md +61 -208
  287. package/skills/arc/references/tenancy-scope-install.md +82 -0
  288. package/skills/arc/references/testing.md +101 -144
  289. package/skills/arc/references/usage-cleanup-capabilities.md +45 -0
  290. package/skills/arc/references/validation.md +91 -0
  291. package/skills/arc/references/writes-hooks-errors.md +80 -0
  292. package/skills/arc-code-review/SKILL.md +67 -114
  293. package/skills/arc-code-review/references/arc-cheatsheet.md +68 -167
  294. package/skills/arc-code-review/references/mongokit-repositories.md +104 -0
  295. package/skills/arc-code-review/references/recipe-events-cache-jobs.md +112 -0
  296. package/skills/arc-code-review/references/recipe-resource.md +100 -0
  297. package/skills/arc-code-review/references/recipe-schemas-fields.md +93 -0
  298. package/skills/arc-code-review/references/recipe-scope-permissions.md +82 -0
  299. package/skills/arc-code-review/references/scaffolding.md +61 -198
  300. package/skills/arc-code-review/references/severity.md +49 -102
  301. package/skills/arc-code-review/references/smells-auth-scope.md +80 -0
  302. package/skills/arc-code-review/references/smells-data-events.md +66 -0
  303. package/skills/arc-code-review/references/smells-imports-style.md +59 -0
  304. package/skills/arc-code-review/references/smells-platform.md +89 -0
  305. package/skills/arc-code-review/references/smells-routes-schemas.md +66 -0
  306. package/skills/arc-module-publishing/SKILL.md +82 -208
  307. package/skills/arc-module-publishing/references/action-presets-and-plugins.md +87 -0
  308. package/skills/arc-module-publishing/references/build-and-types.md +73 -0
  309. package/skills/arc-module-publishing/references/module-lifecycle.md +101 -0
  310. package/skills/arc-module-publishing/references/package-manifest.md +34 -122
  311. package/skills/arc-module-publishing/references/publishing-workflow.md +44 -140
  312. package/skills/arc-module-publishing/references/resource-assembly.md +102 -0
  313. package/skills/arc-module-publishing/references/testing-packages.md +82 -0
  314. package/skills/arc/references/auth.md +0 -729
  315. package/skills/arc/references/integrations.md +0 -452
  316. package/skills/arc/references/mcp.md +0 -691
  317. package/skills/arc/references/production.md +0 -835
  318. package/skills/arc-code-review/references/anti-patterns.md +0 -1008
  319. package/skills/arc-code-review/references/migration-recipes.md +0 -649
  320. package/skills/arc-code-review/references/mongokit-migration.md +0 -360
  321. package/skills/arc-module-publishing/references/authoring-modules.md +0 -327
@@ -0,0 +1,76 @@
1
+ # Querying: parser, aggregations, query cache
2
+
3
+ ## List query
4
+
5
+ ```
6
+ GET /products?page=2&limit=20&sort=-createdAt&select=name,price
7
+ GET /products?price[gte]=100&status[in]=active,featured&search=keyword
8
+ GET /products?after=<cursor>&limit=20 keyset
9
+ GET /products?populate[category][select]=name,slug
10
+ GET /products?filter[status]=active&filter[price][gte]=100 bracket envelope
11
+ ```
12
+
13
+ Operators: `eq ne gt gte lt lte in nin like regex exists`.
14
+
15
+ ```typescript
16
+ import { QueryParser } from '@classytic/mongokit';
17
+
18
+ defineResource({
19
+ queryParser: new QueryParser({
20
+ allowedFilterFields: ['status', 'category'],
21
+ allowedSortFields: ['createdAt', 'price'],
22
+ allowedOperators: ['eq', 'gte', 'lte', 'in'],
23
+ strictFilterFields: true, // unknown filter key = 400 instead of dropped
24
+ }),
25
+ schemaOptions: { query: { allowedPopulate: ['category'], allowedLookups: ['categories'] } },
26
+ });
27
+ ```
28
+
29
+ - An unknown filter key is DROPPED by default, which WIDENS the result (200 with every row). Set `strictFilterFields: true` or `ARC_STRICT_QUERY_PARAMS=true`.
30
+ - `?limit` above the cap is clamped, not rejected; the cap is in the OpenAPI parameter description.
31
+ - One cap, one owner: parser, repository and arc all cap page size and the lowest wins. Configure the same number everywhere; arc warns at boot on a mismatch.
32
+ - `limit` is `defaultLimit` / `maxLimit` on the resource.
33
+
34
+ ## Aggregations
35
+
36
+ `GET /:prefix/aggregations/:name`, portable `$match -> $group -> $project -> $sort -> $limit` through `repo.aggregate(req, options)`.
37
+
38
+ ```typescript
39
+ import { defineAggregation, defineResource } from '@classytic/arc';
40
+
41
+ aggregations: {
42
+ byMethod: defineAggregation({
43
+ groupBy: 'method',
44
+ measures: { total: 'sum:amount', count: 'count' },
45
+ sort: { total: -1 },
46
+ cache: { staleTime: 60, swr: true, tags: ['revenue'] },
47
+ permissions: canViewRevenue(),
48
+ }),
49
+ byDay: defineAggregation({
50
+ dateBuckets: { day: { field: 'createdAt', interval: 'day' } },
51
+ measures: { total: 'sum:amount' },
52
+ requireDateRange: { field: 'createdAt', maxRangeDays: 365 },
53
+ permissions: canViewRevenue(),
54
+ }),
55
+ }
56
+ ```
57
+
58
+ Guards: `requireFilters`, `requireDateRange`, `maxGroups`. Every aggregation is also an MCP tool. Tenant scope travels in `options`, not in `filter`. With no repository and no `materialized`, `defineResource()` throws.
59
+
60
+ `materialized: async (ctx) => ...` owns dispatch when the portable IR cannot express the query. `ctx.filter` carries only the declaration filter and query string: tenant is `ctx.orgId`, soft-delete is not merged. Route through the kit's pipeline call (mongokit `aggregatePipeline(pipeline, { organizationId: ctx.orgId, ... })`) so tenant, soft-delete and audit hooks run; never call the driver (`Model.aggregate`) directly.
61
+
62
+ ## Query cache
63
+
64
+ ```typescript
65
+ createApp({ arcPlugins: { queryCache: true } });
66
+ defineResource({
67
+ cache: { staleTime: 30, gcTime: 300, tags: ['catalog'],
68
+ invalidateOn: { 'category.*': ['catalog'] }, list: { staleTime: 60 }, byId: { staleTime: 10 } },
69
+ });
70
+ ```
71
+
72
+ SWR with auto-invalidation: POST/PATCH/DELETE bump the resource version. Header `x-cache: HIT | STALE | MISS`. `runtime: 'distributed'` needs `stores.queryCache` (a Redis cache store).
73
+
74
+ ## Query contract in the spec
75
+
76
+ The list operation carries `x-arc-query: { filterFields?, operators?, sortFields? }`, taken from the `queryParser` allow-lists (`allowedFilterFields`, `allowedOperators`, `allowedSortFields`); absent when none is declared. `@classytic/arc-testkit` `checkFilterDeclarations` checks a UI against it.
@@ -0,0 +1,97 @@
1
+ # defineResource: CRUD, routes, actions, presets
2
+
3
+ One `defineResource()` call = REST + validation + permissions + events + cache + OpenAPI + MCP.
4
+
5
+ ```typescript
6
+ import { defineResource } from '@classytic/arc';
7
+ import { allowPublic, requireAuth, requireRoles } from '@classytic/arc/permissions';
8
+ import { createMongooseAdapter } from '@classytic/mongokit/adapter';
9
+
10
+ export default defineResource({
11
+ name: 'product',
12
+ adapter: createMongooseAdapter({ model: ProductModel, repository: productRepo }),
13
+ presets: ['softDelete', 'slugLookup', { name: 'multiTenant', tenantField: 'organizationId' }],
14
+ permissions: {
15
+ list: allowPublic(), get: allowPublic(),
16
+ create: requireRoles(['admin']), update: requireRoles(['admin']), delete: requireRoles(['admin']),
17
+ },
18
+ schemaOptions: {
19
+ fieldRules: {
20
+ name: { minLength: 2, maxLength: 200 },
21
+ status: { enum: ['draft', 'active', 'archived'] },
22
+ organizationId: { systemManaged: true, preserveForElevated: true },
23
+ },
24
+ query: { allowedPopulate: ['category'], filterableFields: { status: { type: 'string' } } },
25
+ },
26
+ cache: { staleTime: 30, gcTime: 300, tags: ['catalog'] },
27
+ routes: [{ method: 'GET', path: '/featured', handler: 'getFeatured', permissions: allowPublic() }],
28
+ actions: { approve: { handler: approve, permissions: requireRoles(['admin']) } },
29
+ });
30
+ ```
31
+
32
+ Auto-generated: `GET /`, `GET /:id`, `POST /`, `PATCH /:id`, `DELETE /:id`. Presets add routes (table below). The adapter comes from the kit (`@classytic/mongokit/adapter`, `sqlitekit/adapter`, `prismakit/adapter`); a custom kit implements `DataAdapter` from `@classytic/repo-core/adapter`.
33
+
34
+ ## Custom routes: `handler` vs `rawHandler`
35
+
36
+ | Field | Signature | Behaviour |
37
+ |---|---|---|
38
+ | `handler` | `(ctx: IRequestContext)` or controller-method name | arc pipeline: envelope, field-write permissions, MCP tool |
39
+ | `rawHandler` | `(request, reply)` or controller-method name | Fastify-native: owns the response, no pipeline, no MCP unless `mcpHandler` |
40
+ | `controllerMethod` | `(c: MyController) => c.method` | typed ref, TS catches typos |
41
+
42
+ Both on one route throws at boot. `streamResponse: true` needs `rawHandler`. Custom endpoints belong in `routes:` / `actions:` (they inherit auth, OpenAPI, MCP); a bare `fastify.get()` bypasses all of it. Declare the schema with `routeInput` (see `references/validation.md`).
43
+
44
+ Actions share one `POST /:id/action` mount (`id: false` mounts `POST /action`); throttle one by making it a route with `rateLimit`. An action with no permission and no `permissions.update` fallback throws at boot (`allowPublic()` to opt out).
45
+
46
+ ## Resource shorthands
47
+
48
+ ```typescript
49
+ defineResource({ name: 'currency', adapter, referenceData: true }); // read-only, limit 1000, cached
50
+ defineResource({ name: 'health', customRoutesOnly: true, routes: [...] }); // no adapter, no CRUD, no registry
51
+ defineResource({ name: 'pipeline', adapter, defaultLimit: 200, maxLimit: 500 });
52
+ defineResource({ name: 'webhook', prefix: '/hooks', skipGlobalPrefix: true });
53
+ defineResource({ name: 'internal', adapter, mcp: false }); // no MCP tools
54
+ ```
55
+
56
+ ## fieldRules
57
+
58
+ | Flag | Effect |
59
+ |---|---|
60
+ | `systemManaged` | stripped from body and `required[]`; the framework stamps it |
61
+ | `preserveForElevated` | elevated admins keep the field on ingest |
62
+ | `immutable` / `immutableAfterCreate` | omitted from update body |
63
+ | `optional` | out of `required[]`, property kept |
64
+ | `nullable` | type widened to include null |
65
+ | `hidden` | blocked from responses, filters, sort and OpenAPI |
66
+ | `minLength` `maxLength` `min` `max` `pattern` `enum` `description` | map to AJV and OpenAPI |
67
+
68
+ Model constraints win; `fieldRules` supplements what the model lacks.
69
+
70
+ ## Presets
71
+
72
+ | Preset | Adds | Config |
73
+ |---|---|---|
74
+ | `softDelete` | `GET /deleted`, `POST /:id/restore` | `{ deletedField }` |
75
+ | `slugLookup` | `GET /slug/:slug` | `{ slugField }` |
76
+ | `tree` | `GET /tree`, `GET /:parent/children` | `{ parentField }` |
77
+ | `ownedByUser` | middleware | `{ ownerField }` |
78
+ | `multiTenant` | middleware | `{ tenantField }` or `{ tenantFields: [...] }` |
79
+ | `audited` | middleware | none |
80
+ | `bulk` | `POST/PATCH/DELETE /bulk` | `{ operations?, maxCreateItems? }` |
81
+ | `filesUpload` | `POST /upload`, `GET /:id`, `DELETE /:id` | `{ storage, allowedMimeTypes?, maxFileSize? }` |
82
+ | `search` | `POST /search`, `/search-similar`, `/embed` | `{ repository?, search?, similar?, embed? }` |
83
+
84
+ - `tenantField: false` disables the org filter (lookup tables, platform settings).
85
+ - `idField` picks the `:id` lookup column (default `_id`). A 404 on `PATCH` when `GET` works is usually a permission `filters` clause, not `idField`.
86
+ - Presets compose and order matters. A custom `controller` does not receive preset-injected fields: forward `tenantField` / `schemaOptions` / `idField` through `super()` and also pass them to `defineResource`, or extend `BaseController`.
87
+
88
+ ## Write behaviour
89
+
90
+ | Behaviour | Default | Switch |
91
+ |---|---|---|
92
+ | non-writable field in body | 403 with the denied list | `onFieldWriteDenied: 'strip'` |
93
+ | write to an `immutable` field | stripped, 200 | `onImmutableWrite: 'reject'` or `ARC_STRICT_IMMUTABLE_WRITES=true` |
94
+ | ungated CRUD write | fatal at define time | `strictPermissions: false` (not recommended) |
95
+ | multiTenant on update | body org overwritten with caller's scope | none |
96
+
97
+ Read-only repositories (Better Auth overlays) refuse write routes at boot: disable those routes or use `auth.api`.
@@ -0,0 +1,79 @@
1
+ # Scheduled jobs: intervals and daily runs
2
+
3
+ `schedulesPlugin` (`@classytic/arc/plugins`) runs in-process recurring jobs. Module-contributed `scheduledJobs` use the same plugin, configured through `arcPlugins.schedules`. For durable, Redis-backed jobs use `@classytic/arc/integrations/jobs` (BullMQ).
4
+
5
+ ## Interval job (module)
6
+
7
+ ```typescript
8
+ import { defineModule } from '@classytic/arc/factory';
9
+
10
+ defineModule({
11
+ name: 'billing',
12
+ scheduledJobs: [{
13
+ name: 'billing.sweep',
14
+ every: 60_000, // ms between the END of one run and the next tick
15
+ jitterMs: 10_000, // spread first tick (ignored with runOnStart)
16
+ handler: async (fastify) => { await sweep(); },
17
+ }],
18
+ });
19
+
20
+ createApp({ arcPlugins: { schedules: { lock, singleReplica: false } }, modules: [billing] });
21
+ ```
22
+
23
+ | Rule | Detail |
24
+ |---|---|
25
+ | No overlap | next tick is scheduled after the current run settles |
26
+ | Fail-open | a throwing handler is logged and counted, the loop continues |
27
+ | Multi-replica | pass `lock` (any `LockAdapter` from `@classytic/repo-core/lock`; `createMemoryLockAdapter()` for tests): winner runs, others skip. Lease is held ~`every` |
28
+ | Distributed runtime | a schedule with neither `lock` nor `singleReplica: true` fails boot |
29
+ | Kill switch | `arcPlugins.schedules: { enabled: false }` arms nothing |
30
+ | Stats | `fastify.getScheduleStats()`: `runs`, `failures`, `skippedByLock`, `lastRunAt`, `lastError` |
31
+ | Roles | `createApp({ role })`: `api`/`worker` arm nothing, `relay` arms `kind: 'relay'`, `scheduler` arms all |
32
+
33
+ Interval only: arc has no cron parser. Wall-clock needs use `daily`.
34
+
35
+ ## Daily: once per local calendar day
36
+
37
+ `every` becomes the poll interval (use 1 to 15 minutes). The job runs once per civil day at or after `hour:minute` in an IANA `zone`.
38
+
39
+ ```typescript
40
+ import { createMemoryDailyLedger, type DailyLedger } from '@classytic/arc/plugins';
41
+
42
+ scheduledJobs: [{
43
+ name: 'competency.daily-sweep',
44
+ every: 15 * 60_000,
45
+ daily: {
46
+ hour: 2, minute: 0, zone: 'Asia/Dhaka',
47
+ ledger, // host DailyLedger
48
+ catchUpWindowMs: 6 * 3_600_000, // optional: skip a run later than this after hh:mm
49
+ staleAfterMs: 30 * 60_000, // optional: re-grant an uncompleted claim (crash mid-run)
50
+ clock: { now: () => new Date() }, // optional: injectable for tests
51
+ },
52
+ handler: async (fastify, ctx) => { await sweep(ctx?.day); }, // ctx.day = 'YYYY-MM-DD'
53
+ }]
54
+ ```
55
+
56
+ Semantics:
57
+ - The day is `civilDateOf(now, zone)` (`@classytic/primitives/timezone`), never UTC and never the server zone. DST-exact: a time inside a spring-forward gap fires when the clock jumps past it; a repeated time fires on its first occurrence; the ledger blocks the second.
58
+ - Restart safe: a new process reads the ledger and sees the day claimed. Multi-replica safe: the schedule lease picks one poller, the ledger claim is the idempotency guard.
59
+ - A throwing handler releases the claim; the next poll retries. A crash leaves the claim (at-most-once) unless `staleAfterMs` is set.
60
+ - `getScheduleStats()` adds `lastDay` and `skippedByGate` for daily schedules; `runs` counts executions, not declined polls.
61
+ - Boot validates `hour` 0-23, `minute` 0-59 and the zone; the error names the schedule.
62
+
63
+ ## The ledger contract (host implements)
64
+
65
+ ```typescript
66
+ interface DailyLedger {
67
+ claimDay(key: string, civilDate: string, info: { now: Date; staleAfterMs?: number }): Promise<boolean>; // atomic, one winner
68
+ completeDay?(key: string, civilDate: string, result?: Record<string, unknown>): Promise<void>;
69
+ releaseDay(key: string, civilDate: string): Promise<void>;
70
+ }
71
+ ```
72
+
73
+ `key` is the schedule name. Back it with a unique `(key, civilDate)` row (insert; duplicate-key means lost). `claimDay` may re-grant a claim only when it was never completed and is older than `info.staleAfterMs`. `createMemoryDailyLedger()` is the test implementation (`.claims()` for assertions).
74
+
75
+ `createDailyGate({ key, ledger, zone, hour, minute?, catchUpWindowMs?, staleAfterMs?, clock? })` is the same gate for a host that ticks elsewhere: `await gate.run(async (day) => ...)` returns `{ ran: true, day, result }` or `{ ran: false, reason: 'too-early' | 'outside-window' | 'already-claimed' }`.
76
+
77
+ ## Test it
78
+
79
+ Inject a fixed `clock`, a memory ledger and `every: 20`; assert the handler ran once across two apps sharing the ledger and lock. Use `waitFor` from `@classytic/arc/testing`, never a fixed sleep.
@@ -1,247 +1,100 @@
1
- # SCIM 2.0 — IdP Provisioning
1
+ # SCIM 2.0 provisioning
2
2
 
3
- Arc ships a SCIM 2.0 plugin (`@classytic/arc/scim`) that auto-mounts `/scim/v2/Users` + `/scim/v2/Groups` REST endpoints and translates SCIM wire shapes onto the canonical **repository contract** (`@classytic/repo-core/adapter`). Arc does NOT introduce a SCIM-specific repository subset, controller pipeline, or storage tier — it composes with what kits already expose.
4
-
5
- ## Honest architecture (what SCIM actually is)
6
-
7
- **SCIM is a thin REST layer over the kit's `RepositoryLike`.** Whatever plugins you wire at the kit/repo layer (audit, multi-tenant, field-policy, etc.) fire for SCIM exactly the way they fire for arc REST, because **both surfaces call the same repository methods**.
8
-
9
- ```
10
- SCIM request → arc/scim plugin → resource.adapter.repository.<method> → kit hooks fire
11
- ```
12
-
13
- This is NOT what some earlier docs implied. SCIM does not run arc's HTTP controller pipeline (`auth → permissions → preHandlers → controller → hooks → audit`). SCIM authentication is bearer/verify only at the REST edge; everything else (row-level perms, audit trail, hooks) is composed at the kit layer where it already lives.
14
-
15
- | Layer | Where it composes | Fires for SCIM? |
16
- |---|---|---|
17
- | Bearer / OIDC verify | `scimPlugin({ bearer, verify })` | ✓ at the SCIM edge |
18
- | Audit trail | `repo.use(auditTrailPlugin())` (mongokit) — kit-specific identifier | ✓ via repo hooks |
19
- | Multi-tenant scope | `repo.use(multiTenantPlugin)` | ✓ via repo hooks |
20
- | Field redaction (read) | mongokit's `fieldFilterPlugin` | ✓ on `getAll` / `getById` |
21
- | Resource hooks | `defineResource({ hooks: { ... } })` | ✗ — those are HTTP-controller hooks; not on the repo path |
22
- | Per-action permissions | `defineResource({ permissions: { ... } })` | ✗ — same reason; gate at the edge via `verify` |
23
-
24
- If you want resource hooks to fire for SCIM writes too, install them as **kit plugins** (`repo.on('before:create', fn)`) rather than `defineResource({ hooks: ... })`. The docs for your kit (mongokit / sqlitekit) cover the hook surface.
25
-
26
- ## CRUD → repository contract mapping
27
-
28
- | SCIM method | Repository call | Notes |
29
- |---|---|---|
30
- | `GET /Users` | `repo.getAll({ filters, page, limit, sort })` | Filter parser maps SCIM filter language → query DSL |
31
- | `GET /Users/:id` | `repo.getById(id)` | |
32
- | `POST /Users` | `repo.create(data)` | Inbound SCIM body maps onto resource shape via `mapping.attributes` |
33
- | `PUT /Users/:id` | `repo.bulkWrite([{ replaceOne: { filter, replacement } }])` | **Kit-conditional** — see "Feature gating" below |
34
- | `PATCH /Users/:id` | `repo.findOneAndUpdate({ id }, ops)` | Operators flow through unchanged (`$set`, `$unset`, `$push`, `$pull`) |
35
- | `DELETE /Users/:id` | `repo.delete(id)` | |
36
-
37
- ## Feature gating (honest about what each kit supports)
38
-
39
- **SCIM PATCH** translates the RFC 7644 PatchOp body into canonical Mongo-style operators and forwards them to `findOneAndUpdate`. The kit decides what's portable:
40
-
41
- | Kit | `$set` / scalar overwrite | `$unset` | `$push` / `$pull` (array mutations) |
42
- |---|---|---|---|
43
- | **mongokit** | ✓ | ✓ | ✓ — applied natively |
44
- | **sqlitekit** | ✓ (compiled to flat column writes) | ✓ | ✗ — JSON columns have no array-op semantics; sqlitekit throws cleanly, SCIM 400s with `scimType: invalidValue` |
45
- | **prismakit** | ✓ | ✓ | depends on column type |
46
- | **Custom kit (only `MinimalRepo`)** | ✓ via `update(id, $set)` fallback | ✗ — no `findOneAndUpdate` exposed → SCIM 400 | ✗ → SCIM 400 |
47
-
48
- **SCIM PUT** requires `repo.bulkWrite([{ replaceOne }])` OR a top-level `repo.replace(id, doc)`. Kits that expose neither return **HTTP 501** with a clear message — no silent merge into `update(id, partial)` (which would leave omitted fields surviving and violate SCIM PUT semantics).
49
-
50
- | Kit | `PUT` (full replace) |
51
- |---|---|
52
- | **mongokit** | ✓ via `bulkWrite([{ replaceOne }])` |
53
- | **sqlitekit** | ✓ via `bulkWrite([{ replaceOne }])` AND `replace(id, doc)` (sqlitekit ≥0.4.0). Routes through `replaceById` (UPDATE with explicit NULLs for omitted columns) so SCIM PUT semantics are honored — omitted fields don't survive. |
54
- | **prismakit** | varies |
55
- | **Custom kit (only `MinimalRepo`)** | ✗ — 501 |
56
-
57
- If your IdP requires PUT semantics and your kit doesn't expose `bulkWrite`, two options: (1) ask the kit team to add it, (2) configure your IdP to use PATCH instead (Okta / Azure AD both support PATCH-only flows).
58
-
59
- ## Quick start
3
+ `@classytic/arc/scim` mounts `/scim/v2/Users` and `/scim/v2/Groups` over the repository contract (`@classytic/repo-core/adapter`). It is a thin REST layer over `resource.adapter.repository`, NOT arc's HTTP controller pipeline.
60
4
 
61
5
  ```typescript
62
- import { scimPlugin } from "@classytic/arc/scim";
6
+ import { scimPlugin } from '@classytic/arc/scim';
63
7
 
64
8
  await app.register(scimPlugin, {
65
- users: { resource: userResource }, // your existing arc resource
66
- groups: { resource: orgResource }, // optional
67
- bearer: process.env.SCIM_TOKEN, // OR: verify: async (req) => …
9
+ users: { resource: userResource }, // existing arc resource
10
+ groups: { resource: orgResource }, // optional
11
+ bearer: process.env.SCIM_TOKEN, // XOR verify
68
12
  });
69
13
  ```
70
14
 
71
- That's it. Endpoints mounted: `GET/POST/PUT/PATCH/DELETE /scim/v2/Users[/:id]`, same for `Groups`, plus `ServiceProviderConfig` / `ResourceTypes` / `Schemas` discovery.
15
+ Mounted: `GET/POST/PUT/PATCH/DELETE /scim/v2/Users[/:id]`, same for `Groups`, plus `ServiceProviderConfig`, `ResourceTypes`, `Schemas`.
72
16
 
73
- ## Default mapping (Better Auth aligned)
17
+ ## Options
74
18
 
75
- If you don't override `mapping`, SCIM assumes the BA `user` / `organization` schema:
76
-
77
- | SCIM attribute | Backend field |
19
+ | Option | Purpose |
78
20
  |---|---|
79
- | `id` | `id` |
80
- | `userName` | `email` |
81
- | `name.formatted` / `displayName` | `name` |
82
- | `emails[].value` | `email` (primary) |
83
- | `active` | `isActive` |
84
- | `externalId` | `externalId` |
85
- | `meta.created` | `createdAt` |
86
- | `meta.lastModified` | `updatedAt` |
87
-
88
- For non-BA schemas, override per-attribute:
21
+ | `users`, `groups` | `{ resource, mapping? }`; `groups` optional |
22
+ | `bearer` | Static token. Exactly one of `bearer` / `verify`; the plugin throws at boot otherwise |
23
+ | `verify(request)` | `true` accepts, `false` or throw rejects (short-lived JWTs, multi-IdP) |
24
+ | `prefix` | Default `/scim/v2` |
25
+ | `maxResults` | Max page size for `count` (default 200) |
26
+ | `observe(event)` | Per-request `ScimObservedEvent { resourceType, op, status, durationMs, scimType?, path }`; default logs `request.log.info({ scim }, 'scim.request')` |
89
27
 
90
28
  ```typescript
91
- import { scimPlugin, DEFAULT_USER_MAPPING } from "@classytic/arc/scim";
92
-
93
- await app.register(scimPlugin, {
94
- users: {
95
- resource: userResource,
96
- mapping: {
97
- attributes: {
98
- ...DEFAULT_USER_MAPPING.attributes,
99
- userName: "username",
100
- "name.familyName": "lastName",
101
- },
102
- },
103
- },
104
- bearer: process.env.SCIM_TOKEN,
105
- });
106
- ```
107
-
108
- ## Filter language (RFC 7644 §3.4.2.2)
109
-
110
- Operators supported: `eq`, `ne`, `co` (contains), `sw` (starts with), `ew` (ends with), `gt`/`ge`/`lt`/`le`, `pr` (present), `and` / `or` / `not`, grouped with `( )`.
111
-
112
- Real production filters that work out of the box:
113
-
114
- ```
115
- filter=userName eq "alice@acme.com" and active eq true
116
- filter=externalId eq "ad:f3e9-..."
117
- filter=meta.lastModified gt "2025-01-01T00:00:00Z"
118
- ```
119
-
120
- ## Auth — bearer or verify
121
-
122
- ```typescript
123
- bearer: process.env.SCIM_TOKEN, // simplest
124
- // OR
125
29
  verify: async (request) => {
126
30
  const auth = request.headers.authorization;
127
- if (!auth?.startsWith("Bearer ")) return false;
31
+ if (!auth?.startsWith('Bearer ')) return false;
128
32
  const claims = await verifyJwt(auth.slice(7));
129
- return claims.scope?.includes("scim:write") ?? false;
33
+ return claims.scope?.includes('scim:write') ?? false;
130
34
  },
131
35
  ```
132
36
 
133
- Pass exactly one — `bearer` XOR `verify`. The plugin throws at boot if both / neither are configured.
37
+ ## What fires for SCIM
134
38
 
135
- ## Observability
39
+ Only what is composed at the kit/repository layer (audit-trail, multi-tenant, field-filter plugins; `repo.on('before:create', fn)`). Resource-level `hooks`, `permissions` and `audit: true` do NOT fire. Gate at the edge with `bearer` / `verify`.
136
40
 
137
- Every request emits one `ScimObservedEvent`:
41
+ ## Method mapping
138
42
 
139
- ```typescript
140
- {
141
- resourceType: "Users" | "Groups" | "discovery",
142
- op: "list" | "get" | "create" | "replace" | "patch" | "delete" | "discovery.<endpoint>",
143
- status: number,
144
- durationMs: number,
145
- scimType?: string, // SCIM error type when failed
146
- path: string,
147
- }
148
- ```
149
-
150
- Wire to your metrics / logging stack via `observe`:
151
-
152
- ```typescript
153
- await app.register(scimPlugin, {
154
- users: { resource: userResource },
155
- bearer: process.env.SCIM_TOKEN,
156
- observe: (event) => {
157
- metrics.histogram("scim.duration_ms", event.durationMs, {
158
- op: event.op,
159
- status: String(event.status),
160
- });
161
- },
162
- });
163
- ```
43
+ | SCIM | Repository call |
44
+ |---|---|
45
+ | `GET /Users` | `getAll({ filters, page, limit, sort })` (filter parser output) |
46
+ | `GET /Users/:id` | `getById(id)` |
47
+ | `POST /Users` | `create(data)` through `mapping.attributes` |
48
+ | `PUT /Users/:id` | `bulkWrite([{ replaceOne }])`; repository without `bulkWrite` => HTTP 501 (no partial-merge fallback) |
49
+ | `PATCH /Users/:id` | `findOneAndUpdate({ id }, ops)` with `$set`, `$unset`, `$push`, `$pull` |
50
+ | `DELETE /Users/:id` | `delete(id)` |
164
51
 
165
- Default (when `observe` is omitted): `request.log.info({ scim: event }, "scim.request")` — Pino-friendly structured log line.
52
+ Kit support:
166
53
 
167
- ## Discovery endpoints
54
+ | Kit | `$set` / `$unset` | `$push` / `$pull` | PUT |
55
+ |---|---|---|---|
56
+ | mongokit | yes | yes | yes |
57
+ | sqlitekit | yes | refused => 400 `scimType: invalidValue` | yes (omitted columns set NULL) |
58
+ | minimal repo (no `findOneAndUpdate`) | `$set` via `update` | 400 | 501 |
168
59
 
169
- Auto-mounted; every IdP probes them during connector setup:
60
+ If an IdP needs PUT and the kit lacks `bulkWrite`, switch the IdP to PATCH-only mode (Okta and Azure AD support it).
170
61
 
171
- - `/scim/v2/ServiceProviderConfig` — capability advertisement (`patch.supported: true`, `bulk.supported: false`, `oauthbearertoken` auth)
172
- - `/scim/v2/ResourceTypes` — `User` (always) + `Group` (when `groups` binding present)
173
- - `/scim/v2/Schemas` — id + name stub (most IdPs treat as a sanity check)
62
+ ## Mapping
174
63
 
175
- ## Error envelope (RFC 7644 §3.12)
64
+ Default user mapping (Better Auth shaped): `id`=>`id`, `userName`=>`email`, `name.formatted` and `displayName`=>`name`, `emails.value`=>`email`, `active`=>`isActive`, `externalId`=>`externalId`, `meta.created`=>`createdAt`, `meta.lastModified`=>`updatedAt`. Groups: `id`, `displayName`=>`name`, `externalId`, `meta.*`.
176
65
 
177
- Every error response uses the canonical SCIM shape:
66
+ ```typescript
67
+ import { scimPlugin, DEFAULT_USER_MAPPING } from '@classytic/arc/scim';
178
68
 
179
- ```json
180
- {
181
- "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
182
- "status": "400",
183
- "scimType": "invalidFilter",
184
- "detail": "Attribute 'xyz' is not filterable"
185
- }
69
+ users: {
70
+ resource: userResource,
71
+ mapping: { attributes: { ...DEFAULT_USER_MAPPING.attributes, userName: 'username', 'name.familyName': 'lastName' } },
72
+ },
186
73
  ```
187
74
 
188
- Content-Type: `application/scim+json` on every response. Parser auto-registered, idempotent on redeclare.
189
-
190
- ## What's NOT supported (yet)
191
-
192
- - **Bulk operations** (`/Bulk`) — most IdPs don't use them; discovery advertises `bulk.supported: false`
193
- - **EnterpriseUser extension** (`employeeNumber`, `manager`, `costCenter`) — pass-through via `mapping.attributes` works today; first-class extension support lands when a paying customer asks
194
- - **Schema introspection beyond IDs** — `/Schemas` returns id+name only
195
-
196
- ## Production checklist
197
-
198
- - [ ] Mount on the same host as your REST surface (no separate SCIM service)
199
- - [ ] Rotate `SCIM_TOKEN` quarterly; use `verify` callback with short-lived JWTs for multi-IdP setups
200
- - [ ] Wire your kit's audit plugin at the **kit** layer (mongokit: `repo.use(auditTrailPlugin())` from `@classytic/mongokit/plugins`), not via `defineResource({ audit: true })` — only the kit-layer plugin fires for SCIM writes
201
- - [ ] Test the Okta / Azure AD connector against `playground/enterprise-auth/` before production cutover
202
- - [ ] Confirm your kit exposes `findOneAndUpdate` (for PATCH operators) and `bulkWrite` (for PUT) — see "Feature gating" above; otherwise pick the IdP flows your kit supports
75
+ ## Filters (RFC 7644)
203
76
 
204
- ## sqlitekit gap message — RESOLVED in sqlitekit ≥0.4.0
77
+ Operators: `eq ne co sw ew gt ge lt le pr`, `and or not`, parentheses.
205
78
 
206
- sqlitekit ≥0.4.0 ships both asks. The original message is preserved below for historical context.
207
-
208
- **Status of each ask:**
209
-
210
- 1. **`bulkWrite([{ replaceOne }])` with full-replace semantics — ✓ shipped.** Routes through `actions/update.replaceById` which UPDATE-with-explicit-NULLs every column omitted from the replacement. Pinned by `tests/integration/replace-and-array-ops.test.ts`. The earlier behavior (silent partial-update) is fixed; SCIM PUT clients now see the contract honored.
211
- 2. **JSON-column array policy — ✓ shipped (option a, refuse cleanly).** `findOneAndUpdate` and `updateMany` throw a clear actionable error on `$push` / `$pull` / `$addToSet` / `$pop` / `$pullAll`, mirroring the refusal `claim()` already shipped. Arc's SCIM plugin translates the throw into `400 Bad Request` with `scimType: invalidValue`.
212
- 3. **Top-level `replace(id, doc)` — ✓ shipped.** Available alongside `bulkWrite([{ replaceOne }])`; arc can feature-detect either.
213
-
214
- **Bonus fix:** `findOneAndUpdate` and `updateMany` now also accept raw mongo `$set` / `$unset` / `$inc` / `$setOnInsert` operator records (compiled to flat column writes via the existing `UpdateSpec` path). Previously these silently produced `near "where": syntax error` from Drizzle. SCIM PATCH operator forwarding now works on sqlitekit without an arc-side translation step.
79
+ ```
80
+ filter=userName eq "alice@acme.com" and active eq true
81
+ filter=meta.lastModified gt "2025-01-01T00:00:00Z"
82
+ ```
215
83
 
216
- ---
84
+ Pagination: `startIndex` (1-based) and `count` (capped by `maxResults`).
217
85
 
218
- ### Original gap message (historical)
86
+ ## Wire format
219
87
 
220
- If your sqlitekit-backed app needs SCIM PUT (full replace) or PATCH array ops (`$push`/`$pull`), the underlying repository needs to expose two ops it currently doesn't:
88
+ - Content-Type `application/scim+json` (parser auto-registered).
89
+ - Errors: `{ schemas: ['urn:ietf:params:scim:api:messages:2.0:Error'], status: '400', scimType: 'invalidFilter', detail }`.
90
+ - Discovery advertises `patch` and `filter` supported, `bulk`, `changePassword`, `etag` not supported. `/Schemas` returns id and name only.
221
91
 
222
- > **From:** arc 2.13 SCIM consumer
223
- >
224
- > **Subject:** `bulkWrite` + JSON-column array operators for SCIM 2.0 PUT / PATCH
225
- >
226
- > **Context.** Arc 2.13 ships a SCIM 2.0 plugin that translates IdP requests onto the canonical `@classytic/repo-core/adapter` `RepositoryLike` contract. PATCH uses `findOneAndUpdate(filter, ops)` so operators (`$set` / `$unset` / `$push` / `$pull`) flow through unchanged. PUT uses `bulkWrite([{ replaceOne }])` because full-document replace isn't in `MinimalRepo`. mongokit covers both today; sqlitekit doesn't.
227
- >
228
- > **Asks (in priority order):**
229
- >
230
- > 1. **`bulkWrite([...])` with `replaceOne` support.** SCIM PUT (full replace) currently 501s on sqlitekit. The contract: `replaceOne: { filter, replacement }` should DELETE then INSERT (or UPDATE all columns) atomically. Other op types (`updateOne`, `deleteOne`) can stub or fan out to existing methods. Returning `{ matchedCount, modifiedCount }` is enough.
231
- >
232
- > 2. **Documented JSON-column array policy for `findOneAndUpdate`.** sqlitekit currently rejects `$push` / `$pull` on `text` (JSON) columns. Three reasonable options for the kit team to pick:
233
- > - **(a)** Refuse cleanly (current behaviour) — sqlitekit throws; arc 400s with `scimType: invalidValue`. Honest. Document it.
234
- > - **(b)** Read-modify-write helper (non-atomic). Reads the JSON, mutates, writes back. Document the non-atomicity for hosts to evaluate.
235
- > - **(c)** SQLite `json_insert` / `json_remove` functions. Atomic via SQL; sqlite-version dependent.
236
- >
237
- > arc consumes whatever sqlitekit decides; the SCIM plugin doesn't depend on (b) or (c) being shipped.
238
- >
239
- > 3. **Optional: a `replace(id, doc)` top-level convenience.** If the team prefers not to expose `bulkWrite`, a kit-specific `replace(id, doc)` method on `SqliteRepository` would also unlock PUT — arc could feature-detect either path.
240
- >
241
- > **No urgency** — SCIM PUT can be substituted with PATCH for most IdPs (Okta / Azure AD support PATCH-only reconciliation modes). This is a "ship when natural" ask, not a blocker for any current consumer.
92
+ Not supported: `/Bulk`, first-class EnterpriseUser extension (pass attributes through `mapping.attributes`).
242
93
 
243
- ## See also
94
+ ## Checklist
244
95
 
245
- - [enterprise-auth.md](enterprise-auth.md) — feature matrix
246
- - [agent-auth.md](agent-auth.md) — DPoP + capability mandates
247
- - [`playground/enterprise-auth/`](../../../playground/enterprise-auth/) — runnable smoke
96
+ - Serve on the same host as the REST surface.
97
+ - Rotate `SCIM_TOKEN`; prefer `verify` with short-lived JWTs for several IdPs.
98
+ - Register the audit plugin on the repository (mongokit: `repo.use(auditTrailPlugin())`), not `defineResource({ audit })`.
99
+ - Confirm the kit exposes `findOneAndUpdate` (PATCH) and `bulkWrite` (PUT).
100
+ - Test the IdP connector against `playground/enterprise-auth/`.
@@ -0,0 +1,82 @@
1
+ # Installing request scope from custom auth
2
+
3
+ Pick where scope gets set. Arc reads `request.scope` and does not care how it got there.
4
+
5
+ | Your auth source | Where to set scope |
6
+ |---|---|
7
+ | Better Auth session | Nothing: the adapter with `orgContext: true` does it |
8
+ | JWT or authenticator, user has `organizationId` | Return the user from `authenticate()`: arc derives `member` |
9
+ | JWT with org chosen by header | `resolveOrgFromHeader` preHandler (auth-strategies.md) |
10
+ | API key with DB lookup | `allow({ scope })` from a permission check |
11
+ | Gateway-injected headers | `allow({ scope })` or an `onRequest` hook |
12
+ | Service account OAuth token | `allow({ scope })` with `kind: 'service'`, or `authenticate` |
13
+ | Platform admin | `createApp({ elevation })` => `kind: 'elevated'` |
14
+
15
+ ## 1. Better Auth
16
+
17
+ ```typescript
18
+ await createApp({ auth: { type: 'betterAuth', betterAuth: createBetterAuthAdapter({ auth, orgContext: true }) } });
19
+ ```
20
+
21
+ ## 2. Authenticator returning a user
22
+
23
+ ```typescript
24
+ await createApp({
25
+ auth: {
26
+ type: 'authenticator',
27
+ authenticate: async (request, reply) => {
28
+ const user = await verifyJwt(request.headers.authorization);
29
+ if (!user) return reply.code(401).send({ code: 'arc.unauthorized', message: 'Unauthorized', status: 401 });
30
+ request.user = user; // `organizationId` on the user => member scope
31
+ },
32
+ },
33
+ });
34
+ ```
35
+
36
+ ## 3. Scope from a permission check (API keys, service accounts)
37
+
38
+ ```typescript
39
+ import { allow, deny, type PermissionCheck } from '@classytic/arc/permissions';
40
+
41
+ export function requireApiKey(): PermissionCheck {
42
+ return async ({ request }) => {
43
+ const apiKey = request.headers['x-api-key'];
44
+ if (typeof apiKey !== 'string') return deny('Missing API key');
45
+ const client = await clientRepo.getOne({ apiKey });
46
+ if (!client) return deny('Invalid API key');
47
+
48
+ return allow({
49
+ scope: {
50
+ kind: 'service',
51
+ clientId: String(client._id),
52
+ organizationId: String(client.companyId),
53
+ scopes: client.allowedScopes,
54
+ },
55
+ ...(client.projectId ? { policy: { projectId: client.projectId } } : {}), // extra row narrowing
56
+ });
57
+ };
58
+ }
59
+
60
+ defineResource({
61
+ name: 'job',
62
+ adapter,
63
+ tenantField: 'companyId',
64
+ permissions: { list: requireApiKey(), get: requireApiKey(), create: requireApiKey() },
65
+ });
66
+ ```
67
+
68
+ No auth plugin, scope hook or tenant middleware needed; cross-tenant get/list/update/delete isolation is covered by `tests/e2e/permission-scope-wire.test.ts`.
69
+
70
+ Override safety: `allow({ scope })` installs scope only while the current scope is `public`. An already-authenticated request is never downgraded or overwritten.
71
+
72
+ ## 4. Fastify hook
73
+
74
+ For mTLS or RPC callers, set `request.scope` in an `onRequest` hook.
75
+
76
+ ## Mongokit plugin order
77
+
78
+ Mongokit validates plugin order on the repository you pass to `defineResource`: multi-tenant must precede cache, soft-delete must precede batch-operations. Set `pluginOrderChecks: 'throw'` in the `Repository` options (fourth constructor argument) in production. Arc does not surface this option.
79
+
80
+ ```typescript
81
+ new Repository(Model, [multiTenantPlugin({ tenantField: 'organizationId' }), softDeletePlugin(), batchOperationsPlugin()], {}, { pluginOrderChecks: 'throw' });
82
+ ```