OVOS-STOP-1 v1 — stop pipeline plugin specification

README.md

@@ -112,15 +112,16 @@ below). Adoption is voluntary; conformance, once adopted, is not.
 | OVOS-TRANSFORM-1 | [Transformer Plugins](transformer.md) | 1 | [Draft — in review (PR #20)](https://github.com/OpenVoiceOS/architecture/pull/20) |
 | OVOS-CONTEXT-1 | [Intent Context](intent-context.md) | 1 | [Draft — in review (PR #18)](https://github.com/OpenVoiceOS/architecture/pull/18) |
 | OVOS-CONVERSE-1 | [Active Handlers and Interactive Response](converse.md) | 1 | [Draft — in review (PR #25)](https://github.com/OpenVoiceOS/architecture/pull/25) |
+| OVOS-STOP-1 | [Stop Pipeline Plugin](ovos-stop-1.md) | 1 | [Draft — in review (PR #33)](https://github.com/OpenVoiceOS/architecture/pull/33) |
 
 Each spec carries its own scope statement, design rationale, and
 conformance section in its header. Open the document for the full
 picture — the tables above are an index.
 
 **Reading order by role:**
 - *Writing a skill?* INTENT-1 → INTENT-2 → INTENT-3. INTENT-4 only if you need the registration wire format.
-- *Building a pipeline plugin?* PIPELINE-1, then SESSION-1 + SESSION-2, then the role spec (CONVERSE-1, CONTEXT-1, or TRANSFORM-1).
-- *Building an orchestrator?* MSG-1 → SESSION-1 → SESSION-2 → PIPELINE-1, then INTENT-4, CONTEXT-1, CONVERSE-1, TRANSFORM-1.
+- *Building a pipeline plugin?* PIPELINE-1, then SESSION-1 + SESSION-2, then the role spec (CONVERSE-1, CONTEXT-1, TRANSFORM-1, or STOP-1).
+- *Building an orchestrator?* MSG-1 → SESSION-1 → SESSION-2 → PIPELINE-1, then INTENT-4, CONTEXT-1, CONVERSE-1, TRANSFORM-1, STOP-1.
 - *Surveying the architecture?* [appendix/overview.md §1](appendix/overview.md) for the three-stack narrative.
 
 For background — design rationale, comparisons with other systems,

ovos-pipeline-1.md

@@ -807,6 +807,25 @@ The dispatch Message's `context` (OVOS-MSG-1 §4):
   `pipeline_id` of the plugin that produced the match (§3.1). When
   the match is self-addressed (`skill_id == pipeline_id`, §7.0),
   both context keys carry the same identifier.
+- **`session.active_handlers` push.** The orchestrator **MUST**
+  push `{skill_id: <skill_id>, activated_at: <orchestrator-stamped
+  Unix timestamp in seconds>}` onto `session.active_handlers`,
+  evicting any prior entry with the same `skill_id`. The list is
+  a recency record keyed by `activated_at` — consumers determine
+  "most recently activated" by comparing timestamps, not by list
+  position. The push is
+  **suppressed** only for dispatches on reserved intent_names
+  listed in §7.3 — a reserved-name dispatch represents a
+  continuation of an already-active skill's participation or its
+  termination, not a fresh activation. The orchestrator applies
+  the polymorphism rule (§7.0) uniformly and does not otherwise
+  distinguish skill from pipeline-plugin dispatches; suppression
+  is keyed strictly off the reserved-name registry. The push is
+  applied after `Match.updated_session` is committed: a plugin
+  that mutates `active_handlers` via `updated_session` (e.g.,
+  STOP-1's global stop wiping the list) sees the stamp applied
+  on top, so the dispatched skill_id always lands at the head
+  unless the intent_name is reserved.
 
 The dispatch Message's `data`:
 
@@ -859,9 +878,13 @@ pipeline plugin role. A reserved intent_name is one that:
   reserving specification defines.
 
 A reservation is a **namespace lease**, not a dispatch
-modification. Every dispatch in this specification — including
-dispatches on reserved intent_names — fires §7.1 stamping,
-§7.2 routing, and §8 handler-trio identically. The reserving
+modification. Dispatches on reserved intent_names fire §7.1
+context stamping, §7.2 routing, and §8 handler-trio identically
+to ordinary dispatches. The one exception is the
+`session.active_handlers` push defined in §7.1, which is
+suppressed on reserved-name dispatches — a reserved name
+represents a continuation or termination of an already-active
+skill's participation, not a fresh activation. The reserving
 specification gets exclusive use of the name across the
 deployment's skill set; it gets no other privilege.
 
@@ -871,6 +894,7 @@ Reservations currently in force:
 |----------------------|----------------|--------------------------------------|
 | `converse` | OVOS-CONVERSE-1 §4 | a converse plugin's claim that `<skill_id>` (an active handler) wants this utterance — the orchestrator dispatches `<skill_id>:converse` and the owner's converse handler runs |
 | `response` | OVOS-CONVERSE-1 §5 | a converse plugin's signal that `<skill_id>` (the response-mode holder) is to receive the awaited utterance — the orchestrator dispatches `<skill_id>:response` and the owner's response handler runs |
+| `stop` | OVOS-STOP-1 §4 | a stop plugin's claim that `<skill_id>` (an active handler) should cease activity — the orchestrator dispatches `<skill_id>:stop` and the owner's stop handler runs |
 
 This specification fixes only the registry mechanism (reservation
 listing); the per-name semantics are owned by the reserving

ovos-session-1.md

@@ -192,7 +192,7 @@ session and persist across utterances.
 | `detected_lang` | string (BCP-47) | §3.2 (this spec) |
 | `pipeline` | array of string | OVOS-PIPELINE-1 §5 |
 | `intent_context` | object | OVOS-CONTEXT-1 §2 |
-| `active_handlers` | array of object `{id, activated_at}` | OVOS-CONVERSE-1 §2.1 |
+| `active_handlers` | array of object `{skill_id, activated_at, ...}` | OVOS-PIPELINE-1 §7.1 |
 | `response_mode` | object `{owner_id, expires_at}` | OVOS-CONVERSE-1 §2.2 |
 | `audio_transformers` | array of string | OVOS-TRANSFORM-1 §5 |
 | `utterance_transformers` | array of string | OVOS-TRANSFORM-1 §5 |