effect 4.0.0-beta.101 → 4.0.0-beta.103

package/src/unstable/cli/Prompt.ts

@@ -29,6 +29,11 @@ import type { Covariant } from "../../Types.ts"
 import * as Ansi from "./internal/ansi.ts"
 import type * as Primitive from "./Primitive.ts"
 
+declare const process: {
+  readonly platform: string
+  readonly cwd: () => string
+}
+
 const TypeId = "~effect/cli/Prompt"
 
 /**
@@ -651,28 +656,35 @@ export declare namespace All {
  *
  * **Example** (Collecting prompt results)
  *
- * ```ts
- * import { Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, FileSystem, Layer, Path, Terminal } from "effect"
  * import { Prompt } from "effect/unstable/cli"
  *
- * const username = Prompt.text({
- *   message: "Enter your username: "
+ * const terminal = Terminal.make({
+ *   columns: Effect.succeed(80),
+ *   rows: Effect.succeed(24),
+ *   readInput: Effect.succeed({} as never),
+ *   readLine: Effect.die("unused"),
+ *   display: () => Effect.void
  * })
+ * const services = Layer.mergeAll(
+ *   FileSystem.layerNoop({}),
+ *   Path.layer,
+ *   Layer.succeed(Terminal.Terminal, terminal)
+ * )
  *
- * const password = Prompt.password({
- *   message: "Enter your password: ",
- *   validate: (value) =>
- *     value.length === 0
- *       ? Effect.fail("Password cannot be empty")
- *       : Effect.succeed(value)
- * })
+ * const username = Prompt.succeed("alice")
+ * const password = Prompt.succeed("secret")
  *
  * const allWithTuple = Prompt.all([username, password])
  *
  * const allWithRecord = Prompt.all({ username, password })
+ *
+ * await Effect.runPromise(Effect.provide(allWithTuple, services)) // => ["alice", "secret"]
+ * await Effect.runPromise(Effect.provide(allWithRecord, services)) // => { username: "alice", password: "secret" }
  * ```
  *
- * @category collecting & elements
+ * @category combining
  * @since 4.0.0
  */
 export const all: <
@@ -1128,7 +1140,7 @@ export const password = (
  * The returned effect may fail with `Terminal.QuitError` if terminal input ends
  * or the prompt is quit.
  *
- * @category execution
+ * @category running
  * @since 4.0.0
  */
 export const run: <Output>(
@@ -1194,7 +1206,7 @@ export const select = <const A>(options: SelectOptions<A>): Prompt<A> => {
  *
  * **Example** (Filtering choices with autocomplete)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Prompt } from "effect/unstable/cli"
  *
  * const language = Prompt.autoComplete({
@@ -1205,6 +1217,8 @@ export const select = <const A>(options: SelectOptions<A>): Prompt<A> => {
  *     { title: "Kotlin", value: "kt" }
  *   ]
  * })
+ *
+ * Prompt.isPrompt(language) // => true
  * ```
  *
  * @category constructors

package/src/unstable/cli/internal/command.ts

@@ -125,7 +125,7 @@ export const makeCommand = <const Name extends string, Input, E, R, ContextInput
       : Effect.fail(new CliError.ShowHelp({ commandPath, errors: [] }))
 
   const parse = options.parse ?? makeParser(config) as any
-  const parseContext = options.parseContext ?? makeParser(contextConfig) as any
+  const parseContext = options.parseContext ?? makeParser(contextConfig, { allowLeftovers: true }) as any
 
   const buildHelpDoc = (commandPath: ReadonlyArray<string>): HelpDoc => {
     const args: Array<ArgDoc> = []
@@ -263,10 +263,18 @@ const appendChoiceKeys = (
  * and `parseContext`, and also by `withSharedFlags` to avoid constructing a
  * full throwaway command.
  */
-export const makeParser = (cfg: ConfigInternal) =>
+export const makeParser = (
+  cfg: ConfigInternal,
+  options?: {
+    readonly allowLeftovers?: boolean | undefined
+  } | undefined
+) =>
   Effect.fnUntraced(function*(input: ParsedTokens) {
     const parsedArgs: Param.ParsedArgs = { flags: input.flags, arguments: input.arguments }
-    const values = yield* parseParams(parsedArgs, cfg.orderedParams)
+    const [remainingArguments, values] = yield* parseParams(parsedArgs, cfg.orderedParams)
+    if (options?.allowLeftovers !== true && remainingArguments.length > 0) {
+      return yield* new CliError.UnexpectedArgument({ arguments: remainingArguments })
+    }
     return reconstructTree(cfg.tree, values)
   })
 
@@ -275,7 +283,7 @@ export const makeParser = (cfg: ConfigInternal) =>
  * representations.
  */
 const parseParams: (parsedArgs: Param.ParsedArgs, params: ReadonlyArray<Param.Any>) => Effect.Effect<
-  ReadonlyArray<unknown>,
+  readonly [remainingArguments: ReadonlyArray<string>, values: ReadonlyArray<unknown>],
   CliError.CliError,
   Environment
 > = Effect.fnUntraced(function*(parsedArgs, params) {
@@ -291,7 +299,7 @@ const parseParams: (parsedArgs: Param.ParsedArgs, params: ReadonlyArray<Param.An
     currentArguments = remainingArguments
   }
 
-  return results
+  return [currentArguments, results] as const
 })
 
 /**

package/src/unstable/cli/internal/config.ts

@@ -46,6 +46,7 @@
  * 1. Flat iteration over all params for parsing/validation
  * 2. Reconstruction of original nested shape for handler input
  */
+import * as InternalRecord from "../../../internal/record.ts"
 import * as Param from "../Param.ts"
 
 /* ========================================================================== */
@@ -135,8 +136,8 @@ export const parseConfig = (config: Config): ConfigInternal => {
   const args: Array<Param.AnyArgument> = []
 
   function parse(config: Config): ConfigInternal.Tree {
-    const tree: ConfigInternal.Tree = {}
-    for (const key in config) {
+    const tree: ConfigInternal.Tree = Object.create(null)
+    for (const key of Object.keys(config)) {
       tree[key] = parseValue(config[key])
     }
     return tree
@@ -202,8 +203,8 @@ const shiftNodeIndexes = (node: ConfigInternal.Node, offset: number): ConfigInte
 }
 
 const shiftTreeIndexes = (tree: ConfigInternal.Tree, offset: number): ConfigInternal.Tree => {
-  const output: ConfigInternal.Tree = {}
-  for (const key in tree) {
+  const output: ConfigInternal.Tree = Object.create(null)
+  for (const key of Object.keys(tree)) {
     output[key] = shiftNodeIndexes(tree[key], offset)
   }
   return output
@@ -220,10 +221,7 @@ export const mergeConfig = (
     flags: [...left.flags, ...right.flags],
     arguments: [...left.arguments, ...right.arguments],
     orderedParams: [...left.orderedParams, ...right.orderedParams],
-    tree: {
-      ...left.tree,
-      ...shiftTreeIndexes(right.tree, offset)
-    }
+    tree: Object.assign(Object.create(null), left.tree, shiftTreeIndexes(right.tree, offset))
   }
 }
 
@@ -245,8 +243,8 @@ export const reconstructTree = (
 ): Record<string, any> => {
   const output: Record<string, any> = {}
 
-  for (const key in tree) {
-    output[key] = nodeValue(tree[key])
+  for (const key of Object.keys(tree)) {
+    InternalRecord.assignProperty(output, key, nodeValue(tree[key]))
   }
 
   return output

package/src/unstable/cli/internal/lexer.ts

@@ -47,8 +47,14 @@ const lexTokens = (args: ReadonlyArray<string>): ReadonlyArray<Token> => {
     if (!arg.startsWith("-")) {
       tokens.push({ _tag: "Value", value: arg })
     } else if (arg.startsWith("--")) {
-      const [name, value] = arg.slice(2).split("=", 2)
-      tokens.push({ _tag: "LongOption", name, raw: arg, value })
+      const equalIndex = arg.indexOf("=")
+      if (equalIndex !== -1) {
+        const name = arg.slice(2, equalIndex)
+        const value = arg.slice(equalIndex + 1)
+        tokens.push({ _tag: "LongOption", name, raw: arg, value })
+      } else {
+        tokens.push({ _tag: "LongOption", name: arg.slice(2), raw: arg })
+      }
     } else if (arg.length > 1) {
       const flags = arg.slice(1)
       const equalIndex = flags.indexOf("=")

package/src/unstable/cli/internal/parser.ts

@@ -84,7 +84,7 @@ export const parseArgs = (
       }
     }
 
-    const subLex: LexResult = { tokens: result.childTokens, trailingOperands: [] }
+    const subLex: LexResult = { tokens: result.childTokens, trailingOperands: afterEndOfOptions }
     const subParsed = yield* parseArgs(
       subLex,
       result.sub,
@@ -94,7 +94,7 @@ export const parseArgs = (
     const allErrors = [...result.errors, ...(subParsed.errors ?? [])]
     return {
       flags: result.flags,
-      arguments: afterEndOfOptions,
+      arguments: [],
       subcommand: Option.some({ name: result.sub.name, parsedInput: subParsed }),
       ...(allErrors.length > 0 && { errors: allErrors })
     }

package/src/unstable/cluster/ClusterSchema.ts

@@ -20,7 +20,7 @@ import type { Request } from "./Envelope.ts"
  *
  * The default value is `false`.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export const Persisted = Context.Reference<boolean>("effect/cluster/ClusterSchema/Persisted", {
@@ -46,7 +46,7 @@ export const Persisted = Context.Reference<boolean>("effect/cluster/ClusterSchem
  * This annotation has transactional behavior only when the configured
  * `MessageStorage` implements it.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export const WithTransaction = Context.Reference<boolean>(
@@ -64,7 +64,7 @@ export const WithTransaction = Context.Reference<boolean>(
  * handling only, `"server"` for server-side handling only, or `false` to allow
  * interruption.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export const Uninterruptible = Context.Reference<boolean | "client" | "server">(
@@ -83,7 +83,7 @@ export const Uninterruptible = Context.Reference<boolean | "client" | "server">(
  * @see {@link Uninterruptible} for the annotation values interpreted by this helper
  * @see {@link isUninterruptibleForClient} for the client-side counterpart
  *
- * @category annotations
+ * @category predicates
  * @since 4.0.0
  */
 export const isUninterruptibleForServer = (context: Context.Context<never>): boolean => {
@@ -108,7 +108,7 @@ export const isUninterruptibleForServer = (context: Context.Context<never>): boo
  * @see {@link Uninterruptible} for the annotation values interpreted by this helper
  * @see {@link isUninterruptibleForServer} for the server-side counterpart
  *
- * @category annotations
+ * @category predicates
  * @since 4.0.0
  */
 export const isUninterruptibleForClient = (context: Context.Context<never>): boolean => {
@@ -123,7 +123,7 @@ export const isUninterruptibleForClient = (context: Context.Context<never>): boo
  *
  * By default, every entity id is assigned to the `"default"` shard group.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export const ShardGroup = Context.Reference<(entityId: EntityId) => string>(
@@ -139,7 +139,7 @@ export const ShardGroup = Context.Reference<(entityId: EntityId) => string>(
  *
  * The default value is `true`.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export const ClientTracingEnabled = Context.Reference<boolean>("effect/cluster/ClusterSchema/ClientTracingEnabled", {
@@ -159,7 +159,7 @@ export const ClientTracingEnabled = Context.Reference<boolean>("effect/cluster/C
  * This only applies to requests handled by the entity, not to the generated
  * client.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export const Dynamic = Context.Reference<

package/src/unstable/cluster/ClusterWorkflowEngine.ts

@@ -83,7 +83,7 @@ export const make = Effect.gen(function*() {
       | Rpc.Rpc<
         "activity",
         Schema.Struct<
-          { name: typeof Schema.String; attempt: typeof Schema.Number; withTransaction: typeof Schema.Boolean }
+          { name: typeof Schema.String; attempt: typeof Schema.Int; withTransaction: typeof Schema.Boolean }
         >,
         Schema.declare<Workflow.Result<any, any>>
       >
@@ -97,7 +97,7 @@ export const make = Effect.gen(function*() {
       | Rpc.Rpc<"deferred", Schema.Struct<{ name: typeof Schema.String; exit: typeof ExitUnknown }>, typeof ExitUnknown>
       | Rpc.Rpc<
         "activity",
-        Schema.Struct<{ name: typeof Schema.String; attempt: typeof Schema.Number }>,
+        Schema.Struct<{ name: typeof Schema.String; attempt: typeof Schema.Int }>,
         Schema.declare<Workflow.Result<any, any>>
       >
       | Rpc.Rpc<"resume">
@@ -167,12 +167,16 @@ export const make = Effect.gen(function*() {
     readonly payload: unknown
   }) {
     const payload = (options.rpc.payloadSchema as any).make(options.payload)
+    const span = yield* Effect.orDie(Effect.currentSpan)
     const envelope = Envelope.makeRequest<any>({
       requestId: yield* sharding.getSnowflake,
       address: options.address,
       tag: options.rpc._tag as any,
       payload,
-      headers: Headers.empty
+      headers: Headers.empty,
+      traceId: span.traceId,
+      spanId: span.spanId,
+      sampled: span.sampled
     })
     yield* sharding.sendOutgoing(
       new Message.OutgoingRequest({
@@ -644,7 +648,7 @@ const ExitUnknown = Schema.Exit(AnyOrVoid, AnyOrVoid, Schema.Any)
 const ActivityRpc = Rpc.make("activity", {
   payload: {
     name: Schema.String,
-    attempt: Schema.Number,
+    attempt: Schema.Int,
     withTransaction: Schema.Boolean.pipe(
       Schema.withDecodingDefault(Effect.succeed(false))
     )

package/src/unstable/cluster/Entity.ts

@@ -216,7 +216,7 @@ export type Any = Entity<string, Rpc.Any>
  * Each handler receives the entity request envelope for that RPC and returns the
  * RPC result or a supported RPC wrapper.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type HandlersFrom<Rpc extends Rpc.Any> = {
@@ -232,7 +232,7 @@ export type HandlersFrom<Rpc extends Rpc.Any> = {
  *
  * The check is based on the internal entity type identifier.
  *
- * @category refinements
+ * @category guards
  * @since 4.0.0
  */
 export const isEntity = (u: unknown): u is Any => Predicate.hasProperty(u, TypeId)
@@ -349,7 +349,7 @@ const Proto = {
           ),
           Stream.unwrap
         )
-      const handlers: Record<string, any> = {}
+      const handlers: Record<string, any> = Object.create(null)
       for (const rpc_ of this.protocol.requests.values()) {
         const rpc = rpc_ as any as Rpc.AnyWithProps
         handlers[rpc._tag] = RpcSchema.isStreamSchema(rpc.successSchema) ? streamHandler : handler
@@ -464,7 +464,7 @@ export const make = <const Type extends string, Rpcs extends ReadonlyArray<Rpc.A
  * Use to read the current entity identity and shard address from entity
  * handlers and keep-alive logic.
  *
- * @category context
+ * @category services
  * @since 4.0.0
  */
 export class CurrentAddress extends Context.Service<
@@ -480,7 +480,7 @@ export class CurrentAddress extends Context.Service<
  * Use to read the runner address associated with the current entity handler
  * registration.
  *
- * @category context
+ * @category services
  * @since 4.0.0
  */
 export class CurrentRunnerAddress extends Context.Service<
@@ -496,7 +496,7 @@ export class CurrentRunnerAddress extends Context.Service<
  * Use when you use it to complete an entity request by succeeding, failing, failing with a
  * cause, or supplying an explicit `Exit`.
  *
- * @category Replier
+ * @category models
  * @since 4.0.0
  */
 export interface Replier<Rpcs extends Rpc.Any> {
@@ -535,7 +535,7 @@ export declare namespace Replier {
    * For streaming RPCs this may be either a stream of success chunks or a dequeue
    * of success chunks. For non-streaming RPCs it is the RPC success value.
    *
-   * @category Replier
+   * @category utility types
    * @since 4.0.0
    */
   export type Success<R extends Rpc.Any> = Rpc.Success<R> extends Stream.Stream<infer _A, infer _E, infer _R> ?
@@ -551,7 +551,7 @@ export declare namespace Replier {
  * It includes the underlying request envelope plus the last stream reply chunk
  * that was sent, allowing handlers to resume chunk sequencing after a restart.
  *
- * @category request
+ * @category models
  * @since 4.0.0
  */
 export class Request<Rpc extends Rpc.Any> extends Data.Class<
@@ -645,12 +645,11 @@ export const makeTestClient: <Type extends string, Rpcs extends Rpc.Any, LA, LE,
       shardId: makeShardId(entityId)
     })
     const scope = yield* Effect.scope
-    const handlerContext = Context.mutate(entityEntry.context, (context) =>
-      context.pipe(
-        Context.add(CurrentRunnerAddress, runnerAddress),
-        Context.add(CurrentAddress, address),
-        Context.add(Scope, scope)
-      ))
+    const handlerContext = entityEntry.context.pipe(
+      Context.add(CurrentRunnerAddress, runnerAddress),
+      Context.add(CurrentAddress, address),
+      Context.add(Scope, scope)
+    )
     const handlers = yield* entityEntry.build.pipe(
       Effect.setContext(handlerContext as Context.Context<any>)
     )
@@ -699,7 +698,7 @@ export const makeTestClient: <Type extends string, Rpcs extends Rpc.Any, LA, LE,
  * When enabled it sends the internal keep-alive RPC for the current address; when
  * disabled it releases the keep-alive latch if one is present.
  *
- * @category Keep alive
+ * @category keep alive
  * @since 4.0.0
  */
 export const keepAlive: (
@@ -755,7 +754,7 @@ export const keepAlive: (
  * The RPC is marked as persisted and uninterruptible so the keep-alive signal
  * survives normal entity restarts.
  *
- * @category Keep alive
+ * @category keep alive
  * @since 4.0.0
  */
 export const KeepAliveRpc = Rpc.make("Cluster/Entity/keepAlive")
@@ -770,7 +769,7 @@ export const KeepAliveRpc = Rpc.make("Cluster/Entity/keepAlive")
  * `keepAlive` closes the latch when keep-alive is active and opens it again when
  * the resource no longer needs to keep the entity alive.
  *
- * @category Keep alive
+ * @category services
  * @since 4.0.0
  */
 export class KeepAliveLatch extends Context.Service<KeepAliveLatch, Latch.Latch>()(

package/src/unstable/cluster/EntityProxy.ts

@@ -29,7 +29,7 @@ const clientErrors = [
  *
  * **Example** (Deriving RPC endpoints from an entity)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Layer, Schema } from "effect"
  * import { ClusterSchema, Entity, EntityProxy, EntityProxyServer } from "effect/unstable/cluster"
  * import { Rpc, RpcServer } from "effect/unstable/rpc"
@@ -50,6 +50,7 @@ const clientErrors = [
  * const RpcServerLayer = RpcServer.layer(MyRpcs).pipe(
  *   Layer.provide(EntityProxyServer.layerRpcHandlers(Counter))
  * )
+ * const result = [MyRpcs.requests.size, Layer.isLayer(RpcServerLayer)] // => [2, true]
  * ```
  *
  * @category constructors
@@ -147,7 +148,7 @@ const entityIdPath = {
  *
  * **Example** (Deriving HTTP API endpoints from an entity)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Layer, Schema } from "effect"
  * import { ClusterSchema, Entity, EntityProxy, EntityProxyServer } from "effect/unstable/cluster"
  * import { HttpApi, HttpApiBuilder } from "effect/unstable/httpapi"
@@ -175,6 +176,7 @@ const entityIdPath = {
  * const ApiLayer = HttpApiBuilder.layer(MyApi).pipe(
  *   Layer.provide(EntityProxyServer.layerHttpApi(MyApi, "counter", Counter))
  * )
+ * const result = [Object.keys(MyApi.groups.counter.endpoints).length, Layer.isLayer(ApiLayer)] // => [2, true]
  * ```
  *
  * @category constructors

package/src/unstable/cluster/EntityResource.ts

@@ -66,7 +66,7 @@ export interface EntityResource<out A, out E = never> {
  *
  * It is not closed during restarts, due to shard movement or node shutdowns.
  *
- * @category resource management
+ * @category services
  * @since 4.0.0
  */
 export class CloseScope extends Context.Service<
@@ -156,7 +156,7 @@ export const make: <A, E, R>(options: {
  * The pod is created and waited on through `K8sHttpClient`, and is kept alive
  * until the resource is closed or its idle time to live expires.
  *
- * @category Kubernetes
+ * @category constructors
  * @since 4.0.0
  */
 export const makeK8sPod: (

package/src/unstable/cluster/Envelope.ts

@@ -320,7 +320,7 @@ export declare namespace Request {
  *
  * The check is based on the envelope type identifier.
  *
- * @category refinements
+ * @category guards
  * @since 4.0.0
  */
 export const isEnvelope = (u: unknown): u is Envelope<any> => Predicate.hasProperty(u, TypeId)
@@ -403,7 +403,7 @@ export const RequestTransform: SchemaTransformation.Transformation<
  * Returns the storage primary key for a request envelope whose payload has a
  * primary key, or `null` when the envelope is not a keyed request.
  *
- * @category primary key
+ * @category getters
  * @since 4.0.0
  */
 export const primaryKey = <R extends Rpc.Any>(envelope: Envelope<R>): string | null => {
@@ -421,7 +421,7 @@ export const primaryKey = <R extends Rpc.Any>(envelope: Envelope<R>): string | n
  * Builds a storage primary-key string from an entity address, RPC tag, and
  * payload primary-key ID.
  *
- * @category primary key
+ * @category constructors
  * @since 4.0.0
  */
 export const primaryKeyByAddress = (options: {
@@ -429,5 +429,6 @@ export const primaryKeyByAddress = (options: {
   readonly tag: string
   readonly id: string
 }): string =>
-  // hash the entity address to save space?
+  // storage drivers with fixed-width key columns (e.g. SqlMessageStorage)
+  // hash this composed key at their own boundary
   `${options.address.entityType}/${options.address.entityId}/${options.tag}/${options.id}`

package/src/unstable/cluster/HttpRunner.ts

@@ -139,7 +139,7 @@ export const layerClientProtocolWebsocketDefault: Layer.Layer<
  * The returned effect is produced from `RunnerServer.layerHandlers` and the
  * cluster runner RPC group.
  *
- * @category http app
+ * @category running
  * @since 4.0.0
  */
 export const toHttpEffect: Effect.Effect<
@@ -150,7 +150,8 @@ export const toHttpEffect: Effect.Effect<
   const handlers = yield* Layer.build(RunnerServer.layerHandlers)
   return yield* RpcServer.toHttpEffect(Runners.Rpcs, {
     spanPrefix: "RunnerServer",
-    disableTracing: true
+    disableTracing: true,
+    disableFatalDefects: true
   }).pipe(Effect.provideContext(handlers))
 })
 
@@ -162,7 +163,7 @@ export const toHttpEffect: Effect.Effect<
  * The returned effect is produced from `RunnerServer.layerHandlers` and the
  * cluster runner RPC group.
  *
- * @category http app
+ * @category running
  * @since 4.0.0
  */
 export const toHttpEffectWebsocket: Effect.Effect<
@@ -173,7 +174,8 @@ export const toHttpEffectWebsocket: Effect.Effect<
   const handlers = yield* Layer.build(RunnerServer.layerHandlers)
   return yield* RpcServer.toHttpEffectWebsocket(Runners.Rpcs, {
     spanPrefix: "RunnerServer",
-    disableTracing: true
+    disableTracing: true,
+    disableFatalDefects: true
   }).pipe(Effect.provideContext(handlers))
 })
 

package/src/unstable/cluster/Message.ts

@@ -31,7 +31,7 @@ import type { Snowflake } from "./Snowflake.ts"
  * An incoming message is either a persisted request with an encoded payload or an
  * incoming control envelope.
  *
- * @category incoming
+ * @category models
  * @since 4.0.0
  */
 export type Incoming<R extends Rpc.Any> = IncomingRequest<R> | IncomingEnvelope
@@ -43,7 +43,7 @@ export type Incoming<R extends Rpc.Any> = IncomingRequest<R> | IncomingEnvelope
  *
  * It is either a request with a decoded payload or an incoming control envelope.
  *
- * @category incoming
+ * @category models
  * @since 4.0.0
  */
 export type IncomingLocal<R extends Rpc.Any> = IncomingRequestLocal<R> | IncomingEnvelope
@@ -56,7 +56,7 @@ export type IncomingLocal<R extends Rpc.Any> = IncomingRequestLocal<R> | Incomin
  * Request messages keep their decoded payload and response callback, while
  * control envelopes are wrapped as incoming envelopes.
  *
- * @category incoming
+ * @category converting
  * @since 4.0.0
  */
 export const incomingLocalFromOutgoing = <R extends Rpc.Any>(self: Outgoing<R>): IncomingLocal<R> => {
@@ -83,7 +83,7 @@ export const incomingLocalFromOutgoing = <R extends Rpc.Any>(self: Outgoing<R>):
  * It carries the last reply that was sent and a callback for persisting encoded
  * replies.
  *
- * @category incoming
+ * @category models
  * @since 4.0.0
  */
 export class IncomingRequest<R extends Rpc.Any> extends Data.TaggedClass("IncomingRequest")<{
@@ -100,7 +100,7 @@ export class IncomingRequest<R extends Rpc.Any> extends Data.TaggedClass("Incomi
  * It includes dynamic annotations, the last sent reply, and a callback for
  * replying with decoded replies.
  *
- * @category incoming
+ * @category models
  * @since 4.0.0
  */
 export class IncomingRequestLocal<R extends Rpc.Any> extends Data.TaggedClass("IncomingRequestLocal")<{
@@ -113,7 +113,7 @@ export class IncomingRequestLocal<R extends Rpc.Any> extends Data.TaggedClass("I
 /**
  * Represents an incoming control envelope carrying an `AckChunk` or `Interrupt`.
  *
- * @category incoming
+ * @category models
  * @since 4.0.0
  */
 export class IncomingEnvelope extends Data.TaggedClass("IncomingEnvelope")<{
@@ -128,7 +128,7 @@ export class IncomingEnvelope extends Data.TaggedClass("IncomingEnvelope")<{
  *
  * An outgoing message is either an entity request or a control envelope.
  *
- * @category outgoing
+ * @category models
  * @since 4.0.0
  */
 export type Outgoing<R extends Rpc.Any> = OutgoingRequest<R> | OutgoingEnvelope
@@ -141,7 +141,7 @@ export type Outgoing<R extends Rpc.Any> = OutgoingRequest<R> | OutgoingEnvelope
  * It carries the service context used for serialization, the last received reply,
  * the reply callback, dynamic annotations, and an optional encoded request cache.
  *
- * @category outgoing
+ * @category models
  * @since 4.0.0
  */
 export class OutgoingRequest<R extends Rpc.Any> extends Data.TaggedClass("OutgoingRequest")<{
@@ -168,7 +168,7 @@ export class OutgoingRequest<R extends Rpc.Any> extends Data.TaggedClass("Outgoi
  * Use to construct an interrupt envelope for an
  * in-flight request.
  *
- * @category outgoing
+ * @category models
  * @since 4.0.0
  */
 export class OutgoingEnvelope extends Data.TaggedClass("OutgoingEnvelope")<{