@effect/language-service 0.84.1 → 0.84.3

package/cli.js

@@ -25942,7 +25942,7 @@ var runWith2 = (command, config2) => {
 // package.json
 var package_default = {
   name: "@effect/language-service",
-  version: "0.84.1",
+  version: "0.84.3",
   publishConfig: {
     access: "public",
     directory: "dist"
@@ -28665,10 +28665,42 @@ function makeTypeCheckerUtils(ts, typeChecker, tsUtils) {
     if (node.parent && ts.isJsxOpeningElement(node.parent) && node.parent.tagName === node) return;
     if (node.parent && ts.isJsxClosingElement(node.parent) && node.parent.tagName === node) return;
     if (node.parent && ts.isJsxAttribute(node.parent) && node.parent.name === node) return;
+    if (isInsideTypeOnlyHeritageExpression(node)) return;
     if (ts.isExpression(node) || ts.isTypeNode(node)) {
       return typeChecker.getTypeAtLocation(node);
     }
   }
+  function isInsideTypeOnlyHeritageExpression(node) {
+    if (ts.isExpressionWithTypeArguments(node)) {
+      return isTypeOnlyHeritageClause(node.parent);
+    }
+    if (!ts.isIdentifier(node) && !ts.isPropertyAccessExpression(node)) {
+      return false;
+    }
+    for (let current = node.parent; current; current = current.parent) {
+      if (ts.isPropertyAccessExpression(current)) {
+        continue;
+      }
+      if (ts.isExpressionWithTypeArguments(current)) {
+        return isTypeOnlyHeritageClause(current.parent);
+      }
+      return false;
+    }
+    return false;
+  }
+  function isTypeOnlyHeritageClause(node) {
+    if (!node || !ts.isHeritageClause(node)) {
+      return false;
+    }
+    const container = node.parent;
+    if (!container) {
+      return false;
+    }
+    if (ts.isInterfaceDeclaration(container)) {
+      return true;
+    }
+    return ts.isClassLike(container) && node.token === ts.SyntaxKind.ImplementsKeyword;
+  }
   function resolveToGlobalSymbol(symbol4) {
     if (symbol4.flags & ts.SymbolFlags.Alias) {
       symbol4 = typeChecker.getAliasedSymbol(symbol4);
@@ -28992,6 +29024,14 @@ function make26(ts, tsUtils, typeChecker, typeCheckerUtils, program) {
     ),
     ([A, E, R]) => ({ A, E, R })
   );
+  const streamVarianceStruct = (type, atLocation) => map12(
+    all3(
+      varianceStructCovariantType(type, atLocation, "_A"),
+      varianceStructCovariantType(type, atLocation, "_E"),
+      varianceStructCovariantType(type, atLocation, "_R")
+    ),
+    ([A, E, R]) => ({ A, E, R })
+  );
   const layerVarianceStruct = (type, atLocation) => map12(
     all3(
       varianceStructContravariantType(type, atLocation, "_ROut"),
@@ -29038,6 +29078,21 @@ function make26(ts, tsUtils, typeChecker, typeCheckerUtils, program) {
     "TypeParser.strictEffectType",
     (type) => type
   );
+  const streamType = cachedBy(
+    fn3("TypeParser.streamType")(function* (type, atLocation) {
+      if (supportedEffect() === "v3") {
+        return yield* effectType(type, atLocation);
+      }
+      const typeIdSymbol = typeChecker.getPropertyOfType(type, "~effect/Stream");
+      if (!typeIdSymbol) {
+        return yield* typeParserIssue("Type is not a stream", type, atLocation);
+      }
+      const typeIdType = typeChecker.getTypeOfSymbolAtLocation(typeIdSymbol, atLocation);
+      return yield* streamVarianceStruct(typeIdType, atLocation);
+    }),
+    "TypeParser.streamType",
+    (type) => type
+  );
   const isEffectTypeSourceFile = cachedBy(
     fn3("TypeParser.isEffectTypeSourceFile")(function* (sourceFile) {
       const moduleSymbol = typeChecker.getSymbolAtLocation(sourceFile);
@@ -30773,6 +30828,7 @@ function make26(ts, tsUtils, typeChecker, typeCheckerUtils, program) {
     isServiceMapTypeSourceFile,
     isNodeReferenceToServiceMapModuleApi,
     effectType,
+    streamType,
     strictEffectType,
     layerType,
     fiberType,
@@ -33455,7 +33511,7 @@ var catchAllToMapError = createDiagnostic({
         const { failArg, failCall } = failCallInfo;
         report({
           location: transformation.callee,
-          messageText: `You can use Effect.mapError instead of Effect.${catchAllName} + Effect.fail to transform the error type.`,
+          messageText: `\`Effect.mapError\` expresses the same error-type transformation more directly than \`Effect.${catchAllName}\` followed by \`Effect.fail\`.`,
           fixes: [{
             fixName: "catchAllToMapError_fix",
             description: "Replace with Effect.mapError",
@@ -33519,7 +33575,7 @@ var catchUnfailableEffect = createDiagnostic({
           if (E.flags & ts.TypeFlags.Never) {
             report({
               location: transformation.callee,
-              messageText: `Looks like the previous effect never fails, so probably this error handling will never be triggered.`,
+              messageText: "The previous Effect does not fail, so this error-handling branch will never run.",
               fixes: []
             });
           }
@@ -33582,7 +33638,7 @@ var classSelfMismatch = createDiagnostic({
           if (actualName !== expectedName) {
             report({
               location: selfTypeNode,
-              messageText: `Self type parameter should be '${expectedName}'`,
+              messageText: `The \`Self\` type parameter for this class should be \`${expectedName}\`.`,
               fixes: [{
                 fixName: "classSelfMismatch_fix",
                 description: `Replace '${actualName}' with '${expectedName}'`,
@@ -33772,7 +33828,7 @@ var deterministicKeys = createDiagnostic({
           if (actualIdentifier !== expectedKey) {
             report({
               location: keyStringLiteral,
-              messageText: `Key should be '${expectedKey}'`,
+              messageText: `This key does not match the deterministic key for this declaration. The expected key is \`${expectedKey}\`.`,
               fixes: [{
                 fixName: "deterministicKeys_fix",
                 description: `Replace '${actualIdentifier}' with '${expectedKey}'`,
@@ -33811,9 +33867,8 @@ var duplicatePackage = createDiagnostic({
         const versions = Object.keys(resolvedPackages[packageName]);
         report({
           location: sourceFile.statements[0],
-          messageText: `Package ${packageName} is referenced multiple times with different versions (${versions.join(", ")}) and may cause unexpected type errors.
-Cleanup your dependencies and your package lockfile to avoid multiple instances of this package and reload the project.
-If this is intended set the LSP config "allowedDuplicatedPackages" to ${JSON.stringify(options.allowedDuplicatedPackages.concat([packageName]))}.
+          messageText: `Multiple versions of package \`${packageName}\` were detected: ${versions.join(", ")}. Package duplication can change runtime identity and type equality across Effect modules.
+If this is intentional, set the LSP config \`allowedDuplicatedPackages\` to ${JSON.stringify(options.allowedDuplicatedPackages.concat([packageName]))}.
 
 ${versions.map((version2) => `- found ${version2} at ${resolvedPackages[packageName][version2]}`).join("\n")}`,
           fixes: []
@@ -33921,7 +33976,7 @@ var effectFnIife = createDiagnostic({
       const traceExpressionText = traceExpression ? sourceFile.text.slice(traceExpression.pos, traceExpression.end) : void 0;
       report({
         location: node,
-        messageText: `${effectModuleName}.${kind} returns a reusable function that can take arguments, but here it's called immediately. Use Effect.gen instead${traceExpressionText ? ` with Effect.withSpan(${traceExpressionText}) piped in the end to mantain tracing spans` : ``}.`,
+        messageText: `\`${effectModuleName}.${kind}\` returns a reusable function that can take arguments, but it is invoked immediately here. \`Effect.gen\` represents the immediate-use form for this pattern${traceExpressionText ? ` with \`Effect.withSpan(${traceExpressionText})\` piped at the end to maintain tracing spans` : ``}.`,
         fixes
       });
     }
@@ -34006,7 +34061,7 @@ var effectFnImplicitAny = createDiagnostic({
         const parameterName = getParameterName(ts, parameter.name);
         report({
           location: parameter.name,
-          messageText: `Parameter '${parameterName}' implicitly has an 'any' type in Effect.fn/Effect.fnUntraced. Add an explicit type annotation or provide a contextual function type.`,
+          messageText: `Parameter \`${parameterName}\` implicitly has type \`any\` in \`Effect.fn\`, \`Effect.fnUntraced\`, or \`Effect.fnUntracedEager\`. No parameter type is available from an explicit annotation or contextual function type.`,
           fixes: []
         });
       }
@@ -34602,7 +34657,7 @@ var effectFnOpportunity = createDiagnostic({
       const expectedSignature = generateExpectedSignature();
       report({
         location: nameIdentifier ?? targetNode,
-        messageText: `Can be rewritten as a reusable function: ${expectedSignature}`,
+        messageText: `This expression can be rewritten in the reusable function form \`${expectedSignature}\`.`,
         fixes
       });
     }
@@ -34814,7 +34869,7 @@ var effectMapVoid = createDiagnostic({
           if (isNone2(match9)) continue;
           report({
             location: node.expression,
-            messageText: "Effect.asVoid can be used instead to discard the success value",
+            messageText: "This expression discards the success value through mapping. `Effect.asVoid` represents that form directly.",
             fixes: [{
               fixName: "effectMapVoid_fix",
               description: "Replace with Effect.asVoid",
@@ -34869,7 +34924,7 @@ var effectSucceedWithVoid = createDiagnostic({
           if (!tsUtils.isVoidExpression(argument)) continue;
           report({
             location: node,
-            messageText: "Effect.void can be used instead of Effect.succeed(undefined) or Effect.succeed(void 0)",
+            messageText: "`Effect.void` represents the same outcome as `Effect.succeed(undefined)` or `Effect.succeed(void 0)`.",
             fixes: [{
               fixName: "effectSucceedWithVoid_fix",
               description: "Replace with Effect.void",
@@ -34931,7 +34986,7 @@ var extendsNativeError = createDiagnostic({
             if (isNativeError) {
               report({
                 location: node.name ?? typeExpression,
-                messageText: "Avoid extending the native 'Error' class directly. Consider using a tagged error (e.g. Data.TaggedError) to maintain type safety in the Effect failure channel.",
+                messageText: "This class extends the native `Error` type directly. Untagged native errors lose distinction in the Effect failure channel.",
                 fixes: []
               });
             }
@@ -34976,7 +35031,12 @@ var floatingEffect = createDiagnostic({
       if (!isFloatingExpression(node)) continue;
       const type = typeCheckerUtils.getTypeAtLocation(node.expression);
       if (!type) continue;
-      const effect2 = yield* option4(typeParser.effectType(type, node.expression));
+      const effect2 = yield* option4(
+        pipe(
+          typeParser.effectType(type, node.expression),
+          orElse5(() => typeParser.streamType(type, node.expression))
+        )
+      );
       if (isSome2(effect2)) {
         const allowedFloatingEffects = yield* pipe(
           typeParser.fiberType(type, node.expression),
@@ -34985,10 +35045,9 @@ var floatingEffect = createDiagnostic({
         );
         if (isNone2(allowedFloatingEffects)) {
           const isStrictEffect = yield* option4(typeParser.strictEffectType(type, node.expression));
-          const name = isSome2(isStrictEffect) ? "Effect" : "Effect-able " + typeChecker.typeToString(type);
           report({
             location: node,
-            messageText: `${name} must be yielded or assigned to a variable.`,
+            messageText: isSome2(isStrictEffect) ? "This Effect value is neither yielded nor used in an assignment." : `This Effect-able \`${typeChecker.typeToString(type)}\` value is neither yielded nor assigned to a variable.`,
             fixes: []
           });
         }
@@ -35083,7 +35142,7 @@ var makeGlobalConsoleApply = (checkInEffect) => fn3(`globalConsole${checkInEffec
     if (inEffect !== checkInEffect) continue;
     report({
       location: node,
-      messageText: checkInEffect ? `Prefer using ${alternative} instead of console.${method} inside Effect generators.` : `Prefer using ${alternative} instead of console.${method}.`,
+      messageText: checkInEffect ? `This Effect code uses \`console.${method}\`, logging in Effect code is represented through \`${alternative}\`.` : `This code uses \`console.${method}\`, the corresponding Effect logging API is \`${alternative}\`.`,
       fixes: []
     });
   }
@@ -35132,10 +35191,10 @@ var makeGlobalDateApply = (checkInEffect) => fn3(`globalDate${checkInEffect ? "I
     let objectNode;
     if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && ts.idText(node.expression.name) === "now") {
       objectNode = node.expression.expression;
-      messageText = checkInEffect ? "Prefer using Clock or DateTime from Effect instead of Date.now() inside Effect generators." : "Prefer using Clock or DateTime from Effect instead of Date.now().";
+      messageText = checkInEffect ? "This Effect code uses `Date.now()`, time access in Effect code is represented through `Clock` from Effect." : "This code uses `Date.now()`, time access is represented through `Clock` from Effect.";
     } else if (ts.isNewExpression(node)) {
       objectNode = node.expression;
-      messageText = checkInEffect ? "Prefer using DateTime from Effect instead of new Date() inside Effect generators." : "Prefer using DateTime from Effect instead of new Date().";
+      messageText = checkInEffect ? "This Effect code constructs `new Date()`, date values in Effect code are represented through `DateTime` from Effect." : "This code constructs `new Date()`, date values are represented through `DateTime` from Effect.";
     }
     if (!messageText || !objectNode) continue;
     const symbol4 = typeChecker.getSymbolAtLocation(objectNode);
@@ -35218,7 +35277,7 @@ var globalErrorInEffectCatch = createDiagnostic({
                     );
                     report({
                       location: node.expression,
-                      messageText: `The 'catch' callback in ${nodeText} returns global 'Error', which loses type safety as untagged errors merge together. Consider using a tagged error and optionally wrapping the original in a 'cause' property.`,
+                      messageText: `The \`catch\` callback in \`${nodeText}\` returns the global \`Error\` type. Untagged errors merge together in the Effect error channel and lose type-level distinction; a tagged error preserves that distinction and can wrap the original error in a \`cause\` property.`,
                       fixes: []
                     });
                   }
@@ -35298,7 +35357,7 @@ var makeGlobalFetchApply = (checkInEffect) => fn3(`globalFetch${checkInEffect ?
   if (!fetchSymbol) return;
   const effectVersion = typeParser.supportedEffect();
   const packageName = effectVersion === "v3" ? "@effect/platform" : "effect/unstable/http";
-  const messageText = checkInEffect ? `Prefer using HttpClient from ${packageName} instead of the global 'fetch' function inside Effect generators.` : `Prefer using HttpClient from ${packageName} instead of the global 'fetch' function.`;
+  const messageText = checkInEffect ? `This Effect code calls the global \`fetch\` function, HTTP requests in Effect code are represented through \`HttpClient\` from \`${packageName}\`.` : `This code uses the global \`fetch\` function, HTTP requests are represented through \`HttpClient\` from \`${packageName}\`.`;
   const nodeToVisit = [];
   const appendNodeToVisit = (node) => {
     nodeToVisit.push(node);
@@ -35371,7 +35430,7 @@ var makeGlobalRandomApply = (checkInEffect) => fn3(`globalRandom${checkInEffect
     if (inEffect !== checkInEffect) continue;
     report({
       location: node,
-      messageText: checkInEffect ? "Prefer using the Random service from Effect instead of Math.random() inside Effect generators." : "Prefer using the Random service from Effect instead of Math.random().",
+      messageText: checkInEffect ? "This Effect code uses `Math.random()`, randomness is represented through the Effect `Random` service." : "This code uses `Math.random()`, randomness is represented through the Effect `Random` service.",
       fixes: []
     });
   }
@@ -35402,12 +35461,12 @@ var globalRandom = createDiagnostic({
 // src/diagnostics/globalTimersInEffect.ts
 var timerAlternatives = {
   "setTimeout": {
-    inEffect: "Prefer using Effect.sleep or Schedule from Effect instead of setTimeout inside Effect generators.",
-    outsideEffect: "Prefer using Effect.sleep or Schedule from Effect instead of setTimeout."
+    inEffect: "This Effect code uses `setTimeout`, the corresponding timer API in this context is `Effect.sleep or Schedule` from Effect.",
+    outsideEffect: "This code uses `setTimeout`, the corresponding Effect timer API is `Effect.sleep or Schedule` from Effect."
   },
   "setInterval": {
-    inEffect: "Prefer using Schedule or Effect.repeat from Effect instead of setInterval inside Effect generators.",
-    outsideEffect: "Prefer using Schedule or Effect.repeat from Effect instead of setInterval."
+    inEffect: "This Effect code uses `setInterval`, the corresponding timer API in this context is `Schedule or Effect.repeat` from Effect.",
+    outsideEffect: "This code uses `setInterval`, the corresponding Effect timer API is `Schedule or Effect.repeat` from Effect."
   }
 };
 var makeGlobalTimersApply = (checkInEffect) => fn3(`globalTimers${checkInEffect ? "InEffect" : ""}.apply`)(function* (sourceFile, report) {
@@ -35649,7 +35708,7 @@ var instanceOfSchema = createDiagnostic({
         if (isSchemaType._tag === "Some") {
           report({
             location: node,
-            messageText: "Consider using Schema.is instead of instanceof for Effect Schema types.",
+            messageText: "This code uses `instanceof` with an Effect Schema type. `Schema.is` is the schema-aware runtime check for this case.",
             fixes: [{
               fixName: "instanceOfSchema_fix",
               description: "Replace with Schema.is",
@@ -35919,7 +35978,7 @@ var leakingRequirements = createDiagnostic({
         location: node,
         messageText: `Methods of this Service require \`${requirementsStr}\` from every caller.
 
-This leaks implementation details into the service's public type \u2014 callers shouldn't need to know *how* the service works internally, only *what* it provides.
+The requirement becomes part of the public service surface instead of remaining internal to Layer implementation.
 
 Resolve these dependencies at Layer creation and provide them to each method, so the service's type reflects its purpose, not its implementation.
 
@@ -36116,7 +36175,7 @@ var missedPipeableOpportunity = createDiagnostic({
           ).trim() : "";
           report({
             location: flow2.node,
-            messageText: `Nested function calls can be converted to pipeable style for better readability; consider using ${subjectText}.pipe(...) instead.`,
+            messageText: `This nested call structure has a pipeable form. \`${subjectText}.pipe(...)\` represents the same call sequence in pipe style and may be easier to read.`,
             fixes: [{
               fixName: "missedPipeableOpportunity_fix",
               description: "Convert to pipe style",
@@ -36197,7 +36256,7 @@ var missingEffectContext = createDiagnostic({
             (missingTypes) => missingTypes.length > 0 ? report(
               {
                 location: node,
-                messageText: `Missing '${sortTypes(missingTypes).map((_) => typeChecker.typeToString(_)).join(" | ")}' in the expected Effect context.`,
+                messageText: `This Effect requires a service that is missing from the expected Effect context: \`${sortTypes(missingTypes).map((_) => typeChecker.typeToString(_)).join(" | ")}\`.`,
                 fixes: []
               }
             ) : void 0
@@ -36548,7 +36607,7 @@ var missingReturnYieldStar = createDiagnostic({
       }];
       report({
         location: unwrapped,
-        messageText: `It is recommended to use return yield* for Effects that never succeed to signal a definitive exit point for type narrowing and tooling support.`,
+        messageText: "This Effect never succeeds; using `return yield*` preserves a definitive generator exit point for type narrowing and tooling support.",
         fixes: fix
       });
     }
@@ -36604,7 +36663,7 @@ var missingStarInYieldEffectGen = createDiagnostic({
     brokenGenerators.forEach(
       (pos) => report({
         location: { pos, end: pos + "function".length },
-        messageText: `Seems like you used yield instead of yield* inside this Effect.gen.`,
+        messageText: "This uses `yield` for an `Effect` value. `yield*` is the Effect-aware form in this context.",
         fixes: []
       })
     );
@@ -36626,7 +36685,7 @@ var missingStarInYieldEffectGen = createDiagnostic({
       }] : [];
       report({
         location: node,
-        messageText: `When yielding Effects inside Effect.gen, you should use yield* instead of yield.`,
+        messageText: "This uses `yield` for an `Effect` value. `yield*` is the Effect-aware form in this context.",
         fixes: fix
       });
     });
@@ -36694,7 +36753,7 @@ var multipleEffectProvide = createDiagnostic({
         if (chunk.length < 2) continue;
         report({
           location: chunk[0].node,
-          messageText: "Avoid chaining Effect.provide calls, as this can lead to service lifecycle issues. Instead, merge layers and provide them in a single call.",
+          messageText: "This expression chains multiple `Effect.provide` calls. Providing Layers in multiple calls in a chain can break service lifecycle behavior compared with a single combined provide with merged layers.",
           fixes: [{
             fixName: "multipleEffectProvide_fix",
             description: "Combine into a single provide",
@@ -36784,7 +36843,7 @@ var nodeBuiltinImport = createDiagnostic({
         if (match9) {
           report({
             location: statement.moduleSpecifier,
-            messageText: `Prefer using ${match9.alternative} from ${match9.package} instead of the Node.js '${match9.module}' module.`,
+            messageText: `This module reference uses the \`${match9.module}\` module, the corresponding Effect API is \`${match9.alternative}\` from \`${match9.package}\`.`,
             fixes: []
           });
         }
@@ -36797,7 +36856,7 @@ var nodeBuiltinImport = createDiagnostic({
             if (match9) {
               report({
                 location: arg,
-                messageText: `Prefer using ${match9.alternative} from ${match9.package} instead of the Node.js '${match9.module}' module.`,
+                messageText: `This module reference uses the \`${match9.module}\` module, the corresponding Effect API is \`${match9.alternative}\` from \`${match9.package}\`.`,
                 fixes: []
               });
             }
@@ -36851,7 +36910,7 @@ var nonObjectEffectServiceType = createDiagnostic({
             const propertyValue = property.initializer;
             const errorToReport = {
               location: property.name,
-              messageText: "Effect.Service requires the service type to be an object {} and not a primitive type. \nConsider wrapping the value in an object, or manually using Context.Tag or Effect.Tag if you want to use a primitive instead.",
+              messageText: "`Effect.Service` is declared with a primitive service type. `Effect.Service` models object-shaped services; primitive values use `Context.Tag` or `Effect.Tag` directly.",
               fixes: []
             };
             if (propertyName === "succeed") {
@@ -37613,7 +37672,7 @@ var outdatedApi = createDiagnostic({
       hasReported = true;
       report({
         location: propertyAccess.name,
-        messageText: `${propertyName} is an Effect v3 API, but the project is using Effect v4.`,
+        messageText: `This project targets Effect v4, but this code uses the Effect v3 API \`${propertyName}\`. The referenced API belongs to the v3 surface rather than the configured v4 surface.`,
         fixes: []
       });
     }
@@ -37656,7 +37715,7 @@ var outdatedApi = createDiagnostic({
     if (hasReported) {
       report({
         location: { pos: 0, end: 0 },
-        messageText: "This project targets Effect v4, but is using Effect v3 APIs. To find the correct API to use, clone and consult the github.com/effect-ts/effect-smol repository for the corresponding v4 replacement.",
+        messageText: "This project targets Effect v4, but this code uses Effect v3 APIs. The referenced API belongs to the v3 surface rather than the configured v4 surface.",
         fixes: []
       });
     }
@@ -37832,7 +37891,7 @@ var overriddenSchemaConstructor = createDiagnostic({
               };
               report({
                 location: member,
-                messageText: "Classes extending Schema must not override the constructor; this is because it silently breaks the schema decoding behaviour. If that's needed, we recommend instead to use a static 'new' method that constructs the instance.",
+                messageText: "This Schema subclass defines its own constructor. For Schema classes, constructor overrides break decoding behavior for the class shape. Custom construction can be expressed through a static `new` method instead.",
                 fixes: (member.body ? [fixAsStaticNew] : []).concat([{
                   fixName: "overriddenSchemaConstructor_fix",
                   description: "Remove the constructor override",
@@ -37954,7 +38013,7 @@ var preferSchemaOverJson = createDiagnostic({
       if (isSome2(match9)) {
         report({
           location: match9.value,
-          messageText: "Consider using Effect Schema for JSON operations instead of JSON.parse/JSON.stringify",
+          messageText: "This code uses `JSON.parse` or `JSON.stringify`. Effect Schema provides Effect-aware APIs for JSON parsing and stringifying.",
           fixes: []
         });
       }
@@ -38072,9 +38131,7 @@ var returnEffectInGen = createDiagnostic({
                 }] : [];
                 report({
                   location: node,
-                  messageText: `You are returning an Effect-able type inside a generator function, and will result in nested Effect<Effect<...>>.
-Maybe you wanted to return yield* instead?
-Nested Effect-able types may be intended if you plan to later manually flatten or unwrap this Effect, if so you can safely disable this diagnostic for this line through quickfixes.`,
+                  messageText: "This generator returns an Effect-able value directly, which produces a nested `Effect<Effect<...>>`. If the intended result is the inner Effect value, `return yield*` represents that form.",
                   fixes: fix
                 });
               }),
@@ -38229,9 +38286,7 @@ var runEffectInsideEffect = createDiagnostic({
             );
           });
           const v4MethodName = `${isEffectRunCall.value.methodName}With`;
-          const messageText = supportedEffect === "v4" ? `Using ${nodeText} inside an Effect is not recommended. The same services should generally be used instead to run child effects.
-Consider extracting the current services by using for example Effect.services and then use Effect.${v4MethodName} with the extracted services instead.` : `Using ${nodeText} inside an Effect is not recommended. The same runtime should generally be used instead to run child effects.
-Consider extracting the Runtime by using for example Effect.runtime and then use Runtime.${isEffectRunCall.value.methodName} with the extracted runtime instead.`;
+          const messageText = supportedEffect === "v4" ? `\`${nodeText}\` is called inside an Effect with a separate services invocation. In this context, child Effects run with the surrounding services, which can be accessed through \`Effect.services\` and \`Effect.${v4MethodName}\`.` : `\`${nodeText}\` is called inside an Effect with a separate runtime invocation. In this context, run child Effects with the surrounding runtime, which can be accessed through \`Effect.runtime\` and \`Runtime.${isEffectRunCall.value.methodName}\`.`;
           report({
             location: node.expression,
             messageText,
@@ -38244,7 +38299,7 @@ Consider extracting the Runtime by using for example Effect.runtime and then use
         } else {
           report({
             location: node.expression,
-            messageText: `Using ${nodeText} inside an Effect is not recommended. Effects inside generators can usually just be yielded.`,
+            messageText: `\`${nodeText}\` is called inside an existing Effect context. Here, the inner Effect can be used directly.`,
             fixes: []
           });
         }
@@ -38299,7 +38354,7 @@ var schemaStructWithTag = createDiagnostic({
                   const otherProperties = arg.properties.filter((prop) => prop !== tagProperty);
                   report({
                     location: node,
-                    messageText: "Schema.Struct with a _tag field can be simplified to Schema.TaggedStruct to make the tag optional in the constructor.",
+                    messageText: "This `Schema.Struct` includes a `_tag` field. `Schema.TaggedStruct` is the tagged-struct form for this pattern and makes the tag optional in the constructor.",
                     fixes: [{
                       fixName: "schemaStructWithTag_fix",
                       description: "Replace with Schema.TaggedStruct",
@@ -38392,7 +38447,7 @@ var schemaSyncInEffect = createDiagnostic({
       const effectMethodName = syncToEffectMethod[isSchemaSyncCall.value.methodName];
       report({
         location: node.expression,
-        messageText: `Using ${nodeText} inside an Effect generator is not recommended. Use Schema.${effectMethodName} instead to get properly typed error channel.`,
+        messageText: `\`${nodeText}\` is used inside an Effect generator. \`Schema.${effectMethodName}\` preserves the typed Effect error channel for this operation without throwing.`,
         fixes: []
       });
     }
@@ -38452,7 +38507,7 @@ var schemaUnionOfLiterals = createDiagnostic({
                 const schemaLiteralExpression = firstLiteralCall.expression;
                 report({
                   location: node,
-                  messageText: "A Schema.Union of multiple Schema.Literal calls can be simplified to a single Schema.Literal call.",
+                  messageText: "This `Schema.Union` contains multiple `Schema.Literal` members and can be simplified to a single `Schema.Literal` call.",
                   fixes: [{
                     fixName: "schemaUnionOfLiterals_fix",
                     description: "Replace with a single Schema.Literal call",
@@ -38515,8 +38570,7 @@ var scopeInLayerEffect = createDiagnostic({
         map12(
           () => report({
             location: node,
-            messageText: `Seems like you are constructing a layer with a scope in the requirements.
-Consider using "scoped" instead to get rid of the scope in the requirements.`,
+            messageText: "This layer construction leaves `Scope` in the requirement set. The scoped API removes `Scope` from the resulting requirements.",
             fixes: methodIdentifier ? [{
               fixName: "scopeInLayerEffect_scoped",
               description: "Use scoped for Layer creation",
@@ -38616,7 +38670,7 @@ var serviceNotAsClass = createDiagnostic({
       const shapeText = typeArgs.length > 0 ? typeArgs.map((t) => sourceFile.text.substring(ts.getTokenPosOfNode(t, sourceFile), t.end)).join(", ") : "Shape";
       report({
         location: callExpr,
-        messageText: `ServiceMap.Service should be used in a class declaration instead of as a variable. Use: class ${variableName} extends ServiceMap.Service<${variableName}, ${shapeText}>()("${argsText.replace(/['"]/g, "")}") {}`,
+        messageText: `\`ServiceMap.Service\` is assigned to a variable here, but this API is intended for a class declaration shape such as \`class ${variableName} extends ServiceMap.Service<${variableName}, ${shapeText}>()("${argsText.replace(/['"]/g, "")}") {}\`.`,
         fixes: [{
           fixName: "serviceNotAsClass",
           description: `Convert to class declaration`,
@@ -38829,7 +38883,7 @@ var tryCatchInEffectGen = createDiagnostic({
             map12(() => {
               report({
                 location: node,
-                messageText: `Avoid using try/catch inside Effect generators. Use Effect's error handling mechanisms instead (e.g. ${alternatives.join(", ")}).`,
+                messageText: `This Effect generator contains \`try/catch\`; in this context, error handling is expressed with Effect APIs such as ${alternatives.join(", ")}).`,
                 fixes: []
               });
             }),
@@ -38890,8 +38944,7 @@ var unknownInEffectCatch = createDiagnostic({
                     );
                     report({
                       location: node.expression,
-                      messageText: `The 'catch' callback in ${nodeText} returns 'unknown'. The catch callback should be used to provide typed errors.
-Consider wrapping unknown errors into Effect's Data.TaggedError for example, or narrow down the type to the specific error raised.`,
+                      messageText: `The \`catch\` callback in \`${nodeText}\` returns \`unknown\`, so the Effect error type stays untyped. A specific typed error preserves error-channel information, for example by narrowing the value or wrapping it in \`Data.TaggedError\`.`,
                       fixes: []
                     });
                   }
@@ -38988,7 +39041,7 @@ var unnecessaryFailYieldableError = createDiagnostic({
                 map12(
                   () => report({
                     location: node,
-                    messageText: `This Effect.fail call uses a yieldable error type as argument. You can yield* the error directly instead.`,
+                    messageText: "This `yield* Effect.fail(...)` passes a yieldable error value. `yield*` represents that value directly without wrapping it in `Effect.fail`.",
                     fixes: [{
                       fixName: "unnecessaryFailYieldableError_fix",
                       description: "Replace yield* Effect.fail with yield*",
@@ -39093,7 +39146,7 @@ var unnecessaryPipeChain = createDiagnostic({
           map12(({ innerCall, pipeCall }) => {
             report({
               location: node,
-              messageText: `Chained pipe calls can be simplified to a single pipe call`,
+              messageText: "This expression contains chained `pipe` calls that can be simplified to a single `pipe` call.",
               fixes: [{
                 fixName: "unnecessaryPipeChain_fix",
                 description: "Rewrite as single pipe call",
@@ -39363,7 +39416,7 @@ var metadata_default = {
           {
             start: 154,
             end: 169,
-            text: "Self type parameter should be 'InvalidContextTag'    effect(classSelfMismatch)"
+            text: "The `Self` type parameter for this class should be `InvalidContextTag`.    effect(classSelfMismatch)"
           }
         ]
       }
@@ -39399,7 +39452,7 @@ var metadata_default = {
           {
             start: 86,
             end: 91,
-            text: "Parameter 'input' implicitly has an 'any' type in Effect.fn/Effect.fnUntraced. Add an explicit type annotation or provide a contextual function type.    effect(effectFnImplicitAny)"
+            text: "Parameter `input` implicitly has type `any` in `Effect.fn`, `Effect.fnUntraced`, or `Effect.fnUntracedEager`. No parameter type is available from an explicit annotation or contextual function type.    effect(effectFnImplicitAny)"
           }
         ]
       }
@@ -39420,7 +39473,7 @@ var metadata_default = {
           {
             start: 41,
             end: 64,
-            text: "Effect must be yielded or assigned to a variable.    effect(floatingEffect)"
+            text: "This Effect value is neither yielded nor used in an assignment.    effect(floatingEffect)"
           }
         ]
       }
@@ -39462,7 +39515,7 @@ var metadata_default = {
           {
             start: 160,
             end: 167,
-            text: "Missing 'Db' in the expected Effect context.    effect(missingEffectContext)"
+            text: "This Effect requires a service that is missing from the expected Effect context: `Db`.    effect(missingEffectContext)"
           }
         ]
       }
@@ -39525,7 +39578,7 @@ var metadata_default = {
           {
             start: 121,
             end: 147,
-            text: "It is recommended to use return yield* for Effects that never succeed to signal a definitive exit point for type narrowing and tooling support.    effect(missingReturnYieldStar)"
+            text: "This Effect never succeeds; using `return yield*` preserves a definitive generator exit point for type narrowing and tooling support.    effect(missingReturnYieldStar)"
           }
         ]
       }
@@ -39546,12 +39599,12 @@ var metadata_default = {
           {
             start: 75,
             end: 83,
-            text: "Seems like you used yield instead of yield* inside this Effect.gen.    effect(missingStarInYieldEffectGen)"
+            text: "This uses `yield` for an `Effect` value. `yield*` is the Effect-aware form in this context.    effect(missingStarInYieldEffectGen)"
           },
           {
             start: 105,
             end: 128,
-            text: "When yielding Effects inside Effect.gen, you should use yield* instead of yield.    effect(missingStarInYieldEffectGen)"
+            text: "This uses `yield` for an `Effect` value. `yield*` is the Effect-aware form in this context.    effect(missingStarInYieldEffectGen)"
           }
         ]
       }
@@ -39571,7 +39624,7 @@ var metadata_default = {
           {
             start: 142,
             end: 149,
-            text: "Effect.Service requires the service type to be an object {} and not a primitive type. \nConsider wrapping the value in an object, or manually using Context.Tag or Effect.Tag if you want to use a primitive instead.    effect(nonObjectEffectServiceType)"
+            text: "`Effect.Service` is declared with a primitive service type. `Effect.Service` models object-shaped services; primitive values use `Context.Tag` or `Effect.Tag` directly.    effect(nonObjectEffectServiceType)"
           }
         ]
       }
@@ -39591,12 +39644,12 @@ var metadata_default = {
           {
             start: 0,
             end: 0,
-            text: "This project targets Effect v4, but is using Effect v3 APIs. To find the correct API to use, clone and consult the github.com/effect-ts/effect-smol repository for the corresponding v4 replacement.    effect(outdatedApi)"
+            text: "This project targets Effect v4, but this code uses Effect v3 APIs. The referenced API belongs to the v3 surface rather than the configured v4 surface.    effect(outdatedApi)"
           },
           {
             start: 126,
             end: 133,
-            text: "runtime is an Effect v3 API, but the project is using Effect v4.    effect(outdatedApi)"
+            text: "This project targets Effect v4, but this code uses the Effect v3 API `runtime`. The referenced API belongs to the v3 surface rather than the configured v4 surface.    effect(outdatedApi)"
           }
         ]
       }
@@ -39638,7 +39691,7 @@ var metadata_default = {
           {
             start: 123,
             end: 185,
-            text: "Classes extending Schema must not override the constructor; this is because it silently breaks the schema decoding behaviour. If that's needed, we recommend instead to use a static 'new' method that constructs the instance.    effect(overriddenSchemaConstructor)"
+            text: "This Schema subclass defines its own constructor. For Schema classes, constructor overrides break decoding behavior for the class shape. Custom construction can be expressed through a static `new` method instead.    effect(overriddenSchemaConstructor)"
           }
         ]
       }
@@ -39680,7 +39733,7 @@ var metadata_default = {
           {
             start: 82,
             end: 94,
-            text: "Looks like the previous effect never fails, so probably this error handling will never be triggered.    effect(catchUnfailableEffect)"
+            text: "The previous Effect does not fail, so this error-handling branch will never run.    effect(catchUnfailableEffect)"
           }
         ]
       }
@@ -39701,7 +39754,7 @@ var metadata_default = {
           {
             start: 64,
             end: 137,
-            text: `Effect.fn returns a reusable function that can take arguments, but here it's called immediately. Use Effect.gen instead with Effect.withSpan("preview") piped in the end to mantain tracing spans.    effect(effectFnIife)`
+            text: '`Effect.fn` returns a reusable function that can take arguments, but it is invoked immediately here. `Effect.gen` represents the immediate-use form for this pattern with `Effect.withSpan("preview")` piped at the end to maintain tracing spans.    effect(effectFnIife)'
           }
         ]
       }
@@ -39790,7 +39843,7 @@ var metadata_default = {
           {
             start: 56,
             end: 73,
-            text: "The 'catch' callback in Effect.tryPromise returns global 'Error', which loses type safety as untagged errors merge together. Consider using a tagged error and optionally wrapping the original in a 'cause' property.    effect(globalErrorInEffectCatch)"
+            text: "The `catch` callback in `Effect.tryPromise` returns the global `Error` type. Untagged errors merge together in the Effect error channel and lose type-level distinction; a tagged error preserves that distinction and can wrap the original error in a `cause` property.    effect(globalErrorInEffectCatch)"
           }
         ]
       }
@@ -39853,7 +39906,7 @@ var metadata_default = {
           {
             start: 212,
             end: 217,
-            text: "Methods of this Service require `FileSystem` from every caller.\n\nThis leaks implementation details into the service's public type \u2014 callers shouldn't need to know *how* the service works internally, only *what* it provides.\n\nResolve these dependencies at Layer creation and provide them to each method, so the service's type reflects its purpose, not its implementation.\n\nTo suppress this diagnostic for specific dependency types that are intentionally passed through (e.g., HttpServerRequest), add `@effect-leakable-service` JSDoc to their interface declarations (e.g., the `FileSystem` interface), or to this service by adding a `@effect-expect-leaking FileSystem` JSDoc.\n\nMore info and examples at https://effect.website/docs/requirements-management/layers/#avoiding-requirement-leakage    effect(leakingRequirements)"
+            text: "Methods of this Service require `FileSystem` from every caller.\n\nThe requirement becomes part of the public service surface instead of remaining internal to Layer implementation.\n\nResolve these dependencies at Layer creation and provide them to each method, so the service's type reflects its purpose, not its implementation.\n\nTo suppress this diagnostic for specific dependency types that are intentionally passed through (e.g., HttpServerRequest), add `@effect-leakable-service` JSDoc to their interface declarations (e.g., the `FileSystem` interface), or to this service by adding a `@effect-expect-leaking FileSystem` JSDoc.\n\nMore info and examples at https://effect.website/docs/requirements-management/layers/#avoiding-requirement-leakage    effect(leakingRequirements)"
           }
         ]
       }
@@ -39874,7 +39927,7 @@ var metadata_default = {
           {
             start: 348,
             end: 373,
-            text: "Avoid chaining Effect.provide calls, as this can lead to service lifecycle issues. Instead, merge layers and provide them in a single call.    effect(multipleEffectProvide)"
+            text: "This expression chains multiple `Effect.provide` calls. Providing Layers in multiple calls in a chain can break service lifecycle behavior compared with a single combined provide with merged layers.    effect(multipleEffectProvide)"
           }
         ]
       }
@@ -39895,7 +39948,7 @@ var metadata_default = {
           {
             start: 91,
             end: 115,
-            text: "You are returning an Effect-able type inside a generator function, and will result in nested Effect<Effect<...>>.\nMaybe you wanted to return yield* instead?\nNested Effect-able types may be intended if you plan to later manually flatten or unwrap this Effect, if so you can safely disable this diagnostic for this line through quickfixes.    effect(returnEffectInGen)"
+            text: "This generator returns an Effect-able value directly, which produces a nested `Effect<Effect<...>>`. If the intended result is the inner Effect value, `return yield*` represents that form.    effect(returnEffectInGen)"
           }
         ]
       }
@@ -39916,7 +39969,7 @@ var metadata_default = {
           {
             start: 101,
             end: 115,
-            text: "Using Effect.runSync inside an Effect is not recommended. The same services should generally be used instead to run child effects.\nConsider extracting the current services by using for example Effect.services and then use Effect.runSyncWith with the extracted services instead.    effect(runEffectInsideEffect)"
+            text: "`Effect.runSync` is called inside an Effect with a separate services invocation. In this context, child Effects run with the surrounding services, which can be accessed through `Effect.services` and `Effect.runSyncWith`.    effect(runEffectInsideEffect)"
           }
         ]
       }
@@ -39936,7 +39989,7 @@ var metadata_default = {
           {
             start: 276,
             end: 293,
-            text: "Using Schema.decodeSync inside an Effect generator is not recommended. Use Schema.decode instead to get properly typed error channel.    effect(schemaSyncInEffect)"
+            text: "`Schema.decodeSync` is used inside an Effect generator. `Schema.decode` preserves the typed Effect error channel for this operation without throwing.    effect(schemaSyncInEffect)"
           }
         ]
       }
@@ -39956,7 +40009,7 @@ var metadata_default = {
           {
             start: 211,
             end: 338,
-            text: 'Seems like you are constructing a layer with a scope in the requirements.\nConsider using "scoped" instead to get rid of the scope in the requirements.    effect(scopeInLayerEffect)'
+            text: "This layer construction leaves `Scope` in the requirement set. The scoped API removes `Scope` from the resulting requirements.    effect(scopeInLayerEffect)"
           }
         ]
       }
@@ -39998,7 +40051,7 @@ var metadata_default = {
           {
             start: 91,
             end: 151,
-            text: "Avoid using try/catch inside Effect generators. Use Effect's error handling mechanisms instead (e.g. Effect.try, Effect.tryPromise, Effect.catch, Effect.catchTag).    effect(tryCatchInEffectGen)"
+            text: "This Effect generator contains `try/catch`; in this context, error handling is expressed with Effect APIs such as Effect.try, Effect.tryPromise, Effect.catch, Effect.catchTag).    effect(tryCatchInEffectGen)"
           }
         ]
       }
@@ -40019,7 +40072,7 @@ var metadata_default = {
           {
             start: 56,
             end: 73,
-            text: "The 'catch' callback in Effect.tryPromise returns 'unknown'. The catch callback should be used to provide typed errors.\nConsider wrapping unknown errors into Effect's Data.TaggedError for example, or narrow down the type to the specific error raised.    effect(unknownInEffectCatch)"
+            text: "The `catch` callback in `Effect.tryPromise` returns `unknown`, so the Effect error type stays untyped. A specific typed error preserves error-channel information, for example by narrowing the value or wrapping it in `Data.TaggedError`.    effect(unknownInEffectCatch)"
           }
         ]
       }
@@ -40040,7 +40093,7 @@ var metadata_default = {
           {
             start: 14,
             end: 26,
-            text: "Avoid extending the native 'Error' class directly. Consider using a tagged error (e.g. Data.TaggedError) to maintain type safety in the Effect failure channel.    effect(extendsNativeError)"
+            text: "This class extends the native `Error` type directly. Untagged native errors lose distinction in the Effect failure channel.    effect(extendsNativeError)"
           }
         ]
       }
@@ -40061,7 +40114,7 @@ var metadata_default = {
           {
             start: 1,
             end: 23,
-            text: "Prefer using Effect.log or Logger instead of console.log.    effect(globalConsole)"
+            text: "This code uses `console.log`, the corresponding Effect logging API is `Effect.log or Logger`.    effect(globalConsole)"
           }
         ]
       }
@@ -40082,7 +40135,7 @@ var metadata_default = {
           {
             start: 83,
             end: 103,
-            text: "Prefer using Effect.log or Logger instead of console.log inside Effect generators.    effect(globalConsoleInEffect)"
+            text: "This Effect code uses `console.log`, logging in Effect code is represented through `Effect.log or Logger`.    effect(globalConsoleInEffect)"
           }
         ]
       }
@@ -40103,7 +40156,7 @@ var metadata_default = {
           {
             start: 24,
             end: 34,
-            text: "Prefer using Clock or DateTime from Effect instead of Date.now().    effect(globalDate)"
+            text: "This code uses `Date.now()`, time access is represented through `Clock` from Effect.    effect(globalDate)"
           }
         ]
       }
@@ -40124,7 +40177,7 @@ var metadata_default = {
           {
             start: 95,
             end: 105,
-            text: "Prefer using Clock or DateTime from Effect instead of Date.now() inside Effect generators.    effect(globalDateInEffect)"
+            text: "This Effect code uses `Date.now()`, time access in Effect code is represented through `Clock` from Effect.    effect(globalDateInEffect)"
           }
         ]
       }
@@ -40145,7 +40198,7 @@ var metadata_default = {
           {
             start: 24,
             end: 29,
-            text: "Prefer using HttpClient from @effect/platform instead of the global 'fetch' function.    effect(globalFetch)"
+            text: "This code uses the global `fetch` function, HTTP requests are represented through `HttpClient` from `@effect/platform`.    effect(globalFetch)"
           }
         ]
       }
@@ -40181,7 +40234,7 @@ var metadata_default = {
           {
             start: 24,
             end: 37,
-            text: "Prefer using the Random service from Effect instead of Math.random().    effect(globalRandom)"
+            text: "This code uses `Math.random()`, randomness is represented through the Effect `Random` service.    effect(globalRandom)"
           }
         ]
       }
@@ -40202,7 +40255,7 @@ var metadata_default = {
           {
             start: 93,
             end: 106,
-            text: "Prefer using the Random service from Effect instead of Math.random() inside Effect generators.    effect(globalRandomInEffect)"
+            text: "This Effect code uses `Math.random()`, randomness is represented through the Effect `Random` service.    effect(globalRandomInEffect)"
           }
         ]
       }
@@ -40223,7 +40276,7 @@ var metadata_default = {
           {
             start: 1,
             end: 26,
-            text: "Prefer using Effect.sleep or Schedule from Effect instead of setTimeout.    effect(globalTimers)"
+            text: "This code uses `setTimeout`, the corresponding Effect timer API is `Effect.sleep or Schedule` from Effect.    effect(globalTimers)"
           }
         ]
       }
@@ -40244,7 +40297,7 @@ var metadata_default = {
           {
             start: 83,
             end: 108,
-            text: "Prefer using Effect.sleep or Schedule from Effect instead of setTimeout inside Effect generators.    effect(globalTimersInEffect)"
+            text: "This Effect code uses `setTimeout`, the corresponding timer API in this context is `Effect.sleep or Schedule` from Effect.    effect(globalTimersInEffect)"
           }
         ]
       }
@@ -40265,7 +40318,7 @@ var metadata_default = {
           {
             start: 159,
             end: 180,
-            text: "Consider using Schema.is instead of instanceof for Effect Schema types.    effect(instanceOfSchema)"
+            text: "This code uses `instanceof` with an Effect Schema type. `Schema.is` is the schema-aware runtime check for this case.    effect(instanceOfSchema)"
           }
         ]
       }
@@ -40286,7 +40339,7 @@ var metadata_default = {
           {
             start: 15,
             end: 24,
-            text: "Prefer using FileSystem from @effect/platform instead of the Node.js 'fs' module.    effect(nodeBuiltinImport)"
+            text: "This module reference uses the `fs` module, the corresponding Effect API is `FileSystem` from `@effect/platform`.    effect(nodeBuiltinImport)"
           }
         ]
       }
@@ -40313,7 +40366,7 @@ export const preview = Effect.gen(function*() {
           {
             start: 142,
             end: 158,
-            text: "Consider using Effect Schema for JSON operations instead of JSON.parse/JSON.stringify    effect(preferSchemaOverJson)"
+            text: "This code uses `JSON.parse` or `JSON.stringify`. Effect Schema provides Effect-aware APIs for JSON parsing and stringifying.    effect(preferSchemaOverJson)"
           }
         ]
       }
@@ -40334,7 +40387,7 @@ export const preview = Effect.gen(function*() {
           {
             start: 150,
             end: 162,
-            text: "You can use Effect.mapError instead of Effect.catch + Effect.fail to transform the error type.    effect(catchAllToMapError)"
+            text: "`Effect.mapError` expresses the same error-type transformation more directly than `Effect.catch` followed by `Effect.fail`.    effect(catchAllToMapError)"
           }
         ]
       }
@@ -40355,7 +40408,7 @@ export const preview = Effect.gen(function*() {
           {
             start: 116,
             end: 134,
-            text: "Key should be '@effect/harness-effect-v4/examples/diagnostics/deterministicKeys_preview/RenamedService'    effect(deterministicKeys)"
+            text: "This key does not match the deterministic key for this declaration. The expected key is `@effect/harness-effect-v4/examples/diagnostics/deterministicKeys_preview/RenamedService`.    effect(deterministicKeys)"
           }
         ]
       }
@@ -40376,7 +40429,7 @@ export const preview = Effect.gen(function*() {
           {
             start: 54,
             end: 61,
-            text: "Can be rewritten as a reusable function: Effect.fn(function*() { ... })    effect(effectFnOpportunity)"
+            text: "This expression can be rewritten in the reusable function form `Effect.fn(function*() { ... })`.    effect(effectFnOpportunity)"
           }
         ]
       }
@@ -40397,7 +40450,7 @@ export const preview = Effect.gen(function*() {
           {
             start: 82,
             end: 92,
-            text: "Effect.asVoid can be used instead to discard the success value    effect(effectMapVoid)"
+            text: "This expression discards the success value through mapping. `Effect.asVoid` represents that form directly.    effect(effectMapVoid)"
           }
         ]
       }
@@ -40418,7 +40471,7 @@ export const preview = Effect.gen(function*() {
           {
             start: 56,
             end: 81,
-            text: "Effect.void can be used instead of Effect.succeed(undefined) or Effect.succeed(void 0)    effect(effectSucceedWithVoid)"
+            text: "`Effect.void` represents the same outcome as `Effect.succeed(undefined)` or `Effect.succeed(void 0)`.    effect(effectSucceedWithVoid)"
           }
         ]
       }
@@ -40460,7 +40513,7 @@ export const preview = Effect.gen(function*() {
           {
             start: 116,
             end: 172,
-            text: "Nested function calls can be converted to pipeable style for better readability; consider using Schema.decodeEffect(User)({ id: 1 }).pipe(...) instead.    effect(missedPipeableOpportunity)"
+            text: "This nested call structure has a pipeable form. `Schema.decodeEffect(User)({ id: 1 }).pipe(...)` represents the same call sequence in pipe style and may be easier to read.    effect(missedPipeableOpportunity)"
           }
         ]
       }
@@ -40522,7 +40575,7 @@ export const preview = Effect.gen(function*() {
           {
             start: 64,
             end: 136,
-            text: "Schema.Struct with a _tag field can be simplified to Schema.TaggedStruct to make the tag optional in the constructor.    effect(schemaStructWithTag)"
+            text: "This `Schema.Struct` includes a `_tag` field. `Schema.TaggedStruct` is the tagged-struct form for this pattern and makes the tag optional in the constructor.    effect(schemaStructWithTag)"
           }
         ]
       }
@@ -40542,7 +40595,7 @@ export const preview = Effect.gen(function*() {
           {
             start: 64,
             end: 118,
-            text: "A Schema.Union of multiple Schema.Literal calls can be simplified to a single Schema.Literal call.    effect(schemaUnionOfLiterals)"
+            text: "This `Schema.Union` contains multiple `Schema.Literal` members and can be simplified to a single `Schema.Literal` call.    effect(schemaUnionOfLiterals)"
           }
         ]
       }
@@ -40562,7 +40615,7 @@ export const preview = Effect.gen(function*() {
           {
             start: 60,
             end: 107,
-            text: 'ServiceMap.Service should be used in a class declaration instead of as a variable. Use: class Preview extends ServiceMap.Service<Preview, { port: number }>()("Preview") {}    effect(serviceNotAsClass)'
+            text: '`ServiceMap.Service` is assigned to a variable here, but this API is intended for a class declaration shape such as `class Preview extends ServiceMap.Service<Preview, { port: number }>()("Preview") {}`.    effect(serviceNotAsClass)'
           }
         ]
       }
@@ -40630,7 +40683,7 @@ export const preview = Effect.gen(function*() {
           {
             start: 178,
             end: 208,
-            text: "This Effect.fail call uses a yieldable error type as argument. You can yield* the error directly instead.    effect(unnecessaryFailYieldableError)"
+            text: "This `yield* Effect.fail(...)` passes a yieldable error value. `yield*` represents that value directly without wrapping it in `Effect.fail`.    effect(unnecessaryFailYieldableError)"
           }
         ]
       }
@@ -40672,7 +40725,7 @@ export const preview = Effect.gen(function*() {
           {
             start: 64,
             end: 125,
-            text: "Chained pipe calls can be simplified to a single pipe call    effect(unnecessaryPipeChain)"
+            text: "This expression contains chained `pipe` calls that can be simplified to a single `pipe` call.    effect(unnecessaryPipeChain)"
           }
         ]
       }