spec: session-2.md — v2 write model, sync semantics and default-store rules

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

Reworks OVOS-SESSION-2 into version 2. The previous revision of this branch
proposed three changes; one of them is dropped here and two are reworked, and
the audit findings against the spec on dev are applied on top.

Version 2 is not compatible with version 1

Version 1 left the write model under-determined, and this revision determines
it. Version 1 did not distinguish the two write paths onto the default session,
defined no ordering across the four in-utterance write paths, and required
ovos.session.sync to reach terminal events in §2.7 while §2.6 forbade any
out-of-boundary Message to mutate session mid-utterance. An implementation
built against version 1 can satisfy version 1 and violate version 2 — the
wholesale-replace pathway and the §2.8 ordering both constrain behaviour that
version 1 permitted freely. The bump is therefore a compatibility-class change,
not a cosmetic one.

Write model

• §2.8 is new. It fixes the order in which the inbound merge, transformer
  hooks, match-phase writes, dispatch-time orchestrator writes and
  handler/sync writes apply, and resolves conflicts as last-writer-wins per
  field, so components writing disjoint fields never conflict. Two exceptions
  are named (finer intra-field merges, and the wholesale-replace pathway), and
  unorderable ties are stated to have no defined winner, because the bus
  carries no ordering guarantee.
• §5.1 wholesale replacement now says a field absent from
  Match.updated_session reverts to the deployment default at consumption
  rather than being "deleted" — a consumer never sees a hole. The
  active_handlers push of PIPELINE-1 §7.1 and the entry-level
  intent_context merge of OVOS-CONTEXT-1 §5.3 are carved out, since both
  specs already fix them as applying on top of the committed snapshot.
• §5.1 owns its deviation from SESSION-1 §2.1. The omitted-field-leaves-
  stored-value rule was previously attributed to SESSION-1 §2.1, which says the
  opposite (omission is filled with the deployment default). The deviation is
  real and deliberate, confined to writes into the default-session store, and
  is now stated as such.
• §5.1 default-store write acceptance. The orchestrator merges a
  session-less inbound Message into the store only where the writer plausibly
  is the local device. Without this, any session-less remote write lands in the
  local device's session.

Sync semantics

• §2.6 carves ovos.session.sync out of the incidental-bus-event rule it
  previously contradicted, and states the visibility split: a merged sync
  reaches terminal-event snapshots and any matcher or hook not yet run, and
  never revises a snapshot a consumer already holds.
• §2.6 handler boundary is bounded to fields the handler owns, citing
  OVOS-MSG-1 §4.1's owned-field allowance as what makes the in-place path
  conformant. The handler in-place path is kept; it is not redesigned into
  sync-only.
• §2.7 makes field replacement the default merge rule, permits a claiming
  specification to define a finer intra-field merge, and names
  session.intent_context (OVOS-CONTEXT-1 §5.3) as the one such field today.
• §2.7 defines the previously-undefined cases: a sync on a named session
  with no utterance in flight is an orchestrator no-op (creating state would
  break §2.2) while the owning client still consumes it, and nested lifecycles
  bind the innermost lifecycle in flight.

Client adoption

§3.2 retires "latest received" as a client policy — the bus guarantees no
delivery order, so adopting whichever Message arrived last can install an older
view over a newer one. Adoption at ovos.utterance.handled is RECOMMENDED;
incremental adoption stays a MAY with an explicit staleness warning and a
SHOULD to converge at §3.3.

Dropped from the previous revision: thin intermediate emissions

The previous revision let intermediate and status emissions carry a session of
only {"session_id": ...}. That is removed, not reworked. It contradicted the
opening sentence of the very section it was added to, and §2.7/§6.2 both
require the handler-lifecycle .complete event to carry the merged sync state.
More fundamentally, a thin session is not a thin snapshot: omission means
"deployment default at consumption" (SESSION-1 §2.1), so a client adopting a
thin session would resolve every omitted field to its own defaults and lose
state, rather than merely receiving less of it. It also introduced a REQUIRED
that appeared in no conformance list.

The wire-weight concern behind it is real and already has an instrument:
SESSION-1 §3.4's omit-when-wire-equivalent-to-omission rule, which every
field-claiming specification inherits. That rule cuts the same bytes without
the state loss, because it only omits fields whose value already equals what
the consumer would compute.

Cross-PR dependencies

• msg-1. §2.6 cites OVOS-MSG-1 §4.1's owned-field allowance. That allowance
  is added by the msg-1 PR and is not yet on dev; merge msg-1 first or the
  citation points at a section that still forbids the write outright.
• bridge-1. §5.1 names OVOS-BRIDGE-1 §3.4 as the enforcement point for
  stamping a non-default session_id on relayed inbound traffic. §3.4 exists
  today but does not yet carry that obligation; it lands in the bridge-1 PR.

Also in this revision

Reworks the §2.5 bridge-gate paragraph into a single non-normative pointer to
OVOS-BRIDGE-1 §4.1, rather than restating that spec's MUST. Stops restating
PIPELINE-1 §4.2's commit mechanic and §5.1/§2.7's merge rules in the
conformance section. Separates specification-claimed fields from component
projection: only a specification claims a field under SESSION-1 §2.2, and a
component projecting into an unclaimed field rides SESSION-1 §2.4 tolerance
with no normative reading by anyone else. Rewords the unverifiable
"MUST NOT be expected to" obligations as behaviour required of a named actor.
Pins every end-marker citation to PIPELINE-1 §9.5. Marks the descriptive
passages in §2.3, §2.4, §2.5, §4.3 and §5.2 informative. Folds the dead §5.4
into §7 as a deployment note. Scopes the §2.7 payload note, which previously
applied §5.1's default-store rule to every receiver.

[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: 399c3594-a584-4a11-b618-bd887a2ee183

📥 Commits

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

📒 Files selected for processing (2)

• CHANGELOG.md
• session-2.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

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

---

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