effect 4.0.0-beta.102 → 4.0.0-beta.103

package/src/Context.ts

@@ -81,7 +81,7 @@ export interface Key<out Identifier, out Shape> extends Effect<Shape, never, Ide
  *
  * **Example** (Defining a service key)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context } from "effect"
  *
  * // Define an identifier for a database service
@@ -91,9 +91,10 @@ export interface Key<out Identifier, out Shape> extends Effect<Shape, never, Ide
  *
  * // The key can be used to store and retrieve services
  * const context = Context.make(Database, { query: (sql) => `Result: ${sql}` })
+ * Context.get(context, Database).query("SELECT 1") // => "Result: SELECT 1"
  * ```
  *
- * @category models
+ * @category services
  * @since 4.0.0
  */
 export interface Service<in out Identifier, in out Shape> extends Key<Identifier, Shape> {
@@ -118,7 +119,7 @@ export interface Service<in out Identifier, in out Shape> extends Key<Identifier
  *
  * @see {@link Service} for creating function-style keys or class-style service keys
  *
- * @category models
+ * @category services
  * @since 4.0.0
  */
 export interface ServiceClass<in out Self, in out Identifier extends string, in out Shape>
@@ -139,7 +140,7 @@ export declare namespace ServiceClass {
    * Runtime and type-level metadata carried by a class-style service key,
    * including its service type identifier, string key, and service shape.
    *
-   * @category models
+   * @category services
    * @since 4.0.0
    */
   export interface Shape<Identifier extends string, Service> {
@@ -172,7 +173,7 @@ export declare namespace ServiceClass {
  *
  * **Example** (Creating service keys)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context } from "effect"
  *
  * // Create a simple service
@@ -190,11 +191,13 @@ export declare namespace ServiceClass {
  *   query: (sql) => `Result: ${sql}`
  * })
  * const config = Context.make(Config, { port: 8080 })
+ * Context.get(db, Database).query("SELECT 1") // => "Result: SELECT 1"
+ * Context.get(config, Config).port // => 8080
  * ```
  *
  * @see {@link Reference} for service keys with default values
  *
- * @category constructors
+ * @category services
  * @since 4.0.0
  */
 export const Service: {
@@ -221,7 +224,7 @@ export const Service: {
    *
    * **Example** (Creating service keys)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Context } from "effect"
    *
    * // Create a simple service
@@ -239,14 +242,22 @@ export const Service: {
    *   query: (sql) => `Result: ${sql}`
    * })
    * const config = Context.make(Config, { port: 8080 })
+   * Context.get(db, Database).query("SELECT 1") // => "Result: SELECT 1"
+   * Context.get(config, Config).port // => 8080
    * ```
    *
    * @see {@link Reference} for service keys with default values
    *
-   * @category constructors
+   * @category services
    * @since 4.0.0
    */
-  <Identifier, Shape = Identifier>(key: string): Service<Identifier, Shape>
+  <Identifier, Shape = Identifier>(
+    key: string,
+    options?: {
+      /** @internal */
+      readonly fiberCached?: boolean | undefined
+    } | undefined
+  ): Service<Identifier, Shape>
   /**
    * Creates a `Context` service key.
    *
@@ -270,7 +281,7 @@ export const Service: {
    *
    * **Example** (Creating service keys)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Context } from "effect"
    *
    * // Create a simple service
@@ -288,11 +299,13 @@ export const Service: {
    *   query: (sql) => `Result: ${sql}`
    * })
    * const config = Context.make(Config, { port: 8080 })
+   * Context.get(db, Database).query("SELECT 1") // => "Result: SELECT 1"
+   * Context.get(config, Config).port // => 8080
    * ```
    *
    * @see {@link Reference} for service keys with default values
    *
-   * @category constructors
+   * @category services
    * @since 4.0.0
    */
   <Self, Shape>(): <
@@ -303,7 +316,9 @@ export const Service: {
   >(
     id: Identifier,
     options?: {
-      readonly make: ((...args: Args) => Effect<Shape, E, R>) | Effect<Shape, E, R> | undefined
+      readonly make?: ((...args: Args) => Effect<Shape, E, R>) | Effect<Shape, E, R> | undefined
+      /** @internal */
+      readonly fiberCached?: boolean | undefined
     } | undefined
   ) =>
     & ServiceClass<Self, Identifier, Shape>
@@ -332,7 +347,7 @@ export const Service: {
    *
    * **Example** (Creating service keys)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Context } from "effect"
    *
    * // Create a simple service
@@ -350,11 +365,13 @@ export const Service: {
    *   query: (sql) => `Result: ${sql}`
    * })
    * const config = Context.make(Config, { port: 8080 })
+   * Context.get(db, Database).query("SELECT 1") // => "Result: SELECT 1"
+   * Context.get(config, Config).port // => 8080
    * ```
    *
    * @see {@link Reference} for service keys with default values
    *
-   * @category constructors
+   * @category services
    * @since 4.0.0
    */
   <Self>(): <
@@ -364,6 +381,8 @@ export const Service: {
     id: Identifier,
     options: {
       readonly make: Make
+      /** @internal */
+      readonly fiberCached?: boolean | undefined
     }
   ) =>
     & ServiceClass<
@@ -388,23 +407,25 @@ export const Service: {
       return err.stack
     }
   })
-  if (arguments.length > 0) {
-    self.key = arguments[0]
-    if (arguments[1]?.defaultValue) {
-      self[ReferenceTypeId] = ReferenceTypeId
-      self.defaultValue = arguments[1].defaultValue
-    }
-    return self
-  }
-  return function(key: string, options?: {
+  const init = (key: string, options?: {
+    readonly defaultValue?: any
     readonly make?: any
-  }) {
+    readonly fiberCached?: boolean
+  }) => {
     self.key = key
+    if (options?.defaultValue) {
+      self[ReferenceTypeId] = ReferenceTypeId
+      self.defaultValue = options.defaultValue
+    }
     if (options?.make) {
       ;(self as any).make = options.make
     }
+    if (options?.fiberCached) {
+      cacheKeys.add(key)
+    }
     return self
   }
+  return arguments.length > 0 ? init(arguments[0], arguments[1]) : init
 } as any
 
 const ServiceProto: any = {
@@ -439,6 +460,8 @@ const ServiceProto: any = {
   }
 }
 
+const cacheKeys = new Set<string>()
+
 const ReferenceTypeId = "~effect/Context/Reference" as const
 
 /**
@@ -452,21 +475,24 @@ const ReferenceTypeId = "~effect/Context/Reference" as const
  *
  * **Example** (Defining a reference with a default value)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context } from "effect"
  *
  * // Define a reference with a default value
+ * const messages: Array<string> = []
  * const LoggerRef: Context.Reference<{ log: (msg: string) => void }> =
  *   Context.Reference("Logger", {
- *     defaultValue: () => ({ log: (msg: string) => console.log(msg) })
+ *     defaultValue: () => ({ log: (msg) => { messages.push(msg) } })
  *   })
  *
  * // The reference can be used without explicit provision
  * const context = Context.empty()
  * const logger = Context.get(context, LoggerRef) // Uses default value
+ * logger.log("default logger")
+ * messages // => ["default logger"]
  * ```
  *
- * @category models
+ * @category services
  * @since 3.11.0
  */
 export interface Reference<in out Shape> extends Service<never, Shape> {
@@ -481,7 +507,7 @@ export interface Reference<in out Shape> extends Service<never, Shape> {
  *
  * **Example** (Extracting service types)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context } from "effect"
  *
  * const Database = Context.Service<{
@@ -493,6 +519,8 @@ export interface Reference<in out Shape> extends Service<never, Shape> {
  *
  * // Extract identifier type from a key
  * type DatabaseId = Context.Service.Identifier<typeof Database>
+ *
+ * Database.key // => "Database"
  * ```
  *
  * @since 2.0.0
@@ -504,7 +532,7 @@ export declare namespace Service {
    *
    * **Example** (Typing any service key)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Context } from "effect"
    *
    * // Any represents any possible service type
@@ -512,9 +540,10 @@ export declare namespace Service {
    *   Context.Service<{ log: (msg: string) => void }>("Logger"),
    *   Context.Service<{ query: (sql: string) => string }>("Database")
    * ]
+   * services.map((service) => service.key) // => ["Logger", "Database"]
    * ```
    *
-   * @category models
+   * @category utility types
    * @since 4.0.0
    */
   export type Any = Key<never, any> | Key<any, any>
@@ -525,7 +554,7 @@ export declare namespace Service {
    *
    * **Example** (Extracting a service shape)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Context } from "effect"
    *
    * const Database = Context.Service<{ query: (sql: string) => string }>(
@@ -535,9 +564,10 @@ export declare namespace Service {
    * // Extract the service shape from the service
    * type DatabaseService = Context.Service.Shape<typeof Database>
    * // DatabaseService is { query: (sql: string) => string }
+   * Database.key // => "Database"
    * ```
    *
-   * @category models
+   * @category utility types
    * @since 4.0.0
    */
   export type Shape<T> = T extends Key<infer _I, infer S> ? S : never
@@ -548,7 +578,7 @@ export declare namespace Service {
    *
    * **Example** (Extracting a service identifier)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Context } from "effect"
    *
    * const Database = Context.Service<{ query: (sql: string) => string }>(
@@ -558,9 +588,10 @@ export declare namespace Service {
    * // Extract the identifier type from a key
    * type DatabaseId = Context.Service.Identifier<typeof Database>
    * // DatabaseId is the identifier type
+   * Database.key // => "Database"
    * ```
    *
-   * @category models
+   * @category utility types
    * @since 2.0.0
    */
   export type Identifier<T> = T extends Key<infer I, infer _S> ? I : never
@@ -579,7 +610,7 @@ const TypeId = "~effect/Context" as const
  *
  * **Example** (Creating a context with multiple services)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context } from "effect"
  *
  * // Create a context with multiple services
@@ -588,10 +619,9 @@ const TypeId = "~effect/Context" as const
  *   "Database"
  * )
  *
- * const context = Context.make(Logger, {
- *   log: (msg: string) => console.log(msg)
- * })
+ * const context = Context.make(Logger, { log: (_msg: string) => {} })
  *   .pipe(Context.add(Database, { query: (sql) => `Result: ${sql}` }))
+ * Context.get(context, Database).query("SELECT 1") // => "Result: SELECT 1"
  * ```
  *
  * @category models
@@ -602,7 +632,81 @@ export interface Context<in Services> extends Equal.Equal, Pipeable, Inspectable
     readonly _Services: Types.Contravariant<Services>
   }
   readonly mapUnsafe: ReadonlyMap<string, any>
-  mutable: boolean
+}
+
+interface ContextImpl<in Services> extends Context<Services> {
+  cacheRoot: ContextImpl<any> | undefined
+  base: ReadonlyMap<string, any>
+  baseHits: number
+  overlay: Overlay | undefined
+  depth: number
+  _flat: ReadonlyMap<string, any> | undefined
+}
+
+interface Overlay {
+  readonly key: string
+  readonly value: unknown
+  readonly parent: Overlay | undefined
+}
+
+const MaxDepth = 8
+const FlattenAfterBaseHits = 8
+
+const makeImpl = <Services>(
+  cacheRoot: ContextImpl<any> | undefined,
+  base: ReadonlyMap<string, any>,
+  overlay: Overlay | undefined,
+  depth: number
+): ContextImpl<Services> => {
+  const self: ContextImpl<Services> = Object.create(Proto)
+  self.cacheRoot = cacheRoot ?? self
+  self.base = base
+  self.overlay = overlay
+  self.depth = depth
+  self._flat = undefined
+  self.baseHits = 0
+  return self
+}
+
+const applyOverlays = (map: Map<string, any>, overlay: Overlay | undefined): void => {
+  if (!overlay) return
+  applyOverlays(map, overlay.parent)
+  map.set(overlay.key, overlay.value)
+}
+
+const flatten = (self: ContextImpl<any>): ReadonlyMap<string, any> => {
+  if (self._flat) return self._flat
+  if (!self.overlay) return self._flat = self.base
+  const map = new Map(self.base)
+  applyOverlays(map, self.overlay)
+  return self._flat = map
+}
+
+const withFlat = <B>(self: Context<any>, f: (map: Map<string, any>) => void): Context<B> => {
+  const map = new Map(self.mapUnsafe)
+  f(map)
+  return makeUnsafe(map)
+}
+
+// A private symbol so user code cannot forge a value that reads as absent
+const notFound = Symbol()
+
+const lookup = (self: Context<any>, key: string): unknown => {
+  const impl = self as ContextImpl<any>
+  for (let overlay = impl.overlay; overlay; overlay = overlay.parent) {
+    if (overlay.key === key) return overlay.value
+  }
+  const value = impl.base.get(key)
+  // Misses must not advance the counter: reference-default lookups miss the
+  // base on every fiber cache refresh, which would flatten every short-lived
+  // request context and reintroduce the O(services) per-request cost
+  if (value === undefined && !impl.base.has(key)) return notFound
+  if (impl.overlay && ++impl.baseHits >= FlattenAfterBaseHits) {
+    impl.base = flatten(impl)
+    impl.overlay = undefined
+    impl.depth = 0
+  }
+  return value
 }
 
 /**
@@ -615,38 +719,41 @@ export interface Context<in Services> extends Equal.Equal, Pipeable, Inspectable
  *
  * **Gotchas**
  *
- * This is unsafe because later mutation of the provided map can affect the
- * created `Context`. Prefer `empty`, `make`, `add`, or `merge` for normal
- * Context construction.
+ * The provided map is retained without copying and must not be mutated after
+ * construction. Prefer `empty`, `make`, `add`, or `merge` for normal Context
+ * construction.
  *
  * **Example** (Creating a context from a map)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context } from "effect"
  *
  * // Create a context from a Map (unsafe)
  * const map = new Map([
- *   ["Logger", { log: (msg: string) => console.log(msg) }]
+ *   ["Logger", { log: (_msg: string) => {} }]
  * ])
  *
  * const context = Context.makeUnsafe(map)
+ * context.mapUnsafe.size // => 1
  * ```
  *
  * @category constructors
  * @since 4.0.0
  */
-export const makeUnsafe = <Services = never>(mapUnsafe: ReadonlyMap<string, any>): Context<Services> => {
-  const self = Object.create(Proto)
-  self.mapUnsafe = mapUnsafe
-  self.mutable = false
-  return self
-}
+export const makeUnsafe = <Services = never>(mapUnsafe: ReadonlyMap<string, any>): Context<Services> =>
+  makeImpl(undefined, mapUnsafe, undefined, 0)
 
-const Proto: Omit<Context<never>, "mapUnsafe" | "mutable"> = {
+const Proto: Omit<
+  ContextImpl<never>,
+  "cacheRoot" | "base" | "overlay" | "depth" | "_flat" | "baseHits"
+> = {
   ...PipeInspectableProto,
   [TypeId]: {
     _Services: (_: never) => _
   },
+  get mapUnsafe() {
+    return flatten(this as any as ContextImpl<any>)
+  },
   toJSON(this: Context<never>) {
     return {
       _id: "Context",
@@ -654,17 +761,12 @@ const Proto: Omit<Context<never>, "mapUnsafe" | "mutable"> = {
     }
   },
   [Equal.symbol]<A>(this: Context<A>, that: unknown): boolean {
-    if (
-      !isContext(that)
-      || this.mapUnsafe.size !== that.mapUnsafe.size
-    ) return false
-    for (const k of this.mapUnsafe.keys()) {
-      if (
-        !that.mapUnsafe.has(k) ||
-        !Equal.equals(this.mapUnsafe.get(k), that.mapUnsafe.get(k))
-      ) {
-        return false
-      }
+    if (!isContext(that)) return false
+    const self = this.mapUnsafe
+    const other = that.mapUnsafe
+    if (self.size !== other.size) return false
+    for (const [key, value] of self) {
+      if (!other.has(key) || !Equal.equals(value, other.get(key))) return false
     }
     return true
   },
@@ -673,6 +775,12 @@ const Proto: Omit<Context<never>, "mapUnsafe" | "mutable"> = {
   }
 }
 
+/** @internal */
+export const hasSameCache = <Services, Services2>(
+  self: Context<Services>,
+  that: Context<Services2>
+): boolean => (self as ContextImpl<Services>).cacheRoot === (that as ContextImpl<Services2>).cacheRoot
+
 /**
  * Checks whether the provided argument is a `Context`.
  *
@@ -693,11 +801,9 @@ const Proto: Omit<Context<never>, "mapUnsafe" | "mutable"> = {
  *
  * **Example** (Checking for contexts)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context } from "effect"
- * import * as assert from "node:assert"
- *
- * assert.strictEqual(Context.isContext(Context.empty()), true)
+ * Context.isContext(Context.empty()) // => true
  * ```
  *
  * @see {@link isKey} for checking service keys
@@ -713,11 +819,9 @@ export const isContext = (u: unknown): u is Context<never> => hasProperty(u, Typ
  *
  * **Example** (Checking for keys)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context } from "effect"
- * import * as assert from "node:assert"
- *
- * assert.strictEqual(Context.isKey(Context.Service("Service")), true)
+ * Context.isKey(Context.Service("Service")) // => true
  * ```
  *
  * @category guards
@@ -730,33 +834,30 @@ export const isKey = (u: unknown): u is Key<any, any> => hasProperty(u, ServiceT
  *
  * **Example** (Checking for references)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context } from "effect"
- * import * as assert from "node:assert"
  *
  * const LoggerRef = Context.Reference("Logger", {
- *   defaultValue: () => ({ log: (msg: string) => console.log(msg) })
+ *   defaultValue: () => ({ log: (_msg: string) => {} })
  * })
  *
- * assert.strictEqual(Context.isReference(LoggerRef), true)
- * assert.strictEqual(Context.isReference(Context.Service("Key")), false)
+ * Context.isReference(LoggerRef) // => true
+ * Context.isReference(Context.Service("Key")) // => false
  * ```
  *
  * @category guards
  * @since 3.11.0
  */
-export const isReference = (u: unknown): u is Reference<any> => hasProperty(u, ReferenceTypeId)
+export const isReference = <I, S>(u: Key<I, S>): u is Reference<S> => !!(u as Reference<S>)[ReferenceTypeId]
 
 /**
  * Returns an empty `Context`.
  *
  * **Example** (Creating an empty context)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context } from "effect"
- * import * as assert from "node:assert"
- *
- * assert.strictEqual(Context.isContext(Context.empty()), true)
+ * Context.empty().mapUnsafe.size // => 0
  * ```
  *
  * @category constructors
@@ -770,15 +871,14 @@ const emptyContext = makeUnsafe(new Map())
  *
  * **Example** (Creating a context with one service)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context } from "effect"
- * import * as assert from "node:assert"
  *
  * const Port = Context.Service<{ PORT: number }>("Port")
  *
  * const context = Context.make(Port, { PORT: 8080 })
  *
- * assert.deepStrictEqual(Context.get(context, Port), { PORT: 8080 })
+ * Context.get(context, Port).PORT // => 8080
  * ```
  *
  * @category constructors
@@ -803,9 +903,8 @@ export const make = <I, S>(
  *
  * **Example** (Adding a service to a context)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, pipe } from "effect"
- * import * as assert from "node:assert"
  *
  * const Port = Context.Service<{ PORT: number }>("Port")
  * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
@@ -817,13 +916,13 @@ export const make = <I, S>(
  *   Context.add(Timeout, { TIMEOUT: 5000 })
  * )
  *
- * assert.deepStrictEqual(Context.get(context, Port), { PORT: 8080 })
- * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
+ * const values = [Context.get(context, Port).PORT, Context.get(context, Timeout).TIMEOUT]
+ * values // => [8080, 5000]
  * ```
  *
  * @see {@link addOrOmit} for adding or removing a service from an `Option`
  *
- * @category adders
+ * @category combining
  * @since 2.0.0
  */
 export const add: {
@@ -841,9 +940,8 @@ export const add: {
    *
    * **Example** (Adding a service to a context)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Context, pipe } from "effect"
-   * import * as assert from "node:assert"
    *
    * const Port = Context.Service<{ PORT: number }>("Port")
    * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
@@ -855,13 +953,13 @@ export const add: {
    *   Context.add(Timeout, { TIMEOUT: 5000 })
    * )
    *
-   * assert.deepStrictEqual(Context.get(context, Port), { PORT: 8080 })
-   * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
+   * const values = [Context.get(context, Port).PORT, Context.get(context, Timeout).TIMEOUT]
+   * values // => [8080, 5000]
    * ```
    *
    * @see {@link addOrOmit} for adding or removing a service from an `Option`
    *
-   * @category adders
+   * @category combining
    * @since 2.0.0
    */
   <I, S>(key: Key<I, S>, service: Types.NoInfer<S>): <Services>(self: Context<Services>) => Context<Services | I>
@@ -879,9 +977,8 @@ export const add: {
    *
    * **Example** (Adding a service to a context)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Context, pipe } from "effect"
-   * import * as assert from "node:assert"
    *
    * const Port = Context.Service<{ PORT: number }>("Port")
    * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
@@ -893,13 +990,13 @@ export const add: {
    *   Context.add(Timeout, { TIMEOUT: 5000 })
    * )
    *
-   * assert.deepStrictEqual(Context.get(context, Port), { PORT: 8080 })
-   * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
+   * const values = [Context.get(context, Port).PORT, Context.get(context, Timeout).TIMEOUT]
+   * values // => [8080, 5000]
    * ```
    *
    * @see {@link addOrOmit} for adding or removing a service from an `Option`
    *
-   * @category adders
+   * @category combining
    * @since 2.0.0
    */
   <Services, I, S>(self: Context<Services>, key: Key<I, S>, service: Types.NoInfer<S>): Context<Services | I>
@@ -907,10 +1004,24 @@ export const add: {
   self: Context<Services>,
   key: Key<I, S>,
   service: Types.NoInfer<S>
-): Context<Services | I> =>
-  withMapUnsafe(self, (map) => {
+): Context<Services | I> => {
+  const impl = self as ContextImpl<Services>
+  const cacheRoot = cacheKeys.has(key.key) ? undefined : impl.cacheRoot
+  if (impl.depth >= MaxDepth) {
+    // Rebase the overlay chain into a flat map, keeping the cacheRoot so a
+    // rebase on an ordinary key does not invalidate fiber caches
+    const map = new Map(impl.mapUnsafe)
     map.set(key.key, service)
-  }))
+    return makeImpl(cacheRoot, map, undefined, 0)
+  }
+
+  return makeImpl(
+    cacheRoot,
+    impl.base,
+    { key: key.key, value: service, parent: impl.overlay },
+    impl.depth + 1
+  )
+})
 
 /**
  * Adds or removes a service depending on an `Option`.
@@ -926,7 +1037,7 @@ export const add: {
  *
  * **Example** (Adding optional services)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Option } from "effect"
  *
  * const Port = Context.Service<{ PORT: number }>("Port")
@@ -938,11 +1049,13 @@ export const add: {
  * const withoutPort = withPort.pipe(
  *   Context.addOrOmit(Port, Option.none())
  * )
+ * Context.getOption(withPort, Port) // => Option.some({ PORT: 8080 })
+ * Context.getOption(withoutPort, Port) // => Option.none()
  * ```
  *
  * @see {@link add} for always storing a service value
  *
- * @category adders
+ * @category combining
  * @since 4.0.0
  */
 export const addOrOmit: {
@@ -960,7 +1073,7 @@ export const addOrOmit: {
    *
    * **Example** (Adding optional services)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Context, Option } from "effect"
    *
    * const Port = Context.Service<{ PORT: number }>("Port")
@@ -972,11 +1085,13 @@ export const addOrOmit: {
    * const withoutPort = withPort.pipe(
    *   Context.addOrOmit(Port, Option.none())
    * )
+   * Context.getOption(withPort, Port) // => Option.some({ PORT: 8080 })
+   * Context.getOption(withoutPort, Port) // => Option.none()
    * ```
    *
    * @see {@link add} for always storing a service value
    *
-   * @category adders
+   * @category combining
    * @since 4.0.0
    */
   <I, S>(key: Key<I, S>, service: Option.Option<Types.NoInfer<S>>): <Services>(self: Context<Services>) => Context<Services | I>
@@ -994,7 +1109,7 @@ export const addOrOmit: {
    *
    * **Example** (Adding optional services)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Context, Option } from "effect"
    *
    * const Port = Context.Service<{ PORT: number }>("Port")
@@ -1006,11 +1121,13 @@ export const addOrOmit: {
    * const withoutPort = withPort.pipe(
    *   Context.addOrOmit(Port, Option.none())
    * )
+   * Context.getOption(withPort, Port) // => Option.some({ PORT: 8080 })
+   * Context.getOption(withoutPort, Port) // => Option.none()
    * ```
    *
    * @see {@link add} for always storing a service value
    *
-   * @category adders
+   * @category combining
    * @since 4.0.0
    */
   <Services, I, S>(
@@ -1023,13 +1140,9 @@ export const addOrOmit: {
   key: Key<I, S>,
   service: Option.Option<Types.NoInfer<S>>
 ): Context<Services | I> =>
-  withMapUnsafe(self, (map) => {
-    if (service._tag === "None") {
-      map.delete(key.key)
-    } else {
-      map.set(key.key, service.value)
-    }
-  }))
+  service._tag === "None"
+    ? omit(key)(self) as any
+    : add(self, key, service.value))
 
 /**
  * Gets the service for a key, or evaluates the fallback when a non-reference
@@ -1052,7 +1165,7 @@ export const addOrOmit: {
  *
  * **Example** (Falling back for missing services)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context } from "effect"
  *
  * const Logger = Context.Service<{ log: (msg: string) => void }>("Logger")
@@ -1060,9 +1173,7 @@ export const addOrOmit: {
  *   "Database"
  * )
  *
- * const context = Context.make(Logger, {
- *   log: (msg: string) => console.log(msg)
- * })
+ * const context = Context.make(Logger, { log: (_msg: string) => {} })
  *
  * const logger = Context.getOrElse(context, Logger, () => ({ log: () => {} }))
  * const database = Context.getOrElse(
@@ -1071,8 +1182,8 @@ export const addOrOmit: {
  *   () => ({ query: () => "fallback" })
  * )
  *
- * console.log(logger === Context.get(context, Logger)) // true
- * console.log(database.query("SELECT 1")) // "fallback"
+ * logger === Context.get(context, Logger) // => true
+ * database.query("SELECT 1") // => "fallback"
  * ```
  *
  * @see {@link getOption} for returning `Option.none` when a non-reference key is missing
@@ -1102,7 +1213,7 @@ export const getOrElse: {
    *
    * **Example** (Falling back for missing services)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Context } from "effect"
    *
    * const Logger = Context.Service<{ log: (msg: string) => void }>("Logger")
@@ -1110,9 +1221,7 @@ export const getOrElse: {
    *   "Database"
    * )
    *
-   * const context = Context.make(Logger, {
-   *   log: (msg: string) => console.log(msg)
-   * })
+   * const context = Context.make(Logger, { log: (_msg: string) => {} })
    *
    * const logger = Context.getOrElse(context, Logger, () => ({ log: () => {} }))
    * const database = Context.getOrElse(
@@ -1121,8 +1230,8 @@ export const getOrElse: {
    *   () => ({ query: () => "fallback" })
    * )
    *
-   * console.log(logger === Context.get(context, Logger)) // true
-   * console.log(database.query("SELECT 1")) // "fallback"
+   * logger === Context.get(context, Logger) // => true
+   * database.query("SELECT 1") // => "fallback"
    * ```
    *
    * @see {@link getOption} for returning `Option.none` when a non-reference key is missing
@@ -1152,7 +1261,7 @@ export const getOrElse: {
    *
    * **Example** (Falling back for missing services)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Context } from "effect"
    *
    * const Logger = Context.Service<{ log: (msg: string) => void }>("Logger")
@@ -1160,9 +1269,7 @@ export const getOrElse: {
    *   "Database"
    * )
    *
-   * const context = Context.make(Logger, {
-   *   log: (msg: string) => console.log(msg)
-   * })
+   * const context = Context.make(Logger, { log: (_msg: string) => {} })
    *
    * const logger = Context.getOrElse(context, Logger, () => ({ log: () => {} }))
    * const database = Context.getOrElse(
@@ -1171,8 +1278,8 @@ export const getOrElse: {
    *   () => ({ query: () => "fallback" })
    * )
    *
-   * console.log(logger === Context.get(context, Logger)) // true
-   * console.log(database.query("SELECT 1")) // "fallback"
+   * logger === Context.get(context, Logger) // => true
+   * database.query("SELECT 1") // => "fallback"
    * ```
    *
    * @see {@link getOption} for returning `Option.none` when a non-reference key is missing
@@ -1182,9 +1289,8 @@ export const getOrElse: {
    */
   <Services, S, I, B>(self: Context<Services>, key: Key<I, S>, orElse: LazyArg<B>): S | B
 } = dual(3, <Services, S, I, B>(self: Context<Services>, key: Key<I, S>, orElse: LazyArg<B>): S | B => {
-  if (self.mapUnsafe.has(key.key)) {
-    return self.mapUnsafe.get(key.key)! as any
-  }
+  const value = lookup(self, key.key)
+  if (value !== notFound) return value as any
   return isReference(key) ? getDefaultValue(key) : orElse()
 })
 
@@ -1250,9 +1356,15 @@ export const getOrUndefined: {
   <Services, S, I>(self: Context<Services>, key: Key<I, S>): S | undefined
 } = dual(
   2,
-  <Services, S, I>(self: Context<Services>, key: Key<I, S>): S | undefined => self.mapUnsafe.get(key.key)
+  <Services, S, I>(self: Context<Services>, key: Key<I, S>): S | undefined => getOrUndefinedUnsafe(self, key.key)
 )
 
+/** @internal */
+export const getOrUndefinedUnsafe = <A, Services = never>(self: Context<Services>, key: string): A | undefined => {
+  const value = lookup(self, key)
+  return value === notFound ? undefined : value as A
+}
+
 /**
  * Gets the service for a key, throwing if an absent non-reference key cannot be
  * resolved.
@@ -1270,17 +1382,16 @@ export const getOrUndefined: {
  *
  * **Example** (Getting services unsafely)
  *
- * ```ts
- * import { Context } from "effect"
- * import * as assert from "node:assert"
+ * ```ts import.meta.vitest
+ * import { Context, Option } from "effect"
  *
  * const Port = Context.Service<{ PORT: number }>("Port")
  * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
  *
  * const context = Context.make(Port, { PORT: 8080 })
  *
- * assert.deepStrictEqual(Context.getUnsafe(context, Port), { PORT: 8080 })
- * assert.throws(() => Context.getUnsafe(context, Timeout))
+ * Context.getUnsafe(context, Port).PORT // => 8080
+ * Context.getOption(context, Timeout) // => Option.none()
  * ```
  *
  * @see {@link get} for type-checked service access
@@ -1307,17 +1418,16 @@ export const getUnsafe: {
    *
    * **Example** (Getting services unsafely)
    *
-   * ```ts
-   * import { Context } from "effect"
-   * import * as assert from "node:assert"
+   * ```ts import.meta.vitest
+   * import { Context, Option } from "effect"
    *
    * const Port = Context.Service<{ PORT: number }>("Port")
    * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
    *
    * const context = Context.make(Port, { PORT: 8080 })
    *
-   * assert.deepStrictEqual(Context.getUnsafe(context, Port), { PORT: 8080 })
-   * assert.throws(() => Context.getUnsafe(context, Timeout))
+   * Context.getUnsafe(context, Port).PORT // => 8080
+   * Context.getOption(context, Timeout) // => Option.none()
    * ```
    *
    * @see {@link get} for type-checked service access
@@ -1344,17 +1454,16 @@ export const getUnsafe: {
    *
    * **Example** (Getting services unsafely)
    *
-   * ```ts
-   * import { Context } from "effect"
-   * import * as assert from "node:assert"
+   * ```ts import.meta.vitest
+   * import { Context, Option } from "effect"
    *
    * const Port = Context.Service<{ PORT: number }>("Port")
    * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
    *
    * const context = Context.make(Port, { PORT: 8080 })
    *
-   * assert.deepStrictEqual(Context.getUnsafe(context, Port), { PORT: 8080 })
-   * assert.throws(() => Context.getUnsafe(context, Timeout))
+   * Context.getUnsafe(context, Port).PORT // => 8080
+   * Context.getOption(context, Timeout) // => Option.none()
    * ```
    *
    * @see {@link get} for type-checked service access
@@ -1367,11 +1476,12 @@ export const getUnsafe: {
 } = dual(
   2,
   <Services, I extends Services, S>(self: Context<Services>, service: Key<I, S>): S => {
-    if (!self.mapUnsafe.has(service.key)) {
-      if (ReferenceTypeId in service) return getDefaultValue(service as any)
+    const value = lookup(self, service.key)
+    if (value === notFound) {
+      if (isReference(service)) return getDefaultValue(service as any)
       throw serviceNotFoundError(service)
     }
-    return self.mapUnsafe.get(service.key)! as any
+    return value as any
   }
 )
 
@@ -1385,9 +1495,8 @@ export const getUnsafe: {
  *
  * **Example** (Getting a service from a context)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, pipe } from "effect"
- * import * as assert from "node:assert"
  *
  * const Port = Context.Service<{ PORT: number }>("Port")
  * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
@@ -1397,7 +1506,7 @@ export const getUnsafe: {
  *   Context.add(Timeout, { TIMEOUT: 5000 })
  * )
  *
- * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
+ * Context.get(context, Timeout).TIMEOUT // => 5000
  * ```
  *
  * @see {@link getOption} for optional service access
@@ -1417,9 +1526,8 @@ export const get: {
    *
    * **Example** (Getting a service from a context)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Context, pipe } from "effect"
-   * import * as assert from "node:assert"
    *
    * const Port = Context.Service<{ PORT: number }>("Port")
    * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
@@ -1429,7 +1537,7 @@ export const get: {
    *   Context.add(Timeout, { TIMEOUT: 5000 })
    * )
    *
-   * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
+   * Context.get(context, Timeout).TIMEOUT // => 5000
    * ```
    *
    * @see {@link getOption} for optional service access
@@ -1449,9 +1557,8 @@ export const get: {
    *
    * **Example** (Getting a service from a context)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Context, pipe } from "effect"
-   * import * as assert from "node:assert"
    *
    * const Port = Context.Service<{ PORT: number }>("Port")
    * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
@@ -1461,7 +1568,7 @@ export const get: {
    *   Context.add(Timeout, { TIMEOUT: 5000 })
    * )
    *
-   * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
+   * Context.get(context, Timeout).TIMEOUT // => 5000
    * ```
    *
    * @see {@link getOption} for optional service access
@@ -1473,54 +1580,6 @@ export const get: {
   <Services, I extends Services, S>(self: Context<Services>, service: Key<I, S>): S
 } = getUnsafe
 
-/**
- * Gets the value for a `Context.Reference`, returning its cached default when
- * the context does not contain an override.
- *
- * **When to use**
- *
- * Use when you need a `Context.Reference` value resolved from either a stored
- * override or the reference's default value.
- *
- * **Details**
- *
- * Stored overrides take precedence. If no override is present, the reference's
- * default value is computed lazily and cached on the reference itself.
- *
- * **Gotchas**
- *
- * Mutable default values can be shared across contexts unless an override is
- * provided, because the default is cached on the `Context.Reference`.
- *
- * **Example** (Getting reference defaults unsafely)
- *
- * ```ts
- * import { Context } from "effect"
- *
- * const LoggerRef = Context.Reference("Logger", {
- *   defaultValue: () => ({ log: (msg: string) => console.log(msg) })
- * })
- *
- * const context = Context.empty()
- * const logger = Context.getReferenceUnsafe(context, LoggerRef)
- *
- * console.log(typeof logger.log) // "function"
- * ```
- *
- * @see {@link getUnsafe} for unsafe access with any service key
- * @see {@link get} for type-checked reference-aware access
- * @see {@link getOption} for optional access to non-reference keys
- *
- * @category unsafe
- * @since 4.0.0
- */
-export const getReferenceUnsafe = <Services, S>(self: Context<Services>, service: Reference<S>): S => {
-  if (!self.mapUnsafe.has(service.key)) {
-    return getDefaultValue(service as any)
-  }
-  return self.mapUnsafe.get(service.key)! as any
-}
-
 const defaultValueCacheKey = "~effect/Context/defaultValue" as const
 
 const getDefaultValue = (ref: Reference<any>) => {
@@ -1567,20 +1626,16 @@ const serviceNotFoundError = (service: Key<any, any>) => {
  *
  * **Example** (Getting optional services)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Option } from "effect"
- * import * as assert from "node:assert"
  *
  * const Port = Context.Service<{ PORT: number }>("Port")
  * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
  *
  * const context = Context.make(Port, { PORT: 8080 })
  *
- * assert.deepStrictEqual(
- *   Context.getOption(context, Port),
- *   Option.some({ PORT: 8080 })
- * )
- * assert.deepStrictEqual(Context.getOption(context, Timeout), Option.none())
+ * Context.getOption(context, Port) // => Option.some({ PORT: 8080 })
+ * Context.getOption(context, Timeout) // => Option.none()
  * ```
  *
  * @see {@link getOrElse} for returning a fallback value directly
@@ -1605,20 +1660,16 @@ export const getOption: {
    *
    * **Example** (Getting optional services)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Context, Option } from "effect"
-   * import * as assert from "node:assert"
    *
    * const Port = Context.Service<{ PORT: number }>("Port")
    * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
    *
    * const context = Context.make(Port, { PORT: 8080 })
    *
-   * assert.deepStrictEqual(
-   *   Context.getOption(context, Port),
-   *   Option.some({ PORT: 8080 })
-   * )
-   * assert.deepStrictEqual(Context.getOption(context, Timeout), Option.none())
+   * Context.getOption(context, Port) // => Option.some({ PORT: 8080 })
+   * Context.getOption(context, Timeout) // => Option.none()
    * ```
    *
    * @see {@link getOrElse} for returning a fallback value directly
@@ -1643,20 +1694,16 @@ export const getOption: {
    *
    * **Example** (Getting optional services)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Context, Option } from "effect"
-   * import * as assert from "node:assert"
    *
    * const Port = Context.Service<{ PORT: number }>("Port")
    * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
    *
    * const context = Context.make(Port, { PORT: 8080 })
    *
-   * assert.deepStrictEqual(
-   *   Context.getOption(context, Port),
-   *   Option.some({ PORT: 8080 })
-   * )
-   * assert.deepStrictEqual(Context.getOption(context, Timeout), Option.none())
+   * Context.getOption(context, Port) // => Option.some({ PORT: 8080 })
+   * Context.getOption(context, Timeout) // => Option.none()
    * ```
    *
    * @see {@link getOrElse} for returning a fallback value directly
@@ -1666,9 +1713,8 @@ export const getOption: {
    */
   <Services, S, I>(self: Context<Services>, service: Key<I, S>): Option.Option<S>
 } = dual(2, <Services, I extends Services, S>(self: Context<Services>, service: Key<I, S>): Option.Option<S> => {
-  if (self.mapUnsafe.has(service.key)) {
-    return Option.some(self.mapUnsafe.get(service.key)! as any)
-  }
+  const value = lookup(self, service.key)
+  if (value !== notFound) return Option.some(value as any)
   return isReference(service) ? Option.some(getDefaultValue(service as any)) : Option.none()
 })
 
@@ -1686,9 +1732,8 @@ export const getOption: {
  *
  * **Example** (Merging two contexts)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context } from "effect"
- * import * as assert from "node:assert"
  *
  * const Port = Context.Service<{ PORT: number }>("Port")
  * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
@@ -1698,8 +1743,8 @@ export const getOption: {
  *
  * const context = Context.merge(firstContext, secondContext)
  *
- * assert.deepStrictEqual(Context.get(context, Port), { PORT: 8080 })
- * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
+ * const values = [Context.get(context, Port).PORT, Context.get(context, Timeout).TIMEOUT]
+ * values // => [8080, 5000]
  * ```
  *
  * @see {@link mergeAll} for merging more than two contexts at once
@@ -1722,9 +1767,8 @@ export const merge: {
    *
    * **Example** (Merging two contexts)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Context } from "effect"
-   * import * as assert from "node:assert"
    *
    * const Port = Context.Service<{ PORT: number }>("Port")
    * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
@@ -1734,8 +1778,8 @@ export const merge: {
    *
    * const context = Context.merge(firstContext, secondContext)
    *
-   * assert.deepStrictEqual(Context.get(context, Port), { PORT: 8080 })
-   * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
+   * const values = [Context.get(context, Port).PORT, Context.get(context, Timeout).TIMEOUT]
+   * values // => [8080, 5000]
    * ```
    *
    * @see {@link mergeAll} for merging more than two contexts at once
@@ -1758,9 +1802,8 @@ export const merge: {
    *
    * **Example** (Merging two contexts)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Context } from "effect"
-   * import * as assert from "node:assert"
    *
    * const Port = Context.Service<{ PORT: number }>("Port")
    * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
@@ -1770,8 +1813,8 @@ export const merge: {
    *
    * const context = Context.merge(firstContext, secondContext)
    *
-   * assert.deepStrictEqual(Context.get(context, Port), { PORT: 8080 })
-   * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
+   * const values = [Context.get(context, Port).PORT, Context.get(context, Timeout).TIMEOUT]
+   * values // => [8080, 5000]
    * ```
    *
    * @see {@link mergeAll} for merging more than two contexts at once
@@ -1783,9 +1826,7 @@ export const merge: {
 } = dual(2, <Services, R1>(self: Context<Services>, that: Context<R1>): Context<Services | R1> => {
   if (self.mapUnsafe.size === 0) return that as any
   if (that.mapUnsafe.size === 0) return self as any
-  return withMapUnsafe(self, (map) => {
-    that.mapUnsafe.forEach((value, key) => map.set(key, value))
-  })
+  return withFlat(self, (map) => that.mapUnsafe.forEach((value, key) => map.set(key, value)))
 })
 
 /**
@@ -1802,9 +1843,8 @@ export const merge: {
  *
  * **Example** (Merging multiple contexts)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context } from "effect"
- * import * as assert from "node:assert"
  *
  * const Port = Context.Service<{ PORT: number }>("Port")
  * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
@@ -1820,9 +1860,7 @@ export const merge: {
  *   thirdContext
  * )
  *
- * assert.deepStrictEqual(Context.get(context, Port), { PORT: 8080 })
- * assert.deepStrictEqual(Context.get(context, Timeout), { TIMEOUT: 5000 })
- * assert.deepStrictEqual(Context.get(context, Host), { HOST: "localhost" })
+ * context.mapUnsafe.size // => 3
  * ```
  *
  * @see {@link merge} for merging two contexts
@@ -1851,9 +1889,8 @@ export const mergeAll = <T extends Array<unknown>>(
  *
  * **Example** (Picking services from a context)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Option, pipe } from "effect"
- * import * as assert from "node:assert"
  *
  * const Port = Context.Service<{ PORT: number }>("Port")
  * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
@@ -1865,11 +1902,8 @@ export const mergeAll = <T extends Array<unknown>>(
  *
  * const context = pipe(someContext, Context.pick(Port))
  *
- * assert.deepStrictEqual(
- *   Context.getOption(context, Port),
- *   Option.some({ PORT: 8080 })
- * )
- * assert.deepStrictEqual(Context.getOption(context, Timeout), Option.none())
+ * Context.getOption(context, Port) // => Option.some({ PORT: 8080 })
+ * Context.getOption(context, Timeout) // => Option.none()
  * ```
  *
  * @see {@link omit} for removing selected services
@@ -1880,14 +1914,13 @@ export const mergeAll = <T extends Array<unknown>>(
 export const pick = <S extends ReadonlyArray<Key<any, any>>>(
   ...services: S
 ) =>
-<Services>(self: Context<Services>): Context<Services & Service.Identifier<S[number]>> =>
-  withMapUnsafe(self, (map) => {
-    const keySet = new Set(services.map((key) => key.key))
+<Services>(self: Context<Services>): Context<Services & Service.Identifier<S[number]>> => {
+  const keep = new Set(services.map((key) => key.key))
+  return withFlat(self, (map) =>
     map.forEach((_, key) => {
-      if (keySet.has(key)) return
-      map.delete(key)
-    })
-  })
+      if (!keep.has(key)) map.delete(key)
+    }))
+}
 
 /**
  * Returns a new `Context` with the specified service keys removed.
@@ -1898,9 +1931,8 @@ export const pick = <S extends ReadonlyArray<Key<any, any>>>(
  *
  * **Example** (Omitting services from a context)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context, Option, pipe } from "effect"
- * import * as assert from "node:assert"
  *
  * const Port = Context.Service<{ PORT: number }>("Port")
  * const Timeout = Context.Service<{ TIMEOUT: number }>("Timeout")
@@ -1912,11 +1944,8 @@ export const pick = <S extends ReadonlyArray<Key<any, any>>>(
  *
  * const context = pipe(someContext, Context.omit(Timeout))
  *
- * assert.deepStrictEqual(
- *   Context.getOption(context, Port),
- *   Option.some({ PORT: 8080 })
- * )
- * assert.deepStrictEqual(Context.getOption(context, Timeout), Option.none())
+ * Context.getOption(context, Port) // => Option.some({ PORT: 8080 })
+ * Context.getOption(context, Timeout) // => Option.none()
  * ```
  *
  * @see {@link pick} for keeping selected services
@@ -1928,108 +1957,12 @@ export const omit = <S extends ReadonlyArray<Key<any, any>>>(
   ...keys: S
 ) =>
 <Services>(self: Context<Services>): Context<Exclude<Services, Service.Identifier<S[number]>>> =>
-  withMapUnsafe(self, (map) => {
+  withFlat(self, (map) => {
     for (let i = 0; i < keys.length; i++) {
       map.delete(keys[i].key)
     }
   })
 
-/**
- * Performs a series of mutations on a `Context`. Prevents unnecessary copying
- * of the underlying map when multiple mutations are needed.
- *
- * **When to use**
- *
- * Use to apply several `Context` transformations in one callback while copying
- * the underlying service map only once.
- *
- * @see {@link add} for adding or replacing a service
- * @see {@link addOrOmit} for adding or removing a service from an `Option`
- * @see {@link merge} for combining two contexts
- * @see {@link pick} for keeping selected services
- * @see {@link omit} for removing selected services
- *
- * @category mutations
- * @since 4.0.0
- */
-export const mutate: {
-  /**
-   * Performs a series of mutations on a `Context`. Prevents unnecessary copying
-   * of the underlying map when multiple mutations are needed.
-   *
-   * **When to use**
-   *
-   * Use to apply several `Context` transformations in one callback while copying
-   * the underlying service map only once.
-   *
-   * @see {@link add} for adding or replacing a service
-   * @see {@link addOrOmit} for adding or removing a service from an `Option`
-   * @see {@link merge} for combining two contexts
-   * @see {@link pick} for keeping selected services
-   * @see {@link omit} for removing selected services
-   *
-   * @category mutations
-   * @since 4.0.0
-   */
-  <Services, B>(f: (context: Context<Services>) => Context<B>): <Services>(self: Context<Services>) => Context<B>
-  /**
-   * Performs a series of mutations on a `Context`. Prevents unnecessary copying
-   * of the underlying map when multiple mutations are needed.
-   *
-   * **When to use**
-   *
-   * Use to apply several `Context` transformations in one callback while copying
-   * the underlying service map only once.
-   *
-   * @see {@link add} for adding or replacing a service
-   * @see {@link addOrOmit} for adding or removing a service from an `Option`
-   * @see {@link merge} for combining two contexts
-   * @see {@link pick} for keeping selected services
-   * @see {@link omit} for removing selected services
-   *
-   * @category mutations
-   * @since 4.0.0
-   */
-  <Services, B>(self: Context<Services>, f: (context: Context<Services>) => Context<B>): Context<B>
-} = dual(
-  2,
-  <Services, B>(self: Context<Services>, f: (context: Context<Services>) => Context<B>): Context<B> => {
-    const next = makeUnsafe</**
-     * Performs a series of mutations on a `Context`. Prevents unnecessary copying
-     * of the underlying map when multiple mutations are needed.
-     *
-     * **When to use**
-     *
-     * Use to apply several `Context` transformations in one callback while copying
-     * the underlying service map only once.
-     *
-     * @see {@link add} for adding or replacing a service
-     * @see {@link addOrOmit} for adding or removing a service from an `Option`
-     * @see {@link merge} for combining two contexts
-     * @see {@link pick} for keeping selected services
-     * @see {@link omit} for removing selected services
-     *
-     * @category mutations
-     * @since 4.0.0
-     */
-    Services>(new Map(self.mapUnsafe))
-    next.mutable = true
-    const result = f(next)
-    result.mutable = false
-    return result
-  }
-)
-
-const withMapUnsafe = <Services, B>(self: Context<Services>, f: (map: Map<string, any>) => void): Context<B> => {
-  if (self.mutable) {
-    f(self.mapUnsafe as any)
-    return self as any
-  }
-  const map = new Map(self.mapUnsafe)
-  f(map)
-  return makeUnsafe(map)
-}
-
 /**
  * Creates a context key with a default value.
  *
@@ -2048,12 +1981,13 @@ const withMapUnsafe = <Services, B>(self: Context<Services>, f: (map: Map<string
  *
  * **Example** (Creating references with default values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Context } from "effect"
  *
  * // Create a reference with a default value
+ * const messages: Array<string> = []
  * const LoggerRef = Context.Reference("Logger", {
- *   defaultValue: () => ({ log: (msg: string) => console.log(msg) })
+ *   defaultValue: () => ({ log: (msg: string) => messages.push(`Default: ${msg}`) })
  * })
  *
  * // The reference provides the default value when accessed from an empty context
@@ -2062,17 +1996,24 @@ const withMapUnsafe = <Services, B>(self: Context<Services>, f: (map: Map<string
  *
  * // You can also override the default value
  * const customContext = Context.make(LoggerRef, {
- *   log: (msg: string) => `Custom: ${msg}`
+ *   log: (msg: string) => messages.push(`Custom: ${msg}`)
  * })
  * const customLogger = Context.get(customContext, LoggerRef)
+ * logger.log("default")
+ * customLogger.log("message")
+ * messages // => ["Default: default", "Custom: message"]
  * ```
  *
  * @see {@link Service} for required services without default values
  *
- * @category references
+ * @category services
  * @since 3.11.0
  */
 export const Reference: <Service>(
   key: string,
-  options: { readonly defaultValue: () => Service }
+  options: {
+    readonly defaultValue: () => Service
+    /** @internal */
+    readonly fiberCached?: boolean | undefined
+  }
 ) => Reference<Service> = Service as any