Roadmap: ReqLLM 2.0 intentional breaking changes

Purpose

This is the master tracking issue for ReqLLM 2.0: a controlled major release containing the roadmap changes that intentionally break existing callers.

V2 is not a rewrite and is not a port of reqllm_next. It should switch defaults and remove legacy contracts only after ReqLLM 1.x has shipped working migration bridges.

• V1 master tracker: #829
• Roadmap index: ROADMAP.md (pending merge)
• V2 breaking-change roadmap: ROADMAP_V2.md (pending merge)

Acknowledged compatibility breaks

ReqLLM 2.0 is expected to break callers in these bounded areas:

1. deprecated bang streaming functions are removed;
2. canonical tagged events become the default raw streaming contract;
3. the legacy monolithic provider behavior is replaced by the versioned extension contract;
4. legacy flat provider options are rejected in favor of namespaced options; and
5. strict final structured-output validation becomes the default.

Every break requires a released V1 bridge and a mechanical migration path.

Entry gates

• Each breaking item has shipped as an additive bridge for at least two V1 minor releases.
• Public compatibility scenarios cover both legacy and replacement behavior.
• Usage/adoption data is available for deprecated APIs and option forms where practical.
• Third-party provider authors have been surveyed before the provider extension contract is frozen.
• A migration guide and static Mix-task checks cover mechanical changes.
• The V2 release candidate passes the same model/surface/scenario evidence as the latest V1 release.
• The Elixir/OTP support window is chosen from ecosystem needs rather than inherited from the prototype.

Breaking workstreams

1. Remove deprecated bang streaming APIs

• Complete the final V1 warning and documentation cycle for stream_text! and stream_object!.
• Verify all package examples and first-party integrations use stream_text / stream_object and StreamResponse helpers.
• Remove the deprecated bang functions in V2.
• Add migration checks and clear upgrade errors for remaining call sites.

2. Make canonical tagged events the default raw stream

• Ship and stabilize StreamResponse.events plus text/item/event projections in V1.
• Prove event materialization parity across non-streaming, streaming, replay, cancellation, and terminal errors.
• Define the final V2 event type and lifecycle contract.
• Change the primary raw stream/default .stream semantics to canonical events.
• Retain an explicit legacy StreamChunk projection only if its maintenance cost remains small.
• Publish streaming migration examples for text, reasoning, tool calls, usage, errors, and cancellation.

3. Replace the legacy provider extension behavior

• Publish the new versioned provider extension contract experimentally in V1.
• Adapt existing provider modules through the new planning/protocol/wire/transport/response seams.
• Survey third-party provider authors and inventory external callback usage.
• Freeze the V2 extension contract and conformance suite.
• Publish a provider-author migration guide and representative migrated provider.
• Remove the legacy monolithic callback contract only after the adapter window is complete.

4. Require namespaced provider options

• Accept, normalize, and document provider-keyed options in V1.
• Warn on legacy flat options, foreign keys, and collisions during V1.
• Provide a static migration check for common legacy option forms.
• Reject the legacy flat shape in V2 with typed, actionable errors.
• Verify provider-native options cannot leak onto a foreign execution surface.

5. Make strict final structured-output validation the default

• Ship explicit strict, warning, and permissive/coercion policies in V1.
• Surface V1 validation failures as structured warnings without silently claiming validity.
• Prove final validation for text/object/array/choice/JSON outputs and tool inputs.
• Make strict final validation the V2 default.
• Keep permissive/coercion and repair behavior explicit, bounded, visible, and opt-in.
• Document behavior changes for callers currently relying on invalid or coerced output.

V2 migration and release work

• Publish a single V1-to-V2 migration guide with before/after examples.
• Add a mix migration audit for removed functions, legacy provider options, provider behaviors, and stream assumptions.
• Publish a versioned deprecation/removal ledger.
• Run release-candidate testing against first-class and representative best-effort providers.
• Verify documentation, examples, Livebooks, Jido integrations, and provider extension examples.
• Publish an explicit rollback/support policy for the final V1 release line.

Explicit non-goals

• No agent loops, approvals, memory, checkpointing, delegation, or durable scheduling in ReqLLM; those remain Jido concerns.
• No wholesale port of the reqllm_next module tree or development workflow.
• No removal of tuple or plain-map model inputs solely for API purity.
• No change from Response.model to %LLMDB.Model{} when an additive resolved model/profile field is sufficient.
• No removal of generate_object or stream_object; they remain convenience wrappers.
• No Elixir minimum-version increase solely to match the prototype.
• No Harness/coding-agent runtime below ReqLLM; see #723.

Release gates

• All accepted breaking scope is listed in this issue; late untracked cleanup is rejected.
• Every break links to its V1 bridge release and migration documentation.
• V2 conformance, quality, docs, package dry-run, and GitHub CI checks are green.
• Jido consumes ReqLLM through the stable one-call extension boundary without provider-specific branching.
• Final release notes distinguish breaking changes, unchanged APIs, and explicit non-goals.

Tracking rules

• Replace checklist items with linked child issues once scoped.
• Keep each breaking change in its own implementation issue and pull request.
• Record scope additions/removals and compatibility decisions as comments.
• A breaking item may be removed from V2 if its V1 additive surface proves sufficient.
• Do not use the major version as permission for unrelated API churn.

Start with ROADMAP_V2.md and the V1 master tracker in #829, then review the five breaking workstreams and their entry gates. This is a master planning issue rather than a self-contained implementation task; done means each accepted change has a scoped child issue, a V1 bridge, migration documentation, and its required release evidence.