tracking: roadmap for current open issues

[catgoose]

Summary

Create a single execution tracker for Tavern's current open work so implementation can proceed in a deliberate order instead of as a flat backlog.

This issue is the working roadmap for the current open issues. It does not replace the underlying issues; it organizes them, defines sequence, and states what "done" should mean for each track.

Current status

Completed

• docs/design: clarify tavern's identity and boundaries #185 docs/design: clarify tavern's identity and boundaries
• tracking: explore tavern as a live hypermedia layer #182 tracking: explore tavern as a live hypermedia layer
• docs/design: topic semantics for live hypermedia #184 docs/design: topic semantics for live hypermedia
• design: snapshot + replay patterns for live documents #183 design: snapshot + replay patterns for live documents
• design: page-level multiplexing for single-connection live pages #186 design: page-level multiplexing for single-connection live pages
• feat: observability export (Prometheus / OpenTelemetry bridge) #134 feat: observability export (Prometheus / OpenTelemetry bridge)
• proposal: composable SSE stream handler helper above raw subscriptions #198 proposal: composable SSE stream handler helper above raw subscriptions
• feat: composable resume-aware subscriptions (SubscribeFromIDWith / SubscribeResumeWith) #201 feat: composable resume-aware subscriptions (SubscribeFromIDWith)
• feat: public multi-topic replay/resume helper #202 feat: public multi-topic replay/resume helper (SubscribeMultiFromID)

Deferred

• docs: HTMX example app demonstrating tavern features #128 docs: HTMX example app demonstrating tavern features

Deferred reason: the example should be extracted from validated usage in the dothog demo rather than invented too early. This stays on the roadmap, but it is waiting on pattern validation there first.

Remaining later work

• feat: distributed presence and state coordination #151 feat: distributed presence and state coordination
• feat: multi-tenant controls (authz hooks, quotas, isolation) #154 feat: multi-tenant controls (authz hooks, quotas, isolation)

Why this exists

The current open issues fall into a few distinct categories:

• product identity and design direction
• live hypermedia design patterns
• examples and developer experience
• observability/productization
• multi-instance and SaaS operational controls
• reusable SSE streaming primitives above raw subscriptions

Those categories are related, but not equally ready. Some should be resolved as design and documentation first. Some can be implemented independently. Some have clear dependencies.

The goal here is to make execution obvious for a follow-on agent or contributor.

Planning principles

• Prefer clarifying Tavern's boundaries before expanding core API surface.
• Prefer naming repeatable patterns before building examples around them.
• Prefer examples that demonstrate settled patterns, not speculative ones.
• Keep distributed and tenant-control work behind clear backend semantics.
• Treat observability export as productization work, not as a design substitute.
• New API surface should start as a narrow composable primitive, not a monolithic handler.

Execution order

Phase 1: Direction and boundaries

These issues define what Tavern is trying to be, and what it should avoid becoming.

• docs/design: clarify tavern's identity and boundaries #185 docs/design: clarify tavern's identity and boundaries
• tracking: explore tavern as a live hypermedia layer #182 tracking: explore tavern as a live hypermedia layer

Exit criteria

• A short design note or README section states what Tavern is for.
• The note explicitly states what should remain outside Tavern core.
• tracking: explore tavern as a live hypermedia layer #182 is updated to reflect the current scope and relationship between the design sub-issues.
• Future feature evaluation has a clearer rubric than "seems useful."

Status: complete.

Phase 2: Core live-hypermedia design patterns

These issues should produce named, recommended patterns for server-owned live documents.

• docs/design: topic semantics for live hypermedia #184 docs/design: topic semantics for live hypermedia
• design: snapshot + replay patterns for live documents #183 design: snapshot + replay patterns for live documents
• design: page-level multiplexing for single-connection live pages #186 design: page-level multiplexing for single-connection live pages

Exit criteria

• Topic semantics are documented for at least resource, collection, presence, and admin/ops use cases.
• Replay guidance explains when to resume from event ID and when to re-snapshot.
• Replay-gap handling has explicit recommended fallback behavior.
• Multiplexed page guidance explains when to use grouped or multi-topic subscriptions and when not to.
• The output is concrete enough that an example app can implement it without inventing missing conventions.

Status: complete.

Phase 3: Reusable SSE streaming primitive

This track is complete. Downstream usage in dothog revealed a repeated middle layer between raw subscriptions and the existing turnkey SSEHandler, and Tavern now has a composable helper for that layer.

• proposal: composable SSE stream handler helper above raw subscriptions #198 proposal: composable SSE stream handler helper above raw subscriptions

Exit criteria

• A small helper lives between raw subscription channels and the existing turnkey SSE handlers.
• The helper prepares SSE headers, verifies http.Flusher, streams values from a subscription or receive-only channel until request cancellation, and supports optional heartbeats, snapshot emission, and an adapter/encoder hook.
• The helper composes with existing subscription APIs rather than replacing them.
• Tests cover cancellation, heartbeats, snapshot emission, and adapter behavior.
• Route semantics remain at the application call site; the helper does not grow into a monolithic all-in-one handler API.

Status: complete.

Phase 3b: Composable resume-aware subscriptions

After StreamSSE (#198) landed, downstream usage in dothog revealed a second repeated pattern: hand-rolling a Last-Event-ID branch on top of the composable subscription API because SubscribeFromID did not accept SubscribeOptions. The subscription half of replay/resume now has first-class composable surface.

• feat: composable resume-aware subscriptions (SubscribeFromIDWith / SubscribeResumeWith) #201 feat: composable resume-aware subscriptions (SubscribeFromIDWith)
• feat: public multi-topic replay/resume helper #202 feat: public multi-topic replay/resume helper (SubscribeMultiFromID)

Exit criteria

• A public SubscribeFromIDWith(topic, lastEventID, opts...) exists with documented semantics for SubWithFilter (uniform across replay and live), SubWithSnapshot (fresh-subscribe only), SubWithMeta (parity with live), SubWithRate (live only), and SubWithScope.
• Control events (tavern-reconnected, tavern-replay-gap, tavern-replay-truncated) bypass user filters so clients can always react to reconnect/gap signals.
• A public SubscribeMultiFromID(topics, lastEventID) exists and mirrors SubscribeMulti's fan-in structure, with per-topic replay/resume and per-topic gap handling.
• Tests cover replay + live, filter, rate, snapshot fresh vs resume, gap fallback, multi-topic replay, live continuation, and teardown.
• Downstream dothog routes no longer need to hand-roll Last-Event-ID branching above the subscription API.

Status: complete.

Phase 4: Example app and documentation proof

The example should validate the design decisions from earlier phases.

• docs: HTMX example app demonstrating tavern features #128 docs: HTMX example app demonstrating tavern features

Exit criteria

• A runnable HTMX example exists under _examples/ or an equivalent clearly documented location.
• The example demonstrates the preferred snapshot/delta and multi-topic page patterns.
• The example is realistic enough to serve as a first evaluation path for new users.
• The example doubles as a living integration reference, not just a toy demo.

Status: deferred pending validation in the dothog demo.

Phase 5: Productization and monitoring

This work is concrete and valuable, and can proceed without waiting on every design discussion to be perfect.

• feat: observability export (Prometheus / OpenTelemetry bridge) #134 feat: observability export (Prometheus / OpenTelemetry bridge)

Exit criteria

• Tavern observability data can be exported to at least one standard monitoring system cleanly.
• The adapter design does not pollute Tavern core with heavy dependencies.
• Metric naming, labeling, and cardinality limits are documented.
• The implementation is compatible with the existing observability snapshot model.

Status: complete.

Phase 6: Multi-instance correctness and SaaS controls

This work matters, but it should follow clearer backend/distributed semantics.

• feat: distributed presence and state coordination #151 feat: distributed presence and state coordination
• feat: multi-tenant controls (authz hooks, quotas, isolation) #154 feat: multi-tenant controls (authz hooks, quotas, isolation)

Exit criteria

For #151:

• Presence and subscriber counts are correct across instances, not just process-local.
• OnFirst and OnLast semantics are defined for clustered deployments.
• Backend responsibilities are explicit rather than implied.

For #154:

• Authorization hooks for publishing are defined clearly.
• Tenant-level fairness and quota behavior are specified and testable.
• Isolation guarantees are documented, including what is and is not enforced.
• The design does not assume a single-process deployment model.

Status: remaining later work.

Priority buckets

Completed

• docs/design: clarify tavern's identity and boundaries #185
• tracking: explore tavern as a live hypermedia layer #182
• docs/design: topic semantics for live hypermedia #184
• design: snapshot + replay patterns for live documents #183
• design: page-level multiplexing for single-connection live pages #186
• feat: observability export (Prometheus / OpenTelemetry bridge) #134
• proposal: composable SSE stream handler helper above raw subscriptions #198
• feat: composable resume-aware subscriptions (SubscribeFromIDWith / SubscribeResumeWith) #201
• feat: public multi-topic replay/resume helper #202

Deferred

• docs: HTMX example app demonstrating tavern features #128

Later / dependency-sensitive

• feat: distributed presence and state coordination #151
• feat: multi-tenant controls (authz hooks, quotas, isolation) #154

Dependencies and sequencing notes

• tracking: explore tavern as a live hypermedia layer #182 is the umbrella for the live-hypermedia exploration track and is now closed as complete.
• proposal: composable SSE stream handler helper above raw subscriptions #198 is complete; the reusable SSE streaming primitive now exists as a narrow composable layer rather than a redesign of the existing SSEHandler.
• feat: composable resume-aware subscriptions (SubscribeFromIDWith / SubscribeResumeWith) #201 and feat: public multi-topic replay/resume helper #202 built directly on the composable subscription system and on SubscribeFromID's existing replay/resume semantics. The subscription half of the replay/resume story is now as composable as the response half (StreamSSE).
• docs: HTMX example app demonstrating tavern features #128 should follow validated real-world usage so the example reflects recommended patterns instead of inventing them ad hoc.
• feat: distributed presence and state coordination #151 is explicitly dependent on backend/distributed capability.
• feat: multi-tenant controls (authz hooks, quotas, isolation) #154 should not be treated as just a thin auth hook issue; it depends on a credible multi-instance resource model.

Suggested execution approach for the next agent

1. Keep tracking: roadmap for current open issues #187 current so the roadmap remains trustworthy.
2. Keep docs: HTMX example app demonstrating tavern features #128 deferred until the dothog demo validates the Tavern patterns well enough to extract a real example.
3. Revisit feat: distributed presence and state coordination #151 once backend/distributed assumptions are explicit.
4. Tackle feat: multi-tenant controls (authz hooks, quotas, isolation) #154 after the distributed/resource model is clearer.

Non-goals of this tracker

• Flattening all issues into equal priority
• Forcing implementation of speculative features before the design is clear
• Treating the example app as the place where architecture decisions get invented
• Pretending multi-instance and tenant-isolation work are low-complexity additions

Related issues

• tracking: explore tavern as a live hypermedia layer #182
• docs/design: clarify tavern's identity and boundaries #185
• docs/design: topic semantics for live hypermedia #184
• design: snapshot + replay patterns for live documents #183
• design: page-level multiplexing for single-connection live pages #186
• docs: HTMX example app demonstrating tavern features #128
• feat: observability export (Prometheus / OpenTelemetry bridge) #134
• feat: distributed presence and state coordination #151
• feat: multi-tenant controls (authz hooks, quotas, isolation) #154
• proposal: composable SSE stream handler helper above raw subscriptions #198
• feat: composable resume-aware subscriptions (SubscribeFromIDWith / SubscribeResumeWith) #201
• feat: public multi-topic replay/resume helper #202