Spec gap: `default_router` placement in the YAML document is never normatively defined #2

New issue

Open

opened 2026-05-27 05:23:48 +00:00 by hurui200320 · 0 comments

hurui200320 commented

2026-05-27 05:23:48 +00:00

Member

Problem

The spec mandates a default_router parameter but never normatively specifies where in a YAML configuration document this parameter lives.

§3.4 states:

A compliant implementation MUST satisfy the default-router requirement through the default_router parameter.

§9.3 defines the parameter but then says:

The mechanism by which an implementation accepts these parameters is outside the scope of this standard.

§11.1 lists it as a validation rule checked at config-load time:

When routes is present, a default_router parameter SHOULD identify a route in routes.

These three sections are in tension. If the parameter is external (host-supplied), the YAML validator cannot check it at load time, making §11.1 unenforceable. If it is internal (in the YAML), its location is undefined — it does not appear in the §3.2 top-level sections table.

The only usage hint is the cleveragents: namespace used in §9.2 examples for template_engine, which a reader might infer also hosts default_router, but this is never stated.

Additionally, the cleveragents: top-level key itself is never listed in §3.2 at all (see related issue).

Impact on Library Implementation

The library cannot implement:

YAML parsing (where to look for the value)
Validation (how to detect and report a missing default_router)
Default routing behavior (which route receives messages when no target is specified)

Decision Needed

Is default_router specified inside the YAML document? If so, add it (or its cleveragents: parent key) to the §3.2 top-level sections table with a concrete example.
Is it external (host API only)? If so, remove or soften the §11.1 validation requirement accordingly.
Provide at least one canonical YAML example showing the default_router value in context.

References

§3.2 — Top-Level Sections (parameter is absent from this table)
§3.4 — The Default Router Requirement
§9.3 — default_router parameter definition
§11.1 — Structural Validation rule

## Problem The spec mandates a `default_router` parameter but never normatively specifies where in a YAML configuration document this parameter lives. **§3.4** states: > A compliant implementation MUST satisfy the default-router requirement through the `default_router` parameter. **§9.3** defines the parameter but then says: > The mechanism by which an implementation accepts these parameters is outside the scope of this standard. **§11.1** lists it as a validation rule checked at config-load time: > When `routes` is present, a `default_router` parameter SHOULD identify a route in `routes`. These three sections are in tension. If the parameter is external (host-supplied), the YAML validator cannot check it at load time, making §11.1 unenforceable. If it is internal (in the YAML), its location is undefined — it does not appear in the §3.2 top-level sections table. The only usage hint is the `cleveragents:` namespace used in §9.2 examples for `template_engine`, which a reader might infer also hosts `default_router`, but this is never stated. Additionally, the `cleveragents:` top-level key itself is never listed in §3.2 at all (see related issue). ## Impact on Library Implementation The library cannot implement: - YAML parsing (where to look for the value) - Validation (how to detect and report a missing `default_router`) - Default routing behavior (which route receives messages when no target is specified) ## Decision Needed 1. Is `default_router` specified **inside** the YAML document? If so, add it (or its `cleveragents:` parent key) to the §3.2 top-level sections table with a concrete example. 2. Is it **external** (host API only)? If so, remove or soften the §11.1 validation requirement accordingly. 3. Provide at least one canonical YAML example showing the `default_router` value in context. ## References - §3.2 — Top-Level Sections (parameter is absent from this table) - §3.4 — The Default Router Requirement - §9.3 — `default_router` parameter definition - §11.1 — Structural Validation rule

hurui200320 added the

labels

2026-05-27 05:27:13 +00:00

~~hurui200320 referenced this issue 2026-05-27 09:32:50 +00:00~~

Remove memory_enabled from LLM agent config — make all actors stateless by design #21