docs: appendix — divergence catalogue and gaps reconciled with the refactored specs

appendix/divergences.md

@@ -49,6 +49,7 @@ that need no change:
 | PIPELINE-1 | `mycroft.skill.handler.start` / `.complete` / `.error` | `ovos.intent.handler.start` / `.complete` / `.error` | Renamed into the `ovos.intent.*` namespace for uniformity. Breaks every existing handler-lifecycle observer; the migration cost is real. |
 | PIPELINE-1 | `recognizer_loop:utterance` | `ovos.utterance.handle` | See §5.4 entry. Migration touches `ovos-dinkum-listener`, `ovos-simple-listener`, `ovos-audio`, and `ovos-core/intent_services/service.py`. |
 | PIPELINE-1 | `complete_intent_failure` | `ovos.intent.unmatched` | Follows `ovos.intent.*` namespace; pairs with `ovos.intent.matched`. |
+| COMMON-QUERY-1 | `<skill_id>:common_query` | `<skill_id>.common_query.request` | The full-answer request is a plugin-emitted addressed message, not a dispatch; MSG-1 §2.1.1 reserves the colon for dispatch-shaped topics, so it moves to the dotted form and pairs with `<skill_id>.common_query.response`. The one colon topic kept is the dispatch `<pipeline_id>:common_query`. |
 
 ### 5.2.1 Topics to remove from ovos-core
 
@@ -177,12 +178,22 @@ defined by any spec** and should be removed or replaced:
   is real — every audio-input service and intent-service
   handler is affected. A transitional deployment MAY
   subscribe to both names during migration.
+- **Transformer priority is ascending** (TRANSFORM-1 §4).
+  The reference implementation sorts transformer chains
+  descending (`reverse=True`), where the lowest number runs
+  *last* and — because each transformer's output overwrites
+  its predecessor's — effectively "wins". That is the exact
+  inverse of the spec's ascending convention (lower = earlier,
+  default 50); an inverse-convention priority assignment MUST
+  be renumbered, since run unrenumbered the chain executes
+  backwards. The TRANSFORM-1 notes in
+  [rationale.md](rationale.md) record why ascending was chosen.
 
 ### 5.5 New topics with no direct precedent
 
 - **`ovos.intent.matched`** (PIPELINE-1 §9.2). The
   positive-match broadcast notification. No current equivalent.
-- **`ovos.intent.unmatched`** (PIPELINE-1 §9.4). Renamed from
+- **`ovos.intent.unmatched`** (PIPELINE-1 §9.3). Renamed from
   `complete_intent_failure`; follows the `ovos.intent.*`
   namespace for symmetry with `ovos.intent.matched`.
 - **`ovos.utterance.speak`** (PIPELINE-1 §9.6). The NL output
@@ -228,7 +239,7 @@ defined by any spec** and should be removed or replaced:
 
 - The session object's internal shape is owned by
   OVOS-SESSION-1; the field set is the closed set defined
-  there plus whatever future specs claim via SESSION-1 §2.1.
+  there plus whatever future specs claim via SESSION-1 §2.2.
   The "extra" fields current OVOS Session carries
   (`persona_id`, `system_unit`, `time_format`, `date_format`,
   …) ride through as non-normative pass-through and may be

appendix/gaps.md

@@ -3,24 +3,15 @@
 
 ## 7. Known gaps
 
-- **Per-plugin behavioural specs.** OVOS-PIPELINE-1 defines
-  the plugin contract (the `match` shape, the orchestrator's
-  iteration semantics) but explicitly defers what each
-  non-trivial plugin type actually *does*. `converse` (OVOS-CONVERSE-1),
-  `stop` (OVOS-STOP-1), and `common_query` (OVOS-COMMON-QUERY-1)
-  have their own specs. Remaining candidates: `fallback`, `ocp`,
-  `persona`. Each defines its own internal behaviour and its
-  own bus emissions beyond the universal lifecycle PIPELINE-1
-  prescribes.
 - **Session preference fields not claimed by a spec.**
   SESSION-1 defines the wire shape and OVOS-SESSION-2 defines
-  the lifecycle and state-ownership model; what remains
-  deferred is the full set of session preferences OVOS
-  carries (`persona_id`, `time_format`, `date_format`,
-  `system_unit`, `tts_preferences`, `location`, …) — these
-  need to be claimed under SESSION-1 §2.1's field registry by
-  their respective owning specs (a preferences spec,
-  OCP / persona / locale specs as appropriate).
+  the lifecycle and state-ownership model; `persona_id` is
+  claimed by OVOS-PERSONA-1. What remains deferred is the rest
+  of the session preferences OVOS carries (`time_format`,
+  `date_format`, `system_unit`, `tts_preferences`, `location`,
+  …) — these need to be claimed under SESSION-1 §2.2's field
+  registry by their respective owning specs (a preferences
+  spec, OCP / locale specs as appropriate).
 - **Text normalization of ASR output.** The basis for slot
   value typing (INTENT-1 §5.3). Deferred to its own
   specification.
@@ -66,18 +57,21 @@
   spec-level way to know whether a remote participant is
   reachable. Deferred to a separate observability specification
   if needed.
-- **Audio transmission over the bus.** BRIDGE-1 §4.2.1 describes
-  two audio-stack placements — local (satellite runs STT and its
-  own audio-output layer) and hub-side (hub runs the full audio
-  stack, satellite transmits raw audio inbound and receives final
-  audio outbound). STT placement and audio-output placement are
-  symmetric and independent: each can live on the satellite or the
-  hub, giving four possible combinations. The hub-side model
-  requires transmitting audio as bus Message payloads (e.g.
-  base64-encoded PCM or compressed frames). The bus surface for
-  any audio transmission — topic names, payload shape, session
-  fields for codec and audio preferences — is not defined by any
-  current specification. Deferred to OVOS-AUDIO-1.
+- **Outbound audio over the bus is specified; inbound is not.**
+  BRIDGE-1 §4.2.1 describes two audio-stack placements — local
+  (satellite runs STT and its own audio-output layer) and
+  hub-side (hub runs the full audio stack). On the output side
+  the bus surface is defined by OVOS-AUDIO-1:
+  `ovos.utterance.speak.b64` → `ovos.audio.speech` for
+  remote-client TTS delivery, and base64 `audio` payloads on
+  `ovos.audio.queue` / `ovos.audio.play_sound` for sound
+  effects. OVOS-AUDIO-IN-1 §1 explicitly scopes audio
+  *capture* out ("acquisition mechanism is deployer-defined"),
+  so what remains undefined is the *inbound* leg of the
+  hub-side model — transmitting raw captured audio from the
+  satellite to a hub-side STT as bus Message payloads (topic
+  names, payload shape, session fields for codec and audio
+  preferences).
 - **Session-scoped pipeline plugin registration.** BRIDGE-1 §4.4
   and INTENT-4 §11 cover session-scoped intent registration for
   satellite-side skills. A satellite that implements a pipeline
@@ -87,12 +81,14 @@
   extension to OVOS-PIPELINE-1.
 - **Managing mode concurrent utterance race.** BRIDGE-1 §3.4.2
   says the bridge SHOULD apply `ovos.utterance.handled` session
-  updates before injecting the next utterance, but makes no
-  guarantee when both arrive simultaneously. The handling of
-  overlapping utterance rounds in managing mode — whether to
-  queue, drop, or process with a stale session — is left as a
-  deployment concern. A revision may define a normative
-  queuing policy.
+  updates before injecting the next utterance, and already
+  defines a MAY-fallback for the race — inject using the last
+  known session state, with the orchestrator supplying the
+  updated session on the following `ovos.utterance.handled`.
+  What is left open is the policy for a *second* utterance
+  arriving before the first round resolves: whether the bridge
+  queues it, drops it, or forwards it against the stale session.
+  A revision may define a normative queuing policy.
 - **NAT bijection and hub-side session cleanup.** When a bridge
   using `session_id` NAT (§3.2) disconnects a participant, the
   hub-side `session_id` may remain in the orchestrator's

appendix/patterns.md

@@ -113,7 +113,7 @@ The specs enforce this consistently:
 | Handler lifecycle trio (PIPELINE-1 §8) | `forward` | Travels toward the client alongside the dispatch |
 | `ovos.session.sync` from a handler (SESSION-2 §2.7) | `forward` | Session update travels toward the client |
 | `ovos.stop.pong` (STOP-1 §4.2) | `reply` | Response back to the stop plugin that pinged |
-| `<owner_id>.converse.response` (CONVERSE-1 §4.2) | `reply` | Response back to the converse plugin that polled |
+| `<skill_id>.converse.pong` (CONVERSE-1 §4.2) | `reply` | Response back to the converse plugin that polled |
 | Pipeline introspection response (PIPELINE-1 §10.2) | `reply` | Response back to the observer that requested |
 
 #### 3.1.3 No central correlation, no central state

appendix/rationale.md

@@ -85,7 +85,7 @@ the normative sections.
   on `session.session_id`. Multi-turn conversation, intent
   context, cross-skill state, and similar concerns are
   deferred to other specifications.
-- **Topic naming conventions** (MSG-1 v2 §2.1.2). The
+- **Topic naming conventions** (MSG-1 v2 §2.1.1). The
   conventions other specs in the family follow are
   codified as SHOULD-rules: dot-separated hierarchy
   with `:` reserved for component-pair shapes; stable

appendix/reference.md

@@ -8,7 +8,7 @@ tables that don't fit cleanly in any single normative spec.
 
 ### 6.1 Topic-name conventions across the family
 
-The naming conventions of OVOS-MSG-1 v2 §2.1.2 — dot-separated
+The naming conventions of OVOS-MSG-1 v2 §2.1.1 — dot-separated
 hierarchy, stable root, verb-tense pattern for the trailing
 segment, request/terminal pairs sharing a root verb,
 `.response` suffix, per-instance
@@ -38,7 +38,7 @@ accidentally parse responses from another.
 ### 6.2 Session-field cheat-sheet
 
 Every spec in the family that claims a `session` field does
-so via the OVOS-SESSION-1 §2.1 registry mechanism. The full
+so via the OVOS-SESSION-1 §2.2 registry mechanism. The full
 set spans four specs; this table consolidates them. All
 fields follow the canonical SHOULD-omit /
 `[]`-equivalent-to-omission wire-weight rule of
@@ -152,5 +152,5 @@ layer-2 transports (see appendix/patterns.md §3.1.2).
 | Handler-lifecycle trio `.start` / `.complete` / `.error` (PIPELINE-1 §8) | `forward` | Same direction as the inbound dispatch |
 | `ovos.session.sync` emitted inside a handler (SESSION-2 §2.7) | `forward` | Session update travels toward the originating client |
 | `ovos.stop.pong` (STOP-1 §4.2) | `reply` | Skill answers back to the stop plugin that sent the ping |
-| `<owner_id>.converse.response` (CONVERSE-1 §4.2) | `reply` | Owner answers back to the converse plugin that polled |
+| `<skill_id>.converse.pong` (CONVERSE-1 §4.2) | `reply` | Owner answers back to the converse plugin that polled |
 | Pipeline introspection response (PIPELINE-1 §10.2) | `reply` | Plugin answers back to the observer that requested |