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

package/src/unstable/httpapi/HttpApiMiddleware.ts

@@ -125,7 +125,7 @@ export interface HttpApiMiddlewareClient<_E, CE, R> {
 /**
  * Client-side service marker required when a middleware declares `requiredForClient`.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export interface ForClient<Id> {
@@ -136,7 +136,7 @@ export interface ForClient<Id> {
 /**
  * Base service key shape for HTTP API middleware services, including provided services, declared error schemas, and client requirements.
  *
- * @category models
+ * @category services
  * @since 4.0.0
  */
 export interface AnyService extends Context.Key<any, any> {
@@ -150,7 +150,7 @@ export interface AnyService extends Context.Key<any, any> {
 /**
  * Middleware service key shape for security middleware, including the security schemes handled by the service.
  *
- * @category models
+ * @category services
  * @since 4.0.0
  */
 export interface AnyServiceSecurity extends AnyService {
@@ -161,7 +161,7 @@ export interface AnyServiceSecurity extends AnyService {
 /**
  * Type-level identifier carried by middleware services to track provided services, required services, errors, client errors, and client requirements.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export interface AnyId {
@@ -177,7 +177,7 @@ export interface AnyId {
 /**
  * Extracts the services provided by a middleware identifier.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type Provides<A> = A extends { readonly [TypeId]: { readonly provides: infer P } } ? P : never
@@ -185,7 +185,7 @@ export type Provides<A> = A extends { readonly [TypeId]: { readonly provides: in
 /**
  * Extracts the services required to run a middleware implementation.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type Requires<A> = A extends { readonly [TypeId]: { readonly requires: infer R } } ? R : never
@@ -193,7 +193,7 @@ export type Requires<A> = A extends { readonly [TypeId]: { readonly requires: in
 /**
  * Applies a middleware's service changes to an existing requirement type by removing services it provides and adding services it requires.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ApplyServices<A extends AnyId, R> = Exclude<R, Provides<A>> | Requires<A>
@@ -201,7 +201,7 @@ export type ApplyServices<A extends AnyId, R> = Exclude<R, Provides<A>> | Requir
 /**
  * Extracts the schema or schema union used for errors declared by a middleware identifier.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ErrorSchema<A> = A extends { readonly [TypeId]: { readonly error: infer E } } ? ErrorSchemaFromConstraint<E>
@@ -210,7 +210,7 @@ export type ErrorSchema<A> = A extends { readonly [TypeId]: { readonly error: in
 /**
  * Extracts the decoded error type declared by a middleware identifier.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type Error<A> = ErrorSchema<A>["Type"]
@@ -218,7 +218,7 @@ export type Error<A> = ErrorSchema<A>["Type"]
 /**
  * Extracts the client-side error type for middleware that is required on generated clients.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ClientError<A> = A extends {
@@ -232,7 +232,7 @@ export type ClientError<A> = A extends {
 /**
  * Computes the client-side service marker required for middleware that must also run in generated clients.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type MiddlewareClient<A> = A extends {
@@ -245,7 +245,7 @@ export type MiddlewareClient<A> = A extends {
 /**
  * Extracts the schema services required to encode errors declared by a middleware identifier.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ErrorServicesEncode<A> = ErrorSchema<A>["EncodingServices"]
@@ -253,7 +253,7 @@ export type ErrorServicesEncode<A> = ErrorSchema<A>["EncodingServices"]
 /**
  * Extracts the schema services required to decode errors declared by a middleware identifier.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ErrorServicesDecode<A> = ErrorSchema<A>["DecodingServices"]
@@ -266,7 +266,7 @@ export type ErrorServicesDecode<A> = ErrorSchema<A>["DecodingServices"]
  * It combines a `Context.Service` class with the middleware metadata used by
  * endpoints, builders, and generated clients.
  *
- * @category schemas
+ * @category services
  * @since 4.0.0
  */
 export type ServiceClass<
@@ -314,7 +314,7 @@ export type ServiceClass<
  * required services, provided services, typed error schemas, security schemes,
  * client errors, or a matching client middleware requirement.
  *
- * @category schemas
+ * @category constructors
  * @since 4.0.0
  */
 export const Service = <
@@ -394,26 +394,73 @@ function getError(error: ErrorConstraint | undefined): ReadonlySet<Schema.Top> {
  *
  * **Example** (Mapping schema errors to custom errors)
  *
- * ```ts
- * import { Effect, Schema } from "effect"
- * import { HttpApiMiddleware } from "effect/unstable/httpapi"
+ * ```ts import.meta.vitest
+ * import { Effect, Schema, type Types } from "effect"
+ * import { HttpRouter, HttpServerResponse } from "effect/unstable/http"
+ * import {
+ *   HttpApiEndpoint,
+ *   HttpApiError,
+ *   HttpApiGroup,
+ *   HttpApiMiddleware
+ * } from "effect/unstable/httpapi"
  *
- * export class CustomError extends Schema.TaggedErrorClass<CustomError>()("CustomError", {}) {}
+ * class CustomError extends Schema.TaggedErrorClass<CustomError>()("CustomError", {}) {}
  *
- * export class ErrorHandler extends HttpApiMiddleware.Service<ErrorHandler>()("api/ErrorHandler", {
+ * class ErrorHandler extends HttpApiMiddleware.Service<ErrorHandler>()("api/ErrorHandler", {
  *   error: CustomError
  * }) {}
  *
- * export const ErrorHandlerLayer = HttpApiMiddleware.layerSchemaErrorTransform(
+ * const messages: Array<string> = []
+ * const ErrorHandlerLayer = HttpApiMiddleware.layerSchemaErrorTransform(
  *   ErrorHandler,
  *   (schemaError) =>
- *     Effect.log("Got SchemaError", schemaError).pipe(
+ *     Effect.sync(() => messages.push(`Mapping ${schemaError.kind} schema error`)).pipe(
  *       Effect.andThen(Effect.fail(new CustomError()))
  *     )
  * )
+ *
+ * const endpoint = HttpApiEndpoint.get("example", "/")
+ * const group = HttpApiGroup.make("examples").add(endpoint)
+ * const middlewareContext = {
+ *   endpoint: endpoint as unknown as HttpApiEndpoint.Top,
+ *   group: group as unknown as HttpApiGroup.Top
+ * }
+ * const Routes = HttpRouter.add(
+ *   "GET",
+ *   "/",
+ *   Effect.gen(function*() {
+ *     const applySchemaErrorTransform = yield* ErrorHandler
+ *     const schemaError = yield* HttpApiError.HttpApiSchemaError.wrap(
+ *       "Body",
+ *       Schema.decodeUnknownEffect(Schema.String)(42)
+ *     ).pipe(Effect.flip)
+ *     const failingResponse = Effect.fail(schemaError as unknown as Types.unhandled)
+ *     const result = yield* applySchemaErrorTransform(failingResponse, middlewareContext).pipe(
+ *       Effect.match({
+ *         onFailure: (error) => error instanceof CustomError ? error._tag : "UnexpectedError",
+ *         onSuccess: () => "Success"
+ *       })
+ *     )
+ *     return HttpServerResponse.text(result)
+ *   })
+ * ).pipe(HttpRouter.provideRequest(ErrorHandlerLayer))
+ *
+ * const program = Effect.acquireUseRelease(
+ *   Effect.sync(() => HttpRouter.toWebHandler(Routes, { disableLogger: true })),
+ *   ({ handler }) =>
+ *     Effect.gen(function*() {
+ *       const response = yield* Effect.promise(() => handler(new Request("http://localhost/")))
+ *       const body = yield* Effect.promise(() => response.text())
+ *       return body
+ *     }),
+ *   ({ dispose }) => Effect.promise(dispose)
+ * )
+ *
+ * const body = await Effect.runPromise(program)
+ * const result = [messages, body] // => [["Mapping Body schema error"], "CustomError"]
  * ```
  *
- * @category SchemaError transform
+ * @category layers
  * @since 4.0.0
  */
 export const layerSchemaErrorTransform = <Id, E extends ErrorConstraint, Requires>(
@@ -451,7 +498,7 @@ export const layerSchemaErrorTransform = <Id, E extends ErrorConstraint, Require
  * The layer captures the surrounding services and makes the middleware available
  * through the `ForClient` service marker used by HTTP API clients.
  *
- * @category client
+ * @category layers
  * @since 4.0.0
  */
 export const layerClient = <Id extends AnyId, S, R, EX = never, RX = never>(

package/src/unstable/httpapi/HttpApiScalar.ts

@@ -87,12 +87,6 @@ export type ScalarConfig = {
   /**
    * Path to a favicon image.
    *
-   * **Example** (Setting a relative favicon)
-   *
-   * ```ts
-   * const favicon = "/favicon.svg"
-   * ```
-   *
    * @default undefined
    */
   favicon?: string
@@ -107,12 +101,6 @@ export type ScalarConfig = {
    * Browsers can derive the origin from `window.location.origin`; server
    * rendering needs this value supplied explicitly.
    *
-   * **Example** (Setting a local server URL)
-   *
-   * ```ts
-   * const baseServerURL = "http://localhost:3000"
-   * ```
-   *
    * @default undefined
    */
   baseServerURL?: string

package/src/unstable/httpapi/HttpApiSchema.ts

@@ -140,7 +140,7 @@ const StreamSchemaTypeId = "~effect/httpapi/HttpApiSchema/Stream"
 /**
  * Common HTTP status code literals accepted by {@link status}.
  *
- * @category status
+ * @category models
  * @since 4.0.0
  */
 export type StatusLiteral = keyof typeof statusCodeByLiteral
@@ -154,7 +154,7 @@ export type StatusLiteral = keyof typeof statusCodeByLiteral
  * schema. You can pass either a numeric status code (for example, `201`) or a
  * common literal name (for example, `"Created"`).
  *
- * @category status
+ * @category schemas
  * @since 4.0.0
  */
 export function status(code: number): {
@@ -174,7 +174,7 @@ export function status(code: number | StatusLiteral) {
  *
  * @see {@link NoContent} for the predefined 204 no content schema.
  *
- * @category Empty
+ * @category constructors
  * @since 4.0.0
  */
 export const Empty = (code: number): Schema.Void => Schema.Void.pipe(status(code))
@@ -190,7 +190,7 @@ export interface NoContent extends Schema.Void {}
 /**
  * Schema for empty HTTP responses with status code 204.
  *
- * @category Empty
+ * @category schemas
  * @since 4.0.0
  */
 export const NoContent: NoContent = Empty(204)
@@ -206,7 +206,7 @@ export interface Created extends Schema.Void {}
 /**
  * Schema for empty HTTP responses with status code 201.
  *
- * @category Empty
+ * @category schemas
  * @since 4.0.0
  */
 export const Created: Created = Empty(201)
@@ -222,7 +222,7 @@ export interface Accepted extends Schema.Void {}
 /**
  * Schema for empty HTTP responses with status code 202.
  *
- * @category Empty
+ * @category schemas
  * @since 4.0.0
  */
 export const Accepted: Accepted = Empty(202)

package/src/unstable/httpapi/OpenApi.ts

@@ -14,13 +14,14 @@ import * as Context from "../../Context.ts"
 import * as Equal from "../../Equal.ts"
 import { constFalse } from "../../Function.ts"
 import * as InternalRecord from "../../internal/record.ts"
+import * as InternalToJsonSchemaDocument from "../../internal/schema/toJsonSchemaDocument.ts"
+import * as InternalToRepresentation from "../../internal/schema/toRepresentation.ts"
 import * as JsonPatch from "../../JsonPatch.ts"
 import { escapeToken } from "../../JsonPointer.ts"
 import * as JsonSchema from "../../JsonSchema.ts"
 import * as Option from "../../Option.ts"
 import * as Schema from "../../Schema.ts"
 import * as SchemaAST from "../../SchemaAST.ts"
-import * as SchemaRepresentation from "../../SchemaRepresentation.ts"
 import * as HttpMethod from "../http/HttpMethod.ts"
 import * as HttpApi from "./HttpApi.ts"
 import * as HttpApiEndpoint from "./HttpApiEndpoint.ts"
@@ -32,7 +33,7 @@ import type { HttpApiSecurity } from "./HttpApiSecurity.ts"
 /**
  * OpenAPI annotation for overriding generated identifiers, including operation ids.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export class Identifier extends Context.Service<Identifier, string>()("effect/httpapi/OpenApi/Identifier") {}
@@ -40,7 +41,7 @@ export class Identifier extends Context.Service<Identifier, string>()("effect/ht
 /**
  * OpenAPI annotation for setting the API title or group tag name.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export class Title extends Context.Service<Title, string>()("effect/httpapi/OpenApi/Title") {}
@@ -48,7 +49,7 @@ export class Title extends Context.Service<Title, string>()("effect/httpapi/Open
 /**
  * OpenAPI annotation for setting the generated API version.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export class Version extends Context.Service<Version, string>()("effect/httpapi/OpenApi/Version") {}
@@ -56,7 +57,7 @@ export class Version extends Context.Service<Version, string>()("effect/httpapi/
 /**
  * OpenAPI annotation for setting generated descriptions on APIs, groups, endpoints, or security schemes.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export class Description extends Context.Service<Description, string>()("effect/httpapi/OpenApi/Description") {}
@@ -64,7 +65,7 @@ export class Description extends Context.Service<Description, string>()("effect/
 /**
  * OpenAPI annotation for setting the generated API license metadata.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export class License extends Context.Service<License, OpenAPISpecLicense>()("effect/httpapi/OpenApi/License") {}
@@ -72,7 +73,7 @@ export class License extends Context.Service<License, OpenAPISpecLicense>()("eff
 /**
  * OpenAPI annotation for adding external documentation metadata to groups or endpoints.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export class ExternalDocs
@@ -82,7 +83,7 @@ export class ExternalDocs
 /**
  * OpenAPI annotation for setting the generated API server list.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export class Servers
@@ -92,7 +93,7 @@ export class Servers
 /**
  * OpenAPI annotation for setting the format metadata, such as a bearer token format on security schemes.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export class Format extends Context.Service<Format, string>()("effect/httpapi/OpenApi/Format") {}
@@ -100,7 +101,7 @@ export class Format extends Context.Service<Format, string>()("effect/httpapi/Op
 /**
  * OpenAPI annotation for setting generated summary text.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export class Summary extends Context.Service<Summary, string>()("effect/httpapi/OpenApi/Summary") {}
@@ -108,7 +109,7 @@ export class Summary extends Context.Service<Summary, string>()("effect/httpapi/
 /**
  * OpenAPI annotation for marking a generated endpoint operation as deprecated.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export class Deprecated extends Context.Service<Deprecated, boolean>()("effect/httpapi/OpenApi/Deprecated") {}
@@ -116,7 +117,7 @@ export class Deprecated extends Context.Service<Deprecated, boolean>()("effect/h
 /**
  * OpenAPI annotation for shallowly merging additional fields into a generated OpenAPI object.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export class Override extends Context.Service<Override, Record<string, unknown>>()("effect/httpapi/OpenApi/Override") {}
@@ -130,7 +131,7 @@ export class Override extends Context.Service<Override, Record<string, unknown>>
  * Use to hide internal, experimental, or otherwise undocumented HTTP API groups
  * and endpoints from generated OpenAPI output.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export const Exclude = Context.Reference<boolean>("effect/httpapi/OpenApi/Exclude", {
@@ -145,7 +146,7 @@ export const Exclude = Context.Reference<boolean>("effect/httpapi/OpenApi/Exclud
  * The function is applied during generation to the annotated API, group tag, or
  * endpoint operation.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export class Transform extends Context.Service<
@@ -212,6 +213,17 @@ export const annotations: (
 
 const apiCache = new WeakMap<HttpApi.Constraint, OpenAPISpec>()
 
+type CompileSchemas = (
+  asts: readonly [SchemaAST.AST, ...Array<SchemaAST.AST>]
+) => JsonSchema.MultiDocument<"openapi-3.1">
+
+const compileSchemas: CompileSchemas = (asts) =>
+  JsonSchema.toMultiDocumentOpenApi3_1(
+    InternalToJsonSchemaDocument.toJsonSchemaMultiDocument(
+      InternalToRepresentation.toRepresentations(Arr.map(asts, Schema.toCodecJsonAST))
+    )
+  )
+
 /**
  * This function checks if a given tag exists within the provided context. If
  * the tag is present, it retrieves the associated value and applies the given
@@ -251,7 +263,15 @@ function processAnnotation<Services, S, I>(
 export function fromApi<Id extends string, Groups extends HttpApiGroup.Constraint>(
   api: HttpApi.HttpApi<Id, Groups>
 ): OpenAPISpec {
-  const cached = apiCache.get(api)
+  return fromApiWith(api, apiCache, compileSchemas)
+}
+
+function fromApiWith<Id extends string, Groups extends HttpApiGroup.Constraint>(
+  api: HttpApi.HttpApi<Id, Groups>,
+  cache: WeakMap<HttpApi.Constraint, OpenAPISpec>,
+  compileSchemas: CompileSchemas
+): OpenAPISpec {
+  const cached = cache.get(api)
   if (cached !== undefined) {
     return cached
   }
@@ -318,7 +338,10 @@ export function fromApi<Id extends string, Groups extends HttpApiGroup.Constrain
         tag.externalDocs = externalDocs
       })
       processAnnotation(group.annotations, Override, (override) => {
-        Object.assign(tag, override)
+        // OpenAPI documents are JSON, so symbol keys are intentionally ignored.
+        for (const [key, value] of Object.entries(override)) {
+          InternalRecord.assignProperty(tag as any, key, value)
+        }
       })
       processAnnotation(group.annotations, Transform, (transformFn) => {
         tag = transformFn(tag) as OpenAPISpecTag
@@ -348,9 +371,9 @@ export function fromApi<Id extends string, Groups extends HttpApiGroup.Constrain
       function processResponseBodies(bodies: ResponseBodies, defaultDescription: () => string) {
         for (const [status, { content, descriptions, streamContent }] of bodies) {
           const description = descriptions.size > 0 ? Array.from(descriptions).join(" | ") : defaultDescription()
-          op.responses[status] = {
+          InternalRecord.assignProperty(op.responses, status, {
             description
-          }
+          })
           if (content !== undefined) {
             content.forEach((map, encoding) => {
               map.forEach((schemas, contentType) => {
@@ -363,9 +386,9 @@ export function fromApi<Id extends string, Groups extends HttpApiGroup.Constrain
                   path: ["paths", path, method, "responses", String(status), "content", contentType, "schema"]
                 })
                 op.responses[status].content ??= {}
-                op.responses[status].content[contentType] = {
+                InternalRecord.assignProperty(op.responses[status].content, contentType, {
                   schema: {}
-                }
+                })
               })
             })
           }
@@ -408,7 +431,7 @@ export function fromApi<Id extends string, Groups extends HttpApiGroup.Constrain
                     "errorSchema"
                   ]
                 })
-                op.responses[status].content[contentType] = {
+                InternalRecord.assignProperty(op.responses[status].content, contentType, {
                   schema: {},
                   "x-effect-stream": {
                     encoding: "sse",
@@ -416,9 +439,9 @@ export function fromApi<Id extends string, Groups extends HttpApiGroup.Constrain
                     errorSchema: {},
                     failureEvent: reservedStreamFailureEvent
                   }
-                }
+                })
               } else {
-                op.responses[status].content[contentType] = {
+                InternalRecord.assignProperty(op.responses[status].content, contentType, {
                   schema: {
                     type: "string",
                     format: "binary"
@@ -426,7 +449,7 @@ export function fromApi<Id extends string, Groups extends HttpApiGroup.Constrain
                   "x-effect-stream": {
                     encoding: "uint8array"
                   }
-                }
+                })
               }
             })
           }
@@ -483,7 +506,7 @@ export function fromApi<Id extends string, Groups extends HttpApiGroup.Constrain
       ) {
         const scheme = makeSecurityScheme(security)
         if (!Object.hasOwn(spec.components.securitySchemes, name)) {
-          InternalRecord.set(spec.components.securitySchemes, name, scheme)
+          InternalRecord.assignProperty(spec.components.securitySchemes, name, scheme)
           return
         }
         if (
@@ -522,9 +545,9 @@ export function fromApi<Id extends string, Groups extends HttpApiGroup.Constrain
               ast: toEncodingAST(ast, encoding._tag),
               path: ["paths", path, method, "requestBody", "content", contentType, "schema"]
             })
-            content[contentType] = {
+            InternalRecord.assignProperty(content, contentType, {
               schema: {}
-            }
+            })
           }
           op.requestBody = { content, required: true }
         }
@@ -552,7 +575,10 @@ export function fromApi<Id extends string, Groups extends HttpApiGroup.Constrain
       )
 
       processAnnotation(endpoint.annotations, Override, (override) => {
-        Object.assign(op, override)
+        // OpenAPI documents are JSON, so symbol keys are intentionally ignored.
+        for (const [key, value] of Object.entries(override)) {
+          InternalRecord.assignProperty(op as any, key, value)
+        }
       })
       processAnnotation(endpoint.annotations, Transform, (transformFn) => {
         op = transformFn(op) as OpenAPISpecOperation
@@ -570,8 +596,8 @@ export function fromApi<Id extends string, Groups extends HttpApiGroup.Constrain
         operationIds.add(operationId)
       }
       pathOperations.add(pathOperation)
-      if (!spec.paths[path]) {
-        spec.paths[path] = {}
+      if (!Object.hasOwn(spec.paths, path)) {
+        InternalRecord.assignProperty(spec.paths, path, {})
       }
       spec.paths[path][method] = op
     }
@@ -581,10 +607,10 @@ export function fromApi<Id extends string, Groups extends HttpApiGroup.Constrain
     componentSchemas.forEach((componentSchema) => {
       const identifier = SchemaAST.resolveIdentifier(componentSchema.ast)
       if (identifier !== undefined) {
-        if (identifier in spec.components.schemas) {
+        if (Object.hasOwn(spec.components.schemas, identifier)) {
           throw new globalThis.Error(`Duplicate component schema identifier: ${identifier}`)
         }
-        spec.components.schemas[identifier] = {}
+        InternalRecord.assignProperty(spec.components.schemas, identifier, {})
         pathOps.push({
           _tag: "schema",
           ast: componentSchema.ast,
@@ -599,12 +625,7 @@ export function fromApi<Id extends string, Groups extends HttpApiGroup.Constrain
   }
 
   if (Arr.isArrayNonEmpty(pathOps)) {
-    const multiDocument = SchemaRepresentation.fromASTs(
-      Arr.map(pathOps, (op) => op.ast)
-    )
-    const jsonSchemaMultiDocument = JsonSchema.toMultiDocumentOpenApi3_1(
-      SchemaRepresentation.toJsonSchemaMultiDocument(multiDocument)
-    )
+    const jsonSchemaMultiDocument = compileSchemas(Arr.map(pathOps, (op) => op.ast))
     const patchOps: Array<JsonPatch.JsonPatchOperation> = pathOps.map((op, i) => {
       const oppath = escapePath(op.path)
       const value = jsonSchemaMultiDocument.schemas[i]
@@ -633,13 +654,16 @@ export function fromApi<Id extends string, Groups extends HttpApiGroup.Constrain
   })
 
   processAnnotation(api.annotations, Override, (override) => {
-    Object.assign(spec, override)
+    // OpenAPI documents are JSON, so symbol keys are intentionally ignored.
+    for (const [key, value] of Object.entries(override)) {
+      InternalRecord.assignProperty(spec as any, key, value)
+    }
   })
   processAnnotation(api.annotations, Transform, (transformFn) => {
     spec = transformFn(spec) as OpenAPISpec
   })
 
-  apiCache.set(api, spec)
+  cache.set(api, spec)
 
   return spec
 }
@@ -793,7 +817,7 @@ function toEncodingAST(ast: SchemaAST.AST, _tag: HttpApiSchema.Encoding["_tag"])
 function persistedFileToBinaryEncoding(ast: SchemaAST.AST): SchemaAST.AST {
   if (
     SchemaAST.isDeclaration(ast) &&
-    ((ast.annotations as (Schema.Annotations.Declaration<unknown, readonly []> | undefined))?.typeConstructor?._tag ===
+    ((ast.annotations as (Schema.Annotations.Declaration<unknown, readonly []> | undefined))?.representation?.id ===
       "effect/http/PersistedFile")
   ) {
     return Uint8ArrayEncoding.ast