effect 4.0.0-beta.71 → 4.0.0-beta.73

package/src/SchemaRepresentation.ts

@@ -758,10 +758,9 @@ export interface References {
  *
  * **When to use**
  *
- * Use when you use {@link fromAST} to create a `Document` from a Schema AST, {@link toSchema}
- * to reconstruct a runtime Schema, {@link toJsonSchemaDocument} to convert to
- * JSON Schema, and {@link toMultiDocument} to wrap it as a
- * {@link MultiDocument}.
+ * Use when representing a single Schema AST together with its named references
+ * before reconstructing a runtime Schema, converting to JSON Schema, or
+ * wrapping it as a {@link MultiDocument}.
  *
  * @see {@link MultiDocument}
  * @see {@link fromAST}
@@ -816,7 +815,7 @@ const toJsonAnnotationsBlacklist: Set<string> = new Set([
 export type PrimitiveTree = Schema.Tree<null | number | boolean | bigint | symbol | string>
 
 /**
- * Schema codec for {@link PrimitiveTree}.
+ * Schema for {@link PrimitiveTree}.
  *
  * **When to use**
  *
@@ -843,8 +842,9 @@ export const $PrimitiveTree: Schema.Codec<PrimitiveTree> = Schema.Tree(
 const isPrimitiveTree = Schema.is($PrimitiveTree)
 
 /**
- * Schema codec for `Schema.Annotations.Annotations`. Filters out internal
- * annotation keys and non-primitive values during encoding.
+ * Schema for serializing public `Schema.Annotations.Annotations` values. It
+ * filters out internal annotation keys and non-primitive values during
+ * encoding.
  *
  * **When to use**
  *
@@ -877,7 +877,7 @@ export const $Annotations = Schema.Record(Schema.String, Schema.Unknown).pipe(
 ).annotate({ identifier: "Annotations" })
 
 /**
- * Schema codec for the {@link Null} representation node.
+ * Schema for the {@link Null} representation node.
  *
  * @category schemas
  * @since 4.0.0
@@ -888,7 +888,7 @@ export const $Null = Schema.Struct({
 }).annotate({ identifier: "Null" })
 
 /**
- * Schema codec for the {@link Undefined} representation node.
+ * Schema for the {@link Undefined} representation node.
  *
  * @category schemas
  * @since 4.0.0
@@ -899,7 +899,7 @@ export const $Undefined = Schema.Struct({
 }).annotate({ identifier: "Undefined" })
 
 /**
- * Schema codec for the {@link Void} representation node.
+ * Schema for the {@link Void} representation node.
  *
  * @category schemas
  * @since 4.0.0
@@ -910,7 +910,7 @@ export const $Void = Schema.Struct({
 }).annotate({ identifier: "Void" })
 
 /**
- * Schema codec for the {@link Never} representation node.
+ * Schema for the {@link Never} representation node.
  *
  * @category schemas
  * @since 4.0.0
@@ -921,7 +921,7 @@ export const $Never = Schema.Struct({
 }).annotate({ identifier: "Never" })
 
 /**
- * Schema codec for the {@link Unknown} representation node.
+ * Schema for the {@link Unknown} representation node.
  *
  * @category schemas
  * @since 4.0.0
@@ -932,7 +932,7 @@ export const $Unknown = Schema.Struct({
 }).annotate({ identifier: "Unknown" })
 
 /**
- * Schema codec for the {@link Any} representation node.
+ * Schema for the {@link Any} representation node.
  *
  * @category schemas
  * @since 4.0.0
@@ -1045,7 +1045,7 @@ const $IsPattern = Schema.Struct({
 }).annotate({ identifier: "IsPattern" })
 
 /**
- * Schema codec for {@link StringMeta}.
+ * Schema for {@link StringMeta}.
  *
  * @category schemas
  * @since 4.0.0
@@ -1090,7 +1090,7 @@ function makeCheck<T>(meta: Schema.Codec<T>, identifier: string) {
 }
 
 /**
- * Schema codec for the {@link String} representation node.
+ * Schema for the {@link String} representation node.
  *
  * @category schemas
  * @since 4.0.0
@@ -1145,7 +1145,7 @@ const $IsBetween = Schema.Struct({
 }).annotate({ identifier: "IsBetween" })
 
 /**
- * Schema codec for {@link NumberMeta}.
+ * Schema for {@link NumberMeta}.
  *
  * @category schemas
  * @since 4.0.0
@@ -1162,7 +1162,7 @@ export const $NumberMeta = Schema.Union([
 ]).annotate({ identifier: "NumberMeta" })
 
 /**
- * Schema codec for the {@link Number} representation node.
+ * Schema for the {@link Number} representation node.
  *
  * @category schemas
  * @since 4.0.0
@@ -1174,7 +1174,7 @@ export const $Number = Schema.Struct({
 }).annotate({ identifier: "Number" })
 
 /**
- * Schema codec for the {@link Boolean} representation node.
+ * Schema for the {@link Boolean} representation node.
  *
  * @category schemas
  * @since 4.0.0
@@ -1221,7 +1221,7 @@ const $BigIntMeta = Schema.Union([
 ]).annotate({ identifier: "BigIntMeta" })
 
 /**
- * Schema codec for the {@link BigInt} representation node.
+ * Schema for the {@link BigInt} representation node.
  *
  * **When to use**
  *
@@ -1245,7 +1245,7 @@ export const $BigInt = Schema.Struct({
 }).annotate({ identifier: "BigInt" })
 
 /**
- * Schema codec for the {@link Symbol} representation node.
+ * Schema for the {@link Symbol} representation node.
  *
  * @category schemas
  * @since 4.0.0
@@ -1256,7 +1256,7 @@ export const $Symbol = Schema.Struct({
 }).annotate({ identifier: "Symbol" })
 
 /**
- * Schema codec for the literal value types allowed in a {@link Literal} node
+ * Schema for the literal value types allowed in a {@link Literal} node
  * (string, finite number, boolean, or bigint).
  *
  * @category schemas
@@ -1270,7 +1270,7 @@ export const $LiteralValue = Schema.Union([
 ]).annotate({ identifier: "LiteralValue" })
 
 /**
- * Schema codec for the {@link Literal} representation node.
+ * Schema for the {@link Literal} representation node.
  *
  * @category schemas
  * @since 4.0.0
@@ -1282,7 +1282,7 @@ export const $Literal = Schema.Struct({
 }).annotate({ identifier: "Literal" })
 
 /**
- * Schema codec for the {@link UniqueSymbol} representation node.
+ * Schema for the {@link UniqueSymbol} representation node.
  *
  * @category schemas
  * @since 4.0.0
@@ -1294,7 +1294,7 @@ export const $UniqueSymbol = Schema.Struct({
 }).annotate({ identifier: "UniqueSymbol" })
 
 /**
- * Schema codec for the {@link ObjectKeyword} representation node.
+ * Schema for the {@link ObjectKeyword} representation node.
  *
  * @category schemas
  * @since 4.0.0
@@ -1305,7 +1305,7 @@ export const $ObjectKeyword = Schema.Struct({
 }).annotate({ identifier: "ObjectKeyword" })
 
 /**
- * Schema codec for the {@link Enum} representation node.
+ * Schema for the {@link Enum} representation node.
  *
  * @category schemas
  * @since 4.0.0
@@ -1325,7 +1325,7 @@ export const $Enum = Schema.Struct({
 }).annotate({ identifier: "Enum" })
 
 /**
- * Schema codec for the {@link TemplateLiteral} representation node.
+ * Schema for the {@link TemplateLiteral} representation node.
  *
  * @category schemas
  * @since 4.0.0
@@ -1337,7 +1337,7 @@ export const $TemplateLiteral = Schema.Struct({
 }).annotate({ identifier: "TemplateLiteral" })
 
 /**
- * Schema codec for the {@link Element} type (positional tuple element).
+ * Schema for the {@link Element} type (positional tuple element).
  *
  * @category schemas
  * @since 4.0.0
@@ -1360,7 +1360,7 @@ const $ArraysMeta = Schema.Union([
 ]).annotate({ identifier: "ArraysMeta" })
 
 /**
- * Schema codec for the {@link Arrays} representation node.
+ * Schema for the {@link Arrays} representation node.
  *
  * @category schemas
  * @since 4.0.0
@@ -1374,7 +1374,7 @@ export const $Arrays = Schema.Struct({
 }).annotate({ identifier: "Arrays" })
 
 /**
- * Schema codec for the {@link PropertySignature} type.
+ * Schema for the {@link PropertySignature} type.
  *
  * @category schemas
  * @since 4.0.0
@@ -1388,7 +1388,7 @@ export const $PropertySignature = Schema.Struct({
 }).annotate({ identifier: "PropertySignature" })
 
 /**
- * Schema codec for the {@link IndexSignature} type.
+ * Schema for the {@link IndexSignature} type.
  *
  * @category schemas
  * @since 4.0.0
@@ -1420,7 +1420,7 @@ const $IsPropertyNames = Schema.Struct({
 }).annotate({ identifier: "IsPropertyNames" })
 
 /**
- * Schema codec for {@link ObjectsMeta}.
+ * Schema for {@link ObjectsMeta}.
  *
  * @category schemas
  * @since 4.0.0
@@ -1433,7 +1433,7 @@ export const $ObjectsMeta = Schema.Union([
 ]).annotate({ identifier: "ObjectsMeta" })
 
 /**
- * Schema codec for the {@link Objects} representation node.
+ * Schema for the {@link Objects} representation node.
  *
  * @category schemas
  * @since 4.0.0
@@ -1447,7 +1447,7 @@ export const $Objects = Schema.Struct({
 }).annotate({ identifier: "Objects" })
 
 /**
- * Schema codec for the {@link Union} representation node.
+ * Schema for the {@link Union} representation node.
  *
  * @category schemas
  * @since 4.0.0
@@ -1460,7 +1460,7 @@ export const $Union = Schema.Struct({
 }).annotate({ identifier: "Union" })
 
 /**
- * Schema codec for the {@link Reference} representation node.
+ * Schema for the {@link Reference} representation node.
  *
  * @category schemas
  * @since 4.0.0
@@ -1503,7 +1503,7 @@ const $IsBetweenDate = Schema.Struct({
 }).annotate({ identifier: "IsBetweenDate" })
 
 /**
- * Schema codec for {@link DateMeta}.
+ * Schema for {@link DateMeta}.
  *
  * @category schemas
  * @since 4.0.0
@@ -1534,7 +1534,7 @@ const $IsSizeBetween = Schema.Struct({
 }).annotate({ identifier: "IsSizeBetween" })
 
 /**
- * Schema codec for {@link SizeMeta}.
+ * Schema for {@link SizeMeta}.
  *
  * @category schemas
  * @since 4.0.0
@@ -1546,7 +1546,7 @@ export const $SizeMeta = Schema.Union([
 ]).annotate({ identifier: "SizeMeta" })
 
 /**
- * Schema codec for {@link DeclarationMeta}.
+ * Schema for {@link DeclarationMeta}.
  *
  * @category schemas
  * @since 4.0.0
@@ -1557,7 +1557,7 @@ export const $DeclarationMeta = Schema.Union([
 ]).annotate({ identifier: "DeclarationMeta" })
 
 /**
- * Schema codec for the {@link Declaration} representation node.
+ * Schema for the {@link Declaration} representation node.
  *
  * @category schemas
  * @since 4.0.0
@@ -1571,7 +1571,7 @@ export const $Declaration = Schema.Struct({
 }).annotate({ identifier: "Declaration" })
 
 /**
- * Schema codec for the {@link Suspend} representation node.
+ * Schema for the {@link Suspend} representation node.
  *
  * @category schemas
  * @since 4.0.0
@@ -1592,8 +1592,8 @@ export const $Suspend = Schema.Struct({
 export interface $Representation extends Schema.Codec<Representation> {}
 
 /**
- * Schema codec for the full {@link Representation} union. This is the
- * recursive codec that can validate/encode any representation node.
+ * Schema for the full {@link Representation} union. It recursively validates
+ * and encodes any representation node.
  *
  * @category schemas
  * @since 4.0.0
@@ -1624,7 +1624,7 @@ export const $Representation: $Representation = Schema.Union([
 ]).annotate({ identifier: "Schema" })
 
 /**
- * Schema codec for {@link Document}.
+ * Schema for {@link Document}.
  *
  * **When to use**
  *
@@ -1648,7 +1648,7 @@ export const $Document = Schema.Struct({
 }).annotate({ identifier: "Document" })
 
 /**
- * Schema codec for {@link MultiDocument}.
+ * Schema for {@link MultiDocument}.
  *
  * @category schemas
  * @since 4.0.0
@@ -1671,7 +1671,6 @@ export const $MultiDocument = Schema.Struct({
  *
  * **Details**
  *
- * This is a pure function and does not mutate the input AST.
  * Shared/recursive sub-schemas are extracted into the `references` map.
  *
  * **Example** (Converting a Schema to a Document)
@@ -1706,8 +1705,7 @@ export const fromAST: (ast: AST.AST) => Document = InternalRepresentation.fromAS
  *
  * **Details**
  *
- * This is a pure function and does not mutate the input ASTs. All schemas share
- * a single `references` map.
+ * All schemas share a single `references` map.
  *
  * @see {@link MultiDocument}
  * @see {@link fromAST}
@@ -1718,7 +1716,7 @@ export const fromAST: (ast: AST.AST) => Document = InternalRepresentation.fromAS
 export const fromASTs: (asts: readonly [AST.AST, ...Array<AST.AST>]) => MultiDocument = InternalRepresentation.fromASTs
 
 /**
- * Schema codec that decodes a {@link Document} from JSON and encodes it back.
+ * Schema that decodes a {@link Document} from JSON and encodes it back.
  *
  * **When to use**
  *
@@ -1744,8 +1742,7 @@ export const fromASTs: (asts: readonly [AST.AST, ...Array<AST.AST>]) => MultiDoc
 export const DocumentFromJson: Schema.Codec<Document, Schema.Json> = Schema.toCodecJson($Document)
 
 /**
- * Schema codec that decodes a {@link MultiDocument} from JSON and encodes it
- * back.
+ * Schema for `MultiDocument` values encoded as JSON.
  *
  * @see {@link $MultiDocument}
  * @see {@link DocumentFromJson}
@@ -1764,10 +1761,6 @@ export const MultiDocumentFromJson: Schema.Codec<MultiDocument, Schema.Json> = S
  * Use when an API expects a `MultiDocument` but you only have a single
  * `Document`.
  *
- * **Details**
- *
- * This is a pure function and does not mutate the input.
- *
  * @see {@link Document}
  * @see {@link MultiDocument}
  *
@@ -1892,7 +1885,7 @@ export const toSchemaDefaultReviver: Reviver<Schema.Top> = (s, recur) => {
 }
 
 /**
- * Reconstructs a runtime Schema from a {@link Document}.
+ * Creates a runtime Schema from a {@link Document}.
  *
  * **When to use**
  *
@@ -2245,10 +2238,6 @@ export function toSchema<S extends Schema.Top = Schema.Top>(document: Document,
  * Use to produce a standard JSON Schema from an Effect Schema
  * representation.
  *
- * **Details**
- *
- * This is a pure function and does not mutate the input.
- *
  * **Example** (Generating JSON Schema)
  *
  * ```ts
@@ -2280,10 +2269,6 @@ export const toJsonSchemaDocument: (
  *
  * Use when you have multiple schemas sharing references.
  *
- * **Details**
- *
- * This is a pure function and does not mutate the input.
- *
  * @see {@link MultiDocument}
  * @see {@link toJsonSchemaDocument}
  * @see {@link fromJsonSchemaMultiDocument}

package/src/SchemaTransformation.ts

@@ -97,7 +97,7 @@ import * as Getter from "./SchemaGetter.ts"
 import * as Issue from "./SchemaIssue.ts"
 
 /**
- * A middleware that wraps the entire parsing `Effect` pipeline for both
+ * Middleware that wraps the entire parsing `Effect` pipeline for both
  * decode and encode directions.
  *
  * **When to use**
@@ -112,7 +112,6 @@ import * as Issue from "./SchemaIssue.ts"
  * `Middleware` receives the full `Effect` produced by the inner schema and can
  * intercept, modify, retry, or replace it.
  *
- * - Immutable — constructing a Middleware does not mutate existing instances.
  * - `decode` receives an `Effect<Option<E>, Issue, RDE>` and returns
  *   `Effect<Option<T>, Issue, RDT>`.
  * - `encode` receives an `Effect<Option<T>, Issue, RET>` and returns
@@ -171,7 +170,7 @@ export class Middleware<in out T, in out E, RDE, RDT, RET, REE> {
 const TypeId = "~effect/SchemaTransformation/Transformation"
 
 /**
- * A bidirectional transformation between a decoded type `T` and an encoded
+ * Represents a bidirectional transformation between a decoded type `T` and an encoded
  * type `E`, built from a pair of `Getter`s.
  *
  * **When to use**
@@ -280,7 +279,6 @@ export function isTransformation(u: unknown): u is Transformation<any, any, unkn
  *
  * **Details**
  *
- * - Does not mutate the input.
  * - Returns the input unchanged if it is already a `Transformation`.
  *
  * **Example** (Wrapping existing getters)
@@ -464,7 +462,7 @@ export function transformOptional<T, E>(options: {
 }
 
 /**
- * A string-to-string transformation that trims whitespace on decode.
+ * Transforms strings by trimming whitespace on decode.
  * Encode is passthrough (no change).
  *
  * **When to use**
@@ -502,7 +500,7 @@ export function trim(): Transformation<string, string> {
 }
 
 /**
- * A string-to-string transformation that converts snake_case to camelCase
+ * Transforms strings by converting snake_case to camelCase
  * on decode and camelCase to snake_case on encode.
  *
  * **When to use**
@@ -539,7 +537,7 @@ export function snakeToCamel(): Transformation<string, string> {
 }
 
 /**
- * A string-to-string transformation that lowercases on decode.
+ * Transforms strings by lowercasing on decode.
  * Encode is passthrough.
  *
  * **When to use**
@@ -576,7 +574,7 @@ export function toLowerCase(): Transformation<string, string> {
 }
 
 /**
- * A string-to-string transformation that uppercases on decode.
+ * Transforms strings by uppercasing on decode.
  * Encode is passthrough.
  *
  * **When to use**
@@ -613,7 +611,7 @@ export function toUpperCase(): Transformation<string, string> {
 }
 
 /**
- * A string-to-string transformation that capitalizes the first character on
+ * Transforms strings by capitalizing the first character on
  * decode. Encode is passthrough.
  *
  * **When to use**
@@ -649,7 +647,7 @@ export function capitalize(): Transformation<string, string> {
 }
 
 /**
- * A string-to-string transformation that lowercases the first character on
+ * Transforms strings by lowercasing the first character on
  * decode. Encode is passthrough.
  *
  * **When to use**
@@ -685,7 +683,7 @@ export function uncapitalize(): Transformation<string, string> {
 }
 
 /**
- * A transformation that decodes a string into a record of key-value pairs and
+ * Transforms a string into a record of key-value pairs and
  * encodes a record of key-value pairs into a string.
  *
  * **When to use**
@@ -735,7 +733,7 @@ const passthrough_ = new Transformation(
 )
 
 /**
- * The identity transformation — returns the input unchanged in both
+ * Transforms values by returning the input unchanged in both
  * directions.
  *
  * **When to use**
@@ -775,7 +773,7 @@ export function passthrough<T>(): Transformation<T, T> {
 }
 
 /**
- * A passthrough transformation typed so that `T extends E`, where the decoded
+ * Transforms values without changing them, typed so that `T extends E`, where the decoded
  * type `T` is a subtype of the encoded type `E`.
  *
  * **When to use**
@@ -808,7 +806,7 @@ export function passthroughSupertype<T>(): Transformation<T, T> {
 }
 
 /**
- * A passthrough transformation typed so that `E extends T` — the encoded
+ * Transforms values without changing them, typed so that `E extends T` — the encoded
  * type is a subtype of the decoded type.
  *
  * **When to use**
@@ -1133,8 +1131,8 @@ export function optionFromNullOr<T>(): Transformation<Option.Option<T>, T | null
 }
 
 /**
- * Decodes `T | undefined` into `Option<T>` and encodes `Option<T>` back
- * to `T | undefined`.
+ * Decodes `T | undefined` into `Option<T>` and encodes `Option.none()` back to
+ * `undefined`.
  *
  * **When to use**
  *
@@ -1264,8 +1262,8 @@ export function optionFromOptionalKey<T>(): Transformation<Option.Option<T>, T>
 }
 
 /**
- * Decodes `T | undefined` into `Option<T>` and encodes `Option<T>` back
- * to `T | undefined`.
+ * Decodes optional values into `Option<T>` and encodes `Option.none()` back to
+ * an omitted optional value.
  *
  * **When to use**
  *

package/src/Scope.ts

@@ -229,7 +229,12 @@ export declare namespace State {
 }
 
 /**
- * The service tag for `Scope`, used for dependency injection in the Effect system.
+ * Service tag for the active resource lifetime.
+ *
+ * **When to use**
+ *
+ * Use to access the active lifetime when registering finalizers or sharing
+ * resources with the surrounding scope.
  *
  * **Example** (Accessing the scope service)
  *
@@ -306,8 +311,16 @@ export const make: (finalizerStrategy?: "sequential" | "parallel") => Effect<Clo
 export const makeUnsafe: (finalizerStrategy?: "sequential" | "parallel") => Closeable = effect.scopeMakeUnsafe
 
 /**
- * Provides a `Scope` to an `Effect`, removing the `Scope` requirement from its context.
- * This allows you to run effects that require a scope by explicitly providing one.
+ * Provides a concrete `Scope` to an effect.
+ *
+ * **When to use**
+ *
+ * Use to run an effect that requires `Scope` with a scope managed by the
+ * caller.
+ *
+ * **Details**
+ *
+ * Providing the scope removes the `Scope` requirement from the effect context.
  *
  * **Example** (Providing a scope)
  *
@@ -333,8 +346,16 @@ export const makeUnsafe: (finalizerStrategy?: "sequential" | "parallel") => Clos
  */
 export const provide: {
   /**
-   * Provides a `Scope` to an `Effect`, removing the `Scope` requirement from its context.
-   * This allows you to run effects that require a scope by explicitly providing one.
+   * Provides a concrete `Scope` to an effect.
+   *
+   * **When to use**
+   *
+   * Use to run an effect that requires `Scope` with a scope managed by the
+   * caller.
+   *
+   * **Details**
+   *
+   * Providing the scope removes the `Scope` requirement from the effect context.
    *
    * **Example** (Providing a scope)
    *
@@ -360,8 +381,16 @@ export const provide: {
    */
   (value: Scope): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, Exclude<R, Scope>>
   /**
-   * Provides a `Scope` to an `Effect`, removing the `Scope` requirement from its context.
-   * This allows you to run effects that require a scope by explicitly providing one.
+   * Provides a concrete `Scope` to an effect.
+   *
+   * **When to use**
+   *
+   * Use to run an effect that requires `Scope` with a scope managed by the
+   * caller.
+   *
+   * **Details**
+   *
+   * Providing the scope removes the `Scope` requirement from the effect context.
    *
    * **Example** (Providing a scope)
    *
@@ -506,7 +535,7 @@ export const fork: (
 ) => Effect<Closeable> = effect.scopeFork
 
 /**
- * Synchronously creates a closeable child scope registered with a parent scope.
+ * Creates a closeable child scope synchronously and registers it with a parent scope.
  *
  * **Details**
  *
@@ -540,8 +569,16 @@ export const forkUnsafe: (scope: Scope, finalizerStrategy?: "sequential" | "para
   effect.scopeForkUnsafe
 
 /**
- * Closes a scope, running all registered finalizers in the appropriate order.
- * The exit value is passed to each finalizer.
+ * Closes a scope and runs its registered finalizers.
+ *
+ * **When to use**
+ *
+ * Use to close a scope manually with a specific exit value.
+ *
+ * **Details**
+ *
+ * Finalizers run in the scope's configured order and receive the supplied
+ * `Exit`.
  *
  * **Example** (Running scope finalizers)
  *
@@ -571,7 +608,7 @@ export const forkUnsafe: (scope: Scope, finalizerStrategy?: "sequential" | "para
 export const close: <A, E>(self: Scope, exit: Exit<A, E>) => Effect<void> = effect.scopeClose
 
 /**
- * Unsafely transitions a scope to `Closed` with the provided exit value.
+ * Closes a scope unsafely with the provided exit value.
  *
  * **When to use**
  *
@@ -611,7 +648,7 @@ export const closeUnsafe: <A, E>(self: Scope, exit_: Exit<A, E>) => Effect<void,
  * finalizers can observe whether the effect succeeded, failed, or was
  * interrupted.
  *
- * @see {@link provide} for providing a scope without closing it automatically
+ * @see `provide` for providing a scope without closing it automatically
  * @see `Effect.scoped` for creating and closing a fresh scope around a workflow
  *
  * @category combinators
@@ -633,7 +670,7 @@ export const use: {
    * finalizers can observe whether the effect succeeded, failed, or was
    * interrupted.
    *
-   * @see {@link provide} for providing a scope without closing it automatically
+   * @see `provide` for providing a scope without closing it automatically
    * @see `Effect.scoped` for creating and closing a fresh scope around a workflow
    *
    * @category combinators
@@ -655,7 +692,7 @@ export const use: {
    * finalizers can observe whether the effect succeeded, failed, or was
    * interrupted.
    *
-   * @see {@link provide} for providing a scope without closing it automatically
+   * @see `provide` for providing a scope without closing it automatically
    * @see `Effect.scoped` for creating and closing a fresh scope around a workflow
    *
    * @category combinators