effect-app 4.0.0-beta.31 → 4.0.0-beta.311

package/src/Schema/Class.ts

@@ -1,95 +1,683 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { pipe, Struct as Struct2 } from "effect"
-import type { Struct } from "effect/Schema"
+import type * as Cause from "effect/Cause"
+import * as Effect from "effect/Effect"
 import * as S from "effect/Schema"
+import * as SchemaGetter from "effect/SchemaGetter"
+import * as SchemaIssue from "effect/SchemaIssue"
+import * as SchemaTransformation from "effect/SchemaTransformation"
+import type { Struct as EffectAppStruct } from "../Schema.ts"
+import * as SchemaAST from "../SchemaAST.ts"
+import { copyOrigin } from "../utils.ts"
+import { concurrencyUnbounded } from "./ext.ts"
+import * as SchemaParser from "./SchemaParser.ts"
 
 type ClassAnnotations<Self> = S.Annotations.Declaration<Self, readonly [any]>
 
-export interface EnhancedClass<Self, SchemaS extends S.Top & { readonly fields: Struct.Fields }, Inherited>
-  extends S.Class<Self, SchemaS, Inherited>, /* Reason for enhancement */ PropsExtensions<SchemaS["fields"]>
-{
+export interface EnhancedClass<
+  Self,
+  SchemaS extends S.Constraint & { readonly fields: S.Struct.Fields },
+  Inherited
+> extends S.Class<Self, SchemaS, Inherited> {
+  /**
+   * See `copyOrigin` docs in `utils.ts` for return-type design details.
+   */
+  readonly copy: ReturnType<typeof copyOrigin<new(_: any) => Self>>
 }
 type MissingSelfGeneric<Usage extends string, Params extends string = ""> =
   `Missing \`Self\` generic - use \`class Self extends ${Usage}<Self>()(${Params}{ ... })\``
 
-export interface PropsExtensions<Fields> {
-  // include: <NewProps extends S.Struct.Fields>(
-  //   fnc: (fields: Fields) => NewProps
-  // ) => NewProps
-  pick: <P extends keyof Fields>(...keys: readonly P[]) => Pick<Fields, P>
-  omit: <P extends keyof Fields>(...keys: readonly P[]) => Omit<Fields, P>
-}
-
-type HasFields<Fields extends Struct.Fields> = {
+type HasFields<Fields extends S.Struct.Fields> = {
   readonly fields: Fields
 } | {
   readonly from: HasFields<Fields>
 }
 
-export const Class: <Self = never>(identifier: string) => <Fields extends S.Struct.Fields>(
+type ClassOptions = {
+  readonly strict?: boolean
+}
+
+export declare const ExtendedSchemaNoEncoded: unique symbol
+
+export type ExtendedSchemaNoEncoded = typeof ExtendedSchemaNoEncoded
+
+/**
+ * Override schema `Encoded` while keeping `Constraint` (intersection, not `Omit`).
+ * Free type-params for `Encoded` keep the conditional unresolved — callers that
+ * need Encoded overrides use the intersection form of the class factory return type.
+ */
+type WithEncoded<SchemaS extends S.Constraint, Encoded> = SchemaS & { readonly Encoded: Encoded }
+
+type ExtendedSchema<SchemaS extends S.Constraint & { readonly fields: S.Struct.Fields }, Encoded> = [
+  Encoded
+] extends [ExtendedSchemaNoEncoded] ? SchemaS
+  : WithEncoded<SchemaS, Encoded>
+
+/** Struct fields schema, optionally with a caller-supplied Encoded override. */
+type ClassFieldsSchema<Fields extends S.Struct.Fields, Encoded> = ExtendedSchema<S.Struct<Fields>, Encoded>
+
+export type Class<Self, S extends S.Constraint & { readonly fields: S.Struct.Fields }, Inherited> = EnhancedClass<
+  Self,
+  S,
+  Inherited
+>
+
+/**
+ * Build a modified Declaration that accepts struct-matching values during
+ * encoding, given the original Declaration and the class's fields.
+ */
+function makeRelaxedDeclaration(
+  ast: SchemaAST.Declaration,
+  fields: S.Struct.Fields,
+  cls: any
+): SchemaAST.Declaration {
+  const parseOptions = ast.annotations?.["parseOptions"] as SchemaAST.ParseOptions | undefined
+  const structSchema = S.Struct(fields)
+  const annotatedStruct = parseOptions ? S.toType(structSchema).annotate({ parseOptions }) : S.toType(structSchema)
+  const decodeStruct = SchemaParser.decodeUnknownEffect(annotatedStruct)
+
+  return new SchemaAST.Declaration(
+    ast.typeParameters,
+    () => (input: unknown, self: SchemaAST.Declaration, options: SchemaAST.ParseOptions) => {
+      if (input instanceof cls) {
+        return Effect.succeed(input)
+      }
+      if (input !== null && typeof input === "object") {
+        return decodeStruct(input, options)
+      }
+      return Effect.fail(new SchemaIssue.InvalidType(self, input))
+    },
+    ast.annotations,
+    ast.checks,
+    ast.encoding,
+    ast.context
+  )
+}
+
+// ---------------------------------------------------------------------------
+// Class — like Schema.Class but with relaxed encoding
+// ---------------------------------------------------------------------------
+
+/**
+ * Like `Schema.Class`, but the resulting class accepts plain objects matching
+ * the struct schema during encoding — not only `instanceof` or type-id
+ * checks.
+ *
+ * @example
+ * ```ts
+ * import * as Schema from "effect/Schema"
+ * import { Class } from "./Class.ts"
+ *
+ * class A extends Class<A>("A")({ a: Schema.String }) {}
+ *
+ * // Construction works as normal:
+ * new A({ a: "hello" })
+ *
+ * // Encoding accepts plain objects:
+ * Schema.encodeUnknownSync(A)({ a: "hello" }) // { a: "hello" }
+ * ```
+ */
+export const Class: <Self = never, Encoded = ExtendedSchemaNoEncoded, Brand = {}>(
+  identifier: string
+) => <Fields extends S.Struct.Fields>(
   fieldsOr: Fields | HasFields<Fields>,
-  annotations?: ClassAnnotations<Self>
+  annotations?: ClassAnnotations<Self>,
+  options?: ClassOptions
 ) => [Self] extends [never] ? MissingSelfGeneric<"Class">
   : EnhancedClass<
     Self,
-    S.Struct<Fields>,
-    {}
-  > = (identifier) => (fields, annotations) => {
-    const cls = S.Class as any
-    return class extends cls(identifier)(fields, annotations) {
-      // static readonly include = include(fields)
-      static readonly pick = (...selection: any[]) => pipe(this["fields"], Struct2.pick(selection))
-      static readonly omit = (...selection: any[]) => pipe(this["fields"], Struct2.omit(selection))
+    ClassFieldsSchema<Fields, Encoded>,
+    Brand
+  > = (identifier) => (fields, annotations, options) => {
+    const relaxed = options?.strict === false
+    // Build the original Schema.Class
+    const Base = (S.Class as any)(identifier)(fields, { ...concurrencyUnbounded, ...annotations })
+    // Get the original ast getter from the base class
+    const originalAstDescriptor = Object.getOwnPropertyDescriptor(Base, "ast")!
+
+    // Cache per-class to avoid recomputing
+    const astCache = new WeakMap<any, SchemaAST.Declaration>()
+    const copyCache = new WeakMap<any, ReturnType<typeof copyOrigin>>()
+
+    return class extends Base {
+      static get copy() {
+        let cached = copyCache.get(this)
+        if (cached === undefined) {
+          cached = copyOrigin(this)
+          copyCache.set(this, cached)
+        }
+        return cached
+      }
+      static get ast(): SchemaAST.Declaration {
+        let cached = astCache.get(this)
+        if (cached !== undefined) return cached
+        // Call the original getter with `this` bound to the actual user class,
+        // so getClassSchema(this) creates a schema that uses `new this(...)`.
+        const originalAst = originalAstDescriptor.get!.call(this) as SchemaAST.Declaration
+        cached = relaxed ? makeRelaxedDeclaration(originalAst, Base.fields, this) : originalAst
+        astCache.set(this, cached)
+        return cached
+      }
+      static mapFields(f: any, options?: any) {
+        return Base.mapFields(f, options).annotate(concurrencyUnbounded)
+      }
     } as any
   }
 
-export const TaggedClass: <Self = never>(identifier?: string) => <Tag extends string, Fields extends S.Struct.Fields>(
+// ---------------------------------------------------------------------------
+// TaggedClass — like Schema.TaggedClass but with relaxed encoding
+// ---------------------------------------------------------------------------
+
+/**
+ * Like `Schema.TaggedClass`, but the resulting class accepts plain objects
+ * matching the struct schema during encoding.
+ *
+ * @example
+ * ```ts
+ * import * as Schema from "effect/Schema"
+ * import { TaggedClass } from "./Class.ts"
+ *
+ * class Circle extends TaggedClass<Circle>()("Circle", {
+ *   radius: Schema.Number
+ * }) {}
+ *
+ * Schema.encodeUnknownSync(Circle)({ _tag: "Circle", radius: 5 })
+ * ```
+ */
+export const TaggedClass: <Self = never, Encoded = ExtendedSchemaNoEncoded, Brand = {}>(
+  identifier?: string
+) => <Tag extends string, Fields extends S.Struct.Fields>(
   tag: Tag,
   fieldsOr: Fields | HasFields<Fields>,
-  annotations?: ClassAnnotations<Self>
-) => [Self] extends [never] ? MissingSelfGeneric<"Class">
+  annotations?: ClassAnnotations<Self>,
+  options?: ClassOptions
+) => [Self] extends [never] ? MissingSelfGeneric<"TaggedClass">
   : EnhancedClass<
     Self,
-    S.Struct<{ readonly _tag: S.tag<Tag> } & Fields>,
-    {}
-  > = (identifier) => (tag, fields, annotations) => {
-    const cls = S.TaggedClass as any
-    return class extends cls(identifier)(tag, fields, annotations) {
-      // static readonly include = include(fields)
-      static readonly pick = (...selection: any[]) => pipe(this["fields"], Struct2.pick(selection))
-      static readonly omit = (...selection: any[]) => pipe(this["fields"], Struct2.omit(selection))
+    ClassFieldsSchema<{ readonly _tag: S.tag<Tag> } & Fields, Encoded>,
+    Brand
+  > = (identifier) => (tag, fields, annotations, options) => {
+    const relaxed = options?.strict === false
+    const Base = (S.TaggedClass as any)(identifier)(tag, fields, { ...concurrencyUnbounded, ...annotations })
+    const originalAstDescriptor = Object.getOwnPropertyDescriptor(Base, "ast")!
+    const astCache = new WeakMap<any, SchemaAST.Declaration>()
+    const copyCache = new WeakMap<any, ReturnType<typeof copyOrigin>>()
+
+    return class extends Base {
+      static get copy() {
+        let cached = copyCache.get(this)
+        if (cached === undefined) {
+          cached = copyOrigin(this)
+          copyCache.set(this, cached)
+        }
+        return cached
+      }
+      static get ast(): SchemaAST.Declaration {
+        let cached = astCache.get(this)
+        if (cached !== undefined) return cached
+        const originalAst = originalAstDescriptor.get!.call(this) as SchemaAST.Declaration
+        cached = relaxed ? makeRelaxedDeclaration(originalAst, Base.fields, this) : originalAst
+        astCache.set(this, cached)
+        return cached
+      }
+      static mapFields(f: any, options?: any) {
+        return Base.mapFields(f, options).annotate(concurrencyUnbounded)
+      }
     } as any
   }
 
-export const ExtendedClass: <Self, _SelfFrom>(identifier: string) => <Fields extends S.Struct.Fields>(
+// ---------------------------------------------------------------------------
+// ErrorClass — like Schema.ErrorClass but with relaxed encoding
+// ---------------------------------------------------------------------------
+
+export const ErrorClass: <Self = never, Encoded = ExtendedSchemaNoEncoded, Brand = {}>(
+  identifier: string
+) => <Fields extends S.Struct.Fields>(
   fieldsOr: Fields | HasFields<Fields>,
-  annotations?: ClassAnnotations<Self>
-) => EnhancedClass<
-  Self,
-  S.Struct<Fields>,
-  {}
-> = Class as any
-
-export interface EnhancedTaggedClass<Self, Tag extends string, Fields extends Struct.Fields, SelfFrom>
-  extends
-    EnhancedClass<
-      Self,
-      S.Struct<Fields> & { readonly Encoded: SelfFrom },
-      {}
-    >
-{
-  readonly _tag: Tag
-}
+  annotations?: ClassAnnotations<Self>,
+  options?: ClassOptions
+) => [Self] extends [never] ? MissingSelfGeneric<"ErrorClass">
+  : EnhancedClass<
+    Self,
+    ClassFieldsSchema<Fields, Encoded>,
+    Cause.YieldableError & Brand
+  > = (identifier) => (fields, annotations, options) => {
+    const relaxed = options?.strict === false
+    const Base = (S.Error as any)(identifier)(fields, { ...concurrencyUnbounded, ...annotations })
+    const originalAstDescriptor = Object.getOwnPropertyDescriptor(Base, "ast")!
+    const astCache = new WeakMap<any, SchemaAST.Declaration>()
+    const copyCache = new WeakMap<any, ReturnType<typeof copyOrigin>>()
+
+    return class extends Base {
+      static get copy() {
+        let cached = copyCache.get(this)
+        if (cached === undefined) {
+          cached = copyOrigin(this)
+          copyCache.set(this, cached)
+        }
+        return cached
+      }
+      static get ast(): SchemaAST.Declaration {
+        let cached = astCache.get(this)
+        if (cached !== undefined) return cached
+        const originalAst = originalAstDescriptor.get!.call(this) as SchemaAST.Declaration
+        cached = relaxed ? makeRelaxedDeclaration(originalAst, Base.fields, this) : originalAst
+        astCache.set(this, cached)
+        return cached
+      }
+      static mapFields(f: any, options?: any) {
+        return Base.mapFields(f, options).annotate(concurrencyUnbounded)
+      }
+    } as any
+  }
 
-export const ExtendedTaggedClass: <Self, SelfFrom>(
+// ---------------------------------------------------------------------------
+// TaggedErrorClass — like Schema.TaggedErrorClass but with relaxed encoding
+// ---------------------------------------------------------------------------
+
+export const TaggedErrorClass: <Self = never, Encoded = ExtendedSchemaNoEncoded, Brand = {}>(
   identifier?: string
 ) => <Tag extends string, Fields extends S.Struct.Fields>(
   tag: Tag,
   fieldsOr: Fields | HasFields<Fields>,
-  annotations?: ClassAnnotations<Self>
-) => EnhancedTaggedClass<
+  annotations?: ClassAnnotations<Self>,
+  options?: ClassOptions
+) => [Self] extends [never] ? MissingSelfGeneric<"TaggedErrorClass">
+  : EnhancedClass<
+    Self,
+    ClassFieldsSchema<{ readonly _tag: S.tag<Tag> } & Fields, Encoded>,
+    Cause.YieldableError & Brand
+  > = (identifier) => (tag, fields, annotations, options) => {
+    const relaxed = options?.strict === false
+    const Base = (S.TaggedError as any)(identifier)(tag, fields, { ...concurrencyUnbounded, ...annotations })
+    const originalAstDescriptor = Object.getOwnPropertyDescriptor(Base, "ast")!
+    const astCache = new WeakMap<any, SchemaAST.Declaration>()
+    const copyCache = new WeakMap<any, ReturnType<typeof copyOrigin>>()
+
+    return class extends Base {
+      static get copy() {
+        let cached = copyCache.get(this)
+        if (cached === undefined) {
+          cached = copyOrigin(this)
+          copyCache.set(this, cached)
+        }
+        return cached
+      }
+      static get ast(): SchemaAST.Declaration {
+        let cached = astCache.get(this)
+        if (cached !== undefined) return cached
+        const originalAst = originalAstDescriptor.get!.call(this) as SchemaAST.Declaration
+        cached = relaxed ? makeRelaxedDeclaration(originalAst, Base.fields, this) : originalAst
+        astCache.set(this, cached)
+        return cached
+      }
+      static mapFields(f: any, options?: any) {
+        return Base.mapFields(f, options).annotate(concurrencyUnbounded)
+      }
+    } as any
+  }
+
+export interface Opaque<Self, Encoded, SchemaS extends S.Top, Brand> extends S.Opaque<Self, SchemaS, Brand> {
+  readonly "Encoded": Encoded extends ExtendedSchemaNoEncoded ? SchemaS["Encoded"] : Encoded
+}
+
+export const Opaque: <Self, Encoded = ExtendedSchemaNoEncoded, Brand = {}>() => <S extends S.Top>(
+  schema: S
+) => Opaque<Self, Encoded, S, Brand> & Omit<S, keyof S.Top> = S.Opaque as any
+
+/**
+ * Like {@link Opaque}, but the class **instance type is exactly `Self`** (the supplied
+ * decoded `Type`) instead of the structurally-computed `struct["Type"] & Brand`.
+ *
+ * Stock `Opaque` types the instance as `struct["Type"] & Brand` and only overrides the
+ * schema's `Type`/`Encoded` *members* with `Self`/`Encoded`. So `make`/`copy`/consumers
+ * still resolve the struct's mapped `Type`. With a codegen-supplied pre-expanded literal
+ * `Type` interface, `OpaqueType` lets all of those resolve a single **named** interface
+ * (resolved once per checker) instead of re-deriving the mapped `Type` — cutting
+ * instantiation on `Type`-touching consumers.
+ *
+ * Use with `class X extends OpaqueType<X.Type, X.Encoded>()(struct) {}` where `X.Type`
+ * and `X.Encoded` are generated literal interfaces (see `@effect-app/eslint-codegen-model`,
+ * `static` + `type` mode).
+ *
+ * KNOWN GAP — **no branding**: the instance type is a plain structural `Self`, so opaque
+ * types of identical shape are mutually assignable. (Stock `Opaque` is also structural by
+ * default — `Brand` defaults to `{}` — so this only differs if you passed a non-default
+ * `Brand`.) Re-introducing a nominal brand on top of a supplied `Self` (e.g. branding the
+ * generated `Type` interface) is not yet implemented.
+ *
+ * NOTE: only `Type` (via `Self`) and `Encoded` are supplied statically here; `make`'s input
+ * (`~type.make.in`) and other derived members are still computed from the struct. See
+ * a future `OpaqueShape`-style helper if those also need to be supplied.
+ */
+export interface OpaqueType<Self, Encoded, SchemaS extends S.Top, Brand> extends S.Opaque<Self, SchemaS, Brand> {
+  readonly "Encoded": Encoded extends ExtendedSchemaNoEncoded ? SchemaS["Encoded"] : Encoded
+  new(_: never): Self
+}
+
+export const OpaqueType: <Self, Encoded = ExtendedSchemaNoEncoded, Brand = {}>() => <S extends S.Top>(
+  schema: S
+) => OpaqueType<Self, Encoded, S, Brand> & Omit<S, keyof S.Top> = S.Opaque as any
+
+type OpaqueFacadeConstructorArgs<MakeIn> = {} extends MakeIn ? [props?: MakeIn, options?: S.MakeOptions]
+  : [props: MakeIn, options?: S.MakeOptions]
+
+// Only the codec channels are required. `copy`/`fields`/`mapFields` are NOT
+// required here: transformed schemas (`.pipe(S.encodeKeys/annotate/filter/...)`)
+// don't expose them at the static level, and requiring them would reject those
+// models from facading. When present they still flow through via
+// `OpaqueFacadeStatics`; when absent the facade simply doesn't offer them.
+type OpaqueFacadeInput<DecodingServices, EncodingServices> = S.Top & {
+  readonly DecodingServices: DecodingServices
+  readonly EncodingServices: EncodingServices
+}
+
+type OpaqueClassFacadeInput<DecodingServices, EncodingServices> =
+  & OpaqueFacadeInput<
+    DecodingServices,
+    EncodingServices
+  >
+  & (abstract new(...args: Array<never>) => unknown)
+
+type PrototypeFunction = Function & { prototype: object }
+
+// Class schemas expose a constructor descriptor under this key (was previously
+// identified via a `~effect/Schema/Class` annotation id).
+const ConstructorAnnotationKey = "~constructor"
+
+const getOwnOrInheritedPropertyDescriptor = (value: object, property: PropertyKey): PropertyDescriptor | undefined => {
+  let current: object | null = value
+  while (current !== null) {
+    const descriptor = Object.getOwnPropertyDescriptor(current, property)
+    if (descriptor !== undefined) return descriptor
+    current = Object.getPrototypeOf(current)
+  }
+}
+
+const isClassSchemaConstructor = (value: unknown): value is PrototypeFunction => {
+  if (typeof value !== "function") return false
+  // Transformed schemas (e.g. `Class.pipe(S.encodeKeys(...))`) are also functions with a
+  // Declaration AST that still carries `~constructor`, but they are not constructable classes.
+  // Real Schema.Class constructors expose a static `identifier`.
+  if (typeof (value as { readonly identifier?: unknown }).identifier !== "string") return false
+  const ast = (value as { readonly ast?: unknown }).ast
+  return SchemaAST.isAST(ast)
+    && SchemaAST.isDeclaration(ast)
+    && ast.annotations?.[ConstructorAnnotationKey] !== undefined
+}
+
+const getFacadeClassSchema = (schema: OpaqueFacadeInput<any, any>): PrototypeFunction | undefined => {
+  if (isClassSchemaConstructor(schema)) return schema
+  const target = "to" in schema ? (schema as { readonly to?: unknown }).to : undefined
+  return isClassSchemaConstructor(target) ? target : undefined
+}
+
+const makePublicClassTransformation = (Public: PrototypeFunction) =>
+  new SchemaTransformation.Transformation<any, any, never, never>(
+    SchemaGetter.transform((input) => Reflect.construct(Public, [input], Public)),
+    SchemaGetter.passthrough()
+  )
+
+const makeFacadeClassAst = (
+  schema: OpaqueFacadeInput<any, any>,
+  originalAst: SchemaAST.AST,
+  Public: PrototypeFunction
+): SchemaAST.AST => {
+  if (SchemaAST.isDeclaration(schema.ast)) {
+    const schemaEncoding = schema.ast.encoding ?? []
+    if (schemaEncoding.length > 0) {
+      return new SchemaAST.Declaration(
+        schema.ast.typeParameters,
+        schema.ast.run,
+        schema.ast.annotations,
+        schema.ast.checks,
+        [new SchemaAST.Link(schemaEncoding[0]!.to, makePublicClassTransformation(Public)), ...schemaEncoding.slice(1)],
+        schema.ast.context,
+        schema.ast.encodingChecks
+      )
+    }
+  }
+
+  return schema.rebuild(originalAst).ast
+}
+
+// Carry the schema's own statics, dropping the generic `S.Top` machinery and
+// `prototype`. EXCEPT `to`: models compose each other via `X.to.fields` /
+// `X.to.copy` at definition time, so it must survive on the facade.
+type OpaqueFacadeStatics<SchemaS extends S.Top> = Omit<SchemaS, Exclude<keyof S.Top, "to"> | "prototype">
+
+/**
+ * Like {@link OpaqueType}, but ALSO supplies a static **make-input** shape, so
+ * `make`/`copy` resolve a named `MakeIn` interface instead of re-deriving the struct's
+ * mapped `~type.make.in`. Use with codegen-supplied `X.Type` / `X.Encoded` / `X.Make`:
+ *
+ * ```ts
+ * class X extends OpaqueShape<X.Type, X.Encoded, X.Make>()(struct) {}
+ * ```
+ *
+ * `decode`/`encode` already use the supplied `Type`/`Encoded` (they read the schema's
+ * `Type`/`Encoded` members, which are `Self`/`Encoded` here) — no separate override needed.
+ *
+ * NOTE — measured gain is modest (~5%): the struct passed to the wrapper is still
+ * constructed in full (definition cost dominates); the static shapes only cheapen
+ * consumer-side reads of `Type`/`Encoded`/`MakeIn`. Same `no-branding` gap as
+ * {@link OpaqueType}.
+ */
+export interface OpaqueShape<Self, Encoded, MakeIn, SchemaS extends S.Top, Brand>
+  extends S.Opaque<Self, SchemaS, Brand>
+{
+  readonly "Encoded": Encoded
+  readonly "~type.make.in": MakeIn
+  new(_: never): Self
+}
+
+export const OpaqueShape: <Self, Encoded, MakeIn, Brand = {}>() => <S extends S.Top>(
+  schema: S
+) => OpaqueShape<Self, Encoded, MakeIn, S, Brand> & Omit<S, keyof S.Top> = S.Opaque as any
+
+/**
+ * Shallow public view for generated model facades.
+ *
+ * The runtime value can still be the full private schema class, but emitted
+ * declarations expose only named `Type` / `Encoded` / `Make` interfaces and a
+ * small static surface. This keeps downstream project references from pulling
+ * the private struct field map back through `typeof Model`.
+ */
+export interface OpaqueFacade<
   Self,
-  Tag,
-  { readonly _tag: S.tag<Tag> } & Fields,
-  SelfFrom
-> = TaggedClass as any
+  Encoded,
+  MakeIn,
+  DecodingServices = never,
+  EncodingServices = DecodingServices,
+  Brand = {}
+> extends
+  S.Bottom<
+    Self,
+    Encoded,
+    DecodingServices,
+    EncodingServices,
+    SchemaAST.AST,
+    S.Codec<Self, Encoded, DecodingServices, EncodingServices>,
+    MakeIn,
+    Self,
+    readonly [],
+    MakeIn
+  >
+{
+  new(_: never): Brand
+  readonly copy: ReturnType<typeof copyOrigin<new(_: MakeIn) => Self>>
+  // NOTE: no `identifier` here — `S.Opaque` (and requests) build on `S.Bottom`, not `S.Class`,
+  // so they have no `identifier`. It lives only on the class facades below.
+  // NOTE: `fields` / `mapFields` are intentionally NOT redeclared here. They are
+  // carried (precise) from the underlying schema via `OpaqueFacadeStatics`. A wide
+  // `mapFields(f: (fields: S.Struct.Fields) => To)` override would win overload
+  // resolution and erase field precision in `Q.project(X.mapFields(...))`.
+}
+
+export interface OpaqueClassFacade<
+  Self,
+  Encoded,
+  MakeIn,
+  DecodingServices = never,
+  EncodingServices = DecodingServices,
+  Brand = {}
+> extends
+  S.Bottom<
+    Self,
+    Encoded,
+    DecodingServices,
+    EncodingServices,
+    SchemaAST.AST,
+    S.Codec<Self, Encoded, DecodingServices, EncodingServices>,
+    MakeIn,
+    Self,
+    readonly [],
+    MakeIn
+  >
+{
+  new(...args: OpaqueFacadeConstructorArgs<MakeIn>): Brand
+  readonly copy: ReturnType<typeof copyOrigin<new(_: MakeIn) => Self>>
+  readonly identifier: string
+}
+
+export function OpaqueFacade<
+  Self,
+  Encoded,
+  MakeIn,
+  DecodingServices = never,
+  EncodingServices = DecodingServices,
+  Brand = {}
+>() {
+  function facade<SchemaS extends OpaqueClassFacadeInput<DecodingServices, EncodingServices>>(
+    schema: SchemaS
+  ):
+    & OpaqueClassFacade<Self, Encoded, MakeIn, DecodingServices, EncodingServices, Brand>
+    & OpaqueFacadeStatics<SchemaS>
+  function facade<SchemaS extends OpaqueFacadeInput<DecodingServices, EncodingServices>>(
+    schema: SchemaS
+  ):
+    & OpaqueFacade<Self, Encoded, MakeIn, DecodingServices, EncodingServices, Brand>
+    & OpaqueFacadeStatics<SchemaS>
+  function facade(schema: OpaqueFacadeInput<DecodingServices, EncodingServices>) {
+    const Base = getFacadeClassSchema(schema)
+    if (Base !== undefined) {
+      const astCache = new WeakMap<object, SchemaAST.AST>()
+      const originalAstDescriptor = getOwnOrInheritedPropertyDescriptor(Base, "ast")
+
+      return class extends (Base as any) {
+        static get ast(): SchemaAST.AST {
+          let cached = astCache.get(this)
+          if (cached !== undefined) return cached
+
+          const originalAst = originalAstDescriptor?.get?.call(this) as SchemaAST.AST
+          cached = makeFacadeClassAst(schema, originalAst, this)
+          astCache.set(this, cached)
+          return cached
+        }
+      }
+    }
+
+    class Facade {}
+    return Object.setPrototypeOf(Facade, schema)
+  }
+
+  return facade
+}
+
+/**
+ * Like class-schema {@link OpaqueFacade}, but for error models (`TaggedErrorClass` /
+ * `ErrorClass`). The decoded instance type carries `Cause.YieldableError`, so
+ * `yield* new MyError(...)`, `Effect.fail(myError)`, and `instanceof` all keep
+ * working through the facade — the runtime `_X` is the real error class (the
+ * facade `X extends ...(_X)` inherits its prototype), and the type reflects it.
+ * Nothing is lost vs the underlying error class.
+ */
+export interface OpaqueErrorFacadeClass<
+  Self,
+  Encoded,
+  MakeIn,
+  DecodingServices = never,
+  EncodingServices = DecodingServices,
+  Brand = {}
+> extends
+  S.Bottom<
+    Self,
+    Encoded,
+    DecodingServices,
+    EncodingServices,
+    SchemaAST.AST,
+    S.Codec<Self, Encoded, DecodingServices, EncodingServices>,
+    MakeIn,
+    Self,
+    readonly [],
+    MakeIn
+  >
+{
+  // YieldableError (not Self) on the constructed instance — like class-schema OpaqueFacade's
+  // `new(): Brand`, the data type comes from the declaration-merged `interface X`,
+  // so `Self` must NOT appear here (would recurse). Merging `X & YieldableError`
+  // makes `yield* new X()` / `Effect.fail` / `instanceof` work without losing data.
+  new(...args: OpaqueFacadeConstructorArgs<MakeIn>): Cause.YieldableError & Brand
+  readonly copy: ReturnType<typeof copyOrigin<new(_: MakeIn) => Self>>
+  readonly identifier: string
+}
+
+export function OpaqueErrorFacadeClass<
+  Self,
+  Encoded,
+  MakeIn,
+  DecodingServices = never,
+  EncodingServices = DecodingServices,
+  Brand = {}
+>() {
+  return <SchemaS extends OpaqueClassFacadeInput<DecodingServices, EncodingServices>>(
+    schema: SchemaS
+  ):
+    & OpaqueErrorFacadeClass<Self, Encoded, MakeIn, DecodingServices, EncodingServices, Brand>
+    & OpaqueFacadeStatics<SchemaS> =>
+  {
+    type FacadeSchema =
+      & OpaqueErrorFacadeClass<Self, Encoded, MakeIn, DecodingServices, EncodingServices, Brand>
+      & OpaqueFacadeStatics<SchemaS>
+
+    if (isClassSchemaConstructor(schema)) {
+      return schema as SchemaS & FacadeSchema
+    }
+
+    throw new TypeError("OpaqueErrorFacadeClass requires a class schema")
+  }
+}
+
+/**
+ * Workflow-compatible struct facade.
+ *
+ * A top-level `const X = S.Struct(...)` / `S.TaggedStruct(...)` schema model whose `.d.ts`
+ * is produced by the schema-aware declaration emitter is retyped from the giant inline
+ * `S.Struct<{ ...fields... }>` to this facade.
+ *
+ * Unlike {@link OpaqueFacade}, `StructFacade` **extends effect-app's `Struct<Fields>`**, so the
+ * value is still a real (effect-app) struct schema: it satisfies `Workflow.AnyStructSchema` and
+ * the `Struct<Fields & Context>` reconstruction the workflow machinery performs, and `Union` /
+ * `.fields.x` keep working. It MUST be effect-app's `Struct` (not effect core's) — scanner
+ * models are effect-app `S.Struct`, so a facade built on `effect/Schema`'s `Struct` is not
+ * assignable where an effect-app struct is expected. At the same time the type-level members
+ * (`Type` / `Encoded` / make-input / services) are pinned to the named interfaces the emitter
+ * generates in `namespace X`, so consumers reference those by name instead of re-deriving them
+ * from `Fields` on every use. `Fields` is the model's own generated `X.Fields` interface — a
+ * single materialization of the (expensive) field shape that every reference site points at.
+ */
+export type StructFacade<
+  Self,
+  Encoded,
+  MakeIn,
+  DecodingServices,
+  EncodingServices,
+  Fields extends S.Struct.Fields
+> =
+  & Omit<EffectAppStruct<Fields>, "Type" | "Encoded" | "~type.make.in" | "DecodingServices" | "EncodingServices">
+  & {
+    readonly "Type": Self
+    readonly "Encoded": Encoded
+    readonly "~type.make.in": MakeIn
+    readonly "DecodingServices": DecodingServices
+    readonly "EncodingServices": EncodingServices
+  }