feat(net)!: routes carry an instance and a per-instance epoch

c/moq/MIGRATE.md

@@ -86,7 +86,7 @@ Publish a replacement under a new name, and expect a finished track's demand ter
 ### A claim answers by publishing (#5678)
 
 `moq_origin_dynamic` takes no route, and `moq_origin_dynamic_update` is gone.
-`moq_broadcast_request_accept` is replaced by `moq_broadcast_request_prepare`, which returns a prepared answer under the epoch you pass: fill its broadcast, then `moq_broadcast_prepared_publish` announces it at the exact path under that epoch.
+`moq_broadcast_request_accept` is replaced by `moq_broadcast_request_prepare`, which returns a prepared answer: fill its broadcast, then `moq_broadcast_prepared_publish` announces it at the exact path under a fresh instance of its own.
 `moq_broadcast_prepared_free` refuses an answer you will not publish.
 
 ### `moq_track_info` gains `compress` (#5928)

cpp/moq/README.md

@@ -1,6 +1,6 @@
 # moq C++ package
 
-C++17 bindings for [rs/moq-ffi](../../rs/moq-ffi): the sources `uniffi-bindgen-cpp` generates, plus `include/moq/moq.hpp`, a thin layer that adds the executor, shutdown, and `co_await` glue. `uniffi.toml` strips moq-ffi's `Moq` type prefix and `moq_` function prefix, so `MoqClient` is generated as `moq::Client` and `moq_mint_epoch` as `moq::mint_epoch`. Nothing here re-implements a method; a shape problem is fixed in moq-ffi, where every binding benefits. User docs: [doc/lib/cpp](../../doc/lib/cpp/index.md).
+C++17 bindings for [rs/moq-ffi](../../rs/moq-ffi): the sources `uniffi-bindgen-cpp` generates, plus `include/moq/moq.hpp`, a thin layer that adds the executor, shutdown, and `co_await` glue. `uniffi.toml` strips moq-ffi's `Moq` type prefix and `moq_` function prefix, so `MoqClient` is generated as `moq::Client` and `moq_log_level` as `moq::log_level`. Nothing here re-implements a method; a shape problem is fixed in moq-ffi, where every binding benefits. User docs: [doc/lib/cpp](../../doc/lib/cpp/index.md).
 
 ## Layout
 

cpp/obs/src/moq-dock.cpp

@@ -1124,11 +1124,6 @@ void MoQDock::StartStream()
 		return;
 	}
 
-	if (auto *moq = static_cast<MoQOutput *>(obs_obj_get_data(output))) {
-		const auto epoch = moq->GetEpoch();
-		if (!epoch.empty())
-			publishSummary += QStringLiteral("\nEpoch ") + QString::fromStdString(epoch);
-	}
 	pollTimer->start();
 
 	SetRunning(true);

cpp/obs/src/moq-output.cpp

@@ -167,7 +167,8 @@ bool MoQOutput::Start()
 	}
 
 	// Create the broadcast on an origin of our own, then announce it so subscribers
-	// can discover it. Stop() finishes it, so each Start creates a fresh one. Only the
+	// can discover it. Stop() finishes it, so each Start creates a fresh one, under a
+	// fresh instance the broadcast mints and keeps across reconnects. Only the
 	// broadcast is kept: the route outlives the publication until the broadcast closes.
 	LOG_INFO("Publishing broadcast: %s", path.c_str());
 	auto next_origin = moq::OriginProducer::init(moq::OriginConfig{});
@@ -176,9 +177,7 @@ bool MoQOutput::Start()
 		LOG_ERROR("Failed to create broadcast: %s", publication.error().to_string().c_str());
 		return false;
 	}
-	moq::AnnounceRoute route;
-	route.epoch = moq::mint_epoch();
-	if (auto announced = (*publication)->announce(route); !announced) {
+	if (auto announced = (*publication)->announce({}); !announced) {
 		LOG_ERROR("Failed to announce broadcast: %s", announced.error().to_string().c_str());
 		return false;
 	}
@@ -229,7 +228,6 @@ bool MoQOutput::Start()
 	{
 		std::lock_guard<std::mutex> lock(mutex);
 		url = server;
-		epoch = *route.epoch;
 	}
 	{
 		std::lock_guard<std::mutex> lock(media_mutex);
@@ -371,7 +369,6 @@ void MoQOutput::Reset()
 		connected = false;
 		live = false;
 		url.clear();
-		epoch.clear();
 		last_failure_code = MoQError::None;
 		last_failure_reason.clear();
 		token_refusal.clear();
@@ -428,12 +425,6 @@ void MoQOutput::Reset()
 		SetBitrate(encoder, bitrate);
 }
 
-std::string MoQOutput::GetEpoch()
-{
-	std::lock_guard<std::mutex> lock(mutex);
-	return epoch;
-}
-
 bool MoQOutput::TryGetConnectionStats(ConnectionStats *out)
 {
 	if (!out)

cpp/obs/src/moq-output.h

@@ -60,9 +60,6 @@ class MoQOutput {
 	// Prefer this over obs_output_get_connect_time_ms, which stays 0 for sub-ms connects.
 	bool IsLiveSession();
 
-	// Publisher epoch of this Start(), retained through session reconnects; empty when stopped.
-	std::string GetEpoch();
-
 	// Most recent connect/reconnect failure for this Start(), or empty when none.
 	// Thread-safe; the dock polls this while connecting, while reconnecting, and on stop.
 	void CopyLastFailure(int *code, std::string *reason);
@@ -174,7 +171,6 @@ class MoQOutput {
 	bool connected = false;
 	bool live = false;
 	std::string url;
-	std::string epoch;
 	int last_failure_code = 0;
 	std::string last_failure_reason;
 	std::string token_refusal;

cpp/obs/src/moq-source.cpp

@@ -940,7 +940,7 @@ static bool moq_source_same_video(const Track *track, const std::string &id, con
 	const bool same_coded =
 		old.coded.has_value() == config.coded.has_value() &&
 		(!old.coded || (old.coded->width == config.coded->width && old.coded->height == config.coded->height));
-	return old.broadcast == config.broadcast && old.epoch == config.epoch && old.codec == config.codec &&
+	return old.broadcast == config.broadcast && old.instance == config.instance && old.codec == config.codec &&
 	       old.description == config.description && same_coded &&
 	       moq_source_same_container(old.container, config.container);
 }
@@ -953,7 +953,7 @@ static bool moq_source_same_audio(const Track *track, const std::string &id, con
 	// The same track under a new catalog ID is the same rendition.
 	if (old.track.value_or(track->id) != config.track.value_or(id))
 		return false;
-	return old.broadcast == config.broadcast && old.epoch == config.epoch && old.codec == config.codec &&
+	return old.broadcast == config.broadcast && old.instance == config.instance && old.codec == config.codec &&
 	       old.description == config.description && old.sample_rate == config.sample_rate &&
 	       old.channel_count == config.channel_count && moq_source_same_container(old.container, config.container);
 }

cpp/obs/test/moq-audio-encoder-test.cpp

@@ -205,9 +205,7 @@ void CheckSubscriberDecodes(const char *preset, size_t channels)
 	auto origin = moq::OriginProducer::init(moq::OriginConfig{});
 	auto publication = TestOk(origin->create_broadcast("room"), "create_broadcast");
 	auto broadcast = publication->broadcast();
-	moq::AnnounceRoute route;
-	route.epoch = moq::mint_epoch();
-	TestOk(publication->announce(route), "announce");
+	TestOk(publication->announce({}), "announce");
 
 	moq::AudioInit init{};
 	init.format = moq::AudioFormat::kOpus;

cpp/obs/test/moq-output-test.cpp

@@ -366,7 +366,7 @@ std::optional<moq::Catalog> relayCatalog(const std::shared_ptr<moq::BroadcastCon
 // The production commit boundary lets a real stats call race retirement without
 // callbacks or branches in the output's hot path.
 struct MoQOutputStatsTest {
-	static std::optional<std::string> Epoch(MoQOutput &output)
+	static std::optional<std::string> Instance(MoQOutput &output)
 	{
 		std::shared_ptr<moq::OriginProducer> origin;
 		{
@@ -381,7 +381,9 @@ struct MoQOutputStatsTest {
 		if (!event)
 			return std::nullopt;
 		const auto *start = std::get_if<moq::AnnounceEvent::kStart>(&event->get_variant());
-		return start ? start->announce.route.epoch : std::nullopt;
+		if (!start)
+			return std::nullopt;
+		return start->announce.route.instance;
 	}
 
 	static std::shared_ptr<moq::Session> Session(MoQOutput &output)
@@ -457,26 +459,22 @@ int main()
 		reset(relay.Url());
 		MoQOutput output(nullptr, OUTPUT);
 		CHECK(output.Start());
-		const auto first = MoQOutputStatsTest::Epoch(output);
-		CHECK(first.has_value());
-		CHECK(first == output.GetEpoch());
+		const auto first = MoQOutputStatsTest::Instance(output);
+		CHECK(first.has_value() && !first->empty());
 		CHECK(WaitFor([&] { return output.IsLiveSession() && relay.Accepted() == 1; }));
 		// The plugin names itself ahead of the C++ package, so a relay can tell it apart.
 		CHECK(relay.Advertised("moq-obs/dev moq-cpp/"));
 		relay.DropSessions();
 		CHECK(WaitFor([&] { return output.GetReconnectCount() == 1 && output.IsLiveSession(); }));
-		CHECK(MoQOutputStatsTest::Epoch(output) == first);
-		CHECK(first == output.GetEpoch());
+		CHECK(MoQOutputStatsTest::Instance(output) == first);
 		output.Stop();
-		CHECK(output.GetEpoch().empty());
 		CHECK(output.Start());
-		const auto second = MoQOutputStatsTest::Epoch(output);
-		CHECK(second.has_value());
+		const auto second = MoQOutputStatsTest::Instance(output);
+		CHECK(second.has_value() && !second->empty());
 		CHECK(second != first);
-		CHECK(second == output.GetEpoch());
 		output.Stop();
 	}
-	printf("each start announces a fresh epoch, reconnect preserves it: ok\n");
+	printf("each start announces a fresh instance, reconnect preserves it: ok\n");
 
 	{
 		TestRelay relay;

cpp/obs/test/moq-source-test.cpp

@@ -1351,7 +1351,7 @@ int main()
 	}
 	report("all-disabled section holds the playing rendition");
 
-	// A rendition's publisher epoch is part of its identity, for the active and the pending
+	// A rendition's stream instance is part of what names it, for the active and the pending
 	// track alike: a sibling publisher restarting behind a stable catalog resubscribes.
 	{
 		TestRelay relay;
@@ -1364,28 +1364,28 @@ int main()
 		{
 			std::lock_guard<std::mutex> lock(ctx->mutex);
 			const auto &conn = ctx->connection;
-			snapshot.video.begin()->second.epoch = "01900000-0000-7000-8000-000000000001";
-			snapshot.audio.begin()->second.epoch = "01900000-0000-7000-8000-000000000001";
+			snapshot.video.begin()->second.instance = "01900000-0000-7000-8000-000000000001";
+			snapshot.audio.begin()->second.instance = "01900000-0000-7000-8000-000000000001";
 			moq_source_subscribe_video(ctx, conn, snapshot);
 			moq_source_subscribe_audio(ctx, conn, snapshot);
 			CHECK(conn->pending_video && conn->pending_audio);
 			const auto pending_video = conn->pending_video;
 			const auto pending_audio = conn->pending_audio;
-			// The same epoch keeps the pending track.
+			// The same instance keeps the pending track.
 			moq_source_subscribe_video(ctx, conn, snapshot);
 			moq_source_subscribe_audio(ctx, conn, snapshot);
 			CHECK(conn->pending_video == pending_video && conn->pending_audio == pending_audio);
-			// Another epoch replaces it.
-			snapshot.video.begin()->second.epoch = "01900000-0000-7000-8000-000000000002";
-			snapshot.audio.begin()->second.epoch = "01900000-0000-7000-8000-000000000002";
+			// Another instance replaces it.
+			snapshot.video.begin()->second.instance = "01900000-0000-7000-8000-000000000002";
+			snapshot.audio.begin()->second.instance = "01900000-0000-7000-8000-000000000002";
 			moq_source_subscribe_video(ctx, conn, snapshot);
 			moq_source_subscribe_audio(ctx, conn, snapshot);
 			CHECK(conn->pending_video && conn->pending_video != pending_video);
 			CHECK(conn->pending_audio && conn->pending_audio != pending_audio);
 		}
 		destroySource(source);
 	}
-	report("epoch change resubscribes");
+	report("instance change resubscribes");
 
 	// A new rendition that has not delivered a frame cannot stop the old track.
 	{
@@ -1607,7 +1607,7 @@ int main()
 		if (sibling) {
 			hidden = TestOk(relay.origin->create_broadcast("obs/hidden"), "unannounced sibling");
 			config.broadcast = "./hidden";
-			config.epoch = "01900000-0000-7000-8000-000000000001";
+			config.instance = "obs-test-pinned";
 		}
 		snapshot->video.clear();
 		snapshot->video.emplace("!unavailable", config);
@@ -1627,9 +1627,9 @@ int main()
 			// An unannounced sibling stays pending, without interrupting current playback.
 			const int frames = g_output_frames;
 			CHECK(publisher.WriteUntil([&] { return g_output_frames >= frames + 3; }));
-			// A different publisher instance is a real resolution failure.
+			// A different stream is a real resolution failure.
 			moq::AnnounceRoute route;
-			route.epoch = "01900000-0000-7000-8000-000000000002";
+			route.instance = "obs-test-other";
 			TestOk(hidden->announce(route), "announce mismatched sibling");
 		}
 		CHECK(WaitFor([] {

dart/moq/MIGRATE.md

@@ -62,8 +62,8 @@ the matching generated bindings and native library.
 
 ### `announce` takes an `AnnounceRoute`
 
-`BroadcastProducer.announce(route:)` takes `AnnounceRoute(cost:, epoch:)` instead of a `MoqRoute`: the origin builds the hop chain, so `hops` is no longer an input.
-`MoqRoute` is only what announcements report. To re-announce an observed route, copy its `cost` and `epoch`.
+`BroadcastProducer.announce(route:)` takes `AnnounceRoute(cost:, instance:, epoch:)` instead of a `MoqRoute`: the origin builds the hop chain, so `hops` is no longer an input.
+`MoqRoute` is only what announcements report. To re-announce an observed route, copy its `cost`, and its `instance` only when forwarding that same stream; leave `instance` unset to keep the one the broadcast minted.
 
 ### Cancelling a stream cancels its pending read
 
@@ -117,11 +117,11 @@ moq-transport and moq-lite-03/04 sessions are unchanged.
 A container import with `ContainerFormat.fmp4` now publishes one Legacy frame per sample instead of one CMAF frame per fragment.
 Pass the new `ContainerFormat.cmaf` to keep publishing CMAF.
 
-### Catalog references carry their epoch
+### Catalog references carry their instance
 
-`Video` and `Audio` renditions gain `epoch`, the publisher instance their `broadcast` reference names.
-`BroadcastConsumer.resolve(reference:)` becomes `resolve(rendition:)`, taking the catalog `Rendition` and reading its `broadcast` and `epoch` from it.
-Resolving, and the rendition-based consumers, throw for a rendition whose broadcast is proven to serve another epoch.
+`Video` and `Audio` renditions gain `instance`, the publisher instance their `broadcast` reference names.
+`BroadcastConsumer.resolve(reference:)` becomes `resolve(rendition:)`, taking the catalog `Rendition` and reading its `broadcast` and `instance` from it.
+Resolving, and the rendition-based consumers, throw for a rendition whose broadcast is proven to serve another instance.
 
 ### Timestamps stop at 2^61 - 1 microseconds (#6168)
 
@@ -137,7 +137,7 @@ Publish a replacement under a new name, and expect a finished track's demand wat
 ### A claim answers by publishing (#5678)
 
 `origin.dynamic_(prefix:)` takes no route, and `update` is gone.
-Replace `request.accept(broadcast:)` with `request.prepare(epoch: mintEpoch())`, which returns a `BroadcastPrepared`: fill its `broadcast()`, then `publish()` announces it at the exact path under that epoch and returns its producer.
+Replace `request.accept(broadcast:)` with `request.prepare()`, which returns a `BroadcastPrepared`: fill its `broadcast()`, then `publish()` announces it at the exact path under a fresh instance of its own and returns its producer.
 
 ### Anchors can name a time (#6074)
 

dart/moq/lib/moq.dart

@@ -5,6 +5,5 @@ export 'package:moq_ffi/moq_ffi.dart';
 
 export 'src/aliases.dart';
 export 'src/client.dart';
-export 'src/epoch.dart';
 export 'src/server.dart';
 export 'src/timestamp.dart';

dart/moq/lib/src/aliases.dart

@@ -64,7 +64,7 @@ typedef AnnounceConfig = MoqAnnounceConfig;
 /// Follows a specific broadcast path across the publisher instances that serve it.
 typedef Following = MoqFollowing;
 
-/// How a broadcast advertises its exact path: its static production cost and publisher epoch.
+/// How a broadcast advertises its exact path: its static production cost and stream instance.
 typedef AnnounceRoute = MoqAnnounceRoute;
 
 /// A route over a prefix: its origin-relative path, required wildcard captures (empty without wildcards), and route metadata.

dart/moq/lib/src/client.dart

@@ -230,15 +230,15 @@ final class Moq {
   }) => session.consume().announced(config: options._ffi);
 
   /// Follow the broadcast at exactly [path]: each `available()` resolves the
-  /// next publisher instance serving it, such as a restarted publisher. Pass an
-  /// [epoch] (UUIDv7 text) to follow only that instance.
-  Following follow(String path, {String? epoch}) =>
-      session.consume().follow(path: path, epoch: epoch);
+  /// next instance serving it, such as a restarted publisher. Pass an
+  /// [instance] to follow only that stream.
+  Following follow(String path, {String? instance}) =>
+      session.consume().follow(path: path, instance: instance);
 
   /// Resolve one publisher instance of the broadcast at [path]. Pass an
-  /// [epoch] (UUIDv7 text) to refuse any other instance.
-  Future<BroadcastConsumer> request(String path, {String? epoch}) =>
-      session.consume().request(path: path, epoch: epoch);
+  /// [instance] to refuse any other stream.
+  Future<BroadcastConsumer> request(String path, {String? instance}) =>
+      session.consume().request(path: path, instance: instance);
 
   /// The session's bandwidth allocator.
   ///