spec: OVOS-COMMON-QUERY-1 — contest correlation, deterministic selection, responder identity

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

Audit pass over common-query.md. The spec stays class 2 — the new
query_id field is tolerated-absent, so skills written against the current
protocol keep participating unchanged.

Behavior changes

Three changes alter what a conformant implementation does, not just how the
text reads:

1. query_id correlation (§6.4). Every contest carries a
   plugin-generated identifier in the ping and the full-answer request;
   skills echo it in the pong and the response, and mismatches are discarded.
   Session + utterance was not a sufficient key: a repeated question, or a
   deployment where several clients share the default session, produce
   contests that key alone cannot tell apart. A pong or response with no
   query_id is still accepted on utterance + session (SHOULD), which is
   what keeps the compatibility class.
2. Early poll close restricted (§6.3). The old text let a deployment
   "proceed as soon as one claims". That made answer choice a race between
   skills' response latencies. Early close is now allowed only on an
   order-independent sufficiency condition — every known subscriber has
   answered — and otherwise the plugin waits out the window.
3. Deterministic tie-break (§8.1). Selection was "highest conf, ties
   broken by any deployer-defined heuristic". It is now conf descending,
   then skill_id lexicographic ascending. Deployer keys are admitted only
   when they are deterministic functions of the response set, and a
   configured reranker MUST be deterministic. The opt-in, default-off
   fast-win rule remains the single sanctioned exception.

Identity and message hygiene

• §6.5 / §7.1.1 — pong skill_id validated against the envelope source
  where the substrate provides it; response payload skill_id MUST equal the
  topic prefix. ovos.common_query.pong is a shared topic with a free-form
  identity field, and the response prefix was never bound to the payload, so
  every downstream decision keyed on skill_id (denylist, dedup, tie-break)
  was acting on an unverified claim.
• One pong and one response per skill_id per contest, first wins.
• Malformed pong ⇒ not claiming. Malformed response ⇒ discarded whole,
  including conf outside [0, 1] — discarded, never clamped.
• Late pongs and responses MUST be discarded and MUST NOT seed a later
  contest.
• §7.1.1 — prefix extraction defined as everything before the
  .common_query. infix, so a dotted skill_id (wiki.test) parses
  unambiguously. MSG-1 §2.1.1 separator hygiene binds only the structural
  infix in this family.

Language

• §5 — early start gets an explicit carve-out against PIPELINE-1 §9.1: the
  pre-resolution tag is provisional, never published in Match.lang, and
  the cached contest is void unless it equals the lang argument the
  orchestrator later passes to match.
• The resolved lang argument replaces context.session.lang as the
  normative language source in §6.1, §7.1 and §9. Match.lang is now that
  argument.

Early start

• §5.1 — the transparency claim is narrowed to selection. Early start is
  not transparent in invocation: a skill a later stage blacklists has
  already run its network and database calls. Deployments where invocation is
  privacy-sensitive or billable SHOULD NOT enable early start.
• §5.2 — an abandoned contest (bounded out, claimed upstream, lifecycle
  ended) MUST evict its cache entry, with a wall-clock backstop.
• §5.2 — n-best resolved: the contest runs for the first candidate
  utterance, which is also Match.utterance, consistent with PIPELINE-1
  §4.1's fallback rule.

Windows, denylist, Match

• §7.2 — extension trigger defined: the collection window extends from the
  initial value toward the ceiling only while a claimant is outstanding;
  otherwise selection happens at the initial window. latency_ms is a hint —
  implausible values ignored, never pushes past the ceiling.
• §8 step 2 — the denylist filter is marked load-bearing. The PIPELINE-1
  §5.3 orchestrator backstop can never fire here, because Match.skill_id is
  the plugin's pipeline_id. The answering skill is surfaced as
  slots.skill_id (§9).
• §9 — Match.updated_session is omitted, not an echo of the inbound
  session (PIPELINE-1 §4.1).

Editorial

• §4.2 — the gate's "MUST accept" over a fuzzy predicate demoted to SHOULD;
  the accept/reject examples are informative.
• §14 — the §5.1/§5.2 early-start rules move from the SHOULD list into the
  MUST list, matching their normative text.
• §4 — rationale prose trimmed.

Not in this PR

• The pipeline-1.md:308 citation of CQ §2.1 (should be §7.2) and the §7.3
  suppression-rationale wording belong to the PIPELINE-1 PR.

🤖 Generated with Claude Code

[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: 52e543ca-7965-457f-a068-d008b0acd47a

📥 Commits

Reviewing files that changed from the base of the PR and between 1d3622b and 785cbe3.

📒 Files selected for processing (2)

• CHANGELOG.md
• common-query.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.}