Shared schemas need a transition period

A shared schema25 change needs time for consumers to move. Discover old uses and prevent new uses before removing the obsolete interface25.

many refactorings require you to run both the original and new versions of the schema in parallel during a transition period that is long enough to allow any applications accessing that portion of the schema time to be redeployed.

Source: Q1933; B1433, B1533.

Failure it prevents

An independently deployed consumer breaks, or a migration never converges because new old-style uses keep appearing.

Our Effect 4.0.0 reading

Schema decoding can express supported representations. Database migrations, consumer rollout, usage evidence, and static backsliding checks remain separate responsibilities.

Source: packages/effect/src/Schema.ts.

How to check

Test old and new consumers during the transition. Prove old usage is gone before contraction. This check is our proposal. The books do not prescribe it.

Continue with Old events must still decode9, Recovery needs model tests10.

Connect this to the existing rat-stack guidance23.

Use the durability skill for the full review. Return to the durability index34.

Sources

  1. Ambler, Scott W.; Sadalage, Pramod J. Refactoring Databases: Evolutionary Database Design. Addison-Wesley, 2006.. Addison-Wesley. §3.11 What You Have Learned (transition period); Chapter 4 Deploying into Production. Accessed 2026-10-23.
  2. Winters, Titus; Manshreck, Tom; Wright, Hyrum, editors. Software Engineering at Google: Lessons Learned from Programming Over Time. O’Reilly, 2020.. O’Reilly. Chapter 15 Deprecation: Deprecation Tooling and Preventing Backsliding; CI Is Alerting (hermetic and flaky tests). Accessed 2026-10-23.
  3. Effect contributors. Effect 4.0.0. Schema.ts. Effect-TS. Pinned source for our Effect mapping, not a claim from the book. Accessed 2026-10-23.

Last changed 2026-10-23 in 58dc623. Source on GitHub. Change log.

Linked from

  1. Agent guide. An Effect stack so pure (aspirational) Kit Langton will blush.

    Shared schemas need a transition period — Keep old and new representations usable while consumers migrate.

  2. Change log. What changed in the files served here, newest first.

    Shared schemas need a transition period — new page: docs(lore): land the durability wiki pages and bibliography

  3. Durability starts with a recovery record. A reading order for storage, replay, worker ownership, overload, and recovery tests.

    Shared schemas need a transition period: Keep old and new representations usable while consumers migrate.¶

  4. Full agent guide. An Effect stack so pure (aspirational) Kit Langton will blush.
  5. Old events must still decode. Retained data needs compatibility rules before recovery depends on it.

    Continue with Shared schemas need a transition period, Replay needs stable inputs.¶

  6. Rat Stack lore | rat-stack. Short, source-grounded notes on the ideas and decisions behind rat-stack.

    Shared schemas need a transition period — Keep old and new representations usable while consumers migrate.

  7. Source change history (log.md). The generated change log as Markdown.

    Shared schemas need a transition period — new page: docs(lore): land the durability wiki pages and bibliography