Skip to content

feat(hang): a player skips a catalog entry newer than it reads - #8950

Merged
kixelated merged 8 commits into
mainfrom
quest/m2/hang04/entry-version
Nov 17, 2026
Merged

kixelated merged 8 commits into
mainfrom
quest/m2/hang04/entry-version

Conversation

@kixelated

@kixelated kixelated commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

Claims quest/m2/hang04/entry-version.md and finishes it (the PR deletes the quest).

Problem

hang-04's only version triggers, a renamed track and a video warmup, are properties of one entry, yet they raised the root version, 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 checks version, so the rule it ships is the forward-compatibility lever every later catalog change gets.

Approach

  • Every entry of a map keyed by ID (audio, video, and text renditions, json/binary tracks, includes) carries its own version, computed by both serializers and absent while 3. A renamed track or a video warmup now raises the entry's version to 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.
  • A reader reads an entry's version before 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. The version is taken out before the entry decodes, so it never lands in a data track's extension fields, and a republish recomputes it.
  • The skip is reported: Rust Catalog::skipped (hang::catalog::Skipped: per-section maps of ID to version, version() for the highest, is_empty()), JS Catalog.skipped(root) returning the same shape or undefined. @moq/watch warns with the version a viewer would need.
  • Rust: Entry trait (renamed from Rendition, matching feat(hang): one rule refuses a mis-shaped catalog section #8920) with check, version, and claims_version; deserialize_entries/serialize_entries on all six maps. A Probe visitor reads the root and every entry version straight from the bytes in from_slice, so a repeated entry version is refused like the root's. Catalog's Deserialize now buffers through a Value so plain serde also reads every version first and reports skips.
  • JS: the entries transform in section.ts does the skip and records it in a WeakMap keyed by the parsed map; skipped(root) reads it. A root-level field was not an option: RootSchema must stay a zod object for z.extend, and a report key would collide with an application's root section.
  • Draft: the Version section covers entry versions, the skip rule, and that a skipped entry is never malformed; the entry schemas list version; the changelog bullet is rewritten.
  • doc/ pages updated, including the stale archive mentions 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.md is kept. They were taken while the maintainer was away:

  • Includes are entries too. An include carries version and is skipped and reported like a rendition. Nothing in hang-04 raises it.
  • References to a skipped entry. No hang-04 field refers to another entry by ID, so there is nothing to resolve. The draft says the catalog reads as if a skipped entry were absent, which is what a later referencing field must honor.
  • A malformed entry version refuses the catalog (string, negative, fractional, null), as a malformed root version does, rather than skipping or reading the entry. The member's shape is the one thing every future draft must keep.
  • A data track's extension member named version is refused when serializing in Rust, as the root extension's is. JS encode drops it and writes the computed one, as it already did for the root.
  • Report shape. Per-section maps of ID to version rather than one flat list, because IDs are only unique within a section (an include and a rendition may share one).
  • Native consumers do not log yet. hang has tracing only as a dev-dependency, and a dependency for one warning isn't worth it. The follow-up below exposes the report to the bindings and moq play.
  • Plain serde refuses a repeated member too. Catalog's Deserialize buffers through a value that rejects any repeated object member, so {"version":5,"version":3} fails at the root and in an entry, as from_slice does.
  • JS cannot refuse a repeated entry version, since JSON.parse keeps 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::skipped and hang::catalog::Skipped. Plain serde decoding of Catalog buffers through a Value, 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 the Skipped type. encode writes entry versions and no root version.
  • Wire (hang-04 catalog JSON, unpublished): entries carry version; a renamed track or video warmup no longer writes the root version.

Alternatives

  • Keep the root gate and tell publishers never to mix new-style and compatibility renditions (rejected in the quest's plan).
  • Have JS return the report from a wrapper schema or a raw-JSON helper: either breaks z.extend(RootSchema, ...) or needs the raw document, which Json.Snapshot.Consumer doesn't expose.

Validation

  • Rust: new tests for written entry versions, republish recomputing them, skipping and reporting across all six maps (via from_str and plain serde), the root still refusing, supported entry versions, malformed and repeated entry versions, and a data track's extension version.
  • JS: the same cases in root.test.ts; js/publish's catalog producer test now checks the entry version.
  • Parity fixtures: a skip across every section, supported entry versions, a newer root beside entry versions, and five malformed entry versions. Both languages compare the skip report.
  • Differential check across languages (scratch, not committed): a catalog @moq/hang encoded (renamed video, warmup video, renamed JSON track, include) decoded and re-encoded by rs/hang gives 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 empty include that Rust omits, which predates this change.
  • just ci passes locally.

Follow-ups

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 review after 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 4

  • Score: 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

kixelated and others added 3 commits November 16, 2026 07:10
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>
@kixelated kixelated changed the title A player skips a catalog entry newer than it reads feat(hang): a player skips a catalog entry newer than it reads Nov 16, 2026
…ersion

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated
kixelated marked this pull request as ready for review November 16, 2026 16:17
@coderabbitai

coderabbitai Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

You'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.

Check out review usage here.

View limit details

Limit details: You’ve used all 4 included reviews currently available.

Learn how review limits work.

Review configuration:

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 46cd295a-5bbb-433b-b231-1f8bc48adca1
Commits

Reviewing files that changed from the base of the PR and between ecdbb3d and 3b9068d.

Files selected for processing: 25

  • doc/concept/hang.md
  • doc/lib/js/hang.md
  • doc/lib/rs/hang.md
  • drafts/draft-lcurley-moq-hang.md
  • js/hang/api/catalog.api.md
  • js/hang/src/catalog/parity.test.ts
  • js/hang/src/catalog/root.test.ts
  • js/hang/src/catalog/root.ts
  • js/hang/src/catalog/section.ts
  • js/hang/src/catalog/version.ts
  • js/publish/src/catalog.test.ts
  • js/watch/src/broadcast.ts
  • quest/m2/hang04/entry-version.md
  • quest/m3/ffi-catalog-skipped.md
  • quest/m4/intra-refresh/catalog-warmup.md
  • rs/hang/fixtures/catalog-parity.json
  • rs/hang/src/catalog/audio/mod.rs
  • rs/hang/src/catalog/binary.rs
  • rs/hang/src/catalog/json.rs
  • rs/hang/src/catalog/mod.rs
  • rs/hang/src/catalog/reference.rs
  • rs/hang/src/catalog/root.rs
  • rs/hang/src/catalog/skipped.rs
  • rs/hang/src/catalog/text/mod.rs
  • rs/hang/src/catalog/video/mod.rs
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

pullfrog[bot]
pullfrog Bot previously approved these changes Nov 16, 2026

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ 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 compute version on each rendition, data track, and include. A renamed track or a video warmup raises only the entry's version to 4, and the root version is never written.
  • Skip instead of refuse. Readers take an entry's version out before decoding the rest of it. An entry above 4 is skipped even if this reader would call it malformed. A malformed or repeated entry version refuses the catalog, but only after the root version check, which still refuses a catalog above 4.
  • Rust Probe and Catalog::skipped. A lenient serde visitor reads the root and every entry version straight from the bytes, so it catches a repeated version member. Deserialize for Catalog now buffers through a Value. Skipped reports, per section, each skipped ID and its version.
  • JS Catalog.skipped(root). The renditions() transform records skips in a WeakMap keyed by the parsed map. encode writes 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.

Pullfrog  | View workflow run | Using claude-opus-5-5 | 𝕏

@kixelated kixelated left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 through serde_json::Value, which collapses duplicate members before the version check. For example, {"version":5,"version":3} can silently become a supported root. The former derived Wire decode rejected a repeated known field, and Catalog::from_slice still has its separate probe. Preserve duplicate root-version detection in the public Deserialize path 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.

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 Catalog now reads into a Value visitor that refuses any object repeating a member. {"version":5,"version":3} no longer reads as 3, at the root or in an entry.
  • Video warmup no longer raises an entry version. main dropped video warmup from hang-04, so the merge removes videoVersion in JS and the warmup arm of VideoConfig::version in Rust. A renamed track is now the only trigger.
  • The draft lists only a renamed track as needing entry version 4. A new paragraph says why every other hang-04 change is safe for an older reader to ignore.
  • The media → sync rename is merged into the PR's docs and draft. include.rs's Entry impl and the .ts import suffixes also come from main, with no other change in behavior.

Pullfrog  | Fix all ➔ | Fix 👍s ➔ | View workflow run | Using claude-opus-5-5 | 𝕏

Comment thread rs/hang/src/catalog/root.rs Resolved

@kixelated kixelated left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found.

Reviewed changes

Reviewed what changed since the prior Pullfrog review at 24d400c: one commit, 3b9068d.

  • from_slice buffers through Strict. Catalog::from_slice (and so from_str, from_reader, and Catalog::subscribe) runs the byte Probe first, so an unsupported root version is still reported before any other fault, then reads the bytes through Strict, 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_refused now also checks that a repeated codec in an entry is refused by both from_str and plain serde.

Pullfrog  | View workflow run | Using claude-sonnet-5-5 | 𝕏

@kixelated
kixelated added this pull request to the merge queue Nov 17, 2026
Merged via the queue into main with commit 1399add Nov 17, 2026
5 checks passed
@kixelated
kixelated deleted the quest/m2/hang04/entry-version branch November 17, 2026 12:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant