Repository navigation
feat(hang): a player skips a catalog entry newer than it reads - #8950
Conversation
Quest-Claim: 021f288f1dcf08e7
Each rendition, data track, and include carries its own computed version. A reader skips an entry whose version is above its own, reports it in Catalog::skipped (Rust) and Catalog.skipped(root) (JS), and plays the rest. The renamed-track and video-warmup triggers move from the root to the entry; the root version still refuses the whole catalog. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ersion Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Warning Review limit reachedYou've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. Next included review available in 9 minutes. View limit details
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. |
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes
Reviewed the full branch: the hang catalog's version gate moves from the root to each entry, in Rust, JS, the draft, and the parity corpus.
- Per-entry
version. Both serializers now computeversionon each rendition, data track, and include. A renamedtrackor a videowarmupraises only the entry's version to 4, and the rootversionis never written. - Skip instead of refuse. Readers take an entry's
versionout before decoding the rest of it. An entry above 4 is skipped even if this reader would call it malformed. A malformed or repeated entryversionrefuses the catalog, but only after the rootversioncheck, which still refuses a catalog above 4. - Rust
ProbeandCatalog::skipped. A lenient serde visitor reads the root and every entryversionstraight from the bytes, so it catches a repeatedversionmember.Deserialize for Catalognow buffers through aValue.Skippedreports, per section, each skipped ID and its version. - JS
Catalog.skipped(root). Therenditions()transform records skips in aWeakMapkeyed by the parsed map.encodewrites the computed entry versions and drops any version the caller carried. @moq/watch. It logs a warning naming the needed draft whenever a catalog it accepts had entries skipped.- Draft, docs, fixtures. The Version section, entry schemas, and changelog are rewritten. Parity cases cover skipping in every section, supported entry versions, a newer root beside entry versions, and five malformed entry versions.
I traced the Rust Probe against deserialize_entries, including the lenient fallback when a section's map isn't an object. Both make the same skip decisions. The root version refuses first in both languages. Neither library uses deny_unknown_fields or a strict zod object, so older readers ignore the new member. CatalogProducer in js/publish publishes through a Json.Snapshot.Producer that has no schema, so the computed entry versions reach the wire.
ℹ️ @moq/watch exposes the skip report only as a console warning
The draft says a player that skips an entry SHOULD tell its user that upgrading would show more. In @moq/watch, the only place the report appears is console.warn. out.catalog is built in #runFiltered from new filtered maps, so Catalog.skipped(broadcast.catalog) always returns undefined there. A web player UI has no way to show the upgrade hint. The follow-up quest covers the bindings and moq play, not @moq/watch. Whether @moq/watch should expose its own signal is a scope call for the maintainer, and it doesn't block this PR.
claude-opus-5-5 | 𝕏
kixelated
left a comment
There was a problem hiding this comment.
Automated review by review (OpenAI)
Reviewed 1eb1aade3b37bad91fd87de63afcf55db564bf94. Entry-level gating is the right direction. Two edge cases still undermine the fallback:
- P2,
rs/hang/src/catalog/root.rs:247: Plain Serde now buffers the root throughserde_json::Value, which collapses duplicate members before the version check. For example,{"version":5,"version":3}can silently become a supported root. The former derivedWiredecode rejected a repeated known field, andCatalog::from_slicestill has its separate probe. Preserve duplicate root-version detection in the publicDeserializepath and test both entry points. - P2,
js/hang/src/catalog/root.ts(skipped):Math.max(...versions)can throw on a large but otherwise valid skip set. The watch loop calls this inside its read loop; if reporting throws, it clears the accepted catalog instead of playing the compatible entries. Compute the maximum in a loop. I reproduced the V8 spread failure with 200,000 versions; I did not run the full playback or Rust test suites.
The draft should also say the compatibility-rendition promise applies to readers that implement entry gating; already-shipped readers that ignore version are not protected by an entry marker.
There was a problem hiding this comment.
Important
Plain serde now refuses a repeated member, but Catalog::from_str and from_slice, the path Catalog::subscribe reads through, still accept one. The two Rust entry points disagree, and the main reader breaks the draft's MUST.
Reviewed changes
Reviewed what changed since the prior Pullfrog review at 1eb1aad: two merges of main and the commit that makes plain serde refuse repeated members.
- Plain serde buffers through
Strict.Deserialize for Catalognow reads into aValuevisitor that refuses any object repeating a member.{"version":5,"version":3}no longer reads as 3, at the root or in an entry. - Video
warmupno longer raises an entryversion.maindropped videowarmupfrom hang-04, so the merge removesvideoVersionin JS and the warmup arm ofVideoConfig::versionin Rust. A renamedtrackis now the only trigger. - The draft lists only a renamed
trackas needing entryversion4. A new paragraph says why every other hang-04 change is safe for an older reader to ignore. - The
media→syncrename is merged into the PR's docs and draft.include.rs'sEntryimpl and the.tsimport suffixes also come frommain, with no other change in behavior.
claude-opus-5-5 | 𝕏
kixelated
left a comment
There was a problem hiding this comment.
Automated review by review (OpenAI)
Reviewed 3b9068d3be25a92af470a3ce733d8c565c5045f2. The Rust duplicate-member finding is addressed: both Catalog::from_slice and plain Serde now reject duplicates, including a non-version member in the new test. The earlier JS finding still applies: Catalog.skipped() spreads the entire skip set into Math.max, so a large set can make the watch loop discard a catalog it otherwise read. Replace the spread with a loop/reduction before release. I didn't rerun the suites.
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes
Reviewed what changed since the prior Pullfrog review at 24d400c: one commit, 3b9068d.
from_slicebuffers throughStrict.Catalog::from_slice(and sofrom_str,from_reader, andCatalog::subscribe) runs the byteProbefirst, so an unsupported rootversionis still reported before any other fault, then reads the bytes throughStrict, which refuses any repeated member. This is the fix suggested in the earlier inline finding, and the two Rust entry points now agree.- Regression test.
a_duplicate_version_is_refusednow also checks that a repeatedcodecin an entry is refused by bothfrom_strand plain serde.
claude-sonnet-5-5 | 𝕏

Claims quest/m2/hang04/entry-version.md and finishes it (the PR deletes the quest).
Problem
hang-04's only
versiontriggers, a renamedtrackand a videowarmup, are properties of one entry, yet they raised the rootversion, which a 0.22 reader refuses whole. One new-style rendition would take the entire catalog from an older reader, including the compatibility rendition the draft tells publishers to add beside it. 0.22 is the first reader that checksversion, so the rule it ships is the forward-compatibility lever every later catalog change gets.Approach
json/binarytracks, includes) carries its ownversion, computed by both serializers and absent while 3. A renamedtrackor a videowarmupnow raises the entry'sversionto 4; nothing in hang-04 raises the root's, so it is never written. The root check and its tests stay for a future reshaped root.versionbefore the rest of the entry and skips it when above its own, so a newer entry this reader would call malformed is skipped, not refused. Theversionis taken out before the entry decodes, so it never lands in a data track's extension fields, and a republish recomputes it.Catalog::skipped(hang::catalog::Skipped: per-section maps of ID to version,version()for the highest,is_empty()), JSCatalog.skipped(root)returning the same shape orundefined.@moq/watchwarns with the version a viewer would need.Entrytrait (renamed fromRendition, matching feat(hang): one rule refuses a mis-shaped catalog section #8920) withcheck,version, andclaims_version;deserialize_entries/serialize_entrieson all six maps. AProbevisitor reads the root and every entryversionstraight from the bytes infrom_slice, so a repeated entryversionis refused like the root's.Catalog'sDeserializenow buffers through aValueso plain serde also reads every version first and reports skips.section.tsdoes the skip and records it in aWeakMapkeyed by the parsed map;skipped(root)reads it. A root-level field was not an option:RootSchemamust stay a zod object forz.extend, and a report key would collide with an application's root section.version; the changelog bullet is rewritten.doc/pages updated, including the stalearchivementions in the Rust and JS hang pages.Decisions
The maintainer picked this PR to merge on 2026-11-16 (/quest-run) and confirmed the decisions below, and the follow-up
quest/m3/ffi-catalog-skipped.mdis kept. They were taken while the maintainer was away:versionand is skipped and reported like a rendition. Nothing in hang-04 raises it.versionrefuses the catalog (string, negative, fractional,null), as a malformed rootversiondoes, rather than skipping or reading the entry. The member's shape is the one thing every future draft must keep.versionis refused when serializing in Rust, as the root extension's is. JSencodedrops it and writes the computed one, as it already did for the root.hanghastracingonly as a dev-dependency, and a dependency for one warning isn't worth it. The follow-up below exposes the report to the bindings andmoq play.Catalog'sDeserializebuffers through a value that rejects any repeated object member, so{"version":5,"version":3}fails at the root and in an entry, asfrom_slicedoes.version, sinceJSON.parsekeeps the last, the same as the root today. The draft already says a reader refuses a JSON object that repeats a member.Impact
hang(additive):Catalog::skippedandhang::catalog::Skipped. Plainserdedecoding ofCatalogbuffers through aValue, so its errors lose line and column. Plain serde refuses a repeated member anywhere in the catalog. The "malformed rendition" error text becomes "malformed entry".@moq/hang(additive):Catalog.skipped(root)and theSkippedtype.encodewrites entry versions and no rootversion.version; a renamedtrackor videowarmupno longer writes the rootversion.Alternatives
z.extend(RootSchema, ...)or needs the raw document, whichJson.Snapshot.Consumerdoesn't expose.Validation
from_strand plain serde), the root still refusing, supported entry versions, malformed and repeated entry versions, and a data track's extensionversion.root.test.ts;js/publish's catalog producer test now checks the entry version.@moq/hangencoded (renamed video, warmup video, renamed JSON track, include) decoded and re-encoded byrs/hanggives identical JSON. A future catalog with versions 5 to 7 on video, audio, and include entries gives the same skip report in both languages. The kept catalogs differ only in JS writing an emptyincludethat Rust omits, which predates this change.just cipasses locally.Follow-ups
skippedonMoqCatalogand every wrapper, and havemoq playwarn. No open decisions.Caused by
None: the root-only gate was a deliberate design choice the pre-cut audit reversed, not a defect one PR introduced.
Models
Size: M
Implementer: Claude, claude-opus-5-5, medium effort (arm A)
Implementer: Claude Code, claude-sonnet-5-5, unknown effort (iterate, M)
🤖 Generated with Claude Code
(Written by Claude Opus 5.5 with medium effort)
Review
Rewritten by
quest reviewafter each round.Head: 3b9068d
Base: origin/main at 9c71cad
Risk: high,
Catalog wire-version and public decoding changes affect downstream consumers and could disrupt playback through incompatible entry handling, although reverting restores the prior behavior.Classified: medium by default
Reviewer: Codex, gpt-6.1-sol, high effort
Session:
01a1e911-9290-7343-ae85-e84fc8264cbd, round 4Score: 10/10,
The incremental change makes convenience constructors consistently reject duplicate members, adds regression coverage, and introduces no issues found by code inspection.Raised the risk to high:
Catalog wire-version and public decoding changes affect downstream consumers and could disrupt playback through incompatible entry handling, although reverting restores the prior behavior.Rounds: 6; first round 1 (medium 1); findings 2 (medium 2): fixed 2, refuted 0, open 0
Findings: none