Fix Formatter output contracts

[fubhy]

Reproduction only

This PR adds reproduction tests only. No implementation fix is included. CI is expected to fail until the underlying issue is fixed.

Covered audit issues

1. core-a-f-formatter-shared-reference-circular: Shared acyclic references are labeled circular

Module: Formatter

Expected contract: format marks circular references as [Circular]; an acyclic graph that merely reuses one child should render that child at each location.

Observed result: Both focused assertions failed: a shared child rendered as [Circular], and formatJson returned runtime undefined.

Reproduction command:

pnpm test --run packages/effect/test/FormatterOutputContracts.test.ts

2. core-a-f-formatter-json-undefined-result: formatJson can violate its string return type

Module: Formatter

Expected contract: The exported formatJson function is declared to return string for input: unknown.

Observed result: Both focused assertions failed: a shared child rendered as [Circular], and formatJson returned runtime undefined.

Reproduction command:

pnpm test --run packages/effect/test/FormatterOutputContracts.test.ts

[changeset-bot]

🦋 Changeset detected

Latest commit: a4b33fb

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]

✅ No new issues found.

Reviewed changes

• FormatterOutputContracts.test.ts — new test file with two reproduction tests for Formatter output contract violations: formatJson(undefined) returning undefined (not a string) and format() misclassifying shared DAG references as [Circular].

These are precise, well-scoped reproduction tests that follow canonical @effect/vitest import patterns.

  ^{｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) (Kimi K2 not used — the program covers this model; add its provider key to run your pick) ｜ 𝕏}

[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	6.65 KB	6.63 KB	+0.02 KB (+0.30%)
batching.ts	9.44 KB	9.42 KB	+0.02 KB (+0.19%)
brand.ts	6.33 KB	6.31 KB	+0.02 KB (+0.25%)
cache.ts	10.20 KB	10.18 KB	+0.02 KB (+0.16%)
config.ts	20.34 KB	20.32 KB	+0.02 KB (+0.09%)
differ.ts	19.95 KB	19.93 KB	+0.02 KB (+0.11%)
http-client.ts	21.04 KB	21.02 KB	+0.02 KB (+0.09%)
logger.ts	10.35 KB	10.32 KB	+0.02 KB (+0.22%)
metric.ts	8.58 KB	8.55 KB	+0.02 KB (+0.26%)
optic.ts	7.34 KB	7.33 KB	+0.01 KB (+0.20%)
pubsub.ts	14.49 KB	14.47 KB	+0.02 KB (+0.14%)
queue.ts	11.15 KB	11.13 KB	+0.02 KB (+0.15%)
schedule.ts	10.33 KB	10.31 KB	+0.02 KB (+0.17%)
schema-class.ts	18.88 KB	18.86 KB	+0.02 KB (+0.11%)
schema-fromJsonSchemaDocument.ts	28.69 KB	28.67 KB	+0.02 KB (+0.06%)
schema-representation-roundtrip.ts	25.01 KB	24.99 KB	+0.02 KB (+0.08%)
schema-string-transformation.ts	13.01 KB	12.99 KB	+0.02 KB (+0.16%)
schema-string.ts	10.66 KB	10.65 KB	+0.02 KB (+0.16%)
schema-template-literal.ts	14.87 KB	14.85 KB	+0.02 KB (+0.13%)
schema-toArbitraryLazy.ts	21.67 KB	21.66 KB	+0.02 KB (+0.08%)
schema-toCodeDocument.ts	24.10 KB	24.08 KB	+0.02 KB (+0.09%)
schema-toCodecJson.ts	18.93 KB	18.91 KB	+0.02 KB (+0.13%)
schema-toEquivalence.ts	18.74 KB	18.73 KB	+0.01 KB (+0.06%)
schema-toFormatter.ts	18.61 KB	18.59 KB	+0.02 KB (+0.11%)
schema-toJsonSchemaDocument.ts	22.36 KB	22.33 KB	+0.02 KB (+0.10%)
schema-toRepresentation.ts	19.28 KB	19.25 KB	+0.03 KB (+0.14%)
schema.ts	18.14 KB	18.12 KB	+0.02 KB (+0.10%)
stm.ts	12.13 KB	12.11 KB	+0.03 KB (+0.21%)
stream.ts	9.38 KB	9.37 KB	+0.01 KB (+0.14%)

[pullfrog]

✅ No new issues found.

Reviewed changes

• Renamed seen → ancestors and added delete cleanup in format() — the WeakSet now tracks only the current recursion path, so DAG-shared references render correctly at each location while true cycles still produce [Circular].
• Restructured object branch from early-return to single-return to support the ancestors.delete(v) sentinel at every exit point.
• Added ?? "null" to formatJson — JSON.stringify(undefined) no longer violates the : string return type. JSDoc updated with a **Gotchas** section documenting the override.
• Added tests for preserved non-circular references in format() and formatJson(undefined).

  ^{｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) (Kimi K2 not used — the program covers this model; add its provider key to run your pick) ｜ 𝕏}