@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 { n as evictToSize } from "./boundedMap-CtdzpJ3X.mjs";
1
+ /*! @classytic/arc v2.49.0 | MIT | https://classytic.com */
2
+ import { t as __exportAll } from "./rolldown-runtime-gKJR3o-6.mjs";
3
+ import { n as evictToSize } from "./boundedMap-C51EUUOm.mjs";
4
4
  // src/cache/memory.ts
5
5
  var memory_exports = /* @__PURE__ */ __exportAll({ MemoryCacheStore: () => MemoryCacheStore });
6
6
  /**
@@ -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 { a as MetricHistogram, i as DURATION_BUCKETS_SECONDS, o as MetricSeries, s as renderMetricSample } from "./health-jkYNdobJ.mjs";
1
+ /*! @classytic/arc v2.49.0 | MIT | https://classytic.com */
2
+ import { t as __exportAll } from "./rolldown-runtime-gKJR3o-6.mjs";
3
+ import { a as MetricHistogram, i as DURATION_BUCKETS_SECONDS, o as MetricSeries, s as renderMetricSample } from "./health-BoFxrkJE.mjs";
4
4
  import fp from "fastify-plugin";
5
5
  // src/plugins/metrics.ts
6
- var metrics_exports = /* @__PURE__ */ __exportAll({
7
- default: () => metrics_default,
8
- metricsPlugin: () => metricsPlugin
9
- });
6
+ var metrics_exports = /* @__PURE__ */ __exportAll({ default: () => metrics_default });
10
7
  var Counter = class {
11
8
  series;
12
9
  constructor(maxSeries) {
@@ -1,5 +1,5 @@
1
1
 
2
- import { A as RequestWithExtras, J as MiddlewareConfig, k as MiddlewareHandler } from "../index-Cy2-QffW.mjs";
2
+ import { A as RequestWithExtras, J as MiddlewareConfig, k as MiddlewareHandler } from "../index-DLCcLUQT.mjs";
3
3
  import { RouteHandlerMethod } from "fastify";
4
4
  interface NamedMiddleware {
5
5
  /** Unique name for debugging/introspection */
@@ -1,6 +1,6 @@
1
- /*! @classytic/arc v2.47.0 | MIT | https://classytic.com */
2
- import { t as CRUD_OPERATIONS } from "../constants-Cx7BcnHT.mjs";
3
- import { t as multipartBody } from "../multipartBody-qU7KCn1l.mjs";
1
+ /*! @classytic/arc v2.49.0 | MIT | https://classytic.com */
2
+ import { t as CRUD_OPERATIONS } from "../constants-DOnfMd7i.mjs";
3
+ import { t as multipartBody } from "../multipartBody-BdG1qbn1.mjs";
4
4
  // src/middleware/middleware.ts
5
5
  /**
6
6
  * Named Middleware — Priority-based, conditional middleware execution.
@@ -1,5 +1,5 @@
1
- /*! @classytic/arc v2.47.0 | MIT | https://classytic.com */
2
- import { t as startRenewingLease } from "../renewingLease-CS43br5E.mjs";
1
+ /*! @classytic/arc v2.49.0 | MIT | https://classytic.com */
2
+ import { t as startRenewingLease } from "../renewingLease-BCJpW9-u.mjs";
3
3
  import { createHash, randomUUID } from "node:crypto";
4
4
  // src/migrations/index.ts
5
5
  /**
@@ -1,4 +1,4 @@
1
- /*! @classytic/arc v2.47.0 | MIT | https://classytic.com */
1
+ /*! @classytic/arc v2.49.0 | MIT | https://classytic.com */
2
2
  // src/factory/module/index.ts
3
3
  /**
4
4
  * Identity helper for authoring a typed module — mirrors `defineResource`.
@@ -1,5 +1,5 @@
1
1
 
2
- import { G as CrudRouteKey, W as PresetResult } from "./index-Cy2-QffW.mjs";
2
+ import { G as CrudRouteKey, W as PresetResult } from "./index-DLCcLUQT.mjs";
3
3
  type TenantFieldSpec = {
4
4
  field: string;
5
5
  type: "org";
@@ -1,4 +1,4 @@
1
- /*! @classytic/arc v2.47.0 | MIT | https://classytic.com */
1
+ /*! @classytic/arc v2.49.0 | MIT | https://classytic.com */
2
2
  import { ARC_ERROR_CODES } from "@classytic/repo-core/errors";
3
3
  import sjson from "secure-json-parse";
4
4
  // src/middleware/multipartBody.ts
@@ -1,4 +1,4 @@
1
- /*! @classytic/arc v2.47.0 | MIT | https://classytic.com */
1
+ /*! @classytic/arc v2.49.0 | MIT | https://classytic.com */
2
2
  // src/utils/observeSend.ts
3
3
  /** Run `fn`, reporting whether it called `reply.send` (or the reply is already sent). */
4
4
  async function runObservingSend(reply, fn) {
@@ -1,9 +1,9 @@
1
- /*! @classytic/arc v2.47.0 | MIT | https://classytic.com */
2
- import { n as getUserRoles } from "./userHelpers-_eGj6kf0.mjs";
3
- import { n as convertRouteSchema } from "./schemaConverter-DtNvts-6.mjs";
4
- import { t as resolveActionPermission } from "./actionPermissions-DXrlWHHK.mjs";
5
- import { t as pluralize } from "./pluralize-ClEjcKlG.mjs";
6
- import { t as buildActionBodySchema } from "./createActionRouter-mLAGbpDV.mjs";
1
+ /*! @classytic/arc v2.49.0 | MIT | https://classytic.com */
2
+ import { n as getUserRoles } from "./userHelpers-CBKx3XJN.mjs";
3
+ import { a as resolveActionPermission } from "./schemaIR-BsY4y9VP.mjs";
4
+ import { t as buildActionBodySchema } from "./createActionRouter-CpTn15dm.mjs";
5
+ import { t as pluralize } from "./pluralize-oVIxJ4CY.mjs";
6
+ import { n as convertRouteSchema } from "./schemaConverter-cIh4oX9a.mjs";
7
7
  import fp from "fastify-plugin";
8
8
  // src/docs/openapi/canonical-schemas.ts
9
9
  /**
@@ -572,7 +572,7 @@ function emitMount(paths, resource, basePath, additionalSecurity, subsetActions,
572
572
  const actionEnum = subsetActions.map((a) => a.name);
573
573
  const actionSchemas = {};
574
574
  for (const a of subsetActions) if (a.schema) actionSchemas[a.name] = a.schema;
575
- const bodySchema = buildActionBodySchema(actionEnum, actionSchemas);
575
+ const bodySchema = buildActionBodySchema(actionEnum, actionSchemas, { keepDefaults: true });
576
576
  const descLines = [
577
577
  hasId ? "Unified action endpoint for state transitions on an existing entity." : "Resource-root action endpoint (no `:id` — operates on the collection or creates new entities).",
578
578
  "",
@@ -1,6 +1,6 @@
1
1
 
2
- import { l as PermissionCheck } from "../base-HXNgPQww.mjs";
3
2
  import { n as ArcModule, u as ModuleName } from "../types-BeEJm-DV.mjs";
3
+ import { l as PermissionCheck } from "../base-HXNgPQww.mjs";
4
4
  import { OutboxStore } from "@classytic/primitives/outbox";
5
5
  /**
6
6
  * A store that can answer an operator's questions.
@@ -1,8 +1,8 @@
1
- /*! @classytic/arc v2.47.0 | MIT | https://classytic.com */
2
- import { i as NotFoundError, u as ValidationError } from "../errors-DnrUChAy.mjs";
3
- import { t as defineResource } from "../defineResource-BROJmhzJ.mjs";
4
- import { n as getModuleExports, t as defineModule } from "../module-BD8xHgrz.mjs";
5
- import { r as readOutboxHealth } from "../health-CRJg3IIq.mjs";
1
+ /*! @classytic/arc v2.49.0 | MIT | https://classytic.com */
2
+ import { t as defineResource } from "../defineResource-BAzNu5Um.mjs";
3
+ import { r as readOutboxHealth } from "../health-DN_pUVMX.mjs";
4
+ import { n as getModuleExports, t as defineModule } from "../module-CWiqsXnh.mjs";
5
+ import { i as NotFoundError, u as ValidationError } from "../errors-BpYV859Y.mjs";
6
6
  // src/outbox-admin/module.ts
7
7
  /**
8
8
  * Strip the domain payload and the stack unless explicitly opted in.
@@ -1,10 +1,10 @@
1
- /*! @classytic/arc v2.47.0 | MIT | https://classytic.com */
2
- import { t as transactionContext } from "./transactionContext-8qKON0Nk.mjs";
3
- import { n as requestContext } from "./requestContext-fWb_YaV2.mjs";
4
- import { i as resolveEventTransport } from "./EventTransport-BHKy4_Bi.mjs";
5
- import { t as EventOutbox } from "./relay-BNrC1CEP.mjs";
6
- import { t as emitObserved } from "./eventPlugin-BhKLUe7H.mjs";
7
- import { n as canReportHealth, r as readOutboxHealth } from "./health-CRJg3IIq.mjs";
1
+ /*! @classytic/arc v2.49.0 | MIT | https://classytic.com */
2
+ import { n as requestContext } from "./requestContext-tUgLt9Ky.mjs";
3
+ import { t as transactionContext } from "./transactionContext-DBbSTfY3.mjs";
4
+ import { i as resolveEventTransport } from "./EventTransport-DbHZK230.mjs";
5
+ import { t as emitObserved } from "./eventPlugin-D7LYtYzL.mjs";
6
+ import { n as canReportHealth, r as readOutboxHealth } from "./health-DN_pUVMX.mjs";
7
+ import { t as EventOutbox } from "./relay-DEIoMntZ.mjs";
8
8
  import { randomBytes } from "node:crypto";
9
9
  import { hostname } from "node:os";
10
10
  // src/events/outbox-module.ts
@@ -47,6 +47,9 @@ const DEFAULT_RELAY_EVERY_MS = 5e3;
47
47
  const DEFAULT_PROBE_CACHE_MS = 5e3;
48
48
  /** How often an unhealthy outbox is logged. See `health.alertEveryMs`. */
49
49
  const DEFAULT_HEALTH_ALERT_EVERY_MS = 3e5;
50
+ /** First pause after a pass that lost leases; doubles per consecutive losing pass. */
51
+ const LEASE_LOSS_BACKOFF_BASE_MS = 1e3;
52
+ const LEASE_LOSS_BACKOFF_MAX_MS = 3e4;
50
53
  /**
51
54
  * One relay identity per RELAY INSTANCE — `<name>:<hostname>:<pid>:<random>`.
52
55
  *
@@ -101,6 +104,8 @@ function mintConsumerId(name) {
101
104
  function createOutboxModule(options) {
102
105
  const name = options.name ?? "outbox";
103
106
  const relayEveryMs = options.relayEveryMs ?? DEFAULT_RELAY_EVERY_MS;
107
+ const maxPassesPerTick = options.maxPassesPerTick ?? 1;
108
+ if (!Number.isInteger(maxPassesPerTick) || maxPassesPerTick < 1) throw new Error(`Outbox module "${name}": maxPassesPerTick must be an integer >= 1, got ${String(options.maxPassesPerTick)}.`);
104
109
  const lagUnhealthyMs = (options.health === false ? void 0 : options.health?.relayLagUnhealthyMs) ?? 3e5;
105
110
  const probeCacheMs = (options.health === false ? void 0 : options.health?.probeCacheMs) ?? DEFAULT_PROBE_CACHE_MS;
106
111
  if (!Number.isFinite(probeCacheMs) || probeCacheMs < 0) throw new Error(`Outbox module "${name}": health.probeCacheMs must be a non-negative number, got ${String(probeCacheMs)}.`);
@@ -138,6 +143,8 @@ function createOutboxModule(options) {
138
143
  * depends on for exactly-once publishing.
139
144
  */
140
145
  let exports;
146
+ /** The untyped single-flight lane, built at bootstrap; the schedule runs in it too. */
147
+ let backlogLane;
141
148
  /** Passes THIS module started (nudge, schedule) that have not settled — `drain()` waits on them. */
142
149
  const inFlightPasses = /* @__PURE__ */ new Set();
143
150
  const trackPass = (pass) => {
@@ -148,6 +155,72 @@ function createOutboxModule(options) {
148
155
  pass.then(untrack, untrack);
149
156
  return pass;
150
157
  };
158
+ /**
159
+ * Up to `maxPassesPerTick` `relayBatch()` calls, continuing while the previous pass
160
+ * claimed rows AND relayed something. A pass of only failures stops the loop: those rows
161
+ * are backing off, and another pass would only re-claim the next batch into the same
162
+ * outage. A pass that claimed nothing ends it.
163
+ *
164
+ * "Fewer than `batchSize`" does NOT end it: a store may cap one claim below
165
+ * `batchSize` (a repository's page `maxLimit`, 100 by default in mongokit), and a
166
+ * clamped page would read as "backlog empty" and strand the rest until the next tick.
167
+ * The price is one empty claim after the backlog clears.
168
+ */
169
+ const relayPasses = async (relay, types) => {
170
+ if (backingOff()) return false;
171
+ let passes = 0;
172
+ for (;;) {
173
+ const r = await relay.relayBatch(types ? { types } : void 0);
174
+ passes++;
175
+ if (observeLeaseLoss(r)) return true;
176
+ if (passes >= maxPassesPerTick || !(r.attempted > 0) || r.relayed === 0) return true;
177
+ }
178
+ };
179
+ /**
180
+ * Lease-loss back-off. A pass whose ack or fail met an ownership mismatch lost
181
+ * rows to another claimant: relaying again at once only re-claims into the same
182
+ * contention. Passes pause for 1 s, doubling per consecutive losing pass up to
183
+ * 30 s, and the loss is logged ONCE per pass with counts — the default `onError`
184
+ * no longer logs it per row.
185
+ */
186
+ let leaseLossStreak = 0;
187
+ let backoffUntil = 0;
188
+ const backingOff = () => Date.now() < backoffUntil;
189
+ const observeLeaseLoss = (r) => {
190
+ const lost = r.ownershipMismatches ?? 0;
191
+ if (lost > 0) {
192
+ leaseLossStreak++;
193
+ const backoffMs = Math.min(LEASE_LOSS_BACKOFF_BASE_MS * 2 ** (leaseLossStreak - 1), LEASE_LOSS_BACKOFF_MAX_MS);
194
+ backoffUntil = Date.now() + backoffMs;
195
+ log?.warn({
196
+ marker: "OUTBOX_LEASE_LOST",
197
+ outbox: name,
198
+ ownershipMismatches: lost,
199
+ attempted: r.attempted,
200
+ relayed: r.relayed,
201
+ leaseDeferred: r.leaseDeferred ?? 0,
202
+ consecutivePasses: leaseLossStreak,
203
+ backoffMs
204
+ }, `outbox relay "${name}" lost ${lost} lease(s) to another claimant; backing off ${backoffMs} ms`);
205
+ return true;
206
+ }
207
+ if (r.attempted > 0) leaseLossStreak = 0;
208
+ return false;
209
+ };
210
+ /** A requested pass that met the back-off reruns when it ends (one timer per lane). */
211
+ const retryTimers = /* @__PURE__ */ new Set();
212
+ let closed = false;
213
+ const retryAfterBackoff = (lane, armed) => {
214
+ if (closed || armed.timer) return;
215
+ armed.timer = true;
216
+ const timer = setTimeout(() => {
217
+ retryTimers.delete(timer);
218
+ armed.timer = false;
219
+ lane.request();
220
+ }, Math.max(0, backoffUntil - Date.now()));
221
+ timer.unref?.();
222
+ retryTimers.add(timer);
223
+ };
151
224
  return {
152
225
  name,
153
226
  bootstrap: (fastify) => {
@@ -180,6 +253,13 @@ function createOutboxModule(options) {
180
253
  ...options.leaseMs !== void 0 ? { leaseMs: options.leaseMs } : {},
181
254
  consumerId: options.consumerId ?? mintConsumerId(name),
182
255
  onError: options.onError ?? ((info) => {
256
+ if (info.kind === "ownership_mismatch") {
257
+ fastify.log.debug({
258
+ kind: info.kind,
259
+ eventId: info.event?.meta.id
260
+ }, `outbox relay "${name}" lost a lease`);
261
+ return;
262
+ }
183
263
  fastify.log.error({
184
264
  err: info.error,
185
265
  kind: info.kind,
@@ -191,25 +271,52 @@ function createOutboxModule(options) {
191
271
  ...options.sessionProvider === false ? {} : { sessionProvider: options.sessionProvider ?? (() => transactionContext.get()) }
192
272
  });
193
273
  /**
194
- * One pass per burst of requests. `drainQueued` stays true from the
195
- * first request until the pass STARTS, so a request landing mid-pass
196
- * schedules the next one — a row written during a pass is never left
197
- * waiting for the interval.
274
+ * Two single-flight lanes: `backlog` (untyped nudges, the scheduled tick,
275
+ * `drain()`) and `priority` (typed nudges, so an alarm never waits behind
276
+ * a slow backlog pass). Each runs at most ONE pass at a time; a request
277
+ * during a pass queues exactly one follow-up that starts after it ends.
278
+ * Overlapping passes were the livelock: the newer one re-claimed the older
279
+ * one's expired rows, both ran the handlers, and the older ack failed.
280
+ *
281
+ * `exit` — NOT merely cosmetic. The lane's `setImmediate` preserves the
282
+ * caller's AsyncLocalStorage store, and the caller is a REQUEST (that is the
283
+ * documented use: drain the row I just committed). A pass drains whatever is
284
+ * pending, so without this every event in the batch — including rows written
285
+ * by other requests, for other tenants — dispatches inside the triggering
286
+ * request's scope: `runWorkScope` inherits it rather than opening the
287
+ * event's own, handlers read that request's `user`/`organizationId`/
288
+ * `requestScopedCache`, and a child event published from one is stamped
289
+ * with its `requestId` as `correlationId`. A relay pass belongs to no
290
+ * request; say so.
198
291
  */
199
- let drainQueued = false;
200
- const requestDrain = () => {
201
- if (drainQueued) return;
202
- drainQueued = true;
203
- let passDone = () => {};
204
- trackPass(new Promise((resolve) => passDone = resolve));
205
- setImmediate(() => {
206
- drainQueued = false;
207
- requestContext.storage.exit(() => {
208
- relay.relayBatch().catch((err) => {
209
- fastify.log.error({ err }, `outbox relay "${name}" requested drain failed`);
210
- }).finally(passDone);
211
- });
212
- });
292
+ const scopeFree = (fn) => requestContext.storage.exit(fn).catch((err) => {
293
+ fastify.log.error({ err }, `outbox relay "${name}" requested drain failed`);
294
+ });
295
+ const backlogArmed = { timer: false };
296
+ const backlog = createPassLane(() => scopeFree(async () => {
297
+ if (!await relayPasses(relay)) retryAfterBackoff(backlog, backlogArmed);
298
+ }), trackPass);
299
+ /** Types asked for by typed requests not yet taken by a priority pass. */
300
+ let typesQueued = null;
301
+ const priorityArmed = { timer: false };
302
+ const priority = createPassLane(() => scopeFree(async () => {
303
+ const typed = typesQueued ? [...typesQueued] : void 0;
304
+ typesQueued = null;
305
+ if (!typed) return;
306
+ if (!await relayPasses(relay, typed)) {
307
+ typesQueued ??= /* @__PURE__ */ new Set();
308
+ for (const t of typed) typesQueued.add(t);
309
+ retryAfterBackoff(priority, priorityArmed);
310
+ }
311
+ }), trackPass);
312
+ backlogLane = backlog;
313
+ const requestDrain = (options) => {
314
+ const types = Array.isArray(options?.types) ? options.types.filter((t) => typeof t === "string" && t.length > 0) : [];
315
+ if (types.length > 0) {
316
+ typesQueued ??= /* @__PURE__ */ new Set();
317
+ for (const t of types) typesQueued.add(t);
318
+ priority.request();
319
+ } else backlog.request();
213
320
  };
214
321
  const drain = ({ maxPasses = 100 } = {}) => requestContext.storage.exit(async () => {
215
322
  const total = {
@@ -219,15 +326,18 @@ function createOutboxModule(options) {
219
326
  deadLettered: 0,
220
327
  drained: false
221
328
  };
329
+ let deferred = false;
222
330
  while (total.passes < maxPasses) {
223
331
  if (inFlightPasses.size > 0) await Promise.allSettled([...inFlightPasses]);
224
- const r = await relay.relayBatch();
332
+ const r = await backlog.exclusive(() => relay.relayBatch());
333
+ observeLeaseLoss(r);
225
334
  total.passes++;
226
335
  total.relayed += r.relayed;
227
336
  total.publishFailed += r.publishFailed;
228
337
  total.deadLettered += r.deadLettered;
338
+ if ((r.leaseDeferred ?? 0) > 0) deferred = true;
229
339
  if (r.attempted === 0 && inFlightPasses.size === 0) {
230
- total.drained = true;
340
+ total.drained = !deferred;
231
341
  break;
232
342
  }
233
343
  }
@@ -246,6 +356,12 @@ function createOutboxModule(options) {
246
356
  };
247
357
  return exports;
248
358
  },
359
+ /** Stop back-off retries; a timer firing after close would relay into a closed store. */
360
+ onClose: () => {
361
+ closed = true;
362
+ for (const timer of retryTimers) clearTimeout(timer);
363
+ retryTimers.clear();
364
+ },
249
365
  ...options.health === false ? {} : { healthChecks: [{
250
366
  name: `${name}.relay`,
251
367
  critical: false,
@@ -261,7 +377,10 @@ function createOutboxModule(options) {
261
377
  every: relayEveryMs,
262
378
  runOnStart: options.runOnStart ?? true,
263
379
  handler: async () => {
264
- if (exports) await trackPass(exports.relay.relay());
380
+ if (exports && backlogLane) {
381
+ const relay = exports.relay;
382
+ await trackPass(backlogLane.exclusive(() => relayPasses(relay)));
383
+ }
265
384
  }
266
385
  }, ...alertEveryMs > 0 ? [{
267
386
  name: `${name}.health`,
@@ -294,4 +413,54 @@ function createOutboxModule(options) {
294
413
  }] : []]
295
414
  };
296
415
  }
416
+ /**
417
+ * `run` must not reject. A requested pass is tracked from the REQUEST, not from
418
+ * its start, so `drain()` called right after a nudge waits for that pass.
419
+ */
420
+ function createPassLane(run, track) {
421
+ let busy;
422
+ /** Resolves the tracked promise of the queued (not yet started) pass. */
423
+ let queuedDone;
424
+ let scheduled = false;
425
+ const schedule = () => {
426
+ if (scheduled) return;
427
+ scheduled = true;
428
+ setImmediate(start);
429
+ };
430
+ const release = () => {
431
+ busy = void 0;
432
+ if (queuedDone) schedule();
433
+ };
434
+ function start() {
435
+ scheduled = false;
436
+ if (busy !== void 0 || !queuedDone) return;
437
+ const done = queuedDone;
438
+ queuedDone = void 0;
439
+ busy = run().finally(() => {
440
+ done();
441
+ release();
442
+ });
443
+ }
444
+ return {
445
+ request() {
446
+ if (!queuedDone) {
447
+ let resolve = () => {};
448
+ track(new Promise((r) => resolve = r));
449
+ queuedDone = resolve;
450
+ }
451
+ if (busy === void 0) schedule();
452
+ },
453
+ async exclusive(fn) {
454
+ while (busy !== void 0) await busy.catch(() => {});
455
+ let done = () => {};
456
+ busy = new Promise((r) => done = r);
457
+ try {
458
+ return await fn();
459
+ } finally {
460
+ done();
461
+ release();
462
+ }
463
+ }
464
+ };
465
+ }
297
466
  export { createOutboxModule as t };
@@ -1,6 +1,6 @@
1
1
 
2
- import { a as EventTransport, n as DomainEvent, t as DeadLetteredEvent } from "./EventTransport-CYEoCJGe.mjs";
3
2
  import { n as ArcModule } from "./types-BeEJm-DV.mjs";
3
+ import { a as EventTransport, n as DomainEvent, t as DeadLetteredEvent } from "./EventTransport-CYEoCJGe.mjs";
4
4
  import { FastifyInstance } from "fastify";
5
5
  import { OutboxFailurePolicy, OutboxStore, OutboxWriteOptions } from "@classytic/primitives/outbox";
6
6
  import { MemoryOutboxStore } from "@classytic/primitives/memory-outbox";
@@ -26,6 +26,14 @@ type OutboxRelayErrorKind = "publish_failed" | "acknowledge_failed" | "fail_fail
26
26
  * The simpler {@link EventOutbox.relay} returns just the `relayed` count for
27
27
  * backward compatibility.
28
28
  */
29
+ /** Options for one {@link EventOutbox.relayBatch} pass. */
30
+ interface RelayBatchOptions {
31
+ /**
32
+ * Claim only events of these types (exact names). A priority pass: rows of
33
+ * other types stay pending for the next untyped pass. Empty = all types.
34
+ */
35
+ readonly types?: readonly string[];
36
+ }
29
37
  interface RelayResult {
30
38
  /** Number of events successfully published AND acknowledged */
31
39
  readonly relayed: number;
@@ -57,6 +65,12 @@ interface RelayResult {
57
65
  readonly claimMs?: number;
58
66
  /** Wall-clock ms spent publishing + acknowledging the batch. */
59
67
  readonly publishMs?: number;
68
+ /**
69
+ * Claimed rows NOT published because the lease budget ran out first. They
70
+ * stay leased to this relay and are re-claimed (unpublished) after expiry;
71
+ * counted in `attempted`.
72
+ */
73
+ readonly leaseDeferred?: number;
60
74
  }
61
75
  /**
62
76
  * Called by {@link EventOutbox.relay} when a non-fatal error occurs during
@@ -97,6 +111,10 @@ interface EventOutboxOptions {
97
111
  /**
98
112
  * Lease duration in ms for claimed events. Only used when the store
99
113
  * supports `claimPending`. Default: 30 seconds.
114
+ *
115
+ * A pass publishes a claimed row only while its lease has budget left, and
116
+ * sizes later claims to fit the lease from the measured per-event time, so
117
+ * this must exceed the slowest SINGLE publish + ack, not a whole batch.
100
118
  */
101
119
  readonly leaseMs?: number;
102
120
  /**
@@ -196,9 +214,20 @@ declare class EventOutbox {
196
214
  * durable count wins — see the failure path in `relayBatch`.
197
215
  */
198
216
  private readonly _attempts;
217
+ /**
218
+ * Measured ms per event (publish + ack), rising at once on a slower batch and
219
+ * decaying slowly. Undefined until a batch has published something.
220
+ */
221
+ private _perEventMs;
199
222
  constructor(opts: EventOutboxOptions);
200
223
  /** Unique consumer ID used for lease ownership when the store supports claims */
201
224
  get consumerId(): string;
225
+ /**
226
+ * Rows claimed per {@link relayBatch} (the `batchSize` option, default 100), lowered to
227
+ * the store's `claimCap` once a claim came back clamped (`repositoryAsOutboxStore`).
228
+ * A pass that attempted this many rows hit the limit, so more may be pending.
229
+ */
230
+ get batchSize(): number;
202
231
  /**
203
232
  * Store event in outbox.
204
233
  *
@@ -252,9 +281,33 @@ declare class EventOutbox {
252
281
  * claimed the event), the event is NOT counted as relayed. The other
253
282
  * worker will re-publish — at-least-once semantics preserved.
254
283
  *
284
+ * - **Types**: `options.types` claims only events of those types (exact
285
+ * names, oldest first), so a priority pass is not queued behind a backlog
286
+ * of other types. Needs a store with `claimPending` / `claimPendingFenced`
287
+ * (both honour `OutboxClaimOptions.types`); on the single-worker
288
+ * `getPending` fallback the filter is ignored and the oldest rows go out.
289
+ *
290
+ * - **Lease budget**: on a leasing store each row is published only while
291
+ * the claim's lease has budget left, and acked right after its publish.
292
+ * Rows past the budget are not published (`leaseDeferred`); they are
293
+ * re-claimed after expiry. The claim size adapts to the measured per-event
294
+ * time so a batch fits the lease. See wiki/delivery-guarantees.md.
295
+ *
255
296
  * @returns Per-kind outcome counts for the batch
256
297
  */
257
- relayBatch(): Promise<RelayResult>;
298
+ relayBatch(options?: RelayBatchOptions): Promise<RelayResult>;
299
+ /**
300
+ * Rows to claim: `batchSize`, or fewer when the measured per-event time says a
301
+ * full batch would outlive {@link LEASE_CLAIM_FRACTION} of the lease.
302
+ */
303
+ private _claimLimit;
304
+ private _recordPerEventMs;
305
+ private _notifyPublished;
306
+ /**
307
+ * Ack a published event, or `fail()` a rejected one. Returns `true` when the
308
+ * batch must stop (a failure on a store without `fail`).
309
+ */
310
+ private _settle;
258
311
  /**
259
312
  * Fetch current dead-lettered events as typed {@link DeadLetteredEvent}
260
313
  * envelopes. Delegates to {@link OutboxStore.getDeadLettered} — returns
@@ -299,7 +352,29 @@ interface OutboxModuleOptions {
299
352
  * throughput tuning decision, not something this module should invent.
300
353
  */
301
354
  batchSize?: number;
302
- /** Lease duration for a claimed batch, in ms. */
355
+ /**
356
+ * Upper bound on relay passes per scheduled tick and per {@link OutboxModuleExports.requestDrain}.
357
+ * Default `1`: one `relayBatch()` per tick, as before this option existed.
358
+ *
359
+ * With a value above 1 the module keeps relaying in the same tick while the last pass claimed
360
+ * rows (`attempted > 0`) and relayed something (`relayed > 0`). A pass that claimed or relayed
361
+ * nothing ends the loop; a pass that claimed fewer than `batchSize` rows does not, so a store
362
+ * whose claim is capped below `batchSize` still drains. A backlog of 250 rows with
363
+ * `batchSize: 100` then clears in one tick instead of three intervals, at the price of one extra
364
+ * empty claim after the backlog clears (4 passes). A pass where every publish failed stops the
365
+ * loop, so a transport outage never spins. The whole loop is one tracked pass, so `drain()`
366
+ * waits for it. Must be an integer >= 1.
367
+ *
368
+ * Keep `maxPassesPerTick × batchSize` relays inside the relay schedule's lock lease. A longer
369
+ * tick is safe on a store with claim leases (`claimPending`), but on the single-worker
370
+ * `getPending` fallback a second worker could start relaying the same rows.
371
+ */
372
+ maxPassesPerTick?: number;
373
+ /**
374
+ * Lease duration for a claimed batch, in ms (`EventOutbox` default 30 000). Must
375
+ * exceed the slowest single publish + ack: the relay stops publishing a batch when
376
+ * its lease budget runs out and sizes later claims to fit it.
377
+ */
303
378
  leaseMs?: number;
304
379
  /**
305
380
  * Consumer id recorded on the lease. Default:
@@ -322,7 +397,9 @@ interface OutboxModuleOptions {
322
397
  * Called for every non-fatal relay problem — publish failures, ownership mismatches,
323
398
  * acknowledge failures.
324
399
  *
325
- * Omit to report through the Arc app's structured logger. Override for metrics, tracing, or
400
+ * Omit to report through the Arc app's structured logger; there `ownership_mismatch` is
401
+ * logged once per pass as a `marker: 'OUTBOX_LEASE_LOST'` warning with counts (per row at
402
+ * debug), and the relay backs off. Override for metrics, tracing, or
326
403
  * external alerting. Silence here is the failure mode that matters: the relay keeps ticking,
327
404
  * rows keep failing, and the only symptom is revenue that never posted.
328
405
  *
@@ -415,12 +492,27 @@ interface OutboxDrainResult {
415
492
  publishFailed: number;
416
493
  deadLettered: number;
417
494
  /**
418
- * `true` once a pass found nothing VISIBLE to claim. Rows backing off after a failed
419
- * publish are invisible until their retry time, so read `publishFailed` too.
495
+ * `true` once a pass found nothing VISIBLE to claim and no claimed row was left
496
+ * unpublished for lack of lease budget (`RelayResult.leaseDeferred`; those stay
497
+ * leased until expiry). Rows backing off after a failed publish are invisible until
498
+ * their retry time, so read `publishFailed` too.
420
499
  */
421
500
  drained: boolean;
422
501
  }
423
502
  /** What the module exports at `fastify.arc.modules.<name>`. */
503
+ /** Options for {@link OutboxModuleExports.requestDrain}. */
504
+ interface OutboxDrainRequest {
505
+ /**
506
+ * Relay only events of these types (exact names), oldest first, ahead of the rest of
507
+ * the backlog: a priority nudge for rows that must not wait behind thousands of others
508
+ * (an alarm committed while a bulk import drains). Coalesced with other typed requests
509
+ * into one pass, in its own single-flight lane, so it never waits behind a running
510
+ * untyped pass. Uses the
511
+ * store's `claimPending({ types })`; on a store with only `getPending` the filter is
512
+ * ignored. Empty or absent = an ordinary untyped nudge.
513
+ */
514
+ types?: readonly string[];
515
+ }
424
516
  interface OutboxModuleExports {
425
517
  /** The store, for consumers that write events transactionally. */
426
518
  store: OutboxStore;
@@ -431,14 +523,15 @@ interface OutboxModuleExports {
431
523
  * any number of calls before the pass runs produce ONE pass. Never throws
432
524
  * and returns nothing — a unit of work calls this after commit so a row it
433
525
  * just wrote is delivered in milliseconds rather than up to `relayEveryMs`
434
- * later. Safe under concurrency: the store's lease and fence token make an
435
- * extra pass a no-op, not a double publish.
526
+ * later. Single-flight: a call while a pass runs queues exactly ONE
527
+ * follow-up that starts when it ends, never a concurrent pass. During a
528
+ * lease-loss back-off the pass runs when the back-off ends.
436
529
  *
437
530
  * Calling from inside a request does NOT put the pass in that request's
438
531
  * scope: a pass drains whatever is pending, which is other requests' rows.
439
532
  * The pass runs scope-free, so each event opens its own (see `runWorkScope`).
440
533
  */
441
- requestDrain: () => void;
534
+ requestDrain: (options?: OutboxDrainRequest) => void;
442
535
  /**
443
536
  * Relay passes until nothing visible is pending, and resolve with the totals —
444
537
  * including events published BY the handlers it ran. For tests that assert what
@@ -482,4 +575,4 @@ interface OutboxModuleExports {
482
575
  * boot error naming the module that needed it.
483
576
  */
484
577
  declare function createOutboxModule(options: OutboxModuleOptions): ArcModule<OutboxModuleExports>;
485
- export { MemoryOutboxStore as a, OutboxRelayErrorHandler as c, DEFAULT_RELAY_LAG_UNHEALTHY_MS as d, OutboxHealth as f, createOutboxModule as i, OutboxRelayErrorKind as l, readOutboxHealth as m, OutboxModuleExports as n, EventOutbox as o, OutboxHealthStore as p, OutboxModuleOptions as r, EventOutboxOptions as s, OutboxDrainResult as t, RelayResult as u };
578
+ export { createOutboxModule as a, EventOutboxOptions as c, RelayBatchOptions as d, RelayResult as f, readOutboxHealth as g, OutboxHealthStore as h, OutboxModuleOptions as i, OutboxRelayErrorHandler as l, OutboxHealth as m, OutboxDrainResult as n, MemoryOutboxStore as o, DEFAULT_RELAY_LAG_UNHEALTHY_MS as p, OutboxModuleExports as r, EventOutbox as s, OutboxDrainRequest as t, OutboxRelayErrorKind as u };