From d90664e5564075d1eca630ffc0cd09f53b2e4e04 Mon Sep 17 00:00:00 2001 From: JarbasAi Date: Tue, 4 Aug 2026 13:51:05 +0100 Subject: [PATCH] =?UTF-8?q?docs:=20appendix=20=E2=80=94=20divergence=20cat?= =?UTF-8?q?alogue=20and=20gaps=20reconciled=20with=20the=20refactored=20sp?= =?UTF-8?q?ecs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Squashed from: - docs: appendix — reconciliation re-verified against dev; MSG-1 v2 §2.1.1 cites - docs: cite the SESSION-1 field registry as §2.2 - docs: appendix — reconcile divergence catalogue and gaps with the refactored specs Co-Authored-By: Claude Fable 5 --- appendix/divergences.md | 15 ++++++++-- appendix/gaps.md | 64 +++++++++++++++++++---------------------- appendix/patterns.md | 2 +- appendix/rationale.md | 2 +- appendix/reference.md | 6 ++-- 5 files changed, 48 insertions(+), 41 deletions(-) diff --git a/appendix/divergences.md b/appendix/divergences.md index 3f631b0c..be7d78d0 100644 --- a/appendix/divergences.md +++ b/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 | `:common_query` | `.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 `.common_query.response`. The one colon topic kept is the dispatch `: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 diff --git a/appendix/gaps.md b/appendix/gaps.md index 8018766e..1c368146 100644 --- a/appendix/gaps.md +++ b/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 diff --git a/appendix/patterns.md b/appendix/patterns.md index e2d2ea96..7a63590d 100644 --- a/appendix/patterns.md +++ b/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 | -| `.converse.response` (CONVERSE-1 §4.2) | `reply` | Response back to the converse plugin that polled | +| `.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 diff --git a/appendix/rationale.md b/appendix/rationale.md index 9981c15c..fdb5ec8b 100644 --- a/appendix/rationale.md +++ b/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 diff --git a/appendix/reference.md b/appendix/reference.md index fd8ba071..23053735 100644 --- a/appendix/reference.md +++ b/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 | -| `.converse.response` (CONVERSE-1 §4.2) | `reply` | Owner answers back to the converse plugin that polled | +| `.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 |