@reventlessdev/reventless-core 3.0.0-alpha.171 → 3.0.0-alpha.173

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 3.0.0-alpha.173 (2026-07-20)
+
+### Features
+
+* **core:** annotate comp + causationId at the dispatch boundary ([ef6d56d](https://github.com/ReventlessDev/reventless-core/commit/ef6d56d0104dbdb21b7cfbb8f3b2b1ead9787595))
+
+
+# 3.0.0-alpha.172 (2026-07-17)
+
+### Bug Fixes
+
+* **plugin:** scale heartbeat disconnect grace and enforce single-source interval ([7ba8fb7](https://github.com/ReventlessDev/reventless-core/commit/7ba8fb7bfbe023aba7b538329d2489f939b7fcea))
+
+
 # 3.0.0-alpha.171 (2026-07-17)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-core",
-  "version": "3.0.0-alpha.171",
+  "version": "3.0.0-alpha.173",
   "description": "Core package for Reventless framework",
   "license": "Apache-2.0",
   "jest": {
@@ -30,15 +30,15 @@
     "uuid": "^13.0.0",
     "@reventlessdev/rescript-effect": "0.1.0-alpha.29",
     "@reventlessdev/rescript-hash-object": "1.2.0-alpha.13",
-    "@reventlessdev/rescript-node-streams": "1.1.0-alpha.13",
-    "@reventlessdev/rescript-jest": "1.0.0-alpha.9",
     "@reventlessdev/rescript-fast-csv": "1.2.0-alpha.14",
+    "@reventlessdev/rescript-jest": "1.0.0-alpha.9",
+    "@reventlessdev/rescript-node-streams": "1.1.0-alpha.13",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.17",
     "@reventlessdev/rescript-ssh2": "1.1.0-alpha.14",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.102",
-    "@reventlessdev/reventless-interop": "3.0.0-alpha.28",
     "@reventlessdev/rescript-uuid": "1.1.0-alpha.17",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.79"
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.102",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.79",
+    "@reventlessdev/reventless-interop": "3.0.0-alpha.28"
   },
   "devDependencies": {
     "rescript": "12.3.0",

package/src/RequestContext.res

@@ -14,14 +14,42 @@
 // In tests:
 //   ->Effect.provideService(RequestContext.tag, RequestContext.test())
 
+// `causationId` = the direct-parent msgId of the message that triggered this
+// invocation (Message.deriveMeta propagates it); reconstructs the parent → child
+// causal chain within one `correlationId`. `component` / `pluginName` identify the
+// component and plugin handling the invocation — mirror the `comp` / `plugin` log
+// fields so a consumer of this service sees the same attribution the logs carry.
+// All three are optional: absent in `.test()` and wherever the dispatch site has
+// no value to supply.
 type t = {
   correlationId: string,
+  causationId?: string,
+  component?: string,
+  pluginName?: string,
   identity: Reventless.Identity.t,
   claims: dict<string>,
 }
 
 let tag: Context.tag<t> = Context.genericTag("reventless/RequestContext")
 
+// Real dispatch-boundary constructor. Use this at runtime dispatch points
+// (see Runtime.runEffect); `test` is test-only.
+let make = (
+  ~correlationId,
+  ~causationId=?,
+  ~component=?,
+  ~pluginName=?,
+  ~identity=Reventless.Identity.anonymous,
+  ~claims=Dict.make(),
+): t => {
+  correlationId,
+  causationId: ?causationId,
+  component: ?component,
+  pluginName: ?pluginName,
+  identity,
+  claims,
+}
+
 let getClaim = (ctx: t, key: string): option<string> =>
   ctx.claims->Dict.get(key)
 

package/src/RequestContext.res.mjs

@@ -5,6 +5,19 @@ import * as Identity$Reventless from "@reventlessdev/reventless-spec/src/types/I
 
 let tag = Context.GenericTag("reventless/RequestContext");
 
+function make(correlationId, causationId, component, pluginName, identityOpt, claimsOpt) {
+  let identity = identityOpt !== undefined ? identityOpt : Identity$Reventless.anonymous;
+  let claims = claimsOpt !== undefined ? claimsOpt : ({});
+  return {
+    correlationId: correlationId,
+    causationId: causationId,
+    component: component,
+    pluginName: pluginName,
+    identity: identity,
+    claims: claims
+  };
+}
+
 function getClaim(ctx, key) {
   return ctx.claims[key];
 }
@@ -12,11 +25,9 @@ function getClaim(ctx, key) {
 function withClaim(ctx, key, value) {
   let next = Object.fromEntries(Object.entries(ctx.claims));
   next[key] = value;
-  return {
-    correlationId: ctx.correlationId,
-    identity: ctx.identity,
-    claims: next
-  };
+  let newrecord = {...ctx};
+  newrecord.claims = next;
+  return newrecord;
 }
 
 function test(correlationIdOpt, identityOpt, claimsOpt) {
@@ -32,6 +43,7 @@ function test(correlationIdOpt, identityOpt, claimsOpt) {
 
 export {
   tag,
+  make,
   getClaim,
   withClaim,
   test,

package/src/adapter/Runtime/AggregateRuntime_Builder_Common.res

@@ -31,26 +31,21 @@ module Make = (
   let commandTopicHandlers: dict<effectHandler> = Dict.make()
   let eventCollectorHandlers: dict<array<effectHandler>> = Dict.make()
 
-  let runEffect = (~correlationId=?, effect) => {
-    let cid = correlationId->Option.getOr("unknown")
-    effect
-    // Annotate the request scope so every EffectLogger call inside the handler
-    // carries correlationId as a top-level JSON field (decoded in install()).
-    ->Effect.annotateLogs("correlationId", cid)
-    ->Effect.provideService(RequestContext.tag, RequestContext.test(~correlationId=cid))
-    ->Effect.runPromise
-  }
-
   let aggregateHandler = aggregateName =>
     async (event: RuntimeEnvironment.event, context) => {
       let correlationId = event->RuntimeEnvironment.extractCorrelationId
+      let causationId = event->RuntimeEnvironment.extractCausationId
       let comp = `AggregateRuntime(${aggregateName})`
+      // Shared dispatch helper (Runtime.runEffect) annotates correlationId / comp /
+      // causationId onto the invocation so the application handler's own log lines
+      // carry them without re-logging by hand.
+      let runEffect = effect => Runtime.runEffect(~correlationId?, ~causationId?, ~comp, effect)
       switch event->CommandGenerator.metaInfo {
       | Some(info) =>
         switch commandGeneratorHandlers->Dict.get(info) {
         | Some(handler) =>
           EffectLogger.logDebug(~comp, `found CommandGenerator handler for ${info}`)->Effect.runSync
-          let _ = await runEffect(~correlationId?, handler(event->CommandGenerator.asPayload, context))
+          let _ = await runEffect(handler(event->CommandGenerator.asPayload, context))
         | None =>
           let available = commandGeneratorHandlers->Dict.keysToArray->Array.join(",")
           EffectLogger.logWarn(
@@ -66,7 +61,7 @@ module Make = (
           switch commandTopicHandlers->Dict.get(urn) {
           | Some(handler) =>
             EffectLogger.logDebug(~comp, `found CommandTopic handler for ${urn}`)->Effect.runSync
-            await runEffect(~correlationId?, handler(event, context))
+            await runEffect(handler(event, context))
           | None =>
             switch eventCollectorHandlers->Dict.get(urn) {
             | Some(handlers) =>
@@ -76,7 +71,7 @@ module Make = (
                 `found ${count} EventCollector handler(s) for ${urn}`,
               )->Effect.runSync
               let _ = await handlers
-              ->Array.map(handler => runEffect(~correlationId?, handler(event, context)))
+              ->Array.map(handler => runEffect(handler(event, context)))
               ->Promise.all
             | None =>
               let available =

package/src/adapter/Runtime/AggregateRuntime_Builder_Common.res.mjs

@@ -6,9 +6,9 @@ import * as Effect from "effect/Effect";
 import * as Pulumi from "@pulumi/pulumi";
 import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
 import * as Logger$ReventlessCore from "../../util/Logger.res.mjs";
+import * as Runtime$ReventlessCore from "./Runtime.res.mjs";
 import * as Component$ReventlessCore from "../../components/Component.res.mjs";
 import * as EffectLogger$ReventlessCore from "../../util/EffectLogger.res.mjs";
-import * as RequestContext$ReventlessCore from "../../RequestContext.res.mjs";
 import * as CommandGenerator$ReventlessCore from "../../components/CommandGenerator/CommandGenerator.res.mjs";
 
 function Make(RuntimeEnvironment) {
@@ -18,19 +18,17 @@ function Make(RuntimeEnvironment) {
     let commandGeneratorHandlers = {};
     let commandTopicHandlers = {};
     let eventCollectorHandlers = {};
-    let runEffect = (correlationId, effect) => {
-      let cid = Stdlib_Option.getOr(correlationId, "unknown");
-      return Effect.runPromise(Effect.provideService(Effect.annotateLogs(effect, "correlationId", cid), RequestContext$ReventlessCore.tag, RequestContext$ReventlessCore.test(cid, undefined, undefined)));
-    };
     let aggregateHandler = aggregateName => (async (event, context) => {
       let correlationId = RuntimeEnvironment.extractCorrelationId(event);
+      let causationId = RuntimeEnvironment.extractCausationId(event);
       let comp = `AggregateRuntime(` + aggregateName + `)`;
+      let runEffect = effect => Runtime$ReventlessCore.runEffect(correlationId, causationId, comp, undefined, effect);
       let info = CommandGenerator$ReventlessCore.metaInfo(event);
       if (info !== undefined) {
         let handler = commandGeneratorHandlers[info];
         if (handler !== undefined) {
           Effect.runSync(EffectLogger$ReventlessCore.logDebug(comp, undefined, `found CommandGenerator handler for ` + info));
-          await runEffect(correlationId, handler(event, context));
+          await runEffect(handler(event, context));
           return;
         }
         let available = Object.keys(commandGeneratorHandlers).join(",");
@@ -42,13 +40,13 @@ function Make(RuntimeEnvironment) {
         let handler = commandTopicHandlers[urn];
         if (handler !== undefined) {
           Effect.runSync(EffectLogger$ReventlessCore.logDebug(comp, undefined, `found CommandTopic handler for ` + urn));
-          return await runEffect(correlationId, handler(event, context));
+          return await runEffect(handler(event, context));
         }
         let handlers = eventCollectorHandlers[urn];
         if (handlers !== undefined) {
           let count = handlers.length.toString();
           Effect.runSync(EffectLogger$ReventlessCore.logDebug(comp, undefined, `found ` + count + ` EventCollector handler(s) for ` + urn));
-          await Promise.all(handlers.map(handler => runEffect(correlationId, handler(event, context))));
+          await Promise.all(handlers.map(handler => runEffect(handler(event, context))));
           return;
         }
         let available = Object.keys(commandTopicHandlers).concat(Object.keys(eventCollectorHandlers)).join(",");
@@ -171,7 +169,6 @@ function Make(RuntimeEnvironment) {
       commandGeneratorHandlers: commandGeneratorHandlers,
       commandTopicHandlers: commandTopicHandlers,
       eventCollectorHandlers: eventCollectorHandlers,
-      runEffect: runEffect,
       aggregateHandler: aggregateHandler,
       getRuntimeSpec: getRuntimeSpec,
       setRuntimeSpec: setRuntimeSpec,

package/src/adapter/Runtime/AggregateRuntime_Builder_Micro.res

@@ -23,10 +23,17 @@ module Make = (
     commandGenerator,
   ) => {
     let resource = commandGenerator->Component.toPulumiResource
+    let name = resource.name->ComponentType.nameOpt(CommandGenerator.componentType)
     let runtime = RuntimeEnvironment.make(
-      ~name=resource.name->ComponentType.nameOpt(CommandGenerator.componentType),
+      ~name,
       ~handler=handler->Pulumi.Output.apply(handler =>
-        handler->RuntimeEnvironment.asEffectHandler->Runtime.runEffectHandler
+        handler
+        ->RuntimeEnvironment.asEffectHandler
+        ->Runtime.runEffectHandler(
+          ~extractCorrelationId=RuntimeEnvironment.extractCorrelationId,
+          ~extractCausationId=RuntimeEnvironment.extractCausationId,
+          ~comp=name,
+        )
       ),
       ~memorySize,
       ~timeout,
@@ -44,10 +51,17 @@ module Make = (
     commandTopic,
   ) => {
     let resource = commandTopic->Component.toPulumiResource
+    let name = resource.name->ComponentType.nameOpt(CommandTopic.componentType)
     let runtime = RuntimeEnvironment.make(
-      ~name=resource.name->ComponentType.nameOpt(CommandTopic.componentType),
+      ~name,
       ~handler=handler->Pulumi.Output.apply(handler =>
-        handler->RuntimeEnvironment.asEffectHandler->Runtime.runEffectHandler
+        handler
+        ->RuntimeEnvironment.asEffectHandler
+        ->Runtime.runEffectHandler(
+          ~extractCorrelationId=RuntimeEnvironment.extractCorrelationId,
+          ~extractCausationId=RuntimeEnvironment.extractCausationId,
+          ~comp=name,
+        )
       ),
       ~memorySize,
       ~timeout,
@@ -72,7 +86,13 @@ module Make = (
     let runtime = RuntimeEnvironment.make(
       ~name,
       ~handler=handler->Pulumi.Output.apply(handler =>
-        handler->RuntimeEnvironment.asEffectHandler->Runtime.runEffectHandler
+        handler
+        ->RuntimeEnvironment.asEffectHandler
+        ->Runtime.runEffectHandler(
+          ~extractCorrelationId=RuntimeEnvironment.extractCorrelationId,
+          ~extractCausationId=RuntimeEnvironment.extractCausationId,
+          ~comp=name,
+        )
       ),
       ~memorySize,
       ~timeout,

package/src/adapter/Runtime/AggregateRuntime_Builder_Micro.res.mjs

@@ -13,7 +13,8 @@ function Make(RuntimeEnvironment) {
       let memorySize = memorySizeOpt !== undefined ? memorySizeOpt : 1024;
       let timeout = timeoutOpt !== undefined ? timeoutOpt : 30;
       let resource = Component$ReventlessCore.toPulumiResource(commandGenerator);
-      return connect(RuntimeEnvironment.make(ComponentType$ReventlessCore.nameOpt(resource.__name, CommandGenerator$ReventlessCore.componentType), handler.apply(handler => Runtime$ReventlessCore.runEffectHandler(RuntimeEnvironment.asEffectHandler(handler))), memorySize, timeout, {
+      let name = ComponentType$ReventlessCore.nameOpt(resource.__name, CommandGenerator$ReventlessCore.componentType);
+      return connect(RuntimeEnvironment.make(name, handler.apply(handler => Runtime$ReventlessCore.runEffectHandler(RuntimeEnvironment.extractCorrelationId, RuntimeEnvironment.extractCausationId, name, undefined, RuntimeEnvironment.asEffectHandler(handler))), memorySize, timeout, {
         parent: resource
       }));
     };
@@ -21,7 +22,8 @@ function Make(RuntimeEnvironment) {
       let memorySize = memorySizeOpt !== undefined ? memorySizeOpt : 1024;
       let timeout = timeoutOpt !== undefined ? timeoutOpt : 30;
       let resource = Component$ReventlessCore.toPulumiResource(commandTopic);
-      return connect(RuntimeEnvironment.make(ComponentType$ReventlessCore.nameOpt(resource.__name, CommandTopic$ReventlessCore.componentType), handler.apply(handler => Runtime$ReventlessCore.runEffectHandler(RuntimeEnvironment.asEffectHandler(handler))), memorySize, timeout, {
+      let name = ComponentType$ReventlessCore.nameOpt(resource.__name, CommandTopic$ReventlessCore.componentType);
+      return connect(RuntimeEnvironment.make(name, handler.apply(handler => Runtime$ReventlessCore.runEffectHandler(RuntimeEnvironment.extractCorrelationId, RuntimeEnvironment.extractCausationId, name, undefined, RuntimeEnvironment.asEffectHandler(handler))), memorySize, timeout, {
         parent: resource
       }));
     };
@@ -34,7 +36,7 @@ function Make(RuntimeEnvironment) {
       let opts = {
         parent: opts_parent
       };
-      let runtime = RuntimeEnvironment.make(name, handler.apply(handler => Runtime$ReventlessCore.runEffectHandler(RuntimeEnvironment.asEffectHandler(handler))), memorySize, timeout, opts);
+      let runtime = RuntimeEnvironment.make(name, handler.apply(handler => Runtime$ReventlessCore.runEffectHandler(RuntimeEnvironment.extractCorrelationId, RuntimeEnvironment.extractCausationId, name, undefined, RuntimeEnvironment.asEffectHandler(handler))), memorySize, timeout, opts);
       EventCollectorChannel.connect(name, [{
           channel: eventCollector.channel,
           eventTopics: eventTopics,

package/src/adapter/Runtime/EventCollectorRuntime_Builder_PerEventCollector.res

@@ -26,7 +26,13 @@ module Make = (
     let runtime = RuntimeEnvironment.make(
       ~name,
       ~handler=handler->Pulumi.Output.apply(handler =>
-        handler->RuntimeEnvironment.asEffectHandler->Runtime.runEffectHandler
+        handler
+        ->RuntimeEnvironment.asEffectHandler
+        ->Runtime.runEffectHandler(
+          ~extractCorrelationId=RuntimeEnvironment.extractCorrelationId,
+          ~extractCausationId=RuntimeEnvironment.extractCausationId,
+          ~comp=name,
+        )
       ),
       ~memorySize,
       ~timeout,

package/src/adapter/Runtime/EventCollectorRuntime_Builder_PerEventCollector.res.mjs

@@ -16,7 +16,7 @@ function Make(RuntimeEnvironment) {
       let opts = {
         parent: opts_parent
       };
-      let runtime = RuntimeEnvironment.make(name, handler.apply(handler => Runtime$ReventlessCore.runEffectHandler(RuntimeEnvironment.asEffectHandler(handler))), memorySize, timeout, {
+      let runtime = RuntimeEnvironment.make(name, handler.apply(handler => Runtime$ReventlessCore.runEffectHandler(RuntimeEnvironment.extractCorrelationId, RuntimeEnvironment.extractCausationId, name, undefined, RuntimeEnvironment.asEffectHandler(handler))), memorySize, timeout, {
         parent: resource
       });
       EventCollectorChannel.connect(name, [{

package/src/adapter/Runtime/EventCollectorRuntime_Builder_Single.res

@@ -35,20 +35,15 @@ module Make = (
   })
   type effectHandler = Runtime.effectHandler<RuntimeEnvironment.event, context, unit, string>
   let eventCollectorHandlers: dict<array<effectHandler>> = Dict.make()
-  let runEffect = (~correlationId=?, effect) => {
-    let cid = correlationId->Option.getOr("unknown")
-    effect
-    // Annotate the request scope so every EffectLogger call inside the handler
-    // carries correlationId as a top-level JSON field (decoded in install()).
-    ->Effect.annotateLogs("correlationId", cid)
-    ->Effect.provideService(RequestContext.tag, RequestContext.test(~correlationId=cid))
-    ->Effect.runPromise
-  }
 
   let eventCollectorHandler = parentName =>
     async (event: RuntimeEnvironment.event, context) => {
       let correlationId = event->RuntimeEnvironment.extractCorrelationId
+      let causationId = event->RuntimeEnvironment.extractCausationId
       let comp = `EventCollectorRuntime(${parentName})`
+      // Shared dispatch helper annotates correlationId / comp / causationId so the
+      // application handler's own log lines carry them (see Runtime.runEffect).
+      let runEffect = effect => Runtime.runEffect(~correlationId?, ~causationId?, ~comp, effect)
       let _ = await event
       ->RuntimeEnvironment.groupBySource
       ->Dict.toArray
@@ -61,7 +56,7 @@ module Make = (
             `found ${count} handler(s) for ${urn}`,
           )->Effect.runSync
           let _ = await handlers
-          ->Array.map(handler => runEffect(~correlationId?, handler(event, context)))
+          ->Array.map(handler => runEffect(handler(event, context)))
           ->Promise.all
         | None => EffectLogger.logWarn(~comp, `no handler found: ${urn}`)->Effect.runSync
         }

package/src/adapter/Runtime/EventCollectorRuntime_Builder_Single.res.mjs

@@ -6,9 +6,9 @@ import * as Pulumi from "@pulumi/pulumi";
 import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
 import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js";
 import * as Logger$ReventlessCore from "../../util/Logger.res.mjs";
+import * as Runtime$ReventlessCore from "./Runtime.res.mjs";
 import * as Component$ReventlessCore from "../../components/Component.res.mjs";
 import * as EffectLogger$ReventlessCore from "../../util/EffectLogger.res.mjs";
-import * as RequestContext$ReventlessCore from "../../RequestContext.res.mjs";
 
 function Make(RuntimeEnvironment) {
   return EventCollectorChannel => {
@@ -29,6 +29,7 @@ function Make(RuntimeEnvironment) {
     let eventCollectorHandlers = {};
     let eventCollectorHandler = parentName => (async (event, context) => {
       let correlationId = RuntimeEnvironment.extractCorrelationId(event);
+      let causationId = RuntimeEnvironment.extractCausationId(event);
       let comp = `EventCollectorRuntime(` + parentName + `)`;
       await Promise.all(Object.entries(RuntimeEnvironment.groupBySource(event)).map(async param => {
         let event = param[1];
@@ -41,8 +42,7 @@ function Make(RuntimeEnvironment) {
         Effect.runSync(EffectLogger$ReventlessCore.logDebug(comp, undefined, `found ` + count + ` handler(s) for ` + urn));
         await Promise.all(handlers.map(handler => {
           let effect = handler(event, context);
-          let cid = Stdlib_Option.getOr(correlationId, "unknown");
-          return Effect.runPromise(Effect.provideService(Effect.annotateLogs(effect, "correlationId", cid), RequestContext$ReventlessCore.tag, RequestContext$ReventlessCore.test(cid, undefined, undefined)));
+          return Runtime$ReventlessCore.runEffect(correlationId, causationId, comp, undefined, effect);
         }));
       }));
     });

package/src/adapter/Runtime/ExtensionPointRuntime_Builder_PerExtensionPoint.res

@@ -22,10 +22,17 @@ module Make = (
     commandTopic,
   ) => {
     let resource = commandTopic->Component.toPulumiResource
+    let name = resource.name->ComponentType.nameOpt(CommandTopic.componentType)
     let runtime = RuntimeEnvironment.make(
-      ~name=resource.name->ComponentType.nameOpt(CommandTopic.componentType),
+      ~name,
       ~handler=handler->Pulumi.Output.apply(handler =>
-        handler->RuntimeEnvironment.asEffectHandler->Runtime.runEffectHandler
+        handler
+        ->RuntimeEnvironment.asEffectHandler
+        ->Runtime.runEffectHandler(
+          ~extractCorrelationId=RuntimeEnvironment.extractCorrelationId,
+          ~extractCausationId=RuntimeEnvironment.extractCausationId,
+          ~comp=name,
+        )
       ),
       ~memorySize,
       ~timeout,

package/src/adapter/Runtime/ExtensionPointRuntime_Builder_PerExtensionPoint.res.mjs

@@ -11,7 +11,8 @@ function Make(RuntimeEnvironment) {
       let memorySize = memorySizeOpt !== undefined ? memorySizeOpt : 1024;
       let timeout = timeoutOpt !== undefined ? timeoutOpt : 30;
       let resource = Component$ReventlessCore.toPulumiResource(commandTopic);
-      return connect(RuntimeEnvironment.make(ComponentType$ReventlessCore.nameOpt(resource.__name, CommandTopic$ReventlessCore.componentType), handler.apply(handler => Runtime$ReventlessCore.runEffectHandler(RuntimeEnvironment.asEffectHandler(handler))), memorySize, timeout, {
+      let name = ComponentType$ReventlessCore.nameOpt(resource.__name, CommandTopic$ReventlessCore.componentType);
+      return connect(RuntimeEnvironment.make(name, handler.apply(handler => Runtime$ReventlessCore.runEffectHandler(RuntimeEnvironment.extractCorrelationId, RuntimeEnvironment.extractCausationId, name, undefined, RuntimeEnvironment.asEffectHandler(handler))), memorySize, timeout, {
         parent: resource
       }));
     };

package/src/adapter/Runtime/PluginRuntime_Builder_Micro.res

@@ -26,7 +26,13 @@ module Make = (
     let runtime = RuntimeEnvironment.make(
       ~name,
       ~handler=handler->Pulumi.Output.apply(handler =>
-        handler->RuntimeEnvironment.asEffectHandler->Runtime.runEffectHandler
+        handler
+        ->RuntimeEnvironment.asEffectHandler
+        ->Runtime.runEffectHandler(
+          ~extractCorrelationId=RuntimeEnvironment.extractCorrelationId,
+          ~extractCausationId=RuntimeEnvironment.extractCausationId,
+          ~comp=name,
+        )
       ),
       ~memorySize,
       ~timeout,
@@ -70,10 +76,17 @@ module Make = (
     dcbCommandTopic,
   ) => {
     let resource = dcbCommandTopic->Component.toPulumiResource
+    let name = resource.name->ComponentType.nameOpt(CommandTopic.componentType)
     let runtime = RuntimeEnvironment.make(
-      ~name=resource.name->ComponentType.nameOpt(CommandTopic.componentType),
+      ~name,
       ~handler=handler->Pulumi.Output.apply(handler =>
-        handler->RuntimeEnvironment.asEffectHandler->Runtime.runEffectHandler
+        handler
+        ->RuntimeEnvironment.asEffectHandler
+        ->Runtime.runEffectHandler(
+          ~extractCorrelationId=RuntimeEnvironment.extractCorrelationId,
+          ~extractCausationId=RuntimeEnvironment.extractCausationId,
+          ~comp=name,
+        )
       ),
       ~memorySize,
       ~timeout,

package/src/adapter/Runtime/PluginRuntime_Builder_Micro.res.mjs

@@ -18,7 +18,7 @@ function Make(RuntimeEnvironment) {
       let opts = {
         parent: opts_parent
       };
-      let runtime = RuntimeEnvironment.make(name, handler.apply(handler => Runtime$ReventlessCore.runEffectHandler(RuntimeEnvironment.asEffectHandler(handler))), memorySize, timeout, {
+      let runtime = RuntimeEnvironment.make(name, handler.apply(handler => Runtime$ReventlessCore.runEffectHandler(RuntimeEnvironment.extractCorrelationId, RuntimeEnvironment.extractCausationId, name, undefined, RuntimeEnvironment.asEffectHandler(handler))), memorySize, timeout, {
         parent: resource
       });
       EventCollectorChannel.connect(name, [{
@@ -40,7 +40,8 @@ function Make(RuntimeEnvironment) {
       let memorySize = memorySizeOpt !== undefined ? memorySizeOpt : 1024;
       let timeout = timeoutOpt !== undefined ? timeoutOpt : 30;
       let resource = Component$ReventlessCore.toPulumiResource(dcbCommandTopic);
-      return connect(RuntimeEnvironment.make(ComponentType$ReventlessCore.nameOpt(resource.__name, CommandTopic$ReventlessCore.componentType), handler.apply(handler => Runtime$ReventlessCore.runEffectHandler(RuntimeEnvironment.asEffectHandler(handler))), memorySize, timeout, {
+      let name = ComponentType$ReventlessCore.nameOpt(resource.__name, CommandTopic$ReventlessCore.componentType);
+      return connect(RuntimeEnvironment.make(name, handler.apply(handler => Runtime$ReventlessCore.runEffectHandler(RuntimeEnvironment.extractCorrelationId, RuntimeEnvironment.extractCausationId, name, undefined, RuntimeEnvironment.asEffectHandler(handler))), memorySize, timeout, {
         parent: resource
       }));
     };

package/src/adapter/Runtime/PluginRuntime_Builder_Single.res

@@ -26,7 +26,13 @@ module Make = (
     let runtime = RuntimeEnvironment.make(
       ~name,
       ~handler=handler->Pulumi.Output.apply(handler =>
-        handler->RuntimeEnvironment.asEffectHandler->Runtime.runEffectHandler
+        handler
+        ->RuntimeEnvironment.asEffectHandler
+        ->Runtime.runEffectHandler(
+          ~extractCorrelationId=RuntimeEnvironment.extractCorrelationId,
+          ~extractCausationId=RuntimeEnvironment.extractCausationId,
+          ~comp=name,
+        )
       ),
       ~memorySize,
       ~timeout,
@@ -70,10 +76,17 @@ module Make = (
     dcbCommandTopic,
   ) => {
     let resource = dcbCommandTopic->Component.toPulumiResource
+    let name = resource.name->ComponentType.nameOpt(CommandTopic.componentType)
     let runtime = RuntimeEnvironment.make(
-      ~name=resource.name->ComponentType.nameOpt(CommandTopic.componentType),
+      ~name,
       ~handler=handler->Pulumi.Output.apply(handler =>
-        handler->RuntimeEnvironment.asEffectHandler->Runtime.runEffectHandler
+        handler
+        ->RuntimeEnvironment.asEffectHandler
+        ->Runtime.runEffectHandler(
+          ~extractCorrelationId=RuntimeEnvironment.extractCorrelationId,
+          ~extractCausationId=RuntimeEnvironment.extractCausationId,
+          ~comp=name,
+        )
       ),
       ~memorySize,
       ~timeout,

package/src/adapter/Runtime/PluginRuntime_Builder_Single.res.mjs

@@ -18,7 +18,7 @@ function Make(RuntimeEnvironment) {
       let opts = {
         parent: opts_parent
       };
-      let runtime = RuntimeEnvironment.make(name, handler.apply(handler => Runtime$ReventlessCore.runEffectHandler(RuntimeEnvironment.asEffectHandler(handler))), memorySize, timeout, {
+      let runtime = RuntimeEnvironment.make(name, handler.apply(handler => Runtime$ReventlessCore.runEffectHandler(RuntimeEnvironment.extractCorrelationId, RuntimeEnvironment.extractCausationId, name, undefined, RuntimeEnvironment.asEffectHandler(handler))), memorySize, timeout, {
         parent: resource
       });
       EventCollectorChannel.connect(name, [{
@@ -40,7 +40,8 @@ function Make(RuntimeEnvironment) {
       let memorySize = memorySizeOpt !== undefined ? memorySizeOpt : 1024;
       let timeout = timeoutOpt !== undefined ? timeoutOpt : 30;
       let resource = Component$ReventlessCore.toPulumiResource(dcbCommandTopic);
-      return connect(RuntimeEnvironment.make(ComponentType$ReventlessCore.nameOpt(resource.__name, CommandTopic$ReventlessCore.componentType), handler.apply(handler => Runtime$ReventlessCore.runEffectHandler(RuntimeEnvironment.asEffectHandler(handler))), memorySize, timeout, {
+      let name = ComponentType$ReventlessCore.nameOpt(resource.__name, CommandTopic$ReventlessCore.componentType);
+      return connect(RuntimeEnvironment.make(name, handler.apply(handler => Runtime$ReventlessCore.runEffectHandler(RuntimeEnvironment.extractCorrelationId, RuntimeEnvironment.extractCausationId, name, undefined, RuntimeEnvironment.asEffectHandler(handler))), memorySize, timeout, {
         parent: resource
       }));
     };

package/src/adapter/Runtime/Runtime.res

@@ -4,17 +4,70 @@ type effectHandler<'event, 'context, 'result, 'error> = (
   'context,
 ) => Effect.t<'result, 'error, unit>
 
-// Convert an effectHandler to an eventHandler by providing Logger, RequestContext, and running as promise.
-// Used at handler dispatch points (runtime builders) where Effect.runPromise is called.
-let runEffectHandler = (handler: effectHandler<'event, 'context, 'result, 'error>): eventHandler<
-  'event,
-  'context,
-  'result,
-> =>
-  (event, ctx) =>
+// ─── Dispatch-boundary annotation ────────────────────────────────────────────
+// Single source of truth for what every handler invocation carries. Annotating
+// here (rather than in each runtime builder) guarantees that every log line
+// inside the handler — framework *and* application — surfaces the same
+// `correlationId` / `comp` / `causationId` top-level JSON fields (EffectLogger
+// decodes them), and that a populated RequestContext is provided. `comp` is what
+// makes two components hosted in one runtime process separable purely by field;
+// `causationId` reconstructs the parent → child chain within one `correlationId`.
+let annotateInvocation = (
+  effect,
+  ~correlationId=?,
+  ~causationId=?,
+  ~comp=?,
+  ~pluginName=?,
+) => {
+  let cid = correlationId->Option.getOr("unknown")
+  let annotateOpt = (eff, key, value) =>
+    switch value {
+    | Some(v) => eff->Effect.annotateLogs(key, v)
+    | None => eff
+    }
+  effect
+  ->Effect.annotateLogs("correlationId", cid)
+  ->annotateOpt("comp", comp)
+  ->annotateOpt("causationId", causationId)
+  ->Effect.provideService(
+    RequestContext.tag,
+    RequestContext.make(~correlationId=cid, ~causationId?, ~component=?comp, ~pluginName?),
+  )
+}
+
+// Annotate + run. Used by the multi-component dispatchers (AllAggregates,
+// AllEventCollectors) that loop over per-source handlers.
+let runEffect = (~correlationId=?, ~causationId=?, ~comp=?, ~pluginName=?, effect) =>
+  effect
+  ->annotateInvocation(~correlationId?, ~causationId?, ~comp?, ~pluginName?)
+  ->Effect.runPromise
+
+// Convert an effectHandler to an eventHandler at build time, annotating the
+// invocation on each call. Used by the single-component-per-Lambda strategies
+// (Micro / PerAggregate / Plugin / PerEventCollector / PerExtensionPoint), which
+// pass the Environment's `extractCorrelationId` / `extractCausationId` and the
+// component `comp` so their application handlers get the same fields as the
+// multi-component path. Extractors default to none for generic use.
+let runEffectHandler = (
+  ~extractCorrelationId: option<'event => option<string>>=?,
+  ~extractCausationId: option<'event => option<string>>=?,
+  ~comp=?,
+  ~pluginName=?,
+  handler: effectHandler<'event, 'context, 'result, 'error>,
+): eventHandler<'event, 'context, 'result> =>
+  (event, ctx) => {
+    let correlationId = switch extractCorrelationId {
+    | Some(f) => f(event)
+    | None => None
+    }
+    let causationId = switch extractCausationId {
+    | Some(f) => f(event)
+    | None => None
+    }
     handler(event, ctx)
-    ->Effect.provideService(RequestContext.tag, RequestContext.test())
+    ->annotateInvocation(~correlationId?, ~causationId?, ~comp?, ~pluginName?)
     ->Effect.runPromise
+  }
 
 type environment<'parts> = {
   parts: 'parts,
@@ -36,6 +89,7 @@ module type Environment = {
   let make: environmentMaker<event, context, 'result, parts>
   let groupBySource: event => dict<event>
   let extractCorrelationId: event => option<string>
+  let extractCausationId: event => option<string>
   let asEventHandler: 'a => eventHandler<event, context, 'result>
   let asEffectHandler: 'a => effectHandler<event, context, 'result, 'error>
 }

package/src/adapter/Runtime/Runtime.res.mjs

@@ -1,10 +1,31 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Effect from "effect/Effect";
 import * as RequestContext$ReventlessCore from "../../RequestContext.res.mjs";
 
-function runEffectHandler(handler) {
-  return (event, ctx) => Effect.runPromise(Effect.provideService(handler(event, ctx), RequestContext$ReventlessCore.tag, RequestContext$ReventlessCore.test(undefined, undefined, undefined)));
+function annotateInvocation(effect, correlationId, causationId, comp, pluginName) {
+  let cid = Stdlib_Option.getOr(correlationId, "unknown");
+  let annotateOpt = (eff, key, value) => {
+    if (value !== undefined) {
+      return Effect.annotateLogs(eff, key, value);
+    } else {
+      return eff;
+    }
+  };
+  return Effect.provideService(annotateOpt(annotateOpt(Effect.annotateLogs(effect, "correlationId", cid), "comp", comp), "causationId", causationId), RequestContext$ReventlessCore.tag, RequestContext$ReventlessCore.make(cid, causationId, comp, pluginName, undefined, undefined));
+}
+
+function runEffect(correlationId, causationId, comp, pluginName, effect) {
+  return Effect.runPromise(annotateInvocation(effect, correlationId, causationId, comp, pluginName));
+}
+
+function runEffectHandler(extractCorrelationId, extractCausationId, comp, pluginName, handler) {
+  return (event, ctx) => {
+    let correlationId = extractCorrelationId !== undefined ? extractCorrelationId(event) : undefined;
+    let causationId = extractCausationId !== undefined ? extractCausationId(event) : undefined;
+    return Effect.runPromise(annotateInvocation(handler(event, ctx), correlationId, causationId, comp, pluginName));
+  };
 }
 
 let CommandHandlerDefaults = {
@@ -16,6 +37,8 @@ let CommandHandlerDefaults = {
 };
 
 export {
+  annotateInvocation,
+  runEffect,
   runEffectHandler,
   CommandHandlerDefaults,
 }

package/src/components/Heartbeat/Heartbeat.res

@@ -11,13 +11,13 @@ module type T = {
   let connect: (
     ~runtime: Runtime.environment<runtimeParts>,
     ~remoteChannel: CommandTopic_Adapter.remoteChannel,
-    ~timeout: int=?,
+    ~timeout: int,
     component,
   ) => unit
 
   let makeHandler: (
     ~id: string,
-    ~timeout: int=?,
+    ~timeout: int,
     ~publishToPluginExtensionPoint: CommandTopic.publishJsons,
   ) => Pulumi.Output.t<Runtime.eventHandler<unit, 'context, unit>>
 

package/src/components/Heartbeat/Heartbeat_Builder.res

@@ -5,7 +5,7 @@ module Make = (Runner: Heartbeat_Adapter.Runner): (
 
   let construct = (_self, _name) => ()
 
-  let connect = (~runtime, ~remoteChannel, ~timeout=10, heartbeat) => {
+  let connect = (~runtime, ~remoteChannel, ~timeout, heartbeat) => {
     let heartbeatResource = heartbeat->Component.toPulumiResource
     let name =
       heartbeatResource.name
@@ -24,7 +24,7 @@ module Make = (Runner: Heartbeat_Adapter.Runner): (
     let _ = heartbeat->Component.setOutputs(outputs)
   }
 
-  let makeHandler = (~id, ~timeout=10, ~publishToPluginExtensionPoint) => {
+  let makeHandler = (~id, ~timeout, ~publishToPluginExtensionPoint) => {
     module Callback = Heartbeat_Callback.Make({
       let publishToPluginExtensionPoint = publishToPluginExtensionPoint
       let id = id

package/src/components/Heartbeat/Heartbeat_Builder.res.mjs

@@ -9,8 +9,7 @@ import * as Heartbeat_Callback$ReventlessCore from "./Heartbeat_Callback.res.mjs
 
 function Make(Runner) {
   let construct = (_self, _name) => {};
-  let connect = (runtime, remoteChannel, timeoutOpt, heartbeat) => {
-    let timeout = timeoutOpt !== undefined ? timeoutOpt : 10;
+  let connect = (runtime, remoteChannel, timeout, heartbeat) => {
     let heartbeatResource = Component$ReventlessCore.toPulumiResource(heartbeat);
     let name = ComponentType$ReventlessCore.name(Stdlib_Option.getOr(heartbeatResource.__name, "Unnamed"), Heartbeat$ReventlessCore.componentType);
     let opts_parent = heartbeatResource;
@@ -24,8 +23,7 @@ function Make(Runner) {
     };
     Component$ReventlessCore.setOutputs(heartbeat, outputs);
   };
-  let makeHandler = (id, timeoutOpt, publishToPluginExtensionPoint) => {
-    let timeout = timeoutOpt !== undefined ? timeoutOpt : 10;
+  let makeHandler = (id, timeout, publishToPluginExtensionPoint) => {
     let Callback = Heartbeat_Callback$ReventlessCore.Make({
       publishToPluginExtensionPoint: publishToPluginExtensionPoint,
       id: id,

package/src/plugin/component/Plugin_Builder.res

@@ -887,7 +887,11 @@ module Make = (
         | Some((_, pluginExtensionPointCommandTopicRemoteChannel)) =>
           // Notify platform hook that the EP channel is available (AWS extracts SQS URL for bundled heartbeat)
           Spec.hooks.onHeartbeatEpChannelAvailable->Option.forEach(hook =>
-            hook(pluginExtensionPointCommandTopicRemoteChannel->Obj.magic, ~pluginId=id)
+            hook(
+              pluginExtensionPointCommandTopicRemoteChannel->Obj.magic,
+              ~pluginId=id,
+              ~heartbeatInterval,
+            )
           )
           heartbeat->PluginRuntimeBuilder.forPluginHeartbeat(
             ~handler,

package/src/plugin/component/Plugin_Builder.res.mjs

@@ -545,7 +545,7 @@ function Make(Spec) {
           let handler = SpecificHeartbeat.makeHandler(id, heartbeatInterval, publishToPluginExtensionPoint);
           if (coreSetup !== undefined) {
             let pluginExtensionPointCommandTopicRemoteChannel$1 = coreSetup[1];
-            Stdlib_Option.forEach(Spec.hooks.onHeartbeatEpChannelAvailable, hook => hook(pluginExtensionPointCommandTopicRemoteChannel$1, id));
+            Stdlib_Option.forEach(Spec.hooks.onHeartbeatEpChannelAvailable, hook => hook(pluginExtensionPointCommandTopicRemoteChannel$1, id, heartbeatInterval));
             PluginRuntimeBuilder.forPluginHeartbeat(handler, none => SpecificHeartbeat.connect(none, pluginExtensionPointCommandTopicRemoteChannel$1, heartbeatInterval, heartbeat), undefined, undefined, heartbeat);
           } else {
             PluginRuntimeBuilder.forPluginHeartbeat(handler, param => {}, undefined, undefined, heartbeat);

package/src/plugin/component/Plugin_Helpers.res

@@ -957,7 +957,12 @@ type platformHooks = {
   onDcbEventLogCreated?: unknown => unit,
   onDcbCommandTopicCreated?: unknown => unit,
   onDcbSlicesCreated?: unknown => unit,
-  onHeartbeatEpChannelAvailable?: (unknown, ~pluginId: string) => unit,
+  // heartbeatInterval carries the plugin's heartbeat cadence so the AWS bundled
+  // heartbeat Lambda emits Heartbeat(interval) matching its EventBridge schedule
+  // rate. Both derive from the same heartbeatInterval; threading it here prevents
+  // the schedule-rate vs command-interval divergence that caused connect/disconnect
+  // flapping (schedule every 60min but Heartbeat(10) → 12min grace).
+  onHeartbeatEpChannelAvailable?: (unknown, ~pluginId: string, ~heartbeatInterval: int) => unit,
   // ── Admin → Plugin coordination ────────────────────────────────────────
   // Set by makePlatform after Admin.construct(); read by Plugin_Builder to
   // wire the local admin connection path (in-memory).  Starts as an empty

package/src/plugin/connect/PluginExtensionPoint_Plugin.res

@@ -5,6 +5,14 @@ open Reventless.Plugin
 
 module PluginExtensionPointSpec = ReventlessInfra.PluginExtensionPointSpec
 
+// Grace before a plugin is marked Disconnected once heartbeats stop, expressed in
+// whole minutes (schedules can only be created by minute). The margin scales with
+// the interval so large cadences keep real headroom: a fixed +2 gave a 60-min
+// heartbeat only ~3% slack, so a single late EventBridge beat + Lambda cold-start
+// could trip a spurious disconnect. `+ max(2, interval / 2)` keeps ≥ +2 min for
+// small intervals and ≥ +50% for large ones (5→7, 10→15, 60→90).
+let disconnectGrace = interval => interval + max(2, interval / 2)
+
 module type Spec = {
   let runtimeOps: PluginRuntimeOperations.operations
   let environment: string
@@ -145,10 +153,9 @@ module Make = (Spec: Spec) => {
       switch cmd {
       | PluginExtensionPointSpec.Heartbeat(interval) => [
           PublishCommand(Plugin.name(id), Delegate.Heartbeat(Plugin.version(id))),
-          // Re-create timeout (+2 minute to avoid toggling)
-          // 1 minute because Schedules can only be created by minute
-          // 1 additional minute to allow additional latency
-          HandleDirective(directiveHandler, CreateDisconnectSchedule(id, interval + 2)),
+          // Re-arm the disconnect schedule with an interval-scaled grace so a
+          // single late beat doesn't trip a spurious disconnect (see disconnectGrace).
+          HandleDirective(directiveHandler, CreateDisconnectSchedule(id, disconnectGrace(interval))),
         ]
       | RedetectPlugin(interval) => [
           // Deploy-time re-detect: drive Redetect (not Heartbeat) so an already-connected
@@ -156,7 +163,7 @@ module Make = (Spec: Spec) => {
           // re-arm the disconnect schedule exactly like a heartbeat so liveness tracking
           // continues from the deploy moment.
           PublishCommand(Plugin.name(id), Delegate.Redetect(Plugin.version(id))),
-          HandleDirective(directiveHandler, CreateDisconnectSchedule(id, interval + 2)),
+          HandleDirective(directiveHandler, CreateDisconnectSchedule(id, disconnectGrace(interval))),
         ]
       | ConnectPlugin(pluginDefinition) =>
         // Validate protocol versions declared by the connecting plugin.

package/src/plugin/connect/PluginExtensionPoint_Plugin.res.mjs

@@ -3,6 +3,7 @@
 import * as S from "sury/src/S.res.mjs";
 import * as Stdlib_JsExn from "@rescript/runtime/lib/es6/Stdlib_JsExn.js";
 import * as Id$Reventless from "@reventlessdev/reventless-spec/src/types/Id.res.mjs";
+import * as Primitive_int from "@rescript/runtime/lib/es6/Primitive_int.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Effect from "effect/Effect";
 import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
@@ -17,6 +18,10 @@ import * as PluginsReadModelSpec$ReventlessCore from "../lifecycle/PluginsReadMo
 import * as ExtensionPointMapping$ReventlessInfra from "@reventlessdev/reventless-infra/src/types/ExtensionPointMapping.res.mjs";
 import * as PluginExtensionPointSpec$ReventlessInfra from "@reventlessdev/reventless-infra/src/types/PluginExtensionPointSpec.res.mjs";
 
+function disconnectGrace(interval) {
+  return interval + Primitive_int.max(2, interval / 2 | 0) | 0;
+}
+
 function Make(Spec) {
   let forwardCommand = async (_id, command, extensionPointName, queryEngine) => {
     let jsons = await queryEngine.scan(PluginSpec$ReventlessCore.name, [
@@ -151,7 +156,7 @@ function Make(Spec) {
             _1: {
               TAG: "CreateDisconnectSchedule",
               _0: id,
-              _1: cmd._0 + 2 | 0
+              _1: disconnectGrace(cmd._0)
             }
           }
         ];
@@ -201,7 +206,7 @@ function Make(Spec) {
             _1: {
               TAG: "CreateDisconnectSchedule",
               _0: id,
-              _1: cmd._0 + 2 | 0
+              _1: disconnectGrace(cmd._0)
             }
           }
         ];
@@ -369,6 +374,7 @@ export {
   name,
   Id,
   PluginExtensionPointSpec,
+  disconnectGrace,
   Make,
   moduleUrl,
 }

package/tests/plugin/HeartbeatDisconnectGraceTest.res

@@ -0,0 +1,98 @@
+// Regression tests for the plugin-lifecycle heartbeat / disconnect margin.
+//
+// A plugin's liveness is scheduler-driven: every heartbeat re-arms a one-time
+// disconnect schedule, and if heartbeats stop the schedule fires and marks the
+// plugin Disconnected. Two independently-wired values must agree — the recurring
+// heartbeat *schedule rate* and the *interval carried inside the Heartbeat command*
+// (which drives CreateDisconnectSchedule). A deployed plugin once ran with schedule
+// rate(60min) but a Heartbeat(10) command (grace ~12min), so it reconnected for
+// ~12min after each hourly beat then sat Disconnected for the rest of the hour —
+// it flapped. See docs/plans/plugin-heartbeat-disconnect-margin-hardening.md.
+//
+// These tests pin the two guarantees that the fix provides at this layer:
+//   1. the disconnect grace scales with the interval (large cadences keep headroom);
+//   2. the disconnect schedule the EP mapping arms is derived from the *same*
+//      interval the Heartbeat/RedetectPlugin command carries — never a constant.
+// (The schedule-rate ⇄ command-interval single-source is additionally enforced at
+//  compile time now that Heartbeat_Builder's ~timeout is mandatory.)
+
+open JestGlobals
+
+module PluginExtensionPointSpec = ReventlessInfra.PluginExtensionPointSpec
+open ReventlessInfra.ExtensionPointMapping
+
+// The mapping functor only needs runtimeOps at directive-*execution* time; the
+// pure mapIncomingCommand under test never touches it, so a stub Spec suffices
+// (mirrors the Obj.magic stubbing already used in HeartbeatTest.res).
+module TestMapping = PluginExtensionPoint_Plugin.Make({
+  let runtimeOps = Obj.magic()
+  let environment = "test"
+  let updateApiSchema = None
+  let manageSubscriptions = None
+})
+
+// Pull the disconnect-schedule grace (in minutes) out of the actions a mapping
+// emits for an incoming command, if any.
+let graceFromActions = actions =>
+  actions->Array.findMap((action: commandAction<_, _>) =>
+    switch action {
+    | HandleDirective(_, PluginExtensionPointSpec.CreateDisconnectSchedule(_, timeout)) =>
+      Some(timeout)
+    | _ => None
+    }
+  )
+
+let meta = Message.generateMeta(~service="test", ~user="test")
+
+describe("disconnectGrace", () => {
+  // The observed-bug fix: the margin must scale, so a 60-min cadence keeps real
+  // headroom instead of the old fixed +2 (~3%).
+  testSync("scales with the interval (5→7, 10→15, 60→90)", () => {
+    expect(PluginExtensionPoint_Plugin.disconnectGrace(5))->toBe(7)
+    expect(PluginExtensionPoint_Plugin.disconnectGrace(10))->toBe(15)
+    expect(PluginExtensionPoint_Plugin.disconnectGrace(60))->toBe(90)
+  })
+
+  testSync("always leaves at least a full interval of headroom past one beat", () => {
+    // Grace must exceed the interval (else a single beat's cadence trips a
+    // disconnect) and keep the historical ≥ +2 min floor for small intervals.
+    [1, 2, 5, 10, 30, 60, 120]->Array.forEach(interval => {
+      let grace = PluginExtensionPoint_Plugin.disconnectGrace(interval)
+      expect(grace > interval)->toBe(true)
+      expect(grace >= interval + 2)->toBe(true)
+    })
+  })
+
+  testSync("a 60-min cadence gets far more than the old fixed +2 grace", () => {
+    // The exact regression: interval 60 previously armed a 62-min disconnect.
+    expect(PluginExtensionPoint_Plugin.disconnectGrace(60) > 62)->toBe(true)
+  })
+})
+
+describe("PluginExtensionPoint mapping arms the disconnect schedule from the beat interval", () => {
+  testSync("Heartbeat(interval) → CreateDisconnectSchedule(_, disconnectGrace(interval))", () => {
+    [5, 10, 60]->Array.forEach(interval => {
+      let actions = TestMapping.PluginMapping.mapIncomingCommand(
+        "Test@1",
+        PluginExtensionPointSpec.Heartbeat(interval),
+        meta,
+      )
+      expect(actions->graceFromActions)->toEqual(
+        Some(PluginExtensionPoint_Plugin.disconnectGrace(interval)),
+      )
+    })
+  })
+
+  testSync("RedetectPlugin(interval) arms the same interval-derived grace as a heartbeat", () => {
+    [5, 10, 60]->Array.forEach(interval => {
+      let actions = TestMapping.PluginMapping.mapIncomingCommand(
+        "Test@1",
+        PluginExtensionPointSpec.RedetectPlugin(interval),
+        meta,
+      )
+      expect(actions->graceFromActions)->toEqual(
+        Some(PluginExtensionPoint_Plugin.disconnectGrace(interval)),
+      )
+    })
+  })
+})