effect 4.0.0-beta.43 → 4.0.0-beta.44

package/src/unstable/ai/Tool.ts

@@ -26,6 +26,7 @@
  *
  * @since 1.0.0
  */
+import * as Context from "../../Context.ts"
 import type * as Effect from "../../Effect.ts"
 import { constFalse, constTrue, identity } from "../../Function.ts"
 import type * as JsonSchema from "../../JsonSchema.ts"
@@ -33,7 +34,6 @@ import { pipeArguments } from "../../Pipeable.ts"
 import * as Predicate from "../../Predicate.ts"
 import * as Schema from "../../Schema.ts"
 import * as AST from "../../SchemaAST.ts"
-import * as ServiceMap from "../../ServiceMap.ts"
 import type * as Struct from "../../Struct.ts"
 import type * as Types from "../../Types.ts"
 import type * as AiError from "./AiError.ts"
@@ -232,10 +232,10 @@ export interface Tool<
   readonly failureSchema: Config["failure"]
 
   /**
-   * A `ServiceMap` containing tool annotations which can store metadata about
+   * A `Context` containing tool annotations which can store metadata about
    * the tool.
    */
-  readonly annotations: ServiceMap.ServiceMap<never>
+  readonly annotations: Context.Context<never>
 
   /**
    * Specifies whether user approval is required before executing this tool.
@@ -257,7 +257,7 @@ export interface Tool<
    * instead of being provided when creating the tool call handler layer.
    */
   addDependency<Identifier, Service>(
-    tag: ServiceMap.Key<Identifier, Service>
+    tag: Context.Key<Identifier, Service>
   ): Tool<Name, Config, Identifier | Requirements>
 
   /**
@@ -311,12 +311,12 @@ export interface Tool<
   /**
    * Add an annotation to the tool.
    */
-  annotate<I, S>(tag: ServiceMap.Key<I, S>, value: S): Tool<Name, Config, Requirements>
+  annotate<I, S>(tag: Context.Key<I, S>, value: S): Tool<Name, Config, Requirements>
 
   /**
    * Add many annotations to the tool.
    */
-  annotateMerge<I>(context: ServiceMap.ServiceMap<I>): Tool<Name, Config, Requirements>
+  annotateMerge<I>(context: Context.Context<I>): Tool<Name, Config, Requirements>
 }
 
 /**
@@ -893,7 +893,7 @@ export type ResultDecodingServices<T> = T extends Tool<
 export interface Handler<Name extends string> {
   readonly _: unique symbol
   readonly name: Name
-  readonly services: ServiceMap.ServiceMap<never>
+  readonly context: Context.Context<never>
   readonly handler: (params: any, ctx: any) => Effect.Effect<any, any>
 }
 
@@ -1006,16 +1006,16 @@ const Proto = {
   setFailure(this: Any, failureSchema: Schema.Top) {
     return userDefinedProto({ ...this, failureSchema })
   },
-  annotate<I, S>(this: Any, tag: ServiceMap.Key<I, S>, value: S) {
+  annotate<I, S>(this: Any, tag: Context.Key<I, S>, value: S) {
     return userDefinedProto({
       ...this,
-      annotations: ServiceMap.add(this.annotations, tag, value)
+      annotations: Context.add(this.annotations, tag, value)
     })
   },
-  annotateMerge<I>(this: Any, context: ServiceMap.ServiceMap<I>) {
+  annotateMerge<I>(this: Any, context: Context.Context<I>) {
     return userDefinedProto({
       ...this,
-      annotations: ServiceMap.merge(this.annotations, context)
+      annotations: Context.merge(this.annotations, context)
     })
   }
 }
@@ -1042,7 +1042,7 @@ const userDefinedProto = <
   readonly parametersSchema: Parameters
   readonly successSchema: Success
   readonly failureSchema: Failure
-  readonly annotations: ServiceMap.ServiceMap<never>
+  readonly annotations: Context.Context<never>
   readonly failureMode: Mode
   readonly needsApproval?: NeedsApproval<Parameters> | undefined
 }): Tool<
@@ -1104,7 +1104,7 @@ const dynamicProto = <
   readonly parametersSchema: Parameters
   readonly successSchema: Success
   readonly failureSchema: Failure
-  readonly annotations: ServiceMap.ServiceMap<never>
+  readonly annotations: Context.Context<never>
   readonly failureMode: Mode
   readonly needsApproval?: NeedsApproval<any> | undefined
   readonly jsonSchema: JsonSchema.JsonSchema | undefined
@@ -1153,7 +1153,7 @@ export const make = <
   Success extends Schema.Top = typeof Schema.Void,
   Failure extends Schema.Top = typeof Schema.Never,
   Mode extends FailureMode | undefined = undefined,
-  Dependencies extends Array<ServiceMap.Key<any, any> | ServiceMap.Key<never, any>> = []
+  Dependencies extends Array<Context.Key<any, any> | Context.Key<never, any>> = []
 >(name: Name, options?: {
   /**
    * An optional description explaining what the tool does.
@@ -1203,7 +1203,7 @@ export const make = <
     readonly failure: Failure
     readonly failureMode: Mode extends undefined ? "error" : Mode
   },
-  ServiceMap.Service.Identifier<Dependencies[number]>
+  Context.Service.Identifier<Dependencies[number]>
 > => {
   const successSchema = options?.success ?? Schema.Void
   const failureSchema = options?.failure ?? Schema.Never
@@ -1214,7 +1214,7 @@ export const make = <
     successSchema,
     failureSchema,
     failureMode: options?.failureMode ?? "error",
-    annotations: ServiceMap.empty(),
+    annotations: Context.empty(),
     needsApproval: options?.needsApproval as any
   }) as any
 }
@@ -1344,7 +1344,7 @@ export const dynamic: {
     successSchema,
     failureSchema,
     failureMode: options?.failureMode ?? "error",
-    annotations: ServiceMap.empty(),
+    annotations: Context.empty(),
     needsApproval: options?.needsApproval,
     jsonSchema
   })
@@ -1653,7 +1653,7 @@ export const getJsonSchemaFromSchema = <S extends Schema.Top>(schema: S, options
  * @since 1.0.0
  * @category annotations
  */
-export class Title extends ServiceMap.Service<Title, string>()("effect/ai/Tool/Title") {}
+export class Title extends Context.Service<Title, string>()("effect/ai/Tool/Title") {}
 
 /**
  * Annotation for providing tool metadata for MCP.
@@ -1668,7 +1668,7 @@ export class Title extends ServiceMap.Service<Title, string>()("effect/ai/Tool/T
  * @since 1.0.0
  * @category annotations
  */
-export class Meta extends ServiceMap.Service<Meta, Record<string, unknown>>()("effect/ai/Tool/Meta") {}
+export class Meta extends Context.Service<Meta, Record<string, unknown>>()("effect/ai/Tool/Meta") {}
 
 /**
  * Annotation indicating whether a tool only reads data without making changes.
@@ -1684,7 +1684,7 @@ export class Meta extends ServiceMap.Service<Meta, Record<string, unknown>>()("e
  * @since 1.0.0
  * @category annotations
  */
-export const Readonly = ServiceMap.Reference<boolean>("effect/ai/Tool/Readonly", {
+export const Readonly = Context.Reference<boolean>("effect/ai/Tool/Readonly", {
   defaultValue: constFalse
 })
 
@@ -1702,7 +1702,7 @@ export const Readonly = ServiceMap.Reference<boolean>("effect/ai/Tool/Readonly",
  * @since 1.0.0
  * @category annotations
  */
-export const Destructive = ServiceMap.Reference<boolean>("effect/ai/Tool/Destructive", {
+export const Destructive = Context.Reference<boolean>("effect/ai/Tool/Destructive", {
   defaultValue: constTrue
 })
 
@@ -1720,7 +1720,7 @@ export const Destructive = ServiceMap.Reference<boolean>("effect/ai/Tool/Destruc
  * @since 1.0.0
  * @category annotations
  */
-export const Idempotent = ServiceMap.Reference<boolean>("effect/ai/Tool/Idempotent", {
+export const Idempotent = Context.Reference<boolean>("effect/ai/Tool/Idempotent", {
   defaultValue: constFalse
 })
 
@@ -1738,7 +1738,7 @@ export const Idempotent = ServiceMap.Reference<boolean>("effect/ai/Tool/Idempote
  * @since 1.0.0
  * @category annotations
  */
-export const OpenWorld = ServiceMap.Reference<boolean>("effect/ai/Tool/OpenWorld", {
+export const OpenWorld = Context.Reference<boolean>("effect/ai/Tool/OpenWorld", {
   defaultValue: constTrue
 })
 
@@ -1764,7 +1764,7 @@ export const OpenWorld = ServiceMap.Reference<boolean>("effect/ai/Tool/OpenWorld
  * @since 1.0.0
  * @category annotations
  */
-export const Strict = ServiceMap.Reference<boolean | undefined>("effect/ai/Tool/Strict", {
+export const Strict = Context.Reference<boolean | undefined>("effect/ai/Tool/Strict", {
   defaultValue: () => undefined
 })
 
@@ -1774,7 +1774,7 @@ export const Strict = ServiceMap.Reference<boolean | undefined>("effect/ai/Tool/
  * @since 1.0.0
  * @category utilities
  */
-export const getStrictMode = <T extends Any>(tool: T): boolean | undefined => ServiceMap.get(tool.annotations, Strict)
+export const getStrictMode = <T extends Any>(tool: T): boolean | undefined => Context.get(tool.annotations, Strict)
 
 // Licensed under BSD-3-Clause (below code only)
 // Code adapted from https://github.com/fastify/secure-json-parse/blob/783fcb1b5434709466759847cec974381939673a/index.js

package/src/unstable/ai/Toolkit.ts

@@ -39,6 +39,7 @@
  * @since 1.0.0
  */
 import type * as Cause from "../../Cause.ts"
+import * as Context from "../../Context.ts"
 import * as Effect from "../../Effect.ts"
 import * as Fiber from "../../Fiber.ts"
 import { identity } from "../../Function.ts"
@@ -50,7 +51,6 @@ import * as Predicate from "../../Predicate.ts"
 import * as Queue from "../../Queue.ts"
 import * as Schema from "../../Schema.ts"
 import type * as Scope from "../../Scope.ts"
-import * as ServiceMap from "../../ServiceMap.ts"
 import * as Stream from "../../Stream.ts"
 import * as AiError from "./AiError.ts"
 import type * as Tool from "./Tool.ts"
@@ -122,12 +122,12 @@ export interface Toolkit<in out Tools extends Record<string, Tool.Any>> extends
   of<Handlers extends HandlersFrom<Tools>>(handlers: Handlers): Handlers
 
   /**
-   * Converts a toolkit into a `ServiceMap` containing handlers for each tool
+   * Converts a toolkit into a `Context` containing handlers for each tool
    * in the toolkit.
    */
   toHandlers<Handlers extends HandlersFrom<Tools>, EX = never, RX = never>(
     build: Handlers | Effect.Effect<Handlers, EX, RX>
-  ): Effect.Effect<ServiceMap.ServiceMap<Tool.HandlersFor<Tools>>, EX, RX>
+  ): Effect.Effect<Context.Context<Tool.HandlersFor<Tools>>, EX, RX>
 
   /**
    * Converts a toolkit into a `Layer` containing handlers for each tool in the
@@ -266,30 +266,30 @@ const Proto = {
     build: Record<string, (params: any) => any> | Effect.Effect<Record<string, (params: any) => any>>
   ) {
     return Effect.gen({ self: this }, function*() {
-      const services = yield* Effect.services<never>()
+      const services = yield* Effect.context<never>()
       const handlers = Effect.isEffect(build) ? yield* build : build
-      const serviceMap = new Map<string, unknown>()
+      const context = new Map<string, unknown>()
       for (const [name, handler] of Object.entries(handlers)) {
         const tool = this.tools[name]!
-        serviceMap.set(tool.id, { name, handler, services })
+        context.set(tool.id, { name, handler, context: services })
       }
-      return ServiceMap.makeUnsafe(serviceMap)
+      return Context.makeUnsafe(context)
     })
   },
   toLayer(
     this: Toolkit<Record<string, Tool.Any>>,
     build: Record<string, (params: any) => any> | Effect.Effect<Record<string, (params: any) => any>>
   ) {
-    return Layer.effectServices(this.toHandlers(build))
+    return Layer.effectContext(this.toHandlers(build))
   },
   asEffect(this: Toolkit<Record<string, Tool.Any>>) {
     return Effect.gen({ self: this }, function*() {
       const tools = this.tools
 
-      const services = yield* Effect.services<never>()
+      const services = yield* Effect.context<never>()
 
       const schemasCache = new WeakMap<any, {
-        readonly services: ServiceMap.ServiceMap<never>
+        readonly context: Context.Context<never>
         readonly handler: Tool.Handler<any>["handler"]
         readonly decodeParameters: (u: unknown) => Effect.Effect<unknown, Schema.SchemaError>
         readonly decodeResult: (u: unknown) => Effect.Effect<unknown, Schema.SchemaError>
@@ -309,7 +309,7 @@ const Proto = {
           const decodeResult = Schema.decodeUnknownEffect(resultSchema) as any
           const encodeResult = Schema.encodeUnknownEffect(resultSchema) as any
           schemas = {
-            services: handler.services,
+            context: handler.context,
             handler: handler.handler,
             decodeParameters,
             decodeResult,
@@ -375,7 +375,7 @@ const Proto = {
 
         const fiber = yield* schemas.handler(decodedParams, context).pipe(
           Effect.flatMap((result) => Queue.offer(queue, { result, isFailure: false, preliminary: false })),
-          Effect.updateServices((input) => ServiceMap.merge(schemas.services, input)),
+          Effect.updateContext((input) => Context.merge(schemas.context, input)),
           Effect.matchCauseEffect({
             onFailure: (cause) => Queue.failCause(queue, cause),
             onSuccess: () => Queue.end(queue)

package/src/unstable/cli/Argument.ts

@@ -11,7 +11,6 @@ import type * as Schema from "../../Schema.ts"
 import type * as CliError from "./CliError.ts"
 import * as Param from "./Param.ts"
 import type * as Primitive from "./Primitive.ts"
-import type * as Prompt from "./Prompt.ts"
 
 // -------------------------------------------------------------------------------------
 // models
@@ -454,7 +453,7 @@ export const withFallbackPrompt: {
    * @since 4.0.0
    * @category combinators
    */
-  <B>(prompt: Prompt.Prompt<B>): <A>(self: Argument<A>) => Argument<A | B>
+  <B>(prompt: Param.FallbackPrompt<B>): <A>(self: Argument<A>) => Argument<A | B>
   /**
    * Adds a fallback prompt that is shown when a required argument is missing.
    *
@@ -470,8 +469,8 @@ export const withFallbackPrompt: {
    * @since 4.0.0
    * @category combinators
    */
-  <A, B>(self: Argument<A>, prompt: Prompt.Prompt<B>): Argument<A | B>
-} = dual(2, <A, B>(self: Argument<A>, prompt: Prompt.Prompt<B>) => Param.withFallbackPrompt(self, prompt))
+  <A, B>(self: Argument<A>, prompt: Param.FallbackPrompt<B>): Argument<A | B>
+} = dual(2, <A, B>(self: Argument<A>, prompt: Param.FallbackPrompt<B>) => Param.withFallbackPrompt(self, prompt))
 
 /**
  * Creates a variadic positional argument that accepts multiple values.

package/src/unstable/cli/CliError.ts

@@ -115,7 +115,7 @@ export type CliError =
  * @since 4.0.0
  * @category models
  */
-export class UnrecognizedOption extends Schema.ErrorClass(`${TypeId}/UnrecognizedOption`)({
+export class UnrecognizedOption extends Schema.ErrorClass<UnrecognizedOption>(`${TypeId}/UnrecognizedOption`)({
   _tag: Schema.tag("UnrecognizedOption"),
   option: Schema.String,
   command: Schema.optional(Schema.Array(Schema.String)),
@@ -161,7 +161,7 @@ export class UnrecognizedOption extends Schema.ErrorClass(`${TypeId}/Unrecognize
  * @since 4.0.0
  * @category models
  */
-export class DuplicateOption extends Schema.ErrorClass(`${TypeId}/DuplicateOption`)({
+export class DuplicateOption extends Schema.ErrorClass<DuplicateOption>(`${TypeId}/DuplicateOption`)({
   _tag: Schema.tag("DuplicateOption"),
   option: Schema.String,
   parentCommand: Schema.String,
@@ -210,7 +210,7 @@ export class DuplicateOption extends Schema.ErrorClass(`${TypeId}/DuplicateOptio
  * @since 4.0.0
  * @category models
  */
-export class MissingOption extends Schema.ErrorClass(`${TypeId}/MissingOption`)({
+export class MissingOption extends Schema.ErrorClass<MissingOption>(`${TypeId}/MissingOption`)({
   _tag: Schema.tag("MissingOption"),
   option: Schema.String
 }) {
@@ -255,7 +255,7 @@ export class MissingOption extends Schema.ErrorClass(`${TypeId}/MissingOption`)(
  * @since 4.0.0
  * @category models
  */
-export class MissingArgument extends Schema.ErrorClass(`${TypeId}/MissingArgument`)({
+export class MissingArgument extends Schema.ErrorClass<MissingArgument>(`${TypeId}/MissingArgument`)({
   _tag: Schema.tag("MissingArgument"),
   argument: Schema.String
 }) {
@@ -305,7 +305,7 @@ export class MissingArgument extends Schema.ErrorClass(`${TypeId}/MissingArgumen
  * @since 4.0.0
  * @category models
  */
-export class InvalidValue extends Schema.ErrorClass(`${TypeId}/InvalidValue`)({
+export class InvalidValue extends Schema.ErrorClass<InvalidValue>(`${TypeId}/InvalidValue`)({
   _tag: Schema.tag("InvalidValue"),
   option: Schema.String,
   value: Schema.String,
@@ -363,7 +363,7 @@ export class InvalidValue extends Schema.ErrorClass(`${TypeId}/InvalidValue`)({
  * @since 4.0.0
  * @category models
  */
-export class UnknownSubcommand extends Schema.ErrorClass(`${TypeId}/UnknownSubcommand`)({
+export class UnknownSubcommand extends Schema.ErrorClass<UnknownSubcommand>(`${TypeId}/UnknownSubcommand`)({
   _tag: Schema.tag("UnknownSubcommand"),
   subcommand: Schema.String,
   parent: Schema.optional(Schema.Array(Schema.String)),
@@ -422,7 +422,7 @@ export class UnknownSubcommand extends Schema.ErrorClass(`${TypeId}/UnknownSubco
  * @since 4.0.0
  * @category models
  */
-export class UserError extends Schema.ErrorClass(`${TypeId}/UserError`)({
+export class UserError extends Schema.ErrorClass<UserError>(`${TypeId}/UserError`)({
   _tag: Schema.tag("UserError"),
   cause: Schema.Defect
 }) {
@@ -432,7 +432,14 @@ export class UserError extends Schema.ErrorClass(`${TypeId}/UserError`)({
   readonly [TypeId] = TypeId
 }
 
-const NonShowHelpErrors: Schema.Union<
+/**
+ * Represents errors that should not trigger the display of the CLI's help
+ * documentation.
+ *
+ * @since 4.0.0
+ * @category models
+ */
+export const NonShowHelpErrors: Schema.Union<
   readonly [
     typeof UnrecognizedOption,
     typeof DuplicateOption,
@@ -452,6 +459,12 @@ const NonShowHelpErrors: Schema.Union<
   UserError
 ])
 
+/**
+ * @since 4.0.0
+ * @category models
+ */
+export type NonShowHelpErrors = typeof NonShowHelpErrors.Type
+
 /**
  * Control flow indicator when help is requested via --help flag.
  * This is not an error but uses the error channel for control flow.
@@ -459,7 +472,7 @@ const NonShowHelpErrors: Schema.Union<
  * @since 4.0.0
  * @category models
  */
-export class ShowHelp extends Schema.ErrorClass(`${TypeId}/ShowHelp`)({
+export class ShowHelp extends Schema.ErrorClass<ShowHelp>(`${TypeId}/ShowHelp`)({
   _tag: Schema.tag("ShowHelp"),
   commandPath: Schema.Array(Schema.String),
   errors: Schema.Array(NonShowHelpErrors)

package/src/unstable/cli/CliOutput.ts

@@ -2,9 +2,9 @@
  * @since 4.0.0
  */
 
+import * as Context from "../../Context.ts"
 import * as Layer from "../../Layer.ts"
 import * as Option from "../../Option.ts"
-import * as ServiceMap from "../../ServiceMap.ts"
 import type * as CliError from "./CliError.ts"
 import type { HelpDoc } from "./HelpDoc.ts"
 
@@ -210,7 +210,7 @@ export interface Formatter {
  * @since 4.0.0
  * @category services
  */
-export const Formatter: ServiceMap.Reference<Formatter> = ServiceMap.Reference(
+export const Formatter: Context.Reference<Formatter> = Context.Reference(
   "effect/cli/CliOutput",
   { defaultValue: () => defaultFormatter() }
 )

package/src/unstable/cli/Command.ts

@@ -3,6 +3,7 @@
  */
 import type { NonEmptyArray, NonEmptyReadonlyArray } from "../../Array.ts"
 import * as Console from "../../Console.ts"
+import * as Context from "../../Context.ts"
 import * as Effect from "../../Effect.ts"
 import type * as FileSystem from "../../FileSystem.ts"
 import { dual } from "../../Function.ts"
@@ -13,7 +14,6 @@ import type { Pipeable } from "../../Pipeable.ts"
 import * as Predicate from "../../Predicate.ts"
 import * as References from "../../References.ts"
 import * as Result from "../../Result.ts"
-import * as ServiceMap from "../../ServiceMap.ts"
 import * as Stdio from "../../Stdio.ts"
 import * as Terminal from "../../Terminal.ts"
 import type { NoInfer, Simplify } from "../../Types.ts"
@@ -125,7 +125,7 @@ export interface Command<Name extends string, Input, ContextInput = {}, E = neve
   /**
    * Custom annotations associated with this command.
    */
-  readonly annotations: ServiceMap.ServiceMap<never>
+  readonly annotations: Context.Context<never>
 }
 
 /**
@@ -359,7 +359,7 @@ export interface CommandContext<Name extends string> {
 export interface ParsedTokens {
   readonly flags: Record<string, ReadonlyArray<string>>
   readonly arguments: ReadonlyArray<string>
-  readonly errors?: ReadonlyArray<CliError.CliError>
+  readonly errors?: ReadonlyArray<CliError.NonShowHelpErrors>
   readonly subcommand: Option.Option<{
     readonly name: string
     readonly parsedInput: ParsedTokens
@@ -1091,7 +1091,7 @@ export const withSharedFlags: {
       annotations: impl.annotations,
       globalFlags: impl.globalFlags,
       examples: impl.examples,
-      service: impl.service as ServiceMap.Key<CommandContext<Name>, NextContextInput>,
+      service: impl.service as Context.Key<CommandContext<Name>, NextContextInput>,
       subcommands: impl.subcommands,
       parse,
       parseContext,
@@ -1339,7 +1339,7 @@ export const annotate: {
    * @since 4.0.0
    * @category combinators
    */
-  <I, S>(service: ServiceMap.Key<I, S>, value: NoInfer<S>): <Name extends string, Input, E, R, ContextInput>(
+  <I, S>(service: Context.Key<I, S>, value: NoInfer<S>): <Name extends string, Input, E, R, ContextInput>(
     self: Command<Name, Input, ContextInput, E, R>
   ) => Command<Name, Input, ContextInput, E, R>
   /**
@@ -1350,50 +1350,50 @@ export const annotate: {
    */
   <Name extends string, Input, E, R, ContextInput, I, S>(
     self: Command<Name, Input, ContextInput, E, R>,
-    service: ServiceMap.Key<I, S>,
+    service: Context.Key<I, S>,
     value: NoInfer<S>
   ): Command<Name, Input, ContextInput, E, R>
 } = dual(3, <Name extends string, Input, E, R, ContextInput, I, S>(
   self: Command<Name, Input, ContextInput, E, R>,
-  service: ServiceMap.Key<I, S>,
+  service: Context.Key<I, S>,
   value: NoInfer<S>
 ) => {
   const impl = toImpl(self)
-  return makeCommand({ ...impl, annotations: ServiceMap.add(impl.annotations, service, value) })
+  return makeCommand({ ...impl, annotations: Context.add(impl.annotations, service, value) })
 })
 
 /**
- * Merges a ServiceMap of annotations into a command.
+ * Merges a Context of annotations into a command.
  *
  * @since 4.0.0
  * @category combinators
  */
 export const annotateMerge: {
   /**
-   * Merges a ServiceMap of annotations into a command.
+   * Merges a Context of annotations into a command.
    *
    * @since 4.0.0
    * @category combinators
    */
-  <I>(annotations: ServiceMap.ServiceMap<I>): <Name extends string, Input, E, R, ContextInput>(
+  <I>(annotations: Context.Context<I>): <Name extends string, Input, E, R, ContextInput>(
     self: Command<Name, Input, ContextInput, E, R>
   ) => Command<Name, Input, ContextInput, E, R>
   /**
-   * Merges a ServiceMap of annotations into a command.
+   * Merges a Context of annotations into a command.
    *
    * @since 4.0.0
    * @category combinators
    */
   <Name extends string, Input, E, R, ContextInput, I>(
     self: Command<Name, Input, ContextInput, E, R>,
-    annotations: ServiceMap.ServiceMap<I>
+    annotations: Context.Context<I>
   ): Command<Name, Input, ContextInput, E, R>
 } = dual(2, <Name extends string, Input, E, R, ContextInput, I>(
   self: Command<Name, Input, ContextInput, E, R>,
-  annotations: ServiceMap.ServiceMap<I>
+  annotations: Context.Context<I>
 ) => {
   const impl = toImpl(self)
-  return makeCommand({ ...impl, annotations: ServiceMap.merge(impl.annotations, annotations) })
+  return makeCommand({ ...impl, annotations: Context.merge(impl.annotations, annotations) })
 })
 
 /**
@@ -1634,7 +1634,7 @@ export const provideSync: {
    * @since 4.0.0
    * @category providing services
    */
-  <I, S, Input>(service: ServiceMap.Key<I, S>, implementation: S | ((input: Input) => S)): <const Name extends string, E, R, ContextInput>(
+  <I, S, Input>(service: Context.Key<I, S>, implementation: S | ((input: Input) => S)): <const Name extends string, E, R, ContextInput>(
     self: Command<Name, Input, ContextInput, E, R>
   ) => Command<Name, Input, ContextInput, E, Exclude<R, I>>
   /**
@@ -1646,12 +1646,12 @@ export const provideSync: {
    */
   <const Name extends string, Input, E, R, ContextInput, I, S>(
     self: Command<Name, Input, ContextInput, E, R>,
-    service: ServiceMap.Key<I, S>,
+    service: Context.Key<I, S>,
     implementation: S | ((input: Input) => S)
   ): Command<Name, Input, ContextInput, E, Exclude<R, I>>
 } = dual(3, <const Name extends string, Input, E, R, ContextInput, I, S>(
   self: Command<Name, Input, ContextInput, E, R>,
-  service: ServiceMap.Key<I, S>,
+  service: Context.Key<I, S>,
   implementation: S | ((input: Input) => S)
 ) =>
   mapHandler(self, (handler, input) =>
@@ -1677,7 +1677,7 @@ export const provideEffect: {
    * @category providing services
    */
   <I, S, Input, R2, E2>(
-    service: ServiceMap.Key<I, S>,
+    service: Context.Key<I, S>,
     effect: Effect.Effect<S, E2, R2> | ((input: Input) => Effect.Effect<S, E2, R2>)
   ): <const Name extends string, E, R, ContextInput>(
     self: Command<Name, Input, ContextInput, E, R>
@@ -1691,12 +1691,12 @@ export const provideEffect: {
    */
   <const Name extends string, Input, E, R, ContextInput, I, S, R2, E2>(
     self: Command<Name, Input, ContextInput, E, R>,
-    service: ServiceMap.Key<I, S>,
+    service: Context.Key<I, S>,
     effect: Effect.Effect<S, E2, R2> | ((input: Input) => Effect.Effect<S, E2, R2>)
   ): Command<Name, Input, ContextInput, E | E2, Exclude<R, I> | R2>
 } = dual(3, <const Name extends string, Input, E, R, ContextInput, I, S, R2, E2>(
   self: Command<Name, Input, ContextInput, E, R>,
-  service: ServiceMap.Key<I, S>,
+  service: Context.Key<I, S>,
   effect: Effect.Effect<S, E2, R2> | ((input: Input) => Effect.Effect<S, E2, R2>)
 ) =>
   mapHandler(
@@ -1751,9 +1751,9 @@ const getOutOfScopeGlobalFlagErrors = (
   activeFlags: ReadonlyArray<GlobalFlag.GlobalFlag<any>>,
   flagMap: Record<string, ReadonlyArray<string>>,
   commandPath: ReadonlyArray<string>
-): ReadonlyArray<CliError.CliError> => {
+): ReadonlyArray<CliError.UnrecognizedOption> => {
   const activeSet = new Set(activeFlags)
-  const errors: Array<CliError.CliError> = []
+  const errors: Array<CliError.UnrecognizedOption> = []
   const seen = new Set<string>()
 
   for (const flag of allFlags) {
@@ -1955,7 +1955,7 @@ export const runWith = <const Name extends string, Input, E, R, ContextInput>(
       // 2. Extract global flag tokens
       const allFlagParams = allFlags.flatMap((f) => Param.extractSingleParams(f.flag))
       const globalRegistry = Parser.createFlagRegistry(allFlagParams.filter(Param.isFlagParam))
-      const { flagMap, remainder } = Parser.consumeKnownFlags(tokens, globalRegistry)
+      const { flagMap, remainder, errors: globalFlagErrors } = Parser.consumeKnownFlags(tokens, globalRegistry)
       const emptyArgs: Param.ParsedArgs = { flags: flagMap, arguments: [] }
 
       // 3. Parse command arguments from remaining tokens
@@ -1966,9 +1966,12 @@ export const runWith = <const Name extends string, Input, E, R, ContextInput>(
 
       // 4. Reject globals that were passed outside the active command scope
       const outOfScopeErrors = getOutOfScopeGlobalFlagErrors(allFlags, activeFlags, flagMap, commandPath)
-      if (outOfScopeErrors.length > 0) {
+      if (outOfScopeErrors.length > 0 || globalFlagErrors.length > 0) {
         const parseErrors = parsedArgs.errors ?? []
-        return yield* new CliError.ShowHelp({ commandPath, errors: [...outOfScopeErrors, ...parseErrors] })
+        return yield* new CliError.ShowHelp({
+          commandPath,
+          errors: [...globalFlagErrors, ...outOfScopeErrors, ...parseErrors]
+        })
       }
 
       // 5. Process action flags — first present action wins, then exit
@@ -1991,7 +1994,10 @@ export const runWith = <const Name extends string, Input, E, R, ContextInput>(
       }
       const parseResult = yield* Effect.result(commandImpl.parse(parsedArgs))
       if (parseResult._tag === "Failure") {
-        return yield* new CliError.ShowHelp({ commandPath, errors: [parseResult.failure] })
+        return yield* new CliError.ShowHelp({
+          commandPath,
+          errors: [parseResult.failure as CliError.NonShowHelpErrors]
+        })
       }
 
       // 7. Provide setting values
@@ -2007,12 +2013,12 @@ export const runWith = <const Name extends string, Input, E, R, ContextInput>(
 
       // 8. Apply built-in setting behavior
       const services = Option.match(logLevel, {
-        onNone: () => ServiceMap.empty(),
-        onSome: (level) => ServiceMap.make(References.MinimumLogLevel, level)
+        onNone: () => Context.empty(),
+        onSome: (level) => Context.make(References.MinimumLogLevel, level)
       })
 
       // 9. Run command handler with composed context
-      yield* Effect.provideServices(program, services)
+      yield* Effect.provideContext(program, services)
     },
     Effect.catchFilter(
       (error) =>