@classytic/arc 2.47.0 → 2.49.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 (216) hide show
  1. package/dist/{EventTransport-BHKy4_Bi.mjs → EventTransport-DbHZK230.mjs} +2 -2
  2. package/dist/{HookSystem-CAIDVoKC.mjs → HookSystem-DMoeJ6Do.mjs} +2 -2
  3. package/dist/{QueryCache-DdvrGG8Q.d.mts → QueryCache-BE47tmlO.d.mts} +36 -1
  4. package/dist/{ResourceRegistry-23Ml6FNe.mjs → ResourceRegistry-CP-iTcKy.mjs} +2 -2
  5. package/dist/{acquire-DoFX06fm.mjs → acquire-CB0va87C.mjs} +1 -1
  6. package/dist/audit/index.d.mts +1 -1
  7. package/dist/audit/index.mjs +4 -4
  8. package/dist/auth/audit.mjs +1 -1
  9. package/dist/auth/index.d.mts +2 -2
  10. package/dist/auth/index.mjs +53 -15
  11. package/dist/auth/redis-session.mjs +1 -1
  12. package/dist/{authorizationDecision-DYiubkYw.mjs → authorizationDecision-DHO94aV2.mjs} +4 -4
  13. package/dist/{boundedMap-CtdzpJ3X.mjs → boundedMap-C51EUUOm.mjs} +1 -1
  14. package/dist/{buildHandler-CARdmPNo.mjs → buildHandler-9DuwEKvr.mjs} +23 -16
  15. package/dist/cache/index.d.mts +2 -2
  16. package/dist/cache/index.mjs +4 -4
  17. package/dist/{caching-QRiryDLs.mjs → caching-COTX3sDa.mjs} +3 -6
  18. package/dist/{claimed-BLecr1j3.mjs → claimed-C7T1nHlo.mjs} +1 -1
  19. package/dist/cleanup/index.d.mts +2 -2
  20. package/dist/cleanup/index.mjs +4 -4
  21. package/dist/cli/commands/describe.d.mts +1 -1
  22. package/dist/cli/commands/describe.mjs +3 -3
  23. package/dist/cli/commands/docs.mjs +3 -3
  24. package/dist/cli/commands/doctor.mjs +1 -1
  25. package/dist/cli/commands/generate.mjs +2 -2
  26. package/dist/cli/commands/init.mjs +2 -2
  27. package/dist/cli/commands/introspect.mjs +2 -2
  28. package/dist/cli/index.mjs +3 -3
  29. package/dist/{constants-Cx7BcnHT.mjs → constants-DOnfMd7i.mjs} +1 -1
  30. package/dist/context/index.mjs +5 -5
  31. package/dist/core/index.d.mts +3 -3
  32. package/dist/core/index.mjs +7 -7
  33. package/dist/{core-0WyMuo0f.mjs → core-BoEdFDDw.mjs} +3 -3
  34. package/dist/{createActionRouter-mLAGbpDV.mjs → createActionRouter-CpTn15dm.mjs} +54 -18
  35. package/dist/{createAggregationRouter-BEAjn3dA.mjs → createAggregationRouter-CD_Hydp0.mjs} +13 -11
  36. package/dist/{createApp-QDP4vYWH.mjs → createApp-Be6XTGD9.mjs} +332 -40
  37. package/dist/{createMcpServer-DzXHX0SO.d.mts → createMcpServer-CS2KOVP6.d.mts} +9 -10
  38. package/dist/{defineAggregation-CFNfvz-C.mjs → defineAggregation-BI5pRb8c.mjs} +1 -1
  39. package/dist/{defineResource-BROJmhzJ.mjs → defineResource-BAzNu5Um.mjs} +8 -8
  40. package/dist/discovery/index.mjs +1 -1
  41. package/dist/docs/index.d.mts +1 -1
  42. package/dist/docs/index.mjs +3 -3
  43. package/dist/{elevation-DrXeEWWk.mjs → elevation-DupGuM41.mjs} +6 -9
  44. package/dist/encryption/index.mjs +3 -3
  45. package/dist/{errorHandler-BiBXtxj4.mjs → errorHandler-DA03vRqp.mjs} +4 -7
  46. package/dist/{errors-DnrUChAy.mjs → errors-BpYV859Y.mjs} +1 -1
  47. package/dist/{eventPlugin-BhKLUe7H.mjs → eventPlugin-D7LYtYzL.mjs} +9 -13
  48. package/dist/{eventTypes-CCIRGakw.mjs → eventTypes-BqA-N-Uz.mjs} +2 -2
  49. package/dist/events/index.d.mts +18 -5
  50. package/dist/events/index.mjs +8 -8
  51. package/dist/events/transports/redis-stream-entry.mjs +4 -4
  52. package/dist/events/transports/redis.d.mts +35 -0
  53. package/dist/events/transports/redis.mjs +87 -11
  54. package/dist/factory/index.d.mts +4 -4
  55. package/dist/factory/index.mjs +6 -6
  56. package/dist/{fastify-augmentation-bzkWPt1f.d.mts → fastify-augmentation-baQc3MaO.d.mts} +2 -2
  57. package/dist/fieldTypes-EFWxCkZ5.mjs +80 -0
  58. package/dist/{fields-CYdpcV73.mjs → fields-CT1Erg7o.mjs} +1 -1
  59. package/dist/{filter-merge-6kasezRH.mjs → filter-merge-B1eJ1pMx.mjs} +1 -1
  60. package/dist/{generate-DUkcbc4r.mjs → generate-Cr0ULavs.mjs} +2 -2
  61. package/dist/{headers-KxhrKevA.mjs → headers-D4bncIOf.mjs} +2 -2
  62. package/dist/{health-jkYNdobJ.mjs → health-BoFxrkJE.mjs} +1 -1
  63. package/dist/{health-CRJg3IIq.mjs → health-DN_pUVMX.mjs} +1 -1
  64. package/dist/hooks/index.d.mts +1 -1
  65. package/dist/hooks/index.mjs +2 -2
  66. package/dist/http-cache/index.d.mts +2 -2
  67. package/dist/http-cache/index.mjs +4 -4
  68. package/dist/http-cache/purgers/cloudflare.mjs +2 -2
  69. package/dist/http-cache/purgers/fastly.mjs +2 -2
  70. package/dist/http-cache/testing/index.mjs +1 -1
  71. package/dist/idempotency/index.d.mts +1 -1
  72. package/dist/idempotency/index.mjs +10 -8
  73. package/dist/idempotency/redis.mjs +2 -2
  74. package/dist/{index-B5i9-vuP.d.mts → index-CMNpMBtW.d.mts} +1 -1
  75. package/dist/{index-BxZS-8So.d.mts → index-DKM2p5w5.d.mts} +48 -23
  76. package/dist/{index-Cy2-QffW.d.mts → index-DLCcLUQT.d.mts} +69 -6
  77. package/dist/{index-DFCCQ9AE.d.mts → index-DexdFs1a.d.mts} +1 -1
  78. package/dist/{index-D1X_C_qz.d.mts → index-Dhrks-hM.d.mts} +60 -10
  79. package/dist/index.d.mts +4 -4
  80. package/dist/index.mjs +11 -11
  81. package/dist/{init-CACwpktI.mjs → init-C4a24wD2.mjs} +1 -1
  82. package/dist/integrations/event-gateway.mjs +2 -2
  83. package/dist/integrations/index.d.mts +2 -2
  84. package/dist/integrations/index.mjs +1 -1
  85. package/dist/integrations/jobs/index.mjs +3 -3
  86. package/dist/integrations/mcp/index.d.mts +6 -38
  87. package/dist/integrations/mcp/index.mjs +2 -2
  88. package/dist/integrations/mcp/testing.d.mts +11 -15
  89. package/dist/integrations/mcp/testing.mjs +22 -42
  90. package/dist/integrations/streamline.mjs +3 -3
  91. package/dist/integrations/webhooks.d.mts +1 -1
  92. package/dist/integrations/webhooks.mjs +4 -4
  93. package/dist/integrations/websocket-pushref-redis.mjs +1 -1
  94. package/dist/integrations/websocket-redis.mjs +1 -1
  95. package/dist/integrations/websocket.mjs +2 -2
  96. package/dist/{jsonBody-CzDBkCme.mjs → jsonBody-DoTt5BS6.mjs} +2 -2
  97. package/dist/{keys-Cbwf6r1B.mjs → keys--l9n7aOC.mjs} +1 -1
  98. package/dist/{loadResources-Kr6vuljv.mjs → loadResources-rygByIQA.mjs} +3 -3
  99. package/dist/{loadResourcesFromEntry-D2e0qoDR.mjs → loadResourcesFromEntry-ItNBIQ5w.mjs} +2 -2
  100. package/dist/logger/index.mjs +2 -2
  101. package/dist/{logger-C110X5Yz.mjs → logger-UbknHqHy.mjs} +1 -1
  102. package/dist/{mcpPlugin-4lIPr9OJ.mjs → mcpPlugin-CTkk4RP8.mjs} +218 -378
  103. package/dist/{memory-D9qkhXiB.mjs → memory-C47xVsjX.mjs} +3 -3
  104. package/dist/{metrics-B-qrrWfI.mjs → metrics-TJyAb1Xk.mjs} +4 -7
  105. package/dist/middleware/index.d.mts +1 -1
  106. package/dist/middleware/index.mjs +3 -3
  107. package/dist/migrations/index.mjs +2 -2
  108. package/dist/{module-BD8xHgrz.mjs → module-CWiqsXnh.mjs} +1 -1
  109. package/dist/{multiTenant-KZj8j1uJ.d.mts → multiTenant-QtDzxx_K.d.mts} +1 -1
  110. package/dist/{multipartBody-qU7KCn1l.mjs → multipartBody-BdG1qbn1.mjs} +1 -1
  111. package/dist/{observeSend-BnPtTotW.mjs → observeSend-DrA3ADFN.mjs} +1 -1
  112. package/dist/{openapi-DoVa5SVP.mjs → openapi-D6MAbYpv.mjs} +7 -7
  113. package/dist/outbox-admin/index.d.mts +1 -1
  114. package/dist/outbox-admin/index.mjs +5 -5
  115. package/dist/{outbox-module-DyITEIop.mjs → outbox-module-D5QABFQW.mjs} +197 -28
  116. package/dist/{outbox-module-5Mnwcycy.d.mts → outbox-module-DzW6zwWJ.d.mts} +103 -10
  117. package/dist/permissions/index.d.mts +2 -2
  118. package/dist/permissions/index.mjs +7 -7
  119. package/dist/{permissions-BBy4bOGi.mjs → permissions-CFsmdYUt.mjs} +9 -9
  120. package/dist/{pipe-BOm2o4UA.mjs → pipe-B_05AgGt.mjs} +2 -2
  121. package/dist/pipeline/index.d.mts +1 -1
  122. package/dist/pipeline/index.mjs +2 -2
  123. package/dist/{plan-DDIGwuxr.mjs → plan-BnlNJhrj.mjs} +1 -1
  124. package/dist/{plugin-Bn4D_0XK.mjs → plugin-CrMPYbdj.mjs} +94 -50
  125. package/dist/plugins/index.d.mts +6 -5
  126. package/dist/plugins/index.mjs +19 -18
  127. package/dist/plugins/response-cache.mjs +4 -4
  128. package/dist/plugins/tracing-entry.mjs +2 -2
  129. package/dist/{pluralize-ClEjcKlG.mjs → pluralize-oVIxJ4CY.mjs} +1 -1
  130. package/dist/presets/filesUpload.d.mts +1 -1
  131. package/dist/presets/filesUpload.mjs +5 -5
  132. package/dist/presets/index.d.mts +2 -2
  133. package/dist/presets/index.mjs +2 -2
  134. package/dist/presets/multiTenant.d.mts +1 -1
  135. package/dist/presets/multiTenant.mjs +5 -5
  136. package/dist/presets/search.d.mts +1 -1
  137. package/dist/presets/search.mjs +2 -2
  138. package/dist/{presets-DK2jh5YR.mjs → presets-CUd3L7v6.mjs} +4 -4
  139. package/dist/{projection-BHH-sXyS.mjs → projection-DowJlIto.mjs} +2 -2
  140. package/dist/{purger.types-2wNJK_89.mjs → purger.types-BjKy8869.mjs} +1 -1
  141. package/dist/{queryCachePlugin-Ckqe98AM.mjs → queryCachePlugin-BvB3k_Fh.mjs} +114 -14
  142. package/dist/{queryCachePlugin-DYQUyeJ9.d.mts → queryCachePlugin-DrQNnGws.d.mts} +1 -1
  143. package/dist/{rateLimitKey-CWAjlqcN.mjs → rateLimitKey-56nH1cWN.mjs} +1 -1
  144. package/dist/{realtime-BIJi9USY.mjs → realtime-DXGBPtYK.mjs} +19 -22
  145. package/dist/registry/index.d.mts +2 -2
  146. package/dist/registry/index.mjs +3 -3
  147. package/dist/{registry-y9ZA-R_J.mjs → registry-Biz-6sEZ.mjs} +2 -2
  148. package/dist/{relay-BNrC1CEP.mjs → relay-DEIoMntZ.mjs} +200 -99
  149. package/dist/{renewingLease-CS43br5E.mjs → renewingLease-BCJpW9-u.mjs} +1 -1
  150. package/dist/{replyHelpers-oZDzakGb.mjs → replyHelpers-DliJNb0-.mjs} +2 -2
  151. package/dist/{requestContext-fWb_YaV2.mjs → requestContext-tUgLt9Ky.mjs} +1 -1
  152. package/dist/{requirement--2hWyyHi.mjs → requirement-0l2DApiQ.mjs} +1 -1
  153. package/dist/{resourceRateLimit-DCWglD7V.d.mts → resourceRateLimit-BPiESPtG.d.mts} +4 -0
  154. package/dist/{resourceRateLimit-1WbcyMZY.mjs → resourceRateLimit-iSXF8rLH.mjs} +19 -4
  155. package/dist/{rolldown-runtime-yH2lHMo_.mjs → rolldown-runtime-gKJR3o-6.mjs} +1 -1
  156. package/dist/{routeValidator-BSlRIA5c.mjs → routeValidator-xNYA4rr1.mjs} +47 -5
  157. package/dist/{runtimeCapabilities-CYCEtU1W.mjs → runtimeCapabilities-BQK-GrYe.mjs} +1 -1
  158. package/dist/{schedules-B5WGlYIT.mjs → schedules-D9iMVFhF.mjs} +6 -9
  159. package/dist/{schemaConverter-DtNvts-6.mjs → schemaConverter-cIh4oX9a.mjs} +2 -2
  160. package/dist/{actionPermissions-DXrlWHHK.mjs → schemaIR-BsY4y9VP.mjs} +184 -16
  161. package/dist/schemas/index.mjs +1 -1
  162. package/dist/scim/index.mjs +2 -2
  163. package/dist/scope/index.d.mts +1 -1
  164. package/dist/scope/index.mjs +5 -5
  165. package/dist/{scope-BwVLSyNG.mjs → scope-QyhM9w8z.mjs} +4 -4
  166. package/dist/{shutdown-BJiJN7FT.mjs → shutdown-BM7Q0h4B.mjs} +1 -1
  167. package/dist/{sse-B_50llZu.mjs → sse-ofvlcTQQ.mjs} +9 -35
  168. package/dist/sseStats-DQqNN385.d.mts +112 -0
  169. package/dist/sseStream-BxQW7hPq.mjs +166 -0
  170. package/dist/{store-helpers-D-n5cwy5.mjs → store-helpers-_FRhHDyv.mjs} +1 -1
  171. package/dist/{simpleEqualityMatcher-DGRLq-1k.mjs → streamFrames-B3ZJfI02.mjs} +19 -2
  172. package/dist/{streaming-Dcgqa-hH.mjs → streaming-HZr63UiM.mjs} +1 -1
  173. package/dist/{subscriberIdentity-C9KhIXTF.mjs → subscriberIdentity-DSgnoT_D.mjs} +1 -1
  174. package/dist/{tenancy-COrhjPRZ.mjs → tenancy-_ukT0oBt.mjs} +2 -2
  175. package/dist/{tenantPreparation-BElWHytd.mjs → tenantPreparation-DSlQI53c.mjs} +4 -4
  176. package/dist/testing/cleanupStoreContract.mjs +1 -1
  177. package/dist/testing/index.d.mts +4 -4
  178. package/dist/testing/index.mjs +324 -17
  179. package/dist/testing/outboxStoreContract.mjs +2 -2
  180. package/dist/testing/requiredPorts.mjs +2 -2
  181. package/dist/testing/storageContract.mjs +1 -1
  182. package/dist/{timing-CaxKbRk_.mjs → timing-Z8p-Zlw1.mjs} +1 -1
  183. package/dist/{transactionContext-8qKON0Nk.mjs → transactionContext-DBbSTfY3.mjs} +1 -1
  184. package/dist/{typeGuards-DVjVSsXO.mjs → typeGuards-_6nNQqgq.mjs} +1 -1
  185. package/dist/types/index.d.mts +1 -1
  186. package/dist/types/index.mjs +1 -1
  187. package/dist/types/storage.mjs +1 -1
  188. package/dist/{types-DeLiuaNv.d.mts → types-B4E0sc6D.d.mts} +20 -31
  189. package/dist/{types-DZHqOuJE.mjs → types-CrOlZ4rY.mjs} +4 -4
  190. package/dist/usage/index.d.mts +1 -1
  191. package/dist/usage/index.mjs +7 -7
  192. package/dist/{userHelpers-_eGj6kf0.mjs → userHelpers-CBKx3XJN.mjs} +1 -1
  193. package/dist/utils/index.d.mts +239 -34
  194. package/dist/utils/index.mjs +13 -13
  195. package/dist/{utils-Dd6MWpye.mjs → utils--HE8R8sH.mjs} +761 -8
  196. package/dist/{validate-BaF5wd0x.mjs → validate-BUeE2MLR.mjs} +3 -3
  197. package/dist/{versioning-S18y2-0C.d.mts → versioning-B07RgD27.d.mts} +2 -13
  198. package/dist/{versioning-DyV7mwtK.mjs → versioning-qYgqwOhL.mjs} +4 -7
  199. package/dist/{workScope-CmCBUmPR.mjs → workScope-C-1QHNmV.mjs} +2 -2
  200. package/llms.txt +2 -2
  201. package/package.json +42 -50
  202. package/skills/arc/references/api-reference.md +2 -2
  203. package/skills/arc/references/auth-better-auth.md +1 -0
  204. package/skills/arc/references/events-outbox.md +7 -4
  205. package/skills/arc/references/events.md +2 -2
  206. package/skills/arc/references/mcp-custom-tools.md +1 -1
  207. package/skills/arc/references/mcp-setup.md +11 -10
  208. package/skills/arc/references/mcp-testing.md +3 -3
  209. package/skills/arc/references/production-api.md +4 -0
  210. package/skills/arc/references/production-boot.md +2 -0
  211. package/skills/arc/references/production-idempotency.md +1 -1
  212. package/skills/arc/references/production-realtime.md +28 -2
  213. package/skills/arc/references/validation.md +4 -0
  214. package/skills/arc/references/writes-hooks-errors.md +1 -0
  215. package/dist/schemaIR-uS_RHqa3.mjs +0 -108
  216. package/dist/sseStream-BjSo9Ult.mjs +0 -57
@@ -1,6 +1,6 @@
1
- /*! @classytic/arc v2.47.0 | MIT | https://classytic.com */
2
- import { t as __exportAll } from "./rolldown-runtime-yH2lHMo_.mjs";
3
- import { x as pathTouchesBlocked } from "./plugin-Bn4D_0XK.mjs";
1
+ /*! @classytic/arc v2.49.0 | MIT | https://classytic.com */
2
+ import { t as __exportAll } from "./rolldown-runtime-gKJR3o-6.mjs";
3
+ import { x as pathTouchesBlocked } from "./plugin-CrMPYbdj.mjs";
4
4
  // src/core/aggregation/normalize.ts
5
5
  /**
6
6
  * Framework cap on URL-driven aggregation limits when the host opts
@@ -1,5 +1,6 @@
1
1
 
2
2
  import { n as DomainEvent } from "./EventTransport-CYEoCJGe.mjs";
3
+ import "./sseStats-DQqNN385.mjs";
3
4
  import { FastifyPluginAsync, FastifyRequest } from "fastify";
4
5
  interface GracefulShutdownOptions {
5
6
  /** Maximum time to wait for graceful shutdown in ms (default: 30000) */
@@ -125,18 +126,6 @@ interface SSEOptions {
125
126
  /** Key a connection is indexed under for `audience` (default: scope user id; none = broadcasts only). */
126
127
  connectionKey?: (request: FastifyRequest) => string | null | undefined;
127
128
  }
128
- /** Live connection gauge, summed across every `ssePlugin` registration on the instance. */
129
- interface SSEStats {
130
- /** Open SSE connections. */
131
- connections: number;
132
- /** Distinct `connectionKey`s indexed (0 without `audience`). */
133
- keys: number;
134
- }
135
- declare module "fastify" {
136
- interface FastifyInstance {
137
- sseStats: () => SSEStats;
138
- }
139
- }
140
129
  declare const _default$3: FastifyPluginAsync<SSEOptions>;
141
130
  declare const CHANGE_OPERATIONS: readonly ["created", "updated", "deleted"];
142
131
  type ChangeOperation = (typeof CHANGE_OPERATIONS)[number];
@@ -251,4 +240,4 @@ declare module "fastify" {
251
240
  }
252
241
  }
253
242
  declare const _default: FastifyPluginAsync<VersioningOptions>;
254
- export { ShutdownState as _, MetricsOptions as a, RealtimeOptions as c, SSEStats as d, _default$3 as f, GracefulShutdownOptions as g, _default$4 as h, MetricsCollector as i, _default$2 as l, CachingRule as m, _default as n, _default$1 as o, CachingOptions as p, MetricEntry as r, ChangeOperation as s, VersioningOptions as t, SSEOptions as u, _default$5 as v };
243
+ export { _default$5 as _, MetricsOptions as a, RealtimeOptions as c, _default$3 as d, CachingOptions as f, ShutdownState as g, GracefulShutdownOptions as h, MetricsCollector as i, _default$2 as l, _default$4 as m, _default as n, _default$1 as o, CachingRule as p, MetricEntry as r, ChangeOperation as s, VersioningOptions as t, SSEOptions as u };
@@ -1,12 +1,9 @@
1
- /*! @classytic/arc v2.47.0 | MIT | https://classytic.com */
2
- import { t as __exportAll } from "./rolldown-runtime-yH2lHMo_.mjs";
3
- import { d as createDomainError } from "./errors-DnrUChAy.mjs";
1
+ /*! @classytic/arc v2.49.0 | MIT | https://classytic.com */
2
+ import { t as __exportAll } from "./rolldown-runtime-gKJR3o-6.mjs";
3
+ import { d as createDomainError } from "./errors-BpYV859Y.mjs";
4
4
  import fp from "fastify-plugin";
5
5
  // src/plugins/versioning.ts
6
- var versioning_exports = /* @__PURE__ */ __exportAll({
7
- default: () => versioning_default,
8
- versioningPlugin: () => versioningPlugin
9
- });
6
+ var versioning_exports = /* @__PURE__ */ __exportAll({ default: () => versioning_default });
10
7
  const PREFIX_REGEX = /^\/v(\d+)\//;
11
8
  const versioningPlugin = async (fastify, opts) => {
12
9
  const { type, defaultVersion = "1", headerName = "accept-version", responseHeader = "x-api-version", versions, deprecated = [], sunset } = opts;
@@ -1,5 +1,5 @@
1
- /*! @classytic/arc v2.47.0 | MIT | https://classytic.com */
2
- import { n as requestContext } from "./requestContext-fWb_YaV2.mjs";
1
+ /*! @classytic/arc v2.49.0 | MIT | https://classytic.com */
2
+ import { n as requestContext } from "./requestContext-tUgLt9Ky.mjs";
3
3
  // src/context/workScope.ts
4
4
  /** Enter a scope for `fn`, or run it inside the active one. */
5
5
  function runWorkScope(seed, fn) {
package/llms.txt CHANGED
@@ -22,7 +22,7 @@ Hand-rolling is a bug in arc apps. Check this table before writing any route, va
22
22
  | Usage counters, quotas, plan limits | @classytic/arc/usage: usagePlugin, requireQuota; rateLimit.plan |
23
23
  | Audit, record history | audit: true, history: true |
24
24
  | Idempotency | @classytic/arc/idempotency |
25
- | Events, outbox, webhooks | @classytic/arc/events, createOutboxModule, integrations/webhooks |
25
+ | Events, outbox, webhooks, SSE replay | @classytic/arc/events, createOutboxModule, integrations/webhooks, createReplayHub |
26
26
  | AI / MCP tools | generated per resource; mcpPlugin from @classytic/arc/mcp |
27
27
  | Unknown route 404 | built in: ErrorContract arc.not_found (errorHandler.notFound to replace) |
28
28
  | Tests | createTestApp, expectArc from @classytic/arc/testing |
@@ -31,7 +31,7 @@ Hand-rolling is a bug in arc apps. Check this table before writing any route, va
31
31
  ## Read next
32
32
 
33
33
  - skills/arc/SKILL.md: golden paths, gotchas, reference index
34
- - skills/arc/references/: one topic per file (validation, schedules, resources, permissions, auth, events, mcp, production, testing)
34
+ - skills/arc/references/: topics (validation, schedules, resources, permissions, auth, events, mcp, production, tests)
35
35
  - skills/arc-code-review/SKILL.md: audit a codebase for hand-rolled code
36
36
  - skills/arc-module-publishing/SKILL.md: ship a reusable arc module
37
37
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@classytic/arc",
3
- "version": "2.47.0",
3
+ "version": "2.49.0",
4
4
  "description": "Resource-oriented backend framework for Fastify - clean, minimal, powerful, tree-shakable",
5
5
  "type": "module",
6
6
  "exports": {
@@ -378,8 +378,8 @@
378
378
  "node": ">=22"
379
379
  },
380
380
  "peerDependencies": {
381
- "@classytic/primitives": ">=0.35.0",
382
- "@classytic/repo-core": ">=0.34.0",
381
+ "@classytic/primitives": ">=0.36.0",
382
+ "@classytic/repo-core": ">=0.37.0",
383
383
  "@classytic/streamline": ">=2.12.0",
384
384
  "@fastify/cors": ">=11.0.0",
385
385
  "@fastify/helmet": ">=13.0.0",
@@ -391,18 +391,18 @@
391
391
  "@fastify/type-provider-typebox": ">=6.0.0",
392
392
  "@fastify/under-pressure": ">=9.0.0",
393
393
  "@fastify/websocket": ">=11.0.0",
394
- "@modelcontextprotocol/client": ">=2.0.0",
395
- "@modelcontextprotocol/node": ">=2.0.0",
396
- "@modelcontextprotocol/server": ">=2.0.0",
394
+ "@modelcontextprotocol/client": ">=2.4.0",
395
+ "@modelcontextprotocol/node": ">=2.1.2",
396
+ "@modelcontextprotocol/server": ">=2.4.0",
397
397
  "@opentelemetry/api": ">=1.9.0",
398
398
  "@opentelemetry/auto-instrumentations-node": ">=0.40.0",
399
399
  "@opentelemetry/exporter-trace-otlp-http": ">=0.50.0",
400
400
  "@opentelemetry/instrumentation-http": ">=0.50.0",
401
401
  "@opentelemetry/instrumentation-mongodb": ">=0.40.0",
402
402
  "@opentelemetry/sdk-node": ">=0.50.0",
403
- "better-auth": ">=1.7.14",
404
- "bullmq": ">=6.5.0",
405
- "fastify": ">=5.12.7",
403
+ "better-auth": ">=1.7.15",
404
+ "bullmq": ">=6.5.4",
405
+ "fastify": ">=5.12.8",
406
406
  "fastify-raw-body": ">=6.0.3",
407
407
  "h3-js": ">=4.0.0",
408
408
  "ioredis": ">=6.0.0",
@@ -508,58 +508,58 @@
508
508
  },
509
509
  "devDependencies": {
510
510
  "@arethetypeswrong/cli": "^0.18.5",
511
- "@better-auth/drizzle-adapter": "^1.7.10",
512
- "@better-auth/mongo-adapter": "^1.7.10",
513
- "@biomejs/biome": "^2.6.3",
511
+ "@better-auth/drizzle-adapter": "^1.7.15",
512
+ "@better-auth/mongo-adapter": "^1.7.15",
513
+ "@biomejs/biome": "^2.6.4",
514
514
  "@classytic/dev-tools": "^0.2.1",
515
515
  "@classytic/gitkit": ">=0.3.0",
516
- "@classytic/mongokit": "^3.43.1",
517
- "@classytic/pgkit": "^0.1.0",
518
- "@classytic/primitives": "^0.35.0",
519
- "@classytic/repo-core": "^0.34.0",
520
- "@classytic/sqlitekit": "^0.11.0",
516
+ "@classytic/mongokit": "^3.44.0",
517
+ "@classytic/pgkit": "^0.1.1",
518
+ "@classytic/primitives": "^0.36.0",
519
+ "@classytic/repo-core": "^0.37.0",
520
+ "@classytic/sqlitekit": "^0.13.0",
521
521
  "@classytic/streamline": "^2.12.0",
522
- "@electric-sql/pglite": "^0.5.10",
523
- "@fastify/cors": "^11.3.1",
522
+ "@electric-sql/pglite": "^0.5.15",
523
+ "@fastify/cors": "^11.4.0",
524
524
  "@fastify/helmet": "^13.2.0",
525
- "@fastify/jwt": "^10.2.5",
526
- "@fastify/multipart": "^10.1.4",
527
- "@fastify/rate-limit": "^11.2.1",
525
+ "@fastify/jwt": "^10.2.7",
526
+ "@fastify/multipart": "^10.1.7",
527
+ "@fastify/rate-limit": "^11.2.2",
528
528
  "@fastify/sensible": "^6.0.7",
529
- "@fastify/static": "^10.1.6",
529
+ "@fastify/static": "^10.1.8",
530
530
  "@fastify/type-provider-typebox": "^6.3.0",
531
531
  "@fastify/under-pressure": "^9.2.1",
532
- "@fastify/websocket": "^11.3.4",
533
- "@modelcontextprotocol/client": "^2.3.1",
534
- "@modelcontextprotocol/node": "^2.1.1",
535
- "@modelcontextprotocol/server": "^2.3.1",
536
- "@opentelemetry/api": "^1.9.1",
537
- "@types/node": "^26.6.5",
532
+ "@fastify/websocket": "^11.3.6",
533
+ "@modelcontextprotocol/client": "^2.4.0",
534
+ "@modelcontextprotocol/node": "^2.1.2",
535
+ "@modelcontextprotocol/server": "^2.4.0",
536
+ "@opentelemetry/api": "^1.10.0",
537
+ "@types/node": "^26.6.6",
538
538
  "@types/qs": "^6.15.1",
539
- "@vitest/coverage-v8": "^5.0.5",
539
+ "@vitest/coverage-v8": "^5.1.0",
540
540
  "ajv": "^8.20.0",
541
- "better-auth": "^1.7.14",
541
+ "better-auth": "^1.7.15",
542
542
  "better-sqlite3": "^13.0.3",
543
- "bullmq": "^6.5.0",
544
- "dotenv": "^18.0.8",
543
+ "bullmq": "^6.5.4",
544
+ "dotenv": "^18.0.9",
545
545
  "drizzle-orm": "^0.45.4",
546
546
  "fast-check": "^4.10.2",
547
- "fastify": "^5.12.7",
547
+ "fastify": "^5.12.8",
548
548
  "fastify-raw-body": "^6.0.3",
549
549
  "h3-js": "^4.5.0",
550
550
  "ioredis": "^6.0.0",
551
- "jose": "^6.2.12",
551
+ "jose": "^6.2.15",
552
552
  "jsonwebtoken": "^9.0.3",
553
- "knip": "^6.43.0",
554
- "mongodb": "^7.7.0",
553
+ "knip": "^6.44.1",
554
+ "mongodb": "~7.7.0",
555
555
  "mongodb-memory-server": "^11.3.0",
556
556
  "mongoose": "^9.11.4",
557
557
  "publint": "^0.3.25",
558
- "tsdown": "^0.23.2",
559
- "typebox": "^1.4.2",
560
- "typescript": "7.1.0-beta",
561
- "vitest": "^5.0.5",
562
- "ws": "^8.22.0",
558
+ "tsdown": "^0.23.4",
559
+ "typebox": "^1.4.3",
560
+ "typescript": "~7.0.2",
561
+ "vitest": "^5.1.0",
562
+ "ws": "^8.22.1",
563
563
  "zod": "^4.6.7"
564
564
  },
565
565
  "config": {
@@ -590,13 +590,5 @@
590
590
  "repository": {
591
591
  "type": "git",
592
592
  "url": "git+https://github.com/classytic/arc.git"
593
- },
594
- "overrides": {
595
- "tsdown": {
596
- "typescript": "$typescript"
597
- },
598
- "@arethetypeswrong/core": {
599
- "typescript": "5.6.1-rc"
600
- }
601
593
  }
602
594
  }
@@ -16,7 +16,7 @@ Import only from these subpaths (tree-shaken, no deep imports). Authoritative li
16
16
  | `/events` | `eventPlugin`, `MemoryEventTransport`, `defineEvent`, `createEventRegistry`, `withRetry`, `withInbox`, `withSubscriberId`, `wrapWithSchema`, `subscribeWithSchema`, `wrapWithBoundary`, `subscribeWithBoundary`, `createDeadLetterPublisher`, `EventOutbox`, `MemoryOutboxStore`, `repositoryAsOutboxStore`, `createOutboxModule`, `exponentialBackoff`, `readOutboxHealth`, `crudEventType`, `ARC_LIFECYCLE_EVENTS` |
17
17
  | `/events/redis`, `/events/redis-stream` | `RedisEventTransport`, `RedisStreamTransport` |
18
18
  | `/outbox-admin` | `createOutboxAdminModule` |
19
- | `/plugins` | `healthPlugin`, `gracefulShutdownPlugin`, `ssePlugin`, `metricsPlugin`, `versioningPlugin`, `schedulesPlugin`, `cachingPlugin`, `pressurePlugin`, `realtimePlugin`, `requestIdPlugin`, `errorHandlerPlugin`, `createPlugin`, `createDailyGate`, `createMemoryDailyLedger`; types `DailyLedger`, `DailyScheduleOptions`, `ScheduleRunContext`, `ScheduleDefinition` |
19
+ | `/plugins` | `healthPlugin`, `gracefulShutdownPlugin`, `ssePlugin`, `metricsPlugin`, `versioningPlugin`, `schedulesPlugin`, `cachingPlugin`, `pressurePlugin`, `realtimePlugin`, `requestIdPlugin`, `errorHandlerPlugin`, `createPlugin`, `createDailyGate`, `createMemoryDailyLedger`, `registerSseStats`, `createSseConnectionGauge`; types `DailyLedger`, `DailyScheduleOptions`, `ScheduleRunContext`, `ScheduleDefinition` |
20
20
  | `/plugins/tracing`, `/plugins/response-cache` | `tracingPlugin`, `traced`, `createSpan`; `responseCachePlugin` |
21
21
  | `/audit` | `auditPlugin`, `MemoryAuditStore`, `repositoryAsAuditStore`, `createAuditEntry` |
22
22
  | `/idempotency` (+ `/idempotency/redis`) | `idempotencyPlugin`, `MemoryIdempotencyStore`, `repositoryAsIdempotencyStore`, `IdempotencyStoreMisconfiguredError`; `RedisIdempotencyStore` |
@@ -25,7 +25,7 @@ Import only from these subpaths (tree-shaken, no deep imports). Authoritative li
25
25
  | `/context`, `/logger` | `requestContext`, `transactionContext`, `runWorkScope`; `arcLog`, `configureArcLogger` |
26
26
  | `/registry`, `/discovery`, `/docs` | `ResourceRegistry`, `introspectionPlugin`; `discoverResources`; `openApiPlugin`, `scalarPlugin`, `buildOpenApiSpec` |
27
27
  | `/schemas` | `Type`, `ArcListResponse`, `ArcErrorResponse`, `ArcPaginationQuery` |
28
- | `/utils` | `createStateMachine`, `CircuitBreaker`, `withCompensation`, `defineGuard`, `declareRuntimeCapability`, `createQueryParser`, `ArcQueryParser`, `createError`, `pipeUIMessageStreamToReply`, `listResponse`, `errorContractSchema`, error classes |
28
+ | `/utils` | `createStateMachine`, `CircuitBreaker`, `withCompensation`, `defineGuard`, `declareRuntimeCapability`, `createQueryParser`, `ArcQueryParser`, `createError`, `pipeUIMessageStreamToReply`, `openSseStream`, `createReplayHub`, `lastEventIdOf`, `STREAM_FRAMES`, `registerSseStats`, `createSseConnectionGauge`, `listResponse`, `errorContractSchema`, error classes |
29
29
  | `/migrations` | `defineMigration`, `MigrationRunner`, `MigrationRegistry`, `MongoMigrationStore` |
30
30
  | `/cleanup` | `createDataCleanupModule`, `createCleanupService`, `createCleanupRegistry`, `recipeFromSteps` |
31
31
  | `/encryption` | `encryptionPlugin`, `encryptField`, `decryptField`, `createStaticKeyProvider` |
@@ -68,6 +68,7 @@ BA stores several roles in one `member.role` string. Arc reads `scope.orgRoles`
68
68
  - Redis sessions: BA `secondaryStorage` (sessions skip the DB unless `session.storeSessionInDatabase: true`). Arc's `RedisSessionStore` (`@classytic/arc/auth/redis`) belongs to `createSessionManager`, a different layer. Do not mix.
69
69
  - BA `session.cookieCache` never caches custom session fields such as `activeOrganizationId`, so scope cannot go stale, but the org lookup still runs.
70
70
  - BA has its own limiter (`rateLimit.storage: 'secondary-storage'`). Exempt it from arc's bucket: `rateLimit: { skipPaths: ['/api/auth/*'] }`.
71
+ - BA JSON refusals (status >= 400) from `/api/auth/*` gain `status` and `correlationId` (`request.id`) when absent, like arc's own errors. Other responses pass through byte-identical. Drop any host `onSend` that added them.
71
72
 
72
73
  ## Bearer transport (SPA, mobile)
73
74
 
@@ -32,14 +32,17 @@ const app = await createApp({
32
32
  | `transport` | Default: the app's raw event transport (not the `app.events` facade) |
33
33
  | `name` | Module name and `dependsOn` key (default `'outbox'`) |
34
34
  | `relayEveryMs` | Default 5000 |
35
- | `batchSize`, `leaseMs`, `consumerId` | Relay tuning; `consumerId` defaults to a per-instance unique id |
35
+ | `batchSize`, `leaseMs`, `consumerId` | Relay tuning; `consumerId` defaults to a per-instance unique id. `leaseMs` must exceed one publish + ack, not a batch: claims shrink to fit the lease. A repository page `maxLimit` below `batchSize` warns `OUTBOX_CLAIM_CAPPED` once and `batchSize` drops to the store's `claimCap` |
36
+ | `maxPassesPerTick` | Default 1. Above 1, a tick (and `requestDrain`) keeps relaying while the last pass claimed and relayed something (a claim capped below `batchSize` does not stop it); an empty or all-failed pass stops. Replaces hand-rolled `relayBatch` loops |
36
37
  | `failurePolicy` | `({ attempts, error }) => { retryAt } \| { deadLetter: true }`. Set one: without it failed rows retry every poll forever |
37
- | `onError` | Per-event relay problems (default: structured logger) |
38
+ | `onError` | Per-event relay problems (default: structured logger; lost leases log one `OUTBOX_LEASE_LOST` warning per pass, then back off) |
38
39
  | `sessionProvider` | Default `() => transactionContext.get()`; `false` opts out |
39
40
  | `runOnStart` | Drain backlog at boot (default true) |
40
41
  | `health` | Readiness check `<name>.relay` + log alerts; `false` disables. `{ relayLagUnhealthyMs, probeCacheMs, alertEveryMs }` |
41
42
 
42
- Exports at `getModuleExports<OutboxModuleExports>(app, 'outbox')`: `store`, `relay` (an `EventOutbox`), `requestDrain()` (coalesced, call after commit), `drain({ maxPasses })` (await in tests), `health()`.
43
+ Exports at `getModuleExports<OutboxModuleExports>(app, 'outbox')`: `store`, `relay` (an `EventOutbox`), `requestDrain({ types? })` (coalesced, call after commit; `types` = a priority pass for those event types ahead of the backlog, published once by the relay), `drain({ maxPasses })` (await in tests), `health()`.
44
+
45
+ Passes are single-flight: a `requestDrain` during a pass queues one follow-up, a tick waits instead of overlapping. Typed drains run in their own lane. A pass publishes a claimed row only while its lease has budget left and acks it at once; rows past the budget stay leased and are re-claimed after expiry, never published twice by one relay. Leave `batchSize` at its default on a slow store.
43
46
 
44
47
  ## Writing
45
48
 
@@ -59,7 +62,7 @@ await outbox.store(
59
62
  ```typescript
60
63
  const outbox = new EventOutbox({ repository: repo, transport, failurePolicy, batchSize: 100, leaseMs: 30000 });
61
64
  const r = await outbox.relayBatch();
62
- // { relayed, attempted, publishFailed, ackFailed, ownershipMismatches, malformed, failHookErrors, deadLettered, usedPublishMany }
65
+ // { relayed, attempted, publishFailed, ackFailed, ownershipMismatches, malformed, failHookErrors, deadLettered, usedPublishMany, leaseDeferred? }
63
66
  const dead = await outbox.getDeadLettered(100); // DeadLetteredEvent[]
64
67
  await outbox.purge(olderThanMs); // delivered rows
65
68
  ```
@@ -104,7 +104,7 @@ await subscribeWithBoundary(app, 'cache.*', invalidate); // log and swallow,
104
104
  | Helper | Use |
105
105
  |---|---|
106
106
  | `withSubscriberId(id, handler)` | Stable per-handler identity for durable per-handler progress (never an index) |
107
- | `withInbox(name, handler, { store, leaseMs?, transaction? })` | Run a handler once per event id; `store` is a repo-core `IdempotencyClaimStore`; handler gets `{ session, eventId }` |
107
+ | `withInbox(name, handler, { store, leaseMs?, transaction? })` | Run a handler once per event id; `store` is a repo-core `IdempotencyClaimStore`; handler gets `{ session, eventId }`; `transaction` covers only writes made with that `session` (omit it when a handler writes elsewhere) |
108
108
  | `createDeadLetterPublisher(app.events)` | Handler that publishes exhausted events to `$deadLetter`; pass as `onDead` or `deadLetter` |
109
109
 
110
110
  Dead-letter contract: a transport may implement `deadLetter(dlq: DeadLetteredEvent)`.
@@ -114,7 +114,7 @@ Dead-letter contract: a transport may implement `deadLetter(dlq: DeadLetteredEve
114
114
  | Transport | Import | Use |
115
115
  |---|---|---|
116
116
  | `MemoryEventTransport` | `@classytic/arc/events` | Dev, tests, one process |
117
- | `RedisEventTransport(redis, { channel, externalLifecycle, logger })` | `@classytic/arc/events/redis` | Pub/Sub, fire-and-forget, live fan-out |
117
+ | `RedisEventTransport(redis, { channel, externalLifecycle, logger, subscribeTimeoutMs, publishTimeoutMs })` | `@classytic/arc/events/redis` | Pub/Sub, fire-and-forget, live fan-out; Redis down: subscribe returns after 2 s (queued), publish rejects after 5 s then at once until ready |
118
118
  | `RedisStreamTransport(redis, opts)` | `@classytic/arc/events/redis-stream` | Persistent, consumer groups, replay, DLQ stream |
119
119
 
120
120
  Streams options: `stream` ('arc:events'), `group` ('default'), `consumer`, `blockTimeMs` (5000), `batchSize` (10), `processingConcurrency` (1, keeps order), `maxRetries` (5), `claimTimeoutMs` (30000), `deadLetterStream` ('arc:events:dlq' or `false`), `maxLen` (0), `groupStart` ('latest' | 'beginning'), `maxPayloadBytes` (1 MB), `externalLifecycle`.
@@ -35,7 +35,7 @@ await app.register(mcpPlugin, { resources, extraTools: [notifyTool], extraPrompt
35
35
  const server = await createMcpServer({ name: 'tools', version: '1.0.0', tools: [notifyTool], prompts: [planPrompt] });
36
36
  ```
37
37
 
38
- - `ToolContext`: `{ session, log(level, msg), extra }`. `session` is the `McpAuthResult` or `null` (no auth).
38
+ - `ToolContext`: `{ session, log(level, msg), extra }`. `session` is the `McpAuthResult` or `null` (no auth). `log` writes server-side (`fastify.log`, or `createMcpServer({ logger })`), never to the client.
39
39
  - Handler returns `CallToolResult`: `{ content: [{ type: 'text', text }], isError? }`. `toCallToolResult`, `toCallToolSuccess`, `toCallToolError`, `permissionDeniedResult` build it.
40
40
  - `defineTool<MySession>(...)` widens `ctx.session` to a host type extending `McpAuthResult`.
41
41
  - Custom tools bypass resource permissions: guard them explicitly.
@@ -21,11 +21,12 @@ const app = await createApp({
21
21
  |---|---|---|
22
22
  | `list` | `list_{plural}` | `readOnlyHint` |
23
23
  | `get` | `get_{name}` | `readOnlyHint` |
24
- | `create` | `create_{name}` | `destructiveHint: false` |
24
+ | `create` | `create_{name}` | not destructive, not idempotent |
25
25
  | `update`, `delete` | `update_{name}`, `delete_{name}` | `destructiveHint`, `idempotentHint` |
26
26
  | `actions` | `{action}_{name}` (input: `id` + action schema) | `destructiveHint` |
27
- | custom routes (function or string handler) | `{operation or slug}_{name}` | GET: `readOnlyHint`, else `openWorldHint` |
27
+ | custom routes (function or string handler) | `{operation or slug}_{name}` | by HTTP method: GET/HEAD read-only; PUT/DELETE destructive + idempotent; POST/PATCH destructive |
28
28
 
29
+ - CRUD hints are all explicit and include `openWorldHint: false`; an omitted hint means the cautious spec default.
29
30
  - A CRUD op becomes a tool only when `permissions.<op>` is declared and the op is not in `disabledRoutes`.
30
31
  - Tools run the same controller pipeline as REST: auth, tenant scope, permission policy, hooks, field masking, events.
31
32
  - `list_*` accepts `page`, `limit`, `cursor` (keyset; `page` ignored when set), `sort`, `search`, `select`, `populate`, filters. `get_*` accepts `id`, `select`. `limit` max follows the resource `queryParser.maxLimit`.
@@ -46,8 +47,7 @@ const app = await createApp({
46
47
  | `toolNamePrefix` | none | `'crm'` gives `crm_list_products` |
47
48
  | `overrides` | none | Per-resource `McpResourceConfig` |
48
49
  | `extraTools`, `extraPrompts` | none | Hand-written tools/prompts |
49
- | `stateful`, `sessionTtlMs`, `maxSessions` | `false`, 1800000, 1000 | Session mode |
50
- | `authCacheTtlMs` | 5000 | Stateless auth-result cache; `0` disables |
50
+ | `authCacheTtlMs` | 5000 | Auth-result cache; `0` disables |
51
51
  | `dnsRebindingProtection` | on if `auth: false` | See below |
52
52
 
53
53
  ## Per-resource overrides
@@ -95,14 +95,15 @@ mcpPlugin({ resources, auth: false, dnsRebindingProtection: false });
95
95
 
96
96
  Absent `Origin` passes; present-but-unlisted is refused. `${prefix}/health` is exempt.
97
97
 
98
- ## Endpoints and modes
98
+ ## Protocol and endpoints
99
99
 
100
- | Mode | Behavior |
101
- |---|---|
102
- | Stateless (default) | `POST /mcp` fresh server per request; `GET` returns 405; `DELETE` no-op. Use for scaling/serverless |
103
- | `stateful: true` | `POST` reuses `Mcp-Session-Id`; `GET` is SSE; `DELETE` ends session. TTL cache, LRU eviction at `maxSessions` |
100
+ The endpoint speaks MCP **2026-07-28 only** (SDK `createMcpHandler` with 2025 serving off): fresh server per request, no sessions.
104
101
 
105
- - `GET /mcp/health` returns `{ status, mode }`; with valid auth (or `auth: false`) it also returns `tools`, `resources`, `toolNames`, `sessions`.
102
+ - `POST /mcp` serves 2026-07-28. A 2025-era `initialize` gets `400`, JSON-RPC `-32022`, `data.supported: ["2026-07-28"]`.
103
+ - `GET`/`DELETE /mcp` return 405 with `Allow: POST`.
104
+ - `stateful: true` is removed and throws at boot; delete `stateful`, `sessionTtlMs`, `maxSessions`.
105
+ - `ctx.log` writes to `fastify.log` tagged `{ mcpTool }`, never to the client.
106
+ - `GET /mcp/health` returns `{ status, protocolVersion }`; with valid auth (or `auth: false`) it also returns `tools`, `resources`, `toolNames`.
106
107
  - Resources `arc://schemas` and `arc://schemas/{name}` expose resource schemas to agents.
107
108
  - Multiple endpoints: register `mcpPlugin` repeatedly with different `resources` and `prefix`.
108
109
 
@@ -1,6 +1,6 @@
1
1
  # MCP: testing
2
2
 
3
- `@classytic/arc/mcp/testing` serves the real Streamable HTTP transport on an ephemeral loopback port (needs `@modelcontextprotocol/client`). Always `await client.close()`.
3
+ `@classytic/arc/mcp/testing` connects an SDK client speaking MCP 2026-07-28 (the only revision arc serves) in memory: no port. Needs `@modelcontextprotocol/client`. Always `await client.close()`. For HTTP status codes and headers, register `mcpPlugin` and use `app.inject()`.
4
4
 
5
5
  ## createTestMcpClient
6
6
 
@@ -25,7 +25,7 @@ await client.close();
25
25
  | Option | Notes |
26
26
  |---|---|
27
27
  | `pluginOptions` | `resources`, `overrides`, `expose`, `exclude`, `toolNamePrefix`, `extraTools`, `extraPrompts`, `instructions` |
28
- | `auth` | `McpAuthResult` for the session; `null` or omitted runs anonymous |
28
+ | `auth` | `McpAuthResult` for the session; `null` runs anonymous; omitted is `{ userId: 'test-user' }` |
29
29
  | `serverName` | default `test-mcp` |
30
30
 
31
31
  `callTool` returns `{ content: [{ type, text }], isError? }`; parse `content[0].text` as JSON.
@@ -38,7 +38,7 @@ For a server you built with `createMcpServer`:
38
38
  import { connectMcpTestClient } from '@classytic/arc/mcp/testing';
39
39
 
40
40
  const server = await createMcpServer({ name: 't', tools: [notifyTool] });
41
- const { client, close } = await connectMcpTestClient(server);
41
+ const { client, close } = await connectMcpTestClient(server); // one connection per server
42
42
  const result = await client.callTool({ name: 'send_notification', arguments: { /* ... */ } });
43
43
  await close();
44
44
  ```
@@ -84,6 +84,10 @@ createApp({
84
84
 
85
85
  Pre-auth paths see the public scope and key by IP: exempt them with `skipPaths`. Per-resource budgets: `defineResource({ rateLimit })`.
86
86
 
87
+ Shared store down (`redis`/`store`): every call is bounded (`storeFallback.timeoutMs`, 250) and an error or timeout is answered from per-instance memory counters (still limited, never hangs or 500s); one warning per outage, probed every `retryAfterMs` (5000), resumes on its first answer; `storeFallback.onStatus` reports each switch for a health/metrics signal. `storeFallback: false` = the plugin's own behaviour.
88
+
89
+ A route's raw `config: { rateLimit: { max, timeWindow, keyGenerator, groupId, allowList } }` runs on arc's resource limiter (same headers, same 429 `arc.rate_limited`). `keyGenerator(req)` replaces the scope/IP key (per device behind one NAT address); `allowList` (keys or `(req, key) => boolean`) skips the limit; `groupId` shares one budget across routes and resources (one group, one `max`/`timeWindow`). Any other option refuses to register.
90
+
87
91
  ## Bulk preset
88
92
 
89
93
  ```typescript
@@ -26,6 +26,7 @@ await app.listen({ port: 3000, host: '0.0.0.0' });
26
26
  | `trustProxy` | `true`, CIDR string/array, or `'loopback'`. Unset behind a proxy makes `request.ip` the proxy |
27
27
  | `keepAliveTimeout` | Default 72000; keep above the LB idle timeout or you get intermittent 502 |
28
28
  | `requestTimeout`, `connectionTimeout`, `bodyLimit`, `maxParamLength` | Fastify pass-through (body 1 MiB, param 400) |
29
+ | `http` | Node server options pass-through: `highWaterMark`, `maxHeaderSize`, `requireHostHeader`, `joinDuplicateHeaders`, `noDelay`, `keepAlive*` |
29
30
  | `underPressure` | Production preset sets `maxEventLoopDelay: 3000`; override `{ maxEventLoopDelay: 500 }`, disable `false` |
30
31
  | `strictResourceDir`, `strictResources` | Throw on empty discovery or duplicate resource names; turn on in production |
31
32
  | `resourceDir: import.meta.url` | Works from `src/` and `dist/`; a path string resolves against `process.cwd()` |
@@ -62,6 +63,7 @@ export default { fetch: toFetchHandler(app) };
62
63
 
63
64
  ## CORS
64
65
 
66
+ - Unset `methods` → arc's verbs (`GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS`), not `@fastify/cors`'s `GET,HEAD,POST`, when `origin` is an explicit allow-list (string, array, RegExp). `origin: true` or a function keeps `GET,HEAD,POST` (boot warning with `credentials: true`). Any resolved list that omits a verb your routes use (e.g. `origin: true` without credentials vs CRUD `PATCH`/`DELETE`) logs one `onReady` warning naming the verbs.
65
67
  - Production without `cors.origin` warns. `origin: '*'` with `credentials: true` throws at boot; use an allow-list.
66
68
  - Arc merges its headers (`x-organization-id`, `x-arc-scope`, `x-request-id`) into a declared `allowedHeaders` list and always exposes its own response headers.
67
69
  - Mobile webviews (Capacitor, Ionic): add webview origins and expose the Better Auth bearer header.
@@ -74,7 +74,7 @@ repository: new Repository(IdempotencyModel, [methodRegistryPlugin(), batchOpera
74
74
 
75
75
  ## IdempotencyStore contract
76
76
 
77
- Required: `name`, `get`, `set`, `tryLock`, `unlock`, `isLocked`, `delete`, `deleteByPrefix`, `findByPrefix`. Optional: `acquire` (atomic check-and-lock), `setIfLocked` (fenced completion), `supportsFencedCompletion`, `completionReleasesLock`, `close`. A custom store without fencing needs `allowUnfencedCompletion: true`.
77
+ Required: `name`, `get`, `set`, `tryLock`, `unlock`, `isLocked`, `delete`, `deleteByPrefix`, `findByPrefix`. Optional: `acquire` (atomic check-and-lock), `setIfLocked` (fenced completion), `supportsFencedCompletion`, `completionReleasesLock`, `close`. A custom store without fencing needs `allowUnfencedCompletion: true`. `unlock` after a non-2xx must leave no claim behind (the repository store deletes a result-less row it locks).
78
78
 
79
79
  ## Gotchas
80
80
 
@@ -22,7 +22,7 @@ const app = await createApp({
22
22
  - `GET /realtime/:resource` (resource name) and multiplexed `GET /realtime?resources=a,b,c` (max 20).
23
23
  - Gated by the resource's own `list` permission; per-event row filtering, tenant guard, field masking.
24
24
  - Client: plain `EventSource` with `?token=` (`tokenQueryParam`, default `token`, `null` disables).
25
- - No replay: on reconnect, refetch the list.
25
+ - No replay: on reconnect, refetch the list. For a resumable stream use `createReplayHub` (below).
26
26
  - Permission filters are snapshotted at connect. The feed closes at token `exp` and at `maxConnectionMs` (default 30 min) to bound staleness.
27
27
 
28
28
  ## SSE plugin
@@ -46,7 +46,33 @@ const app = await createApp({
46
46
 
47
47
  - Events without `organizationId` reach every caller. An elevated admin with no active org sees all tenants.
48
48
  - `orgScoped: false` only for a deliberately cross-tenant stream; keep `requireAuth` and add a `filter`.
49
- - `fastify.sseStats()` returns `{ connections, keys }`.
49
+ - `fastify.sseStats()` returns `{ connections, keys }`, summed over ssePlugin, realtime feeds, replay hubs and `createSseConnectionGauge(app)` (custom routes call `gauge.track(stream)`). Register at boot: `decorate` after ready throws.
50
+
51
+ ## Resumable custom stream (replay over a ChangeLogStore)
52
+
53
+ ```typescript
54
+ import { createReplayHub, lastEventIdOf, openSseStream } from '@classytic/arc/utils';
55
+
56
+ const hub = createReplayHub(app, { // at boot, before ready
57
+ store, // repo-core ChangeLogStore (mongokit createChangeLogStore, MemoryChangeLogStore)
58
+ readScope: (ctx) => ({ tenantId: ctx.orgId, scopes: ['alerts'] }), // tail partition + since() filter
59
+ toFrame: (entry, ctx) => (canSee(ctx, entry) ? { event: 'alert', data: entry.doc } : null),
60
+ isValidCursor: (c) => /^\d{16}$/.test(c),
61
+ compareCursors: (a, b) => (a < b ? -1 : a > b ? 1 : 0),
62
+ revalidate: { everyMs: 15_000, check: (ctx, { memo }) => stillAllowed(ctx, memo), maxConsecutiveFailures: 3 }, // null/undefined/false → revoked; { close: 'revoke' | 'retry', reason }
63
+ identify: (ctx) => ({ userId: ctx.userId, sessionId: ctx.sessionId }),
64
+ revokeVia: { secret: env.REALTIME_REVOKE_SECRET }, // hub.revoke() reaches every replica, sealed (AES-GCM)
65
+ });
66
+ await app.events.subscribe('alert.*', () => hub.notify()); // the bus only WAKES the tail
67
+ // route, after every gate:
68
+ await hub.attach(openSseStream(req, reply), ctx, lastEventIdOf(req));
69
+ ```
70
+
71
+ - Frames: `ready {cursor, resumed}` first, then the replay or one `resync {cursor, reason}`, then live (`id:` = cursor). `revoked {reason}` then close (final). `retry {reason}` then close (not final: reconnect now). Names: `STREAM_FRAMES`, same literals as `@classytic/arc-next/sse`.
72
+ - `openSseStream` waits for `drain` (`maxBufferedBytes` 1 MiB, `drainTimeoutMs` 10 s; `0` bytes = old fail-fast); the hub paces a replay on `needsDrain`/`drain()`, so a large resume is not cut.
73
+ - A live entry the replay already sent goes out once. Entries hidden by `toFrame` are followed by an id-only frame, so the client cursor keeps up.
74
+ - Gap over `maxReplay` (500) → `gap_too_large`; `CursorExpiredError` → `cursor_expired`; invalid or ahead → `cursor_invalid`. Other store errors close with no frame.
75
+ - mongokit `compactSuperseded` keeps only the latest entry per doc, so replay yields latest state; a foreign cursor throws there, so set `isValidCursor`.
50
76
 
51
77
  ## Streaming custom routes
52
78
 
@@ -38,6 +38,7 @@ routes: [{
38
38
 
39
39
  - A failed parse is `400 arc.validation_error` with `details[]` (`path`, `message`), the same wire as an AJV failure.
40
40
  - A plain JSON Schema slot is AJV-only (no preHandler is added for it).
41
+ - AJV coerces querystring, params and headers only. JSON bodies are validated as sent (`"5"` for a number is a 400; `false` under `anyOf [number, boolean]` stays `false`). `createApp({ ajv: { coerceBody: true } })` opts back in.
41
42
  - `parsed(schema, value)` is a typing helper: it does not parse again.
42
43
  - `headers` and `response` are schema-only.
43
44
 
@@ -72,6 +73,8 @@ actions: {
72
73
 
73
74
  `noPayloadSchema` is plain JSON Schema (`additionalProperties: false`): any stray field is a 400.
74
75
 
76
+ Arc owns `action`: `data` never carries it. A schema may still declare it (a contracts union branch, `z.strictObject({ action: z.literal('close'), ... })`): arc keeps its own discriminator for AJV, OpenAPI and MCP, and `parse: true` parses with `action` put back, then drops it from `data`.
77
+
75
78
  ## The wrapper pitfall
76
79
 
77
80
  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.
@@ -88,4 +91,5 @@ schema: z.object({ note: z.string() }) // right
88
91
  - `customSchemas` parts replace generated parts; untouched parts keep auto-generation. Model-required fields the server fills: `schemaOptions.fieldRules: { f: { systemManaged: true } }`.
89
92
  - 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
93
  - A `.refine()` is not enforced by AJV: it needs `routeInput` / `parse: true`, or do it in the handler.
94
+ - Your own error code for a refinement: tag the issue (`ctx.addIssue({ ..., params: { code } })`) and pass `routeInput(slots, { mapIssues })` / `crudInput({ ..., mapIssues })`, returning an `ArcError` (or `undefined` for the default 400).
91
95
  - A thrown raw `ZodError` from your own `.parse()` is not mapped to a 400 by arc; use `routeInput` or throw `ValidationError`.
@@ -21,6 +21,7 @@ defineResource({
21
21
  - Retry belongs to the kit (`transactionRetry`); arc never stacks a second policy.
22
22
  - Boot fails without `withTransaction`, and at registration when `capabilities.transactions !== true` (standalone Mongo, D1).
23
23
  - `ctx.uow.session` is empty on connection-bound backends (SQLite): use the tx-bound repository.
24
+ - With `concurrency` set, a stale `If-Match` is 412 before `writes.update` runs. The verb gets `ctx.expectedVersion` (`ctx.expectedVersionSource`: `'if-match'` or `'loaded'`) and must CAS with it, e.g. mongokit `repo.claimVersion(id, { from: ctx.expectedVersion }, update, session)`; on a miss throw `VersionConflictError` (412 under If-Match, else 409). A conflict whose `id` names another document stays 409.
24
25
 
25
26
  ## Hooks
26
27