effect 4.0.0-beta.99 → 4.0.0-rc.109

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 })
     }
@@ -826,12 +826,12 @@ const resolveFirstValue = (
   // Not a subcommand. Check if this looks like a typo.
   const expectsArgs = toImpl(command).config.arguments.length > 0
   if (!expectsArgs && subIndex.size > 0) {
-    // Exclude hidden subcommands so a typo cannot reveal a subcommand name
-    // that was intentionally kept out of --help. Hidden commands still
+    // Exclude unlisted subcommands so a typo cannot reveal a subcommand name
+    // that was intentionally kept out of --help. Unlisted commands still
     // resolve via subIndex when invoked by exact name.
     const visibleKeys: Array<string> = []
     for (const [key, sub] of subIndex) {
-      if (!sub.hidden) visibleKeys.push(key)
+      if (!sub.unlisted) visibleKeys.push(key)
     }
     const suggestions = suggest(value, visibleKeys)
     state.errors.push(

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

@@ -54,7 +54,7 @@ const promptCommand: (
 ) => Effect.Effect<void, CliError.CliError | Terminal.QuitError, Command.Environment> = Effect.fnUntraced(
   function*(command, commandLine, sectionName) {
     const impl = toImpl(command)
-    const visibleSubcommands = command.subcommands.flatMap((group) => group.commands.filter((child) => !child.hidden))
+    const visibleSubcommands = command.subcommands.flatMap((group) => group.commands.filter((child) => !child.unlisted))
     const config = visibleSubcommands.length === 0 ? impl.config : impl.contextConfig
 
     if (config.flags.length > 0) {
@@ -103,7 +103,7 @@ const promptCommand: (
 )
 
 const hasWizardSteps = (command: Command.Command.Any): boolean => {
-  const hasVisibleSubcommands = command.subcommands.some((group) => group.commands.some((child) => !child.hidden))
+  const hasVisibleSubcommands = command.subcommands.some((group) => group.commands.some((child) => !child.unlisted))
   return hasVisibleSubcommands || toImpl(command).config.orderedParams.length > 0
 }
 

package/src/unstable/cluster/ClusterError.ts

@@ -26,7 +26,7 @@ const TypeId = "~effect/cluster/ClusterError"
  * @since 4.0.0
  */
 export class EntityNotAssignedToRunner
-  extends Schema.ErrorClass<EntityNotAssignedToRunner>(`${TypeId}/EntityNotAssignedToRunner`)({
+  extends Schema.Error<EntityNotAssignedToRunner>(`${TypeId}/EntityNotAssignedToRunner`)({
     _tag: Schema.tag("EntityNotAssignedToRunner"),
     address: EntityAddress
   })
@@ -60,7 +60,7 @@ export class EntityNotAssignedToRunner
  * @category errors
  * @since 4.0.0
  */
-export class MalformedMessage extends Schema.ErrorClass<MalformedMessage>(`${TypeId}/MalformedMessage`)({
+export class MalformedMessage extends Schema.Error<MalformedMessage>(`${TypeId}/MalformedMessage`)({
   _tag: Schema.tag("MalformedMessage"),
   cause: Schema.Defect()
 }) {
@@ -99,7 +99,7 @@ export class MalformedMessage extends Schema.ErrorClass<MalformedMessage>(`${Typ
  * @category errors
  * @since 4.0.0
  */
-export class PersistenceError extends Schema.ErrorClass<PersistenceError>(`${TypeId}/PersistenceError`)({
+export class PersistenceError extends Schema.Error<PersistenceError>(`${TypeId}/PersistenceError`)({
   _tag: Schema.tag("PersistenceError"),
   cause: Schema.Defect()
 }) {
@@ -127,7 +127,7 @@ export class PersistenceError extends Schema.ErrorClass<PersistenceError>(`${Typ
  * @category errors
  * @since 4.0.0
  */
-export class RunnerNotRegistered extends Schema.ErrorClass<RunnerNotRegistered>(`${TypeId}/RunnerNotRegistered`)({
+export class RunnerNotRegistered extends Schema.Error<RunnerNotRegistered>(`${TypeId}/RunnerNotRegistered`)({
   _tag: Schema.tag("RunnerNotRegistered"),
   address: RunnerAddress
 }) {
@@ -145,7 +145,7 @@ export class RunnerNotRegistered extends Schema.ErrorClass<RunnerNotRegistered>(
  * @category errors
  * @since 4.0.0
  */
-export class RunnerUnavailable extends Schema.ErrorClass<RunnerUnavailable>(`${TypeId}/RunnerUnavailable`)({
+export class RunnerUnavailable extends Schema.Error<RunnerUnavailable>(`${TypeId}/RunnerUnavailable`)({
   _tag: Schema.tag("RunnerUnavailable"),
   address: RunnerAddress
 }) {
@@ -171,7 +171,9 @@ export class RunnerUnavailable extends Schema.ErrorClass<RunnerUnavailable>(`${T
  *
  * **Details**
  *
- * Carries the `address` whose bounded mailbox is at capacity.
+ * Carries the `address` whose bounded mailbox is at capacity. It is also used
+ * when the runner has reached `ShardingConfig.maxResidentEntities` and cannot
+ * spawn a new entity for the `address`.
  *
  * **Gotchas**
  *
@@ -181,7 +183,7 @@ export class RunnerUnavailable extends Schema.ErrorClass<RunnerUnavailable>(`${T
  * @category errors
  * @since 4.0.0
  */
-export class MailboxFull extends Schema.ErrorClass<MailboxFull>(`${TypeId}/MailboxFull`)({
+export class MailboxFull extends Schema.Error<MailboxFull>(`${TypeId}/MailboxFull`)({
   _tag: Schema.tag("MailboxFull"),
   address: EntityAddress
 }) {
@@ -214,7 +216,7 @@ export class MailboxFull extends Schema.ErrorClass<MailboxFull>(`${TypeId}/Mailb
  * @since 4.0.0
  */
 export class AlreadyProcessingMessage
-  extends Schema.ErrorClass<AlreadyProcessingMessage>(`${TypeId}/AlreadyProcessingMessage`)({
+  extends Schema.Error<AlreadyProcessingMessage>(`${TypeId}/AlreadyProcessingMessage`)({
     _tag: Schema.tag("AlreadyProcessingMessage"),
     envelopeId: SnowflakeFromString,
     address: EntityAddress

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">
@@ -127,6 +127,7 @@ export const make = Effect.gen(function*() {
   }>()
   const interruptedActivities = new Set<string>()
   const activityLatches = new Map<string, Latch.Latch>()
+  const deferredState = WorkflowEngine.makeDeferredState()
   const clients = yield* RcMap.make({
     lookup: Effect.fnUntraced(function*(workflowName: string) {
       const entity = entities.get(workflowName)
@@ -167,12 +168,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({
@@ -382,7 +387,7 @@ export const make = Effect.gen(function*() {
                     )
                   }),
                   Workflow.intoResult,
-                  Effect.provideService(WorkflowEngine.WorkflowInstance, instance)
+                  (effect) => deferredState.trackRun(instance, effect)
                 ) as any
               },
 
@@ -399,11 +404,12 @@ export const make = Effect.gen(function*() {
                     yield* latch.await
                     entry = activities.get(activityId)
                   }
-                  const contextMap = new Map(entry.context.mapUnsafe)
-                  contextMap.set(Activity.CurrentAttempt.key, payload.attempt)
-                  contextMap.set(WorkflowEngine.WorkflowInstance.key, instance)
+                  const context = entry.context.pipe(
+                    Context.add(WorkflowEngine.WorkflowInstance, instance),
+                    Context.add(Activity.CurrentAttempt, payload.attempt)
+                  )
                   return yield* entry.activity.executeEncoded.pipe(
-                    Effect.provideContext(Context.makeUnsafe(contextMap))
+                    Effect.provideContext(context)
                   )
                 }).pipe(
                   Workflow.intoResult,
@@ -430,13 +436,16 @@ export const make = Effect.gen(function*() {
 
               deferred: Effect.fnUntraced(function*(request: Entity.Request<any>) {
                 const payload = request.payload as any
+                yield* deferredState.deferredDone(executionId, payload.name, payload.exit)
                 yield* ensureSuccess(resume(workflow, executionId))
                 return payload.exit
               }),
 
               resume: () => ensureSuccess(resume(workflow, executionId))
             }
-          })
+          }),
+          // Reserve a slot for deferred completions to wake the active run.
+          { concurrency: 2, maxIdleTime: entityMaxIdleTime }
         ) as Effect.Effect<void, never, Scope.Scope>
       ),
 
@@ -545,24 +554,29 @@ export const make = Effect.gen(function*() {
 
     deferredResult: (deferred) =>
       WorkflowEngine.WorkflowInstance.pipe(
-        Effect.flatMap((instance) =>
-          requestReply({
+        Effect.flatMap((instance) => {
+          const exit = deferredState.pendingResult(instance.executionId, deferred.name)
+          if (exit) {
+            return Effect.succeedSome(exit)
+          }
+          return requestReply({
             workflow: instance.workflow,
             entityType: `Workflow/${instance.workflow._tag}`,
             executionId: instance.executionId,
             tag: "deferred",
             id: deferred.name
-          })
-        ),
-        Effect.map((reply) => {
-          if (Option.isNone(reply)) {
-            return Option.none<Exit.Exit<unknown, unknown>>()
-          }
-          const decoded = decodeDeferredWithExit(reply.value as any)
-          return Option.some(
-            decoded.exit._tag === "Success"
-              ? decoded.exit.value
-              : decoded.exit
+          }).pipe(
+            Effect.map((reply) => {
+              if (Option.isNone(reply)) {
+                return Option.none<Exit.Exit<unknown, unknown>>()
+              }
+              const decoded = decodeDeferredWithExit(reply.value as any)
+              return Option.some(
+                decoded.exit._tag === "Success"
+                  ? decoded.exit.value
+                  : decoded.exit
+              )
+            })
           )
         }),
         Effect.retry({
@@ -614,7 +628,10 @@ export const make = Effect.gen(function*() {
             payload: {
               name: options.clock.name,
               workflowName: workflow._tag,
-              wakeUp: DateTime.addDuration(now, options.clock.duration)
+              wakeUp: DateTime.mapEpochMillis(
+                DateTime.addDuration(now, options.clock.duration),
+                Math.ceil
+              )
             }
           })
         ),
@@ -644,7 +661,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))
     )
@@ -686,6 +703,12 @@ const ResumeRpc = Rpc.make("resume", {
 
 const payloadParentKey = "~effect/cluster/ClusterWorkflowEngine/payloadParentKey"
 
+// Workflow state is durable, so an idle entity (completed or suspended) can
+// be released quickly and is rebuilt from storage when the next message
+// arrives. This keeps completed and suspended executions from holding
+// `maxResidentEntities` slots for the full `entityMaxIdleTime`.
+const entityMaxIdleTime = Duration.seconds(10)
+
 const makeWorkflowEntity = (workflow: Workflow.Any) =>
   Entity.make(`Workflow/${workflow._tag}`, [
     Rpc.make("run", {
@@ -740,22 +763,25 @@ const ClockEntity = Entity.make("Workflow/-/DurableClock", [
   ClockRpc
 ])
 
-const ClockEntityLayer = ClockEntity.toLayer(Effect.gen(function*() {
-  const engine = yield* WorkflowEngine.WorkflowEngine
-  const address = yield* Entity.CurrentAddress
-  const executionId = address.entityId
-  return {
-    run(request) {
-      const deferred = DurableClock.make({ name: request.payload.name, duration: Duration.zero }).deferred
-      return ensureSuccess(engine.deferredDone(deferred, {
-        workflowName: request.payload.workflowName,
-        executionId,
-        deferredName: deferred.name,
-        exit: Exit.void
-      }))
+const ClockEntityLayer = ClockEntity.toLayer(
+  Effect.gen(function*() {
+    const engine = yield* WorkflowEngine.WorkflowEngine
+    const address = yield* Entity.CurrentAddress
+    const executionId = address.entityId
+    return {
+      run(request) {
+        const deferred = DurableClock.make({ name: request.payload.name, duration: Duration.zero }).deferred
+        return ensureSuccess(engine.deferredDone(deferred, {
+          workflowName: request.payload.workflowName,
+          executionId,
+          deferredName: deferred.name,
+          exit: Exit.void
+        }))
+      }
     }
-  }
-}))
+  }),
+  { maxIdleTime: entityMaxIdleTime }
+)
 
 const InterruptSignal = DurableDeferred.make("Workflow/InterruptSignal")
 

package/src/unstable/cluster/Entity.ts

@@ -34,7 +34,12 @@ import * as RpcClient from "../rpc/RpcClient.ts"
 import * as RpcGroup from "../rpc/RpcGroup.ts"
 import * as RpcSchema from "../rpc/RpcSchema.ts"
 import * as RpcServer from "../rpc/RpcServer.ts"
-import type { AlreadyProcessingMessage, MailboxFull, PersistenceError } from "./ClusterError.ts"
+import type {
+  AlreadyProcessingMessage,
+  EntityNotAssignedToRunner,
+  MailboxFull,
+  PersistenceError
+} from "./ClusterError.ts"
 import { Persisted, ShardGroup, Uninterruptible } from "./ClusterSchema.ts"
 import { EntityAddress } from "./EntityAddress.ts"
 import type { EntityId } from "./EntityId.ts"
@@ -117,7 +122,7 @@ export interface Entity<
       entityId: string
     ) => RpcClient.RpcClient.From<
       Rpcs,
-      MailboxFull | AlreadyProcessingMessage | PersistenceError
+      MailboxFull | AlreadyProcessingMessage | PersistenceError | EntityNotAssignedToRunner
     >,
     never,
     Sharding
@@ -216,7 +221,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 +237,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 +354,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 +469,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 +485,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 +501,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 +540,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 +556,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 +650,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 +703,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 +759,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 +774,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

@@ -14,7 +14,7 @@ import * as HttpApiEndpoint from "../httpapi/HttpApiEndpoint.ts"
 import * as HttpApiGroup from "../httpapi/HttpApiGroup.ts"
 import * as Rpc from "../rpc/Rpc.ts"
 import * as RpcGroup from "../rpc/RpcGroup.ts"
-import { AlreadyProcessingMessage, MailboxFull, PersistenceError } from "./ClusterError.ts"
+import { AlreadyProcessingMessage, EntityNotAssignedToRunner, MailboxFull, PersistenceError } from "./ClusterError.ts"
 import type * as Entity from "./Entity.ts"
 import type { EntityId } from "./EntityId.ts"
 
@@ -24,12 +24,17 @@ const clientErrors = [
   PersistenceError
 ] as const
 
+const requestErrors = [
+  ...clientErrors,
+  EntityNotAssignedToRunner
+] as const
+
 /**
  * Derives an `RpcGroup` from an `Entity`.
  *
  * **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 +55,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
@@ -74,7 +80,7 @@ export const toRpcGroup = <Type extends string, Rpcs extends Rpc.Any>(
     }
     const rpc = Rpc.make(`${entity.type}.${parentRpc._tag}`, {
       payload: payloadSchema,
-      error: Schema.Union([parentRpc.errorSchema, ...clientErrors]),
+      error: Schema.Union([parentRpc.errorSchema, ...requestErrors]),
       success: parentRpc.successSchema
     }).annotateMerge(parentRpc.annotations)
     const rpcDiscard = Rpc.make(`${entity.type}.${parentRpc._tag}Discard`, {
@@ -114,11 +120,12 @@ export type ConvertRpcs<Rpcs extends Rpc.Any, Prefix extends string> = Rpcs exte
       }>,
       _Success,
       Schema.Codec<
-        _Error["Type"] | MailboxFull | AlreadyProcessingMessage | PersistenceError,
+        _Error["Type"] | MailboxFull | AlreadyProcessingMessage | PersistenceError | EntityNotAssignedToRunner,
         | _Error["Encoded"]
         | typeof MailboxFull["Encoded"]
         | typeof AlreadyProcessingMessage["Encoded"]
-        | typeof PersistenceError["Encoded"],
+        | typeof PersistenceError["Encoded"]
+        | typeof EntityNotAssignedToRunner["Encoded"],
         _Error["DecodingServices"],
         _Error["EncodingServices"]
       >
@@ -147,7 +154,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 +182,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
@@ -191,7 +199,7 @@ export const toHttpApiGroup = <const Name extends string, Type extends string, R
       params: entityIdPath,
       payload: parentRpc.payloadSchema,
       success: parentRpc.successSchema,
-      error: [parentRpc.errorSchema, ...clientErrors]
+      error: [parentRpc.errorSchema, ...requestErrors]
     }).annotateMerge(parentRpc.annotations)
     const endpointDiscard = HttpApiEndpoint.post(
       `${parentRpc._tag}Discard`,
@@ -248,6 +256,7 @@ export type ConvertHttpApi<Rpcs extends Rpc.Any> = Rpcs extends Rpc.Rpc<
       | typeof MailboxFull
       | typeof AlreadyProcessingMessage
       | typeof PersistenceError
+      | typeof EntityNotAssignedToRunner
     >
     | HttpApiEndpoint.HttpApiEndpoint<
       `${_Tag}Discard`,

package/src/unstable/cluster/EntityResource.ts

@@ -10,7 +10,6 @@
  *
  * @since 4.0.0
  */
-import type * as v1 from "kubernetes-types/core/v1.d.ts"
 import * as Context from "../../Context.ts"
 import * as Duration from "../../Duration.ts"
 import * as Effect from "../../Effect.ts"
@@ -19,6 +18,7 @@ import * as RcRef from "../../RcRef.ts"
 import * as Scope from "../../Scope.ts"
 import * as Entity from "./Entity.ts"
 import * as K8sHttpClient from "./K8sHttpClient.ts"
+import type { Pod as K8sPod } from "./K8sTypes.ts"
 import type { Sharding } from "./Sharding.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,11 +156,11 @@ 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: (
-  spec: v1.Pod,
+  spec: K8sPod,
   options?: {
     readonly idleTimeToLive?: Duration.Input | undefined
   } | undefined
@@ -168,7 +168,7 @@ export const makeK8sPod: (
   EntityResource<K8sHttpClient.PodStatus>,
   never,
   Scope.Scope | Sharding | Entity.CurrentAddress | K8sHttpClient.K8sHttpClient
-> = Effect.fnUntraced(function*(spec: v1.Pod, options?: {
+> = Effect.fnUntraced(function*(spec: K8sPod, options?: {
   readonly idleTimeToLive?: Duration.Input | undefined
 }) {
   const createPod = yield* K8sHttpClient.makeCreatePod