Include plain variant structs in the default union

[fubhy]

Summary

A Union built from documented plain Struct members creates an empty default union that accepts neither member shape.

Important

This PR starts with focused failing reproduction tests. Add the implementation fix to this same branch; CI is expected to fail until that fix is included.

Default union excludes plain variant structs

Module: schema/VariantSchema
Audit ID: unstable-ai-cli-variant-schema-default-union-empty
Severity / confidence: high / high

What happens

A Union built from documented plain Struct members creates an empty default union that accepts neither member shape.

Why it happens

Default construction filters members with Schema.isSchema instead of extracting their configured default variants, and Struct values are not schemas.

Expected behavior

Union accepts Struct members and creates a default union over each member's default schema.

Relevant implementation

These links and excerpts are pinned to audit base c9b56ab507f224426ee8388dc450da447ec4715f.

• packages/effect/src/unstable/schema/VariantSchema.ts:293-305
• packages/effect/src/unstable/schema/VariantSchema.ts:471-473
• packages/effect/src/unstable/schema/VariantSchema.ts:585-595

View problematic code at packages/effect/src/unstable/schema/VariantSchema.ts:293-305

/**
 * Union schema over the default schemas of a list of variant schema structs.
 *
 * @category models
 * @since 4.0.0
 */
export interface Union<Members extends ReadonlyArray<Struct<any>>> extends
  Schema.Union<
    {
      readonly [K in keyof Members]: [Members[K]] extends [Schema.Top] ? Members[K] : never
    }
  >
{}

View exact lines on GitHub

View problematic code at packages/effect/src/unstable/schema/VariantSchema.ts:471-473

  function UnionVariants(members: ReadonlyArray<Struct<any>>) {
    return Union(members, options.variants)
  }

View exact lines on GitHub

View problematic code at packages/effect/src/unstable/schema/VariantSchema.ts:585-595

const Union = <Members extends ReadonlyArray<Struct<any>>, Variants extends ReadonlyArray<string>>(
  members: Members,
  variants: Variants
) => {
  const VariantUnion = Schema.Union(members.filter((member) => Schema.isSchema(member))) as any
  for (const variant of variants) {
    Object.defineProperty(VariantUnion, variant, {
      value: Schema.Union(members.map((member) => extract(member, variant)))
    })
  }
  return VariantUnion

View exact lines on GitHub

Reproduction

pnpm test --run packages/effect/test/unstable/schema/VariantSchemaDefaultUnionAudit.test.ts

Observed failure: FAIL: the default union contained zero members.

Implementation handoff

The initial reproduction tests on this branch are the regression specification for the implementation fix that should follow in this PR.

1. Start with the pinned implementation excerpts and the Why it happens analysis above.
2. Change the implementation so it satisfies the stated Expected behavior; do not weaken or remove the reproduction assertions.
3. Run the focused reproduction command(s) and confirm the observed failures become passing tests:

pnpm test --run packages/effect/test/unstable/schema/VariantSchemaDefaultUnionAudit.test.ts

4. Run the affected package's existing tests, then the repository lint and type checks before requesting review.

Audit provenance

• Audit base: c9b56ab507f224426ee8388dc450da447ec4715f
• Reproduction base: c9b56ab507f224426ee8388dc450da447ec4715f
• Findings: unstable-ai-cli-variant-schema-default-union-empty
• Initial patch: focused reproduction tests; implementation fix pending

Closes EFF-401

[changeset-bot]

🦋 Changeset detected

Latest commit: 9041ee0

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 30 packages

Name	Type
effect	Patch
@effect/opentelemetry	Patch
@effect/platform-browser	Patch
@effect/platform-bun	Patch
@effect/platform-deno	Patch
@effect/platform-node-shared	Patch
@effect/platform-node	Patch
@effect/vitest	Patch
@effect/ai-anthropic	Patch
@effect/ai-openai-compat	Patch
@effect/ai-openai	Patch
@effect/ai-openrouter	Patch
@effect/atom-react	Patch
@effect/atom-solid	Patch
@effect/atom-vue	Patch
@effect/sql-clickhouse	Patch
@effect/sql-d1	Patch
@effect/sql-libsql	Patch
@effect/sql-mssql	Patch
@effect/sql-mysql2	Patch
@effect/sql-pg	Patch
@effect/sql-pglite	Patch
@effect/sql-sqlite-bun	Patch
@effect/sql-sqlite-do	Patch
@effect/sql-sqlite-node	Patch
@effect/sql-sqlite-react-native	Patch
@effect/sql-sqlite-wasm	Patch
@effect/docgen	Patch
@effect/doctest	Patch
@effect/openapi-generator	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pullfrog]

Important

This PR currently adds only the failing regression test; the VariantSchema.ts implementation required to make it pass is still missing.

Reviewed changes

• Added a new test in packages/effect/test/unstable/schema/VariantSchema.test.ts asserting that plain VariantSchema.Struct members are included in the default union produced by VariantSchema.Union.

⚠️ Implementation needed to satisfy the regression test

The new test fails because packages/effect/src/unstable/schema/VariantSchema.ts:585-595 builds the default union as Schema.Union(members.filter(Schema.isSchema)). Plain variant structs are not schemas, so they are dropped and the default union ends up with zero members. The per-variant branches already handle plain structs correctly via extract(member, variant).

The runtime fix should map every member to its default-variant schema, keeping existing schema members as-is and extracting plain structs:

const VariantUnion = Schema.Union(members.map((member) =>
  Schema.isSchema(member) ? member : extract(member, options.defaultVariant)
))

⚠️ Union<Members> interface still excludes plain structs at the type level

The Union<Members> interface at packages/effect/src/unstable/schema/VariantSchema.ts:299-305 maps each member to [Members[K]] extends [Schema.Top] ? Members[K] : never. For plain Struct members this resolves to never, so the default union type would still be empty even after the runtime fix. It should map each member to its default-extracted schema type instead (e.g., Extract<Default, Members[K], true>) so the type and runtime agree.

ℹ️ Nitpicks

• The test only checks union.members.length. Consider adding decode/encode assertions that prove the default union actually accepts both { value: string } and { value: number } shapes and rejects incompatible values.

  ^{｜ ⚠️ this action is pinned to a commit SHA, which freezes the cleanup step — switch to @v0 or keep the SHA fresh with Dependabot ｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

.

[pullfrog]

✅ No new issues found.

Reviewed changes

Reviewed the incremental delta since the prior pullfrog review (90f106b), covering commit 9041ee0 (Fix VariantSchema default unions).

• Implemented the default-union fix in VariantSchema.ts: Union now maps each member to its default-variant schema, keeping schema members (e.g., classes) as-is and extracting plain Struct members via extract(member, defaultVariant, { isDefault: true }).
• Aligned the public Union<Members, Default> type: the interface now maps each member to Extract<Default, Members[K], true> so the type and runtime agree, and make propagates its configured default variant into the return type.
• Strengthened the regression test: added Schema.decodeUnknownSync(union) assertions that prove the default union accepts both { value: string } and { value: number } shapes.
• Added a changeset describing the patch.

The prior Pullfrog thread asking for runtime decode assertions is addressed by the new test; no other prior feedback remains open.

  ^{｜ ⚠️ this action is pinned to a commit SHA, which freezes the cleanup step — switch to @v0 or keep the SHA fresh with Dependabot ｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

[github-actions]

Bundle Size Analysis

Generated from PR build output; treat the content below as untrusted.

File Name	Current Size	Previous Size	Difference
basic.ts	7.06 KB	7.06 KB	0.00 KB (0.00%)
batching.ts	9.86 KB	9.86 KB	0.00 KB (0.00%)
brand.ts	6.34 KB	6.34 KB	0.00 KB (0.00%)
cache.ts	10.62 KB	10.62 KB	0.00 KB (0.00%)
config.ts	20.60 KB	20.60 KB	0.00 KB (0.00%)
differ.ts	20.20 KB	20.20 KB	0.00 KB (0.00%)
http-client.ts	21.49 KB	21.49 KB	0.00 KB (0.00%)
logger.ts	10.76 KB	10.76 KB	0.00 KB (0.00%)
metric.ts	8.98 KB	8.98 KB	0.00 KB (0.00%)
optic.ts	7.18 KB	7.18 KB	0.00 KB (0.00%)
pubsub.ts	14.90 KB	14.90 KB	0.00 KB (0.00%)
queue.ts	11.58 KB	11.58 KB	0.00 KB (0.00%)
schedule.ts	10.74 KB	10.74 KB	0.00 KB (0.00%)
schema-class.ts	19.14 KB	19.14 KB	0.00 KB (0.00%)
schema-fromJsonSchemaDocument.ts	28.96 KB	28.96 KB	0.00 KB (0.00%)
schema-representation-roundtrip.ts	25.29 KB	25.29 KB	0.00 KB (0.00%)
schema-string-transformation.ts	13.30 KB	13.30 KB	0.00 KB (0.00%)
schema-string.ts	10.94 KB	10.94 KB	0.00 KB (0.00%)
schema-template-literal.ts	15.17 KB	15.17 KB	0.00 KB (0.00%)
schema-toArbitraryLazy.ts	21.94 KB	21.94 KB	0.00 KB (0.00%)
schema-toCodeDocument.ts	24.34 KB	24.34 KB	0.00 KB (0.00%)
schema-toCodecJson.ts	19.18 KB	19.18 KB	0.00 KB (0.00%)
schema-toEquivalence.ts	19.01 KB	19.01 KB	0.00 KB (0.00%)
schema-toFormatter.ts	18.87 KB	18.87 KB	0.00 KB (0.00%)
schema-toJsonSchemaDocument.ts	22.60 KB	22.60 KB	0.00 KB (0.00%)
schema-toRepresentation.ts	19.52 KB	19.52 KB	0.00 KB (0.00%)
schema.ts	18.41 KB	18.41 KB	0.00 KB (0.00%)
stm.ts	12.54 KB	12.54 KB	0.00 KB (0.00%)
stream.ts	9.80 KB	9.80 KB	0.00 KB (0.00%)