spec: ocp-1.md — five state axes enumerated; playlist membership; failure signaling

[JarbasAl]

🤖 Auto-generated by Claude Fable 5 (claude-fable-5) via Claude Code — NOT human-reviewed. Verify before acting. Cross-spec citations were model-verified against dev source; behavior-change sections need owner judgment.

Summary

Audit fixes to OVOS-OCP-1, grouped:

• State model (O4): §3 claimed three orthogonal axes but only enumerated three of the five actually in use. Added §3.4 (track state) and §3.5 (PlaybackType) enumeration tables, built minimally and honestly from the existing §4.4/§4.5 prose — no invented transitions; states explicitly "transitions not listed are not valid."
• Dangling cross-reference (O2): §4.4's "(see Follow-ups)" pointed at a section that doesn't exist. Replaced with a real §4.6 "Open items" subsection naming the pending MediaState/track-state numeric code assignment.
• status field typing (O3): retyped from number to reserved — producers SHOULD omit it, consumers MUST ignore any value present, until §4.6's numeric codes are assigned. The old typing implied a stable wire encoding that doesn't exist yet.
• Playlist membership (O5): media MUST be a member of playlist when present, located by uri match; next/previous move relative to that position. This was previously undefined despite being load-bearing for §4.3.
• Failure MUSTs (O6): §8 gained three: reject a play request missing uri before dispatch; announce MediaState INVALID_MEDIA on acquisition failure; announce PlayerState STOPPED if the backend dies mid-track.
• Search payload (O7): confirmed/tightened the existing "implementation-defined in this version" deferral so it explicitly covers the base ovos.common_play.search payload, not just its bracketing Messages.
• Wording (O9): "the media pipeline" → "a pipeline plugin conformant to OVOS-PIPELINE-1" (both the Dependencies line and See also), since PIPELINE-1 doesn't name one specific pipeline.

Cross-dependency note (O1): §4.5 cited OVOS-GUI-1 §3.4 as if the millisecond/-1-unknown time convention were already uniform across GUI-1's media templates. On dev, GUI-1 §3.4 is still split — SYSTEM_audio_player uses seconds, SYSTEM_media_player uses ms — and that unification only lands with #108 (open, not yet merged). The citation is now phrased as "the convention OVOS-GUI-1 v2 adopts," which is true today and stays true once #108 merges; no factual claim in this PR depends on #108's merge order.

O8 (GLOSSARY OCP terms) intentionally out of scope — tracked separately.

Test plan

• Re-read the full file after edits for internal consistency (no remaining "(see Follow-ups)" or "three axes" references).
• Verified GUI-1's current dev state directly (grep on gui-1.md) rather than trusting the audit note.
• CHANGELOG entry added under OVOS-OCP-1 §2, itemized per change.

[coderabbitai]

Warning

Review limit reached

@JarbasAl, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 41 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 694f780d-f237-449e-83ad-dff6b638f50e

📥 Commits

Reviewing files that changed from the base of the PR and between 1d3622b and 56a3145.

📒 Files selected for processing (2)

• CHANGELOG.md
• ocp-1.md

---

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.}