feat(hang)!: unify catalog APIs

[kixelated]

Problem

The HANG catalog model was split between hang and moq-mux, with duplicate root types and constructors. Timeline metadata was also spread across a retired root timeline section, per-data-track timeline fields, archive, and clock. That made the public API harder to compose and allowed a typed extended catalog to deserialize and republish the retired timeline root through its flattened extension map.

Approach

• Make hang::Catalog<E> the single flattened catalog type and carry application-defined root sections in E.
• Fold the segment-index catalog metadata into archive, keep the wall-clock mapping in the root clock, and use moq_net::Timestamp for clock values.
• Remove per-data-track timeline metadata, make the mux catalog producer configuration-driven, and move the JavaScript runtime timeline API from Hang.Container.Timeline to Hang.Timeline.
• Migrate all in-repository Rust and TypeScript consumers, plus the HANG concept documentation and draft.
• Refuse reserved and retired root keys, including timeline, both when mutating and when deserializing Catalog<Extra>.

Impact

This is an intentional breaking pre-release API and catalog-schema change targeting main for the final release pass.

Rust public API changes:

• hang::Catalog becomes Catalog<E = ()> with a flattened public ext: E; parsing requires E: DeserializeOwned + Default, serialization requires E: Serialize, and media() produces the base media-only catalog.
• The standalone catalog Timeline type is removed. Archive directly owns track, timescale, and duration_max, while the catalog root owns the optional Clock.
• Clock construction and conversion use moq_net::Timestamp instead of untyped integer timestamp/timescale pairs.
• moq-mux removes its duplicate HANG catalog model and uses hang::Catalog<Extra>. Extra rejects base, MSF, and retired root names on insertion and decode.
• The mux catalog Producer is constructed from an explicit config and its catalog type is shared with hang; moq-hls reads the segment index directly from catalog.archive.

JavaScript public API changes:

• @moq/hang removes the catalog Timeline schema and the optional timeline members on JSON and binary tracks.
• The runtime timeline module moves from Hang.Container.Timeline to Hang.Timeline.
• ArchiveSchema directly defines the segment-index fields, and ClockSchema remains at the catalog root.

Catalog wire/schema changes:

• The retired root timeline member is replaced by optional root archive and is now rejected by typed mux extension catalogs instead of being silently preserved.
• archive carries track, timescale, and optional durationMax, plus optional replay/store/version metadata. It does not carry wall time.
• Root clock carries the wall-clock mapping and timescale.
• Optional per-JSON-track and per-binary-track timeline members are removed.
• Encoded media payloads and timeline-record framing do not change.

Alternatives

Keeping the duplicate moq-mux catalog type or compatibility constructors would preserve the ownership split this change removes. Keeping the retired timeline root as an extension would also let publishers emit a schema member that supported consumers no longer interpret.

Follow-ups

External Rust and TypeScript consumers must migrate to the APIs and catalog shape above before the release. All in-repository consumers, documentation, and the HANG draft are updated here.

Validation

• Regression reproduced before the fix: Catalog<Extra> accepted and republished a root timeline object.
• Focused retired_timeline_section_is_rejected and full ext::test group pass after the fix.
• nix develop --command just check
• nix develop --command just test

(written by GPT-5)

[moq-bot]

1. Breaking hang/moq-mux/moq-hls API targets main despite published versions (rs/hang/Cargo.toml:8, AGENTS.md#development). Retarget the PR to dev and rebase onto origin/dev.
2. Retired root timeline is refused by Extra::set but accepted via flattened serde and republished (rs/moq-mux/src/catalog/hang/ext.rs:79, AGENTS.md#required). Strip or reject timeline on deserialize and add a Catalog<Extra> regression test.
3. Hang changelog says archive keeps wall, but Archive has no wall field (rs/hang/CHANGELOG.md:12, AGENTS.md#required). Remove wall from the archive bullet and point to the root clock.
4. HLS changelog names catalog.archive.timeline, but the exporter reads catalog.archive (rs/moq-hls/CHANGELOG.md:12, AGENTS.md#required). Change the bullet to catalog.archive.

Verdict: request changes
(Written by Muse Spark)

opencode session  |  github run

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: cbc61891-7db2-4d04-8f55-1676a182fdef

📥 Commits

Reviewing files that changed from the base of the PR and between 0b1a332 and cfbf672.

📒 Files selected for processing (2)

• doc/concept/hang.md
• rs/libmoq/src/publish.rs

🚧 Files skipped from review as they are similar to previous changes (1)

• rs/libmoq/src/publish.rs

Included review availability: Your plan provides up to 4 included reviews per hour; 0 remain after this review.

---

Walkthrough

The change removes companion timeline metadata from data-track schemas and replaces standalone timeline catalog sections with archive sections. Rust catalogs now support generic extension data through Catalog<E>, and catalog producers use explicit Config values. Clock APIs now use typed timestamps. MPEG-TS and other catalog extensions move under catalog.ext. Subscription code constructs entries from track maps with Entry::new. Related tests, examples, documentation, and call sites were updated.

Priority: ➖ Normal

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: unifying the HANG catalog APIs.
Description check	✅ Passed	The description directly explains the catalog API unification, timeline and clock changes, breaking impact, migrations, and validation.
Docstring Coverage	✅ Passed	Docstring coverage is 82.30% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 209 functions across 50 files. (1 skipped: …
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

✨ Simplify code

• Commit to this branch
• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[moq-bot]

1. Breaking hang/moq-mux/moq-hls catalog API targets main despite published versions (rs/hang/Cargo.toml:8, rs/moq-mux/Cargo.toml:8, AGENTS.md#development). Retarget PR to dev and rebase onto origin/dev.
2. Guard::set_section doc says only video/audio are reserved but Extra::set rejects 8 base keys plus retired timeline and MSF roots (rs/moq-mux/src/catalog/producer.rs:722, AGENTS.md#required). List the full reserved set.
3. set_catalog_section doc says only video/audio error but it forwards to Extra::set with wider rejection (rs/moq-ffi/src/producer.rs:289, AGENTS.md#required). List the full reserved set.

Verdict: request changes
(Written by Muse Spark)

opencode session  |  github run

[moq-bot]

1. Breaking hang/moq-mux/moq-hls catalog API targets main despite published versions (rs/hang/Cargo.toml:8, AGENTS.md#development). Retarget PR to dev and rebase onto origin/dev.
2. catalog_section_set doc says only video/audio are reserved but Extra::set rejects 8 base keys plus retired timeline and MSF roots (rs/libmoq/src/publish.rs:353, AGENTS.md#required). List the full reserved set as in rs/moq-mux/src/catalog/producer.rs:721.
3. Concept doc documents archive but omits root clock (doc/concept/hang.md:56, AGENTS.md#cross-package-sync). Add a clock bullet covering wall mapping and live-only use.

Verdict: request changes
(Written by Muse Spark)

opencode session  |  github run

[moq-bot]

1. Breaking hang/moq-mux/moq-hls catalog API targets main despite published versions (rs/hang/Cargo.toml:8, rs/moq-mux/Cargo.toml:8, rs/moq-hls/Cargo.toml:8, AGENTS.md#development). Retarget the PR to dev and rebase onto origin/dev.

Verdict: request changes
(Written by Muse Spark)

opencode session  |  github run

[kixelated]

Merged after rebasing onto the #3816 main tip.

• Rejected the retired root timeline when decoding flattened Catalog<Extra> data, with regression coverage.
• Corrected the HANG and HLS changelog descriptions.
• Documented the complete reserved-root contract across Rust, FFI, and libmoq, and added the root clock concept documentation.
• Regenerated the tracked Dart FFI checksum after the public doc change.
• Verified locally with full just check and just test; the final-head GitHub Check, Test, OBS, Swift, and automated review gates passed.
• Targeting main is intentional under the maintainer's final pre-release exception.

(written by GPT-5)