Upgrade Path

This guide is the canonical support-matrix and lifecycle reference for Threadline's named adoption lanes. guides/integration-contracts.md defines the reusable seams, and guides/operator-surface.md covers mount, auth, and screens. This guide answers a different set of questions: which lane you are on, what compatibility is actually supported, and how surface-only changes move between Threadline minors.

Who this guide is for

Use this guide if you are:

• deciding whether you are running capture-only, phoenix-surface, or sigra-reference
• upgrading Threadline across minors and need to know what the operator-surface contract includes
• checking whether a host path is supported, reference, or unclaimed

If you only need router wiring, auth posture, or screen references, stay in guides/operator-surface.md.

How to tell which lane you are on

You are on the capture-only lane when your host application does not depend on Threadline's optional Phoenix surface dependencies and does not mount threadline_operator_surface/2. The proof point for this lane is mix verify.compile_no_optional.

You are on the phoenix-surface lane when your host application adds the optional Phoenix surface dependencies and mounts threadline_operator_surface/2 in a Phoenix router using the in-tree operator surface. The proof for this lane comes from the root package: mix.exs, mix.lock, root CI, and the root doc-contract tests.

You are on the sigra-reference lane when your Phoenix host already uses Sigra and composes Threadline.Integrations.Sigra into Threadline.Plug using the current example app and guide path. The proof for this lane comes from examples/threadline_phoenix/, its lockfile and README, guides/integrations/sigra.md, and mix verify.example. This is a narrower claim than generic Sigra compatibility.

Threadline uses three support words intentionally:

• supported means the lane is documented and backed by current repo proof.
• reference means the repo maintains a first-party composition path inside a narrower host story.
• unclaimed means the combination may be plausible locally, but this repo does not currently prove it.

That distinction matters more than dependency rows alone:

• capture-only is supported with no optional Phoenix dependencies installed and is enforced by mix verify.compile_no_optional.
• phoenix-surface is supported only for the exact optional dependency ranges Threadline declares and CI-covers in this release.
• sigra-reference is a reference lane for Phoenix hosts already using Sigra; it is proven only by the current example app, example lockfile, docs, and focused verification in this repo.
• Anything outside these named lanes is unclaimed, even if it may work.

Supported compatibility matrix

Support claims in this table come from current in-repo proof only:

1. declared optional dependency ranges in mix.exs
2. current lock resolution in mix.lock
3. current CI coverage in .github/workflows/ci.yml
4. focused guide, doc-contract, and example-app verification for the named lane

Threadline does not claim support for Phoenix, LiveView, HTML, PubSub, or Sigra combinations outside these named proofs. The {:sigra, "~> 0.2", optional: true} declaration is a host install shape, not a blanket promise covering every Sigra 0.2.x host. If your lockfile resolves to different versions within the declared ranges, or your host auth/layout differs from the reference path, treat that as your responsibility to verify locally unless and until the Threadline repo updates its own declared ranges, lock resolution references, docs, and CI coverage accordingly.

Upgrade by Threadline minor

When you upgrade by Threadline minor:

1. read CHANGELOG.md for upgrade notes and any announced surface-only deprecations
2. identify your lane before changing dependencies
3. if you are capture-only, run mix verify.compile_no_optional
4. if you are phoenix-surface, confirm your Phoenix stack still fits the declared optional dependency ranges in mix.exs
5. if you are following the sigra-reference lane, compare your host against the current example-app proof path before widening anything
6. run the lane-appropriate verification entrypoints in the upgraded application

Current guidance by minor:

• 0.3.x -> 0.4.x: the operator surface became an official optional dependency lane. capture-only adopters keep the no-optional-deps path. phoenix-surface adopters must align with the declared phoenix, phoenix_live_view, phoenix_html, and phoenix_pubsub ranges and re-check their router mount/auth setup after upgrade. sigra-reference adopters should also re-check the current example app and Sigra guide before treating that path as unchanged.
• future minor upgrades: do not infer support from ecosystem norms or upstream release notes alone. Re-check this guide, the declared optional dependency ranges, the current example-app proof path, and the current changelog entry for the target Threadline minor.

What breaks when Phoenix/LiveView floors move

If Threadline raises a Phoenix or LiveView floor for the optional surface, the break is surface-only unless the changelog says otherwise.

Typical symptoms:

• mix deps.get or dependency resolution fails because your host app pins older Phoenix surface packages outside the declared ranges
• mix compile fails in a surface-mounted host because the mounted stack no longer satisfies the declared optional dependency ranges
• docs/examples no longer match your older Phoenix router or LiveView APIs

capture-only adopters should not be affected by surface-only dependency floor changes as long as mix verify.compile_no_optional continues to pass for the Threadline release they adopt.

Packaging Boundary Scorecard

Threadline closes v1.19 with a clear package-boundary decision: stay in-tree for now. The optional Phoenix surface is already isolated behind optional dependencies, the repo still proves one coherent release story from the root package, and the current evidence does not justify the extra versioning and release overhead of a separate threadline_web package.

Future extraction is a scorecard decision, not a taste decision. The trigger is "yes, extract" only when one or more of these pressures is sustained and materially increases maintainer or adopter cost:

• Version Matrix Pressure: the root package must regularly prove multiple incompatible Phoenix or LiveView lines, or operator-surface dependency movement starts forcing unrelated core-package release coordination.
• Release Cadence Divergence: operator-surface changes want to ship on a meaningfully different cadence than the core capture/query APIs, so keeping one package either delays surface fixes or churns the core release line unnecessarily.
• Adopter Glue Burden: repeated real-world adopter feedback shows that the in-tree optional surface still leaves too much host-specific mounting or packaging glue, and a separate package would reduce that burden without weakening the core auth-agnostic contract.

Until those pressures are real, Threadline keeps the operator surface optional and in-tree. If a future split happens, Threadline will preserve the public threadline_operator_surface/2 router integration API so hosts do not have to rewrite their mount call shape as the cost of following the package boundary.

Surface-only deprecation and removal policy

Threadline treats the operator surface as a public surface-only contract. That contract includes the router macro and documented options, documented mount/auth pattern, documented operator-surface routes, required optional dependency ranges, parity Mix task names and flags, and stable machine-readable literals already locked by tests.

Surface-only deprecations require overlap:

• deprecate in docs and changelog first
• remove no earlier than the next Threadline minor after at least one released overlap window
• do not silently narrow the supported optional dependency ranges without updating this guide and the changelog together

Exceptions are allowed only for security issues, upstream hard incompatibility, or undocumented internals.

Release checklist for adopters

• Decide whether you are capture-only, phoenix-surface, or following the sigra-reference lane.
• Compare your host dependencies against the declared optional dependency ranges in mix.exs.
• If you are capture-only, run mix verify.compile_no_optional.
• If you are phoenix-surface, run mix ci.all and verify your mounted routes and auth pipeline still match guides/operator-surface.md.
• If you are using the sigra-reference lane, run mix verify.example and compare your host wiring against guides/integrations/sigra.md plus examples/threadline_phoenix/README.md.
• Review CHANGELOG.md for any surface-only deprecation notice before deploying.

Canonical references

• guides/operator-surface.md
• guides/integration-contracts.md
• guides/integrations/sigra.md
• examples/threadline_phoenix/README.md
• mix.exs
• mix.lock
• .github/workflows/ci.yml
• CHANGELOG.md