Document Schema.Date encoded-contract change in the v4 migration guide

[schickling-assistant]

Schema.Date changed its encoded contract between Effect 3 and Effect 4, but the migration guide only documents the DateFromSelf -> Date rename. Existing Effect 3 code using Schema.Date still type-checks after upgrading while changing from an ISO-string transform to a Date instance-only schema.

Reproduction

https://github.com/schickling-repros/2026-07-effect-v4-schema-date-migration

pnpm install
pnpm repro

The repro runs the same ISO value against pinned Effect 3 and Effect 4 versions.

Expected documentation

The migration guide should document what existing Effect 3 Schema.Date users must use to preserve their encoded contract:

Schema.DateFromString.check(Schema.isDateValid())

Schema.DateFromString alone preserves the string-to-Date representation but, unlike Effect 3's Schema.Date, permits invalid dates.

Actual behavior

• effect@3.19.4: Schema.decodeUnknownSync(Schema.Date)(isoString) succeeds.
• effect@4.0.0-beta.98: the same expression fails with Expected Date.
• Effect 4's migration guide documents DateFromSelf -> Date, but does not mention the old Date identifier's semantic reassignment or its replacement.

This is a migration-guide gap rather than a runtime defect. It is particularly easy to miss at JSON, RPC, and persisted-data boundaries because the unchanged identifier remains valid.

Posted on behalf of @schickling

field	value
agent_name	☁️ co3-billow
agent_session_id	7f3b9666-034f-4e9e-890b-491957f7f75b
agent_tool	Codex CLI
agent_tool_version	0.144.1
agent_runtime	Codex CLI 0.144.1
agent_model	unknown
runtime_profile	/nix/store/1n76sy6i9y3ki3k4w04jksqvygw67sj0-coding-agent-runtime-profile/share/coding-agents/profile.json
skills_manifest	/nix/store/jn6r0r7r59x3a525jch4pwzwykszqp60-agent-skills-corpus/share/agent-skills/manifest.json
worktree	2026-07-effect-v4-schema-date-migration/main
machine	dev3
tooling_profile	dotfiles@4eac376