spec: session-1.md — register user-preference fields; one-purpose-per-field language taxonomy

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

OVOS-SESSION-1 v2

Raises OVOS-SESSION-1 to version 2 and folds in the audit rework of the
whole document. Two groups of change: new normative surface, and repairs to
what version 1 already said.

New normative surface

• §3.5 user-preference fields (new). Registers location (object),
  system_unit, time_format, date_format (strings) — the session
  origin's presentation preferences, so a component answering a remote
  participant renders times, dates, units, and place-relative answers for
  the user's locale rather than the device's. The three string fields have
  closed value spaces (metric/imperial, full/half, DMY/MDY);
  location states its full nested key shape (city, coordinate,
  timezone) as §2.2 requires of any object claim. All four are override
  fields: absence resolves to deployment configuration.
• §3.5 deliberately unregistered: transient audio state. is_speaking /
  is_recording describe the device at an instant, not the session, and are
  stale by the time a propagated session is read. Such a field is therefore
  not a field of session (§2.3); a consumer tolerates it under §2.4 and
  SHOULD NOT act on its value. The authoritative surface is OVOS-AUDIO-1
  — the §5.1–§5.2 output-lifecycle signals and the §5.3
  ovos.audio.is_speaking query for on-demand status.
• §3.2 language taxonomy. The six signals get a one-purpose-per-field
  summary table and an explicit split into preference (lang,
  secondary_langs, output_lang) and per-utterance observation
  (stt_lang, request_lang, detected_lang).
• §3 preamble. Session scope is not uniform persistence: observation
  fields are the current reading and a consumer MUST NOT read a surviving
  value as a description of an older utterance.
• §3.4 case 4. An empty object on an object-valued override field is
  wire-equivalent to omission, on the same grounds as the existing
  empty-array case. State-record fields are excluded — for those the empty
  value is the owner-specified resolution, not a deferral.
• §3.1 remote sessions. A remote participant that carries a session
  identity of its own SHOULD send that identifier rather than "default"
  for its own conversational traffic.

Repairs to version 1

• §2 — a wrong-typed value is malformed and MUST be treated as omitted.
  §2.5 already argued from this rule; no section stated it.
• §2.1 — omission resolved in two classes. Override fields fall back
  to deployment configuration. State-record fields (active_handlers,
  converse_handlers, response_mode, intent_context) fall back to the
  empty value their owner names — [], {}, "no holder" — never to
  deployment configuration, which v1 wrongly implied for all fields.
• §2.2 — wire-type vocabulary: integers are claimed as number with the
  constraint in the claiming spec's value space (JSON has one numeric type);
  array claims state element type, object claims state every key.
• §3.2.3 — the MUST NOT on silently rendering in another language was
  discharged only by a SHOULD. The record is now a MUST to set
  data.lang to the language actually rendered in.
• §3.3 — restated as a pointer with OVOS-BRIDGE-1's constraints quoted
  verbatim. v1's local restatement dropped the "after bridge processing"
  precondition and so banned the override that BRIDGE-1 §3.3 step 1 requires.
• §4 — the SHOULD→MUST strengthening of OVOS-MSG-1 §4.1 is now stated
  explicitly, with its rationale, instead of applied silently.
• §4.1 — materialization cited to the OVOS-MSG-1 §5.1–§5.3 derivations;
  the phantom quotation ("any device-local fields the implementation
  chooses", which appears nowhere in MSG-1) is dropped.
• §5 — carrier-parse failure defers to §2.5, so its
  no-default-substitution guarantee is not lost on the routing path.
• §3.1 — default-session ownership cite corrected to OVOS-SESSION-2 §5
  (was §6).
• §3.2.5 — the wake-word-derived request_lang hint cites its
  observable source, ovos.listener.wakeword (OVOS-AUDIO-IN-1 §6.5).
• Editorial — propagation cited uniformly as OVOS-MSG-1 §4.1 +
  §5.1–§5.3; intro reconciled with §2.2 (the registry is the closed set, §3
  enumerates it at publication); §1 no longer disclaims the ~200 lines of
  field semantics this spec owns itself; RFC key-word list completed with
  OPTIONAL / RECOMMENDED and the RFC 8174 caveat; descriptive residue in
  §3.1, §3.2.3, and §3.4 cut or labelled informative.
• CHANGELOG — v2 entry rewritten for the final state; the v1 entry's
  registry cite (§2.1 → §2.2/§3) and roster description corrected.

Dropped from the original PR

• Thin-session note in §3.4 — cited an OVOS-SESSION-2 §3.2 allowance for
  {"session_id": ...} on intermediate emissions. SESSION-2 §3.2 states no
  such rule; it says the opposite ("every assistant-emitted Message carries
  an updated session"). If the allowance is wanted it must land in SESSION-2
  first. The twin hunk is dropped from the SESSION-2 PR too.
• The unconditional §3.1 SHOULD — as originally written, "a remote
  participant SHOULD use a distinct session_id" contradicted the surviving
  paragraph calling remote use of "default" "equally valid", and pushed
  against §2.1's MUST NOT to treat absence as an untrusted origin. It is now
  scoped to participants that have a session identity of their own, and the
  layer-2 gate is back to MAY.
• The duplicate language-count fix — superseded by docs: fix stale language signals count in session-1 #132, already on
  dev.

Dependencies

• The README spec table still lists OVOS-SESSION-1 at version 1. The row
  belongs to spec: README.md — spec-index titles match the spec headers #128 (README), which should land after this.
• Merge order per the family plan: PIPELINE-1 + MSG-1 first, then this.

[coderabbitai]

Warning

Review limit reached

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

Next review available in: 36 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: 0a7bdaf4-3a1f-44a3-9c2a-2109c1ba6d52

📥 Commits

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

📒 Files selected for processing (2)

• CHANGELOG.md
• session-1.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch spec/session-1

---

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