OVOS-INTENT-3 v1.1 — rename "host" to "orchestrator"#13
Merged
Conversation
|
Warning Review limit reached
Your plan currently allows 1 review/hour. Refill in 44 minutes and 52 seconds. Your organization has run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After more review capacity refills, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than trial, open-source, and free plans. In all cases, review capacity refills continuously over time. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (2)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
JarbasAl
added a commit
that referenced
this pull request
May 24, 2026
Refactors INTENT-4 around the refined pipeline-plugin model discussed for OVOS-PIPELINE-1: - Registrations are **broadcast** on the bus. There is no central party that owns, validates, or routes them. Pipeline plugins (OVOS-PIPELINE-1) consume what they want. The orchestrator passively indexes everything for the introspection topics. - INTENT-4 shrinks ~30% (1100 → 736 lines) by moving the bus-level utterance lifecycle (match-result notification, dispatch, handler-lifecycle trio) into OVOS-PIPELINE-1, where it belongs. - Title becomes "Intent and Entity Registration Bus Contract" (was "...and Dispatch"). The spec is now purely about how a skill puts an intent on the bus — what happens to it after that is OVOS-PIPELINE-1's domain. Sections removed (moved to OVOS-PIPELINE-1): - §10 The match-result message (ovos.intent.matched) - §11 Dispatch (<skill_id>:<intent_name>) - §12 Handler-lifecycle messages (ovos.intent.handler.*) - §15 Other utterance-lifecycle messages (out of scope) Sections rewritten: - §1 Scope — much shorter; lists registration topics only, explicit pointer to PIPELINE-1 for the rest - §2 Architectural model — "registrations are broadcast" instead of "host as sole consumer". The orchestrator is now described as a passive indexer, not a routing party. - §3.2 Responses — now plugin-optional; no orchestrator handshake. Producers must not require a response. - §3.3 Error codes — drops `no_compatible_engine` (no central rejection party); the remaining four codes are plugin-emitted on `.response` rejections only. - §4 Topics table — broadcast direction marked explicitly; references to the moved topics are removed. - §10 Introspection — reframed as the orchestrator's passive registration index; clearer that it reflects what skills declared, not what plugins matched. - §11 Conformance — split per-party (skill MUST, plugin MAY, orchestrator MUST). Orchestrator's only responsibility is the passive index. Also folds in the "host → orchestrator" rename (companion to INTENT-3 v2 in #13). 81 occurrences renamed; one explanatory sentence added in §2. CHANGELOG, README, GLOSSARY updated to match. Cross-spec composition: - OVOS-MSG-1: unchanged - OVOS-INTENT-3 v2 (#13): provides the renamed "orchestrator" term - OVOS-INTENT-4 (this PR): pure registration protocol - OVOS-PIPELINE-1 (#11, draft): owns everything else (orchestrator contract, pipeline plugins, utterance lifecycle, dispatch, handler-lifecycle trio, terminal events) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Editorial rename of the term throughout §6.1, §6.2, §7, §8. Conformance semantics are unchanged. Minor version bump (v1 → v1.1) since nothing in the contract broke; the rename is timeless. The renamed term names the function (coordinating intent matching and dispatch). Distinct from the messagebus (transport) and from individual engines. CHANGELOG, README, GLOSSARY updated to match. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
JarbasAl
force-pushed
the
spec/intent3-v2-orchestrator-rename
branch
from
4fbebab to
95d92ce
Compare
JarbasAl
changed the title
JarbasAl
added a commit
that referenced
this pull request
May 24, 2026
… out Refactors INTENT-4 around the pipeline-plugin model from OVOS-PIPELINE-1: - Registrations are **broadcast** on the bus. There is no central party that owns, validates, or routes them. Pipeline plugins (OVOS-PIPELINE-1) consume what they want. The orchestrator passively indexes everything for the introspection topics. The bus-level utterance lifecycle (match-result notification, dispatch, handler-lifecycle trio) moved out to OVOS-PIPELINE-1 where it belongs. Sections removed (moved to OVOS-PIPELINE-1): - The match-result message (ovos.intent.matched) - Dispatch (<skill_id>:<intent_name>) - Handler-lifecycle messages (ovos.intent.handler.*) - Other utterance-lifecycle messages Sections rewritten: - §1 Scope — shorter; registration topics only; explicit pointer to PIPELINE-1 for the rest. - §2 Architectural model — "registrations are broadcast" (no central consumer or router). Orchestrator is passive indexer. - §3.2 Responses — plugin-optional; no orchestrator handshake. - §3.3 Error codes — plugin-emitted only; drops `no_compatible_engine` (no central rejection party). - §4 Topics table — broadcast direction marked explicitly. - §10 Introspection — reframed as orchestrator's passive registration index. - §11 Conformance — split per-party (skill MUST, plugin MAY, orchestrator MUST). Also folds in: - Rename host → orchestrator (companion to INTENT-3 v1.1 in #13). - Removal of the in-spec legacy-mapping appendix (the spec body is now timeless; predecessor-topic mapping is implementation history and belongs in APPENDIX.md, covered in a separate commit). The spec body now references no specific code paths, no Mycroft history, no "current OVOS" qualifiers. All such context lives in APPENDIX.md. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Per draft-stage versioning policy: while a spec is in draft, v1 remains v1 if compatible with current OVOS; a version bump is only triggered by an incompatible feature. The host→orchestrator rename is editorial and drop-in compatible — fold into the v1 release rather than carrying a v1.1 line. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2 tasks
JarbasAl
added a commit
that referenced
this pull request
May 24, 2026
… out Refactors INTENT-4 around the pipeline-plugin model from OVOS-PIPELINE-1: - Registrations are **broadcast** on the bus. There is no central party that owns, validates, or routes them. Pipeline plugins (OVOS-PIPELINE-1) consume what they want. The orchestrator passively indexes everything for the introspection topics. The bus-level utterance lifecycle (match-result notification, dispatch, handler-lifecycle trio) moved out to OVOS-PIPELINE-1 where it belongs. Sections removed (moved to OVOS-PIPELINE-1): - The match-result message (ovos.intent.matched) - Dispatch (<skill_id>:<intent_name>) - Handler-lifecycle messages (ovos.intent.handler.*) - Other utterance-lifecycle messages Sections rewritten: - §1 Scope — shorter; registration topics only; explicit pointer to PIPELINE-1 for the rest. - §2 Architectural model — "registrations are broadcast" (no central consumer or router). Orchestrator is passive indexer. - §3.2 Responses — plugin-optional; no orchestrator handshake. - §3.3 Error codes — plugin-emitted only; drops `no_compatible_engine` (no central rejection party). - §4 Topics table — broadcast direction marked explicitly. - §10 Introspection — reframed as orchestrator's passive registration index. - §11 Conformance — split per-party (skill MUST, plugin MAY, orchestrator MUST). Also folds in: - Rename host → orchestrator (companion to INTENT-3 v1.1 in #13). - Removal of the in-spec legacy-mapping appendix (the spec body is now timeless; predecessor-topic mapping is implementation history and belongs in APPENDIX.md, covered in a separate commit). The spec body now references no specific code paths, no Mycroft history, no "current OVOS" qualifiers. All such context lives in APPENDIX.md. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
JarbasAl
added a commit
that referenced
this pull request
May 26, 2026
… out Refactors INTENT-4 around the pipeline-plugin model from OVOS-PIPELINE-1: - Registrations are **broadcast** on the bus. There is no central party that owns, validates, or routes them. Pipeline plugins (OVOS-PIPELINE-1) consume what they want. The orchestrator passively indexes everything for the introspection topics. The bus-level utterance lifecycle (match-result notification, dispatch, handler-lifecycle trio) moved out to OVOS-PIPELINE-1 where it belongs. Sections removed (moved to OVOS-PIPELINE-1): - The match-result message (ovos.intent.matched) - Dispatch (<skill_id>:<intent_name>) - Handler-lifecycle messages (ovos.intent.handler.*) - Other utterance-lifecycle messages Sections rewritten: - §1 Scope — shorter; registration topics only; explicit pointer to PIPELINE-1 for the rest. - §2 Architectural model — "registrations are broadcast" (no central consumer or router). Orchestrator is passive indexer. - §3.2 Responses — plugin-optional; no orchestrator handshake. - §3.3 Error codes — plugin-emitted only; drops `no_compatible_engine` (no central rejection party). - §4 Topics table — broadcast direction marked explicitly. - §10 Introspection — reframed as orchestrator's passive registration index. - §11 Conformance — split per-party (skill MUST, plugin MAY, orchestrator MUST). Also folds in: - Rename host → orchestrator (companion to INTENT-3 v1.1 in #13). - Removal of the in-spec legacy-mapping appendix (the spec body is now timeless; predecessor-topic mapping is implementation history and belongs in APPENDIX.md, covered in a separate commit). The spec body now references no specific code paths, no Mycroft history, no "current OVOS" qualifiers. All such context lives in APPENDIX.md. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
JarbasAl
added a commit
that referenced
this pull request
May 26, 2026
* docs: OVOS-INTENT-4 — intent and entity registration and dispatch bus contract
Defines the full bus lifecycle of an intent on top of OVOS-MSG-1 and
OVOS-INTENT-3: registration, match notification, dispatch, and the
handler-lifecycle trio.
Topics defined:
- ovos.intent.register.keyword / .template — atomic per-intent
registration (replaces register_vocab + register_intent /
padatious:register_intent dance)
- ovos.entity.register — entity-hint registration (replaces
padatious:register_entity)
- ovos.intent.deregister / .enable / .disable, ovos.entity.deregister,
ovos.skill.deregister
- ovos.intent.list / .describe — introspection
- ovos.intent.matched — broadcast match-result notification
- <skill_id>:<intent_name> — dispatch topic, kept verbatim from
current OVOS so existing skill handler subscriptions need no change
- ovos.intent.handler.{start,complete,error} — handler-lifecycle
trio (renamed from mycroft.skill.handler.* for uniformity)
Architectural model: the host is the sole bus consumer of skill-
originated registration topics and delegates matching to its engines
through a host-internal interface. Engines do not subscribe to the
bus topics defined here. Aligned to OVOS-INTENT-3's keyword/template
duality.
The handler reference is local to the skill and never crosses the
bus; only the dispatch Message and the handler-lifecycle messages do.
APPENDIX additions:
- New §4 subsection: INTENT-4 design rationale (host as sole consumer,
atomic registration, kept dispatch topic, trio not response, rename)
- §6 (Where specs differ from OVOS) extended with INTENT-4-specific
subsections: topic renames, payload shape changes, architectural
divergences, things deliberately not changed
- §9.1 design history updated to mention five specs in two stacks
This is the spec that needs more review and more implementation effort
than MSG-1 — it changes registration topic names and payload shapes,
introduces the host-mediated architectural model (today some engines
subscribe directly to bus topics), and prescribes a uniform `captures`
map for dispatch payloads.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs: INTENT-4 — distinguish utterance-layer from handler-layer lifecycle
The current §12 trio (handler-layer) and §10 match notification were
read as the only lifecycle signals around an utterance. They aren't.
ovos-core's pipeline emits utterance-layer messages that operate at
a different level and must not be confused with handler signals.
Verified flow in ovos-core/intent_services/service.py:
recognizer_loop:utterance → entry
├─ transformer cancel: ovos.utterance.cancelled + ovos.utterance.handled
├─ pipeline match: <skill_id>:<intent_name> → handler trio
│ + ovos.utterance.handled (from workshop _on_event_end)
└─ no match: complete_intent_failure + ovos.utterance.handled
ovos.utterance.handled is the universal end-marker, fired on every
terminal path; complete_intent_failure is the intent-layer failure;
the handler trio is purely handler-layer. The previous Appendix A
entry calling ovos.utterance.handled "subsumed by
ovos.intent.handler.complete" was wrong — they're at different
lifecycle levels.
Changes:
INTENT-4 §1 scope: explicitly defers the broader utterance lifecycle
and the intent-layer failure signal to the future pipeline spec.
INTENT-4 §12.6 (new): "This trio is handler-layer only" — table of
the three lifecycle levels (utterance / intent matching / handler)
and how implementers should distinguish them. Points forward to §15.
INTENT-4 §15 (new): "Other utterance-lifecycle messages (out of
scope)" with four subsections:
- §15.1 ovos.utterance.handled is utterance-layer, not handler-layer
- §15.2 complete_intent_failure and handler error are different
- §15.3 The deferred trio — table of the three trios and what
this spec formalizes vs defers
- §15.4 A known asymmetry in current OVOS: workshop's
_on_event_error doesn't emit ovos.utterance.handled. The spec
declares the invariant normative; the workshop fix is a
separate implementation bug.
INTENT-4 Appendix A: fix the wrong "subsumed" claim on
ovos.utterance.handled (mark as unchanged with §15.1 explanation);
add three new rows for complete_intent_failure,
ovos.utterance.cancelled, recognizer_loop:utterance — all marked
unchanged-and-out-of-scope, pointing at §15.
APPENDIX §6.4: add the workshop _on_event_error asymmetry as a known
architectural divergence with a forward reference to INTENT-4 §15.4.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs: OVOS-INTENT-4 — pure registration-protocol spec; appendix moved out
Refactors INTENT-4 around the pipeline-plugin model from
OVOS-PIPELINE-1:
- Registrations are **broadcast** on the bus. There is no central
party that owns, validates, or routes them. Pipeline plugins
(OVOS-PIPELINE-1) consume what they want. The orchestrator
passively indexes everything for the introspection topics.
The bus-level utterance lifecycle (match-result notification,
dispatch, handler-lifecycle trio) moved out to OVOS-PIPELINE-1
where it belongs.
Sections removed (moved to OVOS-PIPELINE-1):
- The match-result message (ovos.intent.matched)
- Dispatch (<skill_id>:<intent_name>)
- Handler-lifecycle messages (ovos.intent.handler.*)
- Other utterance-lifecycle messages
Sections rewritten:
- §1 Scope — shorter; registration topics only; explicit pointer
to PIPELINE-1 for the rest.
- §2 Architectural model — "registrations are broadcast" (no
central consumer or router). Orchestrator is passive indexer.
- §3.2 Responses — plugin-optional; no orchestrator handshake.
- §3.3 Error codes — plugin-emitted only; drops
`no_compatible_engine` (no central rejection party).
- §4 Topics table — broadcast direction marked explicitly.
- §10 Introspection — reframed as orchestrator's passive
registration index.
- §11 Conformance — split per-party (skill MUST, plugin MAY,
orchestrator MUST).
Also folds in:
- Rename host → orchestrator (companion to INTENT-3 v1.1 in #13).
- Removal of the in-spec legacy-mapping appendix (the spec body
is now timeless; predecessor-topic mapping is implementation
history and belongs in APPENDIX.md, covered in a separate
commit).
The spec body now references no specific code paths, no Mycroft
history, no "current OVOS" qualifiers. All such context lives in
APPENDIX.md.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* INTENT-4: release as v2 (incompatible with current OVOS)
Per the draft-stage versioning policy, v1 is reserved for content
drop-in compatible with current OVOS. INTENT-4's topic-namespace
rename and the orchestrator passive registration index both
require OVOS-side changes, so the first release ships as v2.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* INTENT-4 CHANGELOG: clarify V2 trigger is the topic rename, not the passive registry
* GLOSSARY: fix stale session.pipeline_stages → session.pipeline
* scope: drop APPENDIX/CHANGELOG/GLOSSARY/README/intent-definition; PR #9 is intent-registration.md only per 1-file rule
* OVOS-INTENT-4: announce-on-load + pull-query pattern; skills are authoritative responders
Two related changes around §10 introspection:
§2 — orchestrator's passive index is now MAY, not MUST. Skills
are the authoritative source for their own registrations. The
orchestrator is a logical role; it MAY be implemented as multiple
cooperating processes (PIPELINE-1 §2), each maintaining its own
index slice and responding independently to §10 queries.
§10 — reframed as **broadcast-query / scatter-response** to
explicitly handle load-ordering:
- Registration topics (§5-§8) are themselves load-time
announcements. Consumers that subscribed before the skill loaded
receive them in real time; consumers that started later have
missed them.
- Pull-query via §10 topics is the catch-up mechanism. Skills
MUST respond to queries that match their own registrations
(authoritative source). Orchestrator MAY also respond from its
passive index as a convenience. Consumers aggregate responses
across responders.
- The bus is async with no completeness signal; consumers wanting
guaranteed completeness keep their own roster of expected
responders and time out non-responders.
§11 conformance updated:
- Skills MUST respond to §10 queries for their own registrations.
- Orchestrator's index becomes MAY (was MUST). When maintained, the
prior MUST-bullets apply. An orchestrator without an index is
conformant — skills handle the introspection load.
This aligns INTENT-4 with the same pattern TRANSFORM-1 §6 uses:
producers MAY announce on load (these are the §5-§8 broadcasts);
consumers MUST query when they need accurate state because load
ordering between producer and consumer on the bus is not
guaranteed.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* INTENT-4: orchestrator owns the manifest; skills have no .list duty
§10 (rewritten): the introspection surface is the orchestrator-
owned manifest of observed registrations. Skills have NO
introspection obligation under this spec — they emit
registrations once at load and move on. Per-pipeline-plugin
compiled state is queried via OVOS-PIPELINE-1 §10 (distinct
surface). Adds pull-query-is-source-of-truth boilerplate
parallel to TRANSFORM-1 §6 / CONTEXT-1 §5.4.
§3.3: add idempotent-deregistration carve-out. Plugins SHOULD
reject unknown_intent / unknown_entity / unknown_skill but MAY
treat as no-op success during shutdown. Producers wanting
idempotent removal MAY ignore unknown_* codes.
§11 conformance: drop skill MUST-respond to §10 queries (no
skill-side obligation). Orchestrator promoted from MAY-index to
MUST-maintain-manifest + MUST-serve-§10-queries. Split-
orchestrator: per-process manifest slices, consumers aggregate.
See-also: add MSG-1 §2.1.1 reference, SESSION-1.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* INTENT-4: skill_id emission discipline; RFC 2119 tightening; split-orch ref
§3.1 (new): A skill MUST set Message.context["skill_id"] on every
Message it emits. This is the authoritative attribution surface
for skill-originated bus traffic; observers MUST NOT infer the
originating skill from data fields or topic names. Specifically
a skill discipline — orchestrator and infrastructure components
identify via source and component-specific context keys.
§3 renumbered: §3.1 Identity → §3.2; §3.2 Responses → §3.3; §3.3
error_codes → §3.4. All internal cross-refs updated.
§2: tighten with explicit MUST NOT on producer-side acknowledgement
reliance. Reduce split-orchestrator restatement to a one-sentence
reference to PIPELINE-1 §2. Drop the "skill-side authoritative
record" language that no longer applies after the §10 rewrite
(orchestrator owns the manifest now; skills have no .list duty).
§11 skill conformance: add skill_id-on-every-emission line.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* INTENT-4 §3.1: fix source-as-identity wording — source is opaque metadata
Per design correction: no spec prescribes source as an identity
surface for any component. It is opaque metadata typically populated
by the originator and propagated by MSG-1 §5 derivations.
Components that need to identify themselves use their own
component-specific reserved context keys (pipeline_id,
transformer_id, future entry-service identity).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* INTENT-4 §3.1: clarify data.skill_id vs context.skill_id + loader enforcement
data.skill_id (when defined by a topic's payload schema) is the
SUBJECT of the operation — a search filter, a target, an owning
skill. context.skill_id is the EMITTER. The two MAY differ.
Adds orchestrator-side enforcement rule: a skill loader MUST
intercept the skill's emit pathway and enforce
context.skill_id == loaded skill's skill_id whenever possible, so
non-compliant handlers can't escape attribution. Places the
discipline on infrastructure, not skill authors.
Cross-references CONTEXT-1 §5.2 as an example of a topic owning
spec that rejects messages lacking context.skill_id.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* INTENT-4 §3.3: producers MUST NOT block waiting for .response; use §10 instead
Closes the response-timing gap: producers naively blocking on
.response could wait indefinitely (the spec already says emission
is plugin-discretionary). Explicit MUST NOT block, plus pointer to
§10 manifest query as the supported verification path.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* INTENT-4 §3.1: structural enforcement via dispatch context.skill_id stamping
Per design clarification: the cleanest enforcement path is
structural, not interception-based. The orchestrator stamps
context.skill_id from the dispatch topic prefix
(PIPELINE-1 §7.1); skill emissions via forward/reply inherit
automatically. Interception is reserved for emissions outside
the dispatch path (background workers, initiative-driven traffic).
A drift between context.skill_id and the dispatch <skill_id> is
malformed and detectable — the spec now names this as the
authoritative non-conformance signal.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* INTENT-4 §4: fix PIPELINE-1 section pointer §§9–10 → §§7–9
Cross-spec audit: the trailing pointer in §4's topic table cited
'OVOS-PIPELINE-1 §§9–10' for match notification, dispatch, and
the handler-lifecycle trio. PIPELINE-1 actually houses these in
§§7–9 (§7 dispatch, §8 handler-lifecycle, §9 utterance-layer
events). Old reference pre-dated a PIPELINE-1 numbering revision.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* INTENT-4 §3.1: split stamp rule (originate + modify); add coexistence-with-other-identity-keys paragraph; update Other component types cross-ref
Aligning skills' rule with the uniform MUST-stamp-on-originate-or-
modify discipline adopted across PIPELINE-1 §3.1 and TRANSFORM-1
§1.3.
Added explicit coexistence paragraph: a Message MAY carry other
component-identity keys (context['pipeline_id'], the six
<type>_transformer_id keys) in addition to context['skill_id'].
MSG-1 §5 derivations preserve all such keys; this spec doesn't
require skills to strip them, and consumers MUST NOT treat
multiple identity keys as malformed. Attribution resolves via
CONTEXT-1 §5.2 precedence.
Other component types subsection updated to name the parallel
disciplines (PIPELINE-1 §3.1, TRANSFORM-1 §1.3) and to list the
six per-type transformer keys explicitly.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* INTENT-4 §3.1: stamp rule covers derivations placed on the bus by the skill
Same correction as PIPELINE-1 §3.1: a derivation (forward, reply,
response) the skill performs and emits IS a skill emission. The
resulting Message-on-wire MUST carry context['skill_id'] regardless
of derivation mechanism. The most common case — a handler's .speak
forwarded from a dispatch — is already structurally satisfied
because the dispatch-stamping rule propagates the skill's own id
through .forward; the explicit rule binds for derivations from
non-dispatch sources.
Also updated cross-spec refs to TRANSFORM-1 plural list-valued
<type>_transformer_ids shape.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* INTENT-4 §3.1, §3.3: forward exemption + tighten .response MUST/SHOULD
- §3.1 stamp rule: pure-forward propagation exempt. Same shape
as the PIPELINE-1 §3.1 / TRANSFORM-1 §1.3 changes: .reply /
.response are authorial and MUST stamp; .forward is propagation
and MUST NOT overwrite inherited context['skill_id']. The
dispatch-stamping rule keeps the typical .forward-from-dispatch
path correct by construction (the inherited value is already
the skill's own id).
- §3.3 response asymmetry: a consuming plugin now MUST emit
ok: false on rejection (silent rejection is non-conformant —
the producer cannot distinguish 'rejected here' from 'no
consumer'), and SHOULD emit ok: true on success. The
asymmetry is justified: rejection carries actionable
information; success is more reliably observed via §10
introspection than per-emission ack.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* INTENT-4 §8.4: relax MUST-reject to SHOULD; align with §3.4 idempotent-deregistration carve-out
§3.4 already permitted plugins to respond {ok: true} on
idempotent deregistration (a deliberate carve-out for skill
shutdown sequences). §8.4 still demanded MUST-reject with
unknown_*. The two contradicted.
Aligned: §8.4 is now SHOULD-reject, MAY-no-op-success, with
cross-reference to §3.4's carve-out. Both responses are equally
conformant; choice is per-plugin.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* INTENT-4 §3.4, §3.5: reject registrations of reserved intent_names
Add new error_code 'reserved_name' and a §3.5 cross-reference to
OVOS-PIPELINE-1 §7.3's reserved-intent-name registry. The orchestrator
MUST reject registration payloads that name an intent_name reserved
by a companion specification.
Currently reserved: converse and response, both by OVOS-CONVERSE-1
(PR #25). The reservation registry is owned by PIPELINE-1; this
spec is the enforcement point at registration time.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* INTENT-4 §3.1: drop authorial-action framing; cross-ref PIPELINE-1 §7.1
Replace "authorial action" / "modify-in-place" / .reply/.response
authorship prose with a concise rule. The dispatch-stamping
enforcement detail re-specified here now simply points to
PIPELINE-1 §7.1, which owns it.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* INTENT-4: fix stale topic name, terminology, and grammar
- §1 non-goals: complete_intent_failure → ovos.intent.unmatched
- §5.1: "captures map" → Match.slots (consistent with PIPELINE-1)
- §7.1 / §7 field ref: INTENT-2 §4.4 → §4.3 (correct section)
- §5.3, §6.2, §6.3, §7.2, §8.4: "A orchestrator" → "An orchestrator"
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* INTENT-4: fix four merge blockers
- §3.5 vs §11 contradiction resolved: reserved_name rejection is now
a plugin obligation, not the orchestrator's — the orchestrator is
a passive manifest listener and MUST NOT synthesize responses
(§11 is now internally consistent)
- §8.5: "retains the definition and handler binding" → "retains the
definition in the manifest" — handler bindings never cross the bus
(§9), the orchestrator has no knowledge of them
- §8.4: "a orchestrator" → "an orchestrator" (lowercase missed by
earlier replace_all)
- §10.2: "file forms expanded to inline where possible" → normative
rule: describe response is always inline form; if file-only,
orchestrator MUST omit definition and include a warning
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* INTENT-4 §3.2 / §8.1: fix two stale cross-refs; tighten §8.1 reset rule
- §3.2 lang field cited OVOS-MSG-1 §4.2 (layer-2 picture) for the
data.lang vs session.lang distinction; correct target is
OVOS-SESSION-1 §3.2 (Language signals). Also pin lang
case-insensitivity per SESSION-1 §3.2.
- §3.2 closing line referenced §7 for replacement semantics; §7 is
entity registration. Correct target is §8.1.
- §8.1 said replacement preserves enabled/disabled state "unless the
producer explicitly resets it" — but §8.5 phrased the same carve-out
as "unless the producer deregisters first." Align on "deregister
first," the bus-observable operation.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* INTENT-4: pre-merge polish — trim §3.1, pin empty-expansion, Postel keys, multi-plugin .response, drop §10.2 warning string
- §3.1: collapse the orchestrator-enforcement and other-component-
types sub-sections from ~3 pages to one combined paragraph. The
normative content (loader-side stamping, dispatch-path structural
conformance, symmetry with pipeline_id / transformer_ids) is
retained verbatim; the per-key enumeration of TRANSFORM-1's six
ids is dropped — readers consult TRANSFORM-1 §1.3 directly.
- §5.3 (keyword constraint validity): add the missing
empty-expansion check — a vocabulary descriptor whose samples
expand to zero non-empty entries (INTENT-1 §3.6) is malformed.
Also pin consumer-side Postel rule: a producer MUST include all
four keys, but a consumer SHOULD treat a missing key as an empty
array rather than rejecting.
- §6.3 (template malformed payloads): same INTENT-1 §3.6 carve-out
as keyword — a template that expands to zero non-empty samples
is malformed.
- §3.3 (responses): define multi-plugin consumption semantics —
multiple plugins MAY each emit independent .response Messages;
any ok: false is authoritative for that plugin's rejection only;
no cross-plugin aggregation rule; manifest of §10 is the single
answer to "did anyone consume this?"
- §10.2 (describe response): drop the stringly-typed `warning`
field for unresolvable file: registrations. Absence of
`definition` on an `ok: true` response now carries that signal
on its own — no enum churn, no free-form prose on the wire.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* INTENT-4: drop .response acknowledgement and data["skill_id"] noise
Two simplifications:
1. Registrations become fire-and-forget. The .response reply
mechanism (§3.3), the error_code enum (§3.4), and every
"MUST reject with error_code: …" clause across §§5.3, 5.5,
6.2, 6.3, 7.2, 8.4, 8.5 are gone. A consuming plugin that
judges a registration malformed (or finds it names a reserved
intent_name) simply doesn't index it; the manifest of §10
reflects what landed. Producers verify via §10 query, never
by waiting on an ack. Deregistration becomes naturally
idempotent (no_op semantics) without the prior unknown_*
error-code carve-out.
2. The context["skill_id"] vs data["skill_id"] disambiguation
sub-section (~30 lines) is dropped, along with the §3.2
"data is authoritative" paragraph. Payloads still carry
skill_id as a payload field where the topic schema needs
it — that's just a field name, not a discourse that earns
half a section of normative prose.
3. Version bumped to 3.
Net effect: -153 lines, removes a class of edge cases
(multi-plugin conflicting .response, silent vs structured
rejection, error_code precedence) without losing any
observable behaviour — the manifest was already specified
as the single source of truth, the .response was always
optional, and the error_codes were always plugin-emitted.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* INTENT-4 §3.1: merge "Coexistence with other identity keys" into the enforcement sub-section
The standalone paragraph repeated the pipeline_id / transformer_ids
enumeration that the "Enforcement and other component types"
sub-section already covered, and split the cross-component
discipline across two places. Merge: drop the standalone paragraph,
absorb its three normative bits (consumers MUST NOT treat extra
keys as malformed; skill MUST NOT strip keys it did not set;
CONTEXT-1 §5.2 precedence for single-owner attribution) into one
sentence at the end of the existing sub-section.
Also tighten the "authoritative attribution key" paragraph: drop
the parenthetical list of observer types (loggers, audit,
analytics, telemetry, debug tooling, manifest) — the abstract
"observers" carries the meaning without the enumeration.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* INTENT-4: aggressive simplification pass — drop duplicates and verbose restatements
Net: -122 lines (780 → 658), no normative change.
- §1: scope "does not define" list compacted from 7 bullets to 5;
redundant predecessor-topic-mapping bullet dropped (already in
APPENDIX), language-fallback bullet shortened, handler-reference
collapsed into the INTENT-3 bullet.
- §2: trimmed the "no plugin consumes it" worked example, dropped
the split-orchestrator paragraph (lives in §10), collapsed the
"two consequences" bullets, joined the manifest description into
one paragraph.
- §3.1: dropped the standalone "authoritative attribution key"
paragraph (overlapped with the rule above it) and the entire
"Consumer-side" sub-section (its content is implicit in
"context.skill_id is the only attribution key"). Merged the
must-not-reject diagnostic into the opening paragraph.
- §3.2 reserved-names: collapsed three paragraphs to one — the
authoritative-registry pointer was the only normative content.
lang cell tightened from a paragraph to one sentence.
- §4 trailing paragraph: 5 lines → 1.
- §5.5 file-form rule: tightened, renamed "single-orchestrator only"
to "single-host only" — describes the constraint, not a deployment
shape.
- §8.1 replacement: tightened reset clause.
- §9 handler reference: 3 paragraphs to 1.
- §10 introduction: collapsed 5 paragraphs (load-time announcements,
introspection surface, per-pipeline cross-ref, split orchestrator,
pull-query) into 3, keeping the pull-query-is-truth rule prominent.
- §10.2 describe response: tightened the file:-form omit-definition
rule, dropped the verbose "re-issue against an orchestrator that
shares filesystem" instruction.
- §11 conformance: dropped two redundant skill paragraphs (already
implied by §10 + manifest), dropped the trailing PIPELINE-1 §10
cross-ref paragraph (already in §10) and the orchestrator-
responsibilities filler.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* INTENT-4 v4: address final-review findings — log floors, reserved flag, scope cleanup
Closes the design gaps from the pre-merge review.
Normative additions:
- §3.1: orchestrator MUST (was SHOULD) log absent or mismatched
context["skill_id"] at WARN. The "authoritative attribution key"
framing demanded strict enforcement.
- §5.3 / §6.3 / §7.2: the rejecting plugin MUST log malformed-payload
rejections at WARN with skill_id, intent_name/entity_name, lang,
and a one-line reason. Fire-and-forget removed the .response
channel; the WARN log is now the producer's only debugging signal.
- §3.2 + §10.1: reserved-name registrations are flagged with
reserved: true in ovos.intent.list responses. The split
enforcement (plugins don't index, manifest does) now surfaces the
misregistration through introspection instead of vanishing.
- §3.2 / §11: explicit "replacement is per-(skill_id, intent_name,
lang); other languages unaffected" — closes a cross-language
atomicity question.
- §8.4: pointer to PIPELINE-1 for races between deregistration and
in-flight match (utterance lifecycle owner's concern).
- §8.5: one-sentence rationale on why enable/disable is bus-level
rather than skill-side gating — external tooling (admin UI,
A/B experiments) suppression without skill-code changes.
- §5.5: producers SHOULD prefer inline unconditionally; file form
is portable only under shared filesystem.
- §10.2: consumers SHOULD fall back to PIPELINE-1 §10 per-plugin
introspection when ovos.intent.describe omits definition for an
unexpandable file: registration.
Scope cleanup:
- §3.1: cut the cross-component over-reach paragraph (pipeline_id,
transformer_ids enumeration). INTENT-4 should not prescribe
cross-component identity discipline; one-liner pointer to
CONTEXT-1 §5.2 for single-owner attribution is sufficient.
Removes two fragile forward refs (TRANSFORM-1 §1.3, the
PIPELINE-1 §3.1 enumeration).
- §5.3: dropped the producer-strict / consumer-lenient
contradiction. A payload missing required keys is malformed,
full stop.
§11 conformance updated to match: plugin MUST log rejections;
orchestrator MUST flag reserved entries and log skill_id drift.
Version bumped to 4.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* INTENT-4 v5: drop file: form entirely — wire format is inline-only
A wire format spec has no business carrying producer-side filesystem
paths. Locale resource files (.voc, .intent, .entity, .blacklist —
OVOS-INTENT-2) are an authoring convenience; a skill loader reads
them and inlines their expanded content before emitting the
registration payload. File paths never appear on the bus.
Removed:
- §5.1 file-form vocabulary descriptor example and the samples-XOR-
file rule.
- §5.5 entire "File form is single-host only" section.
- §6.1 file-form template registration example, the `file` and
`blacklist_file` fields from the field table.
- §6.3 "both samples and file present" and "both blacklist and
blacklist_file present" malformed-payload bullets.
- §7.1 file-form entity registration example, the `file` field from
the field table.
- §7.2 "both or neither of samples/file" rule, replaced with the
simpler "samples is missing or empty" rule.
- §10.2 "registered via file: that we can't expand" omit-definition
carve-out — definition is always the broadcast payload as-is.
- §11 conformance §5.5 cross-ref and the §§5.5 entry in the plugin
malformed-registration list.
Added (§5.1): one-paragraph explanation that locale resource files
are a producer-side authoring convenience and never cross the bus.
Eliminates a class of silent failure (unresolvable file: paths
producing empty manifest entries with no diagnostic) and removes
the awkward "single-host only" hedge that admitted the feature was
broken for the deployment shapes the spec ostensibly targets.
Version bumped to 5.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* Update version number in intent-registration.md
* INTENT-4: allow dual-method registration — same intent under both keyword and template
Same handler, same intent identity, two training-data representations
on the wire. Different pipeline plugins consume different methods;
either match dispatches to the same <skill_id>:<intent_name> topic.
Whether to use one or both, and how to resolve a tie if both produce
a match, is pipeline policy (OVOS-PIPELINE-1).
Changes:
- §3.2: split the identity triple (skill_id, intent_name, lang) from
the registration key (skill_id, intent_name, lang, method). The
triple identifies an intent; the quadruple is what the manifest
indexes and what §8.1 replacement targets. A keyword and a template
registration of the same triple are independent manifest entries.
- §3.2: new paragraph stating dual-method registration is explicitly
permitted, what it means (two representations of the same handler),
and that conflict resolution is pipeline policy.
- §3.2: entity registrations clarified as having no method axis
(entities are a single shape).
- §8.2 deregister: clarified that the wire payload targets the triple
and removes ALL methods under it. No per-method deregistration —
ergonomic default. A skill wanting to keep one method
re-registers it.
- §8.5 enable/disable: same — target the triple, affect all methods.
- §10.1 list: explicit note that dual-method intents appear as two
entries distinguished by `method`.
- §10.2 describe: request gains an optional `method` filter; success
response reshaped to a `definitions: [{method, definition}, ...]`
array so both methods can be returned when no filter is given.
- §11 conformance: dropped the "never both for a single intent"
prohibition; replaced with explicit permission, cross-ref §3.2.
- §11 orchestrator: replacement-is-per-key clause updated to name the
quadruple key and note both other languages and the other-method
entry are unaffected.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* INTENT-4: final-review polishes + PIPELINE-1 §7.3 realignment
Three-file change. The PIPELINE-1 edit is included here (rather than
in its own one-file PR) because PIPELINE-1 is already merged on dev
and the §7.3 drift is a direct consequence of INTENT-4's
post-merge-prep simplifications — they need to land together to
avoid leaving dev with contradictory normative content.
INTENT-4 polishes (intent-registration.md):
- §3.2: dual-method registration paragraph clarifies that producers
MAY ship divergent suppression vocabularies per method (different
`excluded` for keyword vs different `blacklist` for template); each
plugin honours only its own method's suppression.
- §5.3: strengthened the WARN-log contract — MUST include the
rejecting topic alongside skill_id/intent_name/lang/reason because
the same triple may be valid as keyword and malformed as template
(or vice versa). Structured logging RECOMMENDED.
- §8.5: explicit footgun-mitigation note — to retain only one method,
deregister the triple (removes both) and re-register the desired one.
- §10.2: pin `definitions[]` ordering to `keyword`, `template` when
two entries are returned so consumers can rely on positional access.
- §10.2: include `reserved: true` at top level when the intent_name
is reserved (§3.2), so a `.describe` consumer can diagnose a
reserved-name misregistration without round-tripping through `.list`.
PIPELINE-1 fix (pipeline.md):
- §7.3 reserved-intent_names: realign with INTENT-4's actual handling.
Previously cited `OVOS-INTENT-4 §3.5` (the section was consolidated
into §3.2 during INTENT-4's pre-merge simplifications) and an
`error_code: "reserved_name"` mechanism (INTENT-4 dropped .response
entirely). Now correctly states: consuming pipeline plugin MUST NOT
index, MUST log per INTENT-4 §5.3; orchestrator manifest still
indexes the broadcast with `reserved: true`.
- Version bumped to 3.
CHANGELOG: added OVOS-PIPELINE-1 (v1/v2/v3) and OVOS-INTENT-4 (v1)
sections; PIPELINE-1's prior versions were merged without a changelog
entry, so the first two entries are housekeeping.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* INTENT-4 / PIPELINE-1: reserved-name registrations are just malformed payloads
Collapses the entire reserved-name machinery into the existing
malformed-payload rules. The orchestrator no longer indexes reserved
registrations for diagnostic visibility, the `reserved: true` flag
in §10.1 / §10.2 is gone, and every consumer (orchestrator manifest
and pipeline plugins alike) treats a reserved intent_name as one
more bullet in the malformed-payload list — log at WARN, do not
index.
INTENT-4:
- §3.2: reserved-name paragraph reduced to one sentence pointing at
the §5.3 / §6.3 malformed-payload rules.
- §5.3 / §6.3: added "intent_name reserved by another spec" as the
first bullet of each malformed-payload list.
- §10.1: dropped `reserved: true` flag from list-response entries
and the descriptive paragraph; reserved registrations don't appear
in the manifest at all.
- §10.2: dropped the `reserved: true` field from describe responses.
- §11: orchestrator conformance no longer enumerates a
reserved-flagging duty; plugin conformance folds reserved-name
rejection into the malformed-registration cross-ref.
PIPELINE-1:
- §7.3: realigned the reserved-name rejection contract — registrations
naming a reserved intent_name are malformed; every consumer
(orchestrator + plugins) treats them under INTENT-4 §5.3. Removes
the stale `OVOS-INTENT-4 §3.5` reference and the prior
manifest-indexes-with-flag wording.
- No version bump (per project preference, drafts stay at their
current version until stable).
CHANGELOG: dropped the staged PIPELINE-1 v3 entry; the §7.3 fix
lands as a non-version-bumped draft polish.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Renames "host" → "orchestrator" throughout OVOS-INTENT-3. The term host was overloaded against:
"Orchestrator" names the function — coordinating intent matching and dispatch — without conflicting with any of those.
Why now
The rename is needed for the in-flight bus / pipeline specs (PR #9, PR #11). Doing it in INTENT-3 first lets both of those pick up the new term cleanly. Companion follow-ups: PR #9 and PR #11 will rename to match.
Changes
Non-breaking
Conformance semantics are unchanged. A skill or engine implementation that read the spec at v1 continues to conform at v2 unchanged. The rename is editorial — same contract, clearer name.
Test plan
🤖 Generated with Claude Code