- Cascade semantics: reconcile "errors only" with "pre-skip unfit steps".
  Now distinguishes ELIGIBILITY (size-based, checked before attempt) from
  RETRY TRIGGER (errors: timeout, 5xx, 429).
- Fix fabricated mechanism reference: there is no `fallbacks` field on
  AlloyConfig. Describe the real mechanism (`ordered_models` returned
  from `select_plan` and iterated in `route_with_fallback`).
- CharRatio safety margin: explicitly flag that 10% is insufficient for
  CJK-heavy prompts; suggest remediations (tune chars_per_token, raise
  safety_margin, or switch to Tiktoken).
- Correct "streaming output doesn't count" — it DOES count against the
  combined context. Describe the input + max_tokens check approach and
  the default output budget callers must supply.
- Fix K-suffix math: 262K = 262*1024 = 268288, not 262144. Add
  clarifying example using "256K" → 262144.
- Remove stale "context_window=0 = unknown" sentinel note; PR #14
  rejects 0 explicitly at alloy validation.
- Call out [tokenizer], [model_defaults], [[models]] as PROPOSED
  schema additions, not current.

* docs(rfc): model-gateway primitives — alloy + cascade + dispatcher

Proposes three explicitly-scoped primitives for model-gateway routing,
each with distinct semantics, and a shared TokenEstimator trait so they
can reason about context-window fit consistently.

Problem motivating this: alloys today assume constituents are
interchangeable, which breaks when mixing models with wildly different
context windows (e.g., local Qwen at 32K and Kimi K2.6 at 262K). Using
an alloy for size-dependent routing leads to silent truncation.

Proposal:
- Alloy (today, + safety) blends equivalent models via sampling. New:
  min_context_window assertion + runtime fit-check rejection.
- Cascade (promoted to named primitive) tries members in order on error.
  New: skip-on-size when a cascade step can't fit the request.
- Dispatcher (new) picks by request shape, MVP rule type is
  max_input_tokens; extensible to other matchers.

Shared TokenEstimator trait:
- Default: CharRatioEstimator (chars-per-token configurable, 3.5 default)
- Safety margin (default 10%) to bias toward over-estimation and avoid
  silent truncation footgun.
- Pluggable for real tokenizers (tiktoken-rs, sentencepiece) as future
  opt-in crates behind feature flags.
- Configurable globally, per-primitive, and per-model with clear
  precedence.

Includes naming discussion (going with "dispatcher"), migration plan
(no breaking changes), edge cases (session-context growth, tool-use
inflation, streaming output), and open questions for reviewers.

Implementation split into focused follow-up PRs. RFC is the long-form
design; PRs execute.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(rfc): incorporate first-round review decisions

Captures reviewer resolutions:
- dispatcher confirmed as the size-routing primitive name
- cascade promoted to a named primitive
- safety margin split into two distinct knobs: estimator safety_margin
  (counting-accuracy pad) and per-model capacity_fraction (avoid the
  quality-degradation zone near a model's ceiling). Composition formula
  and rationale added.
- TiktokenEstimator included in v1 behind a feature flag; SentencePiece
  deferred to avoid C++ deps + per-model vocab plumbing for now
- dispatcher reevaluate default flipped to per_turn (task-completion
  flows benefit from auto-promotion over consistency); sticky and
  sticky_escalate documented as opt-ins
- dispatcher rule semantics simplified: default is "first target whose
  effective ceiling fits the request", computed per-target from
  context_window × capacity_fraction. Explicit rules remain for
  non-size routing.
- alloy context_window required on every constituent. No back-compat
  for missing fields — prototype phase, owned installations, worth the
  one-time config edit to eliminate silent truncation.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(rfc): address Copilot review on model-gateway-primitives

- Cascade semantics: reconcile "errors only" with "pre-skip unfit steps".
  Now distinguishes ELIGIBILITY (size-based, checked before attempt) from
  RETRY TRIGGER (errors: timeout, 5xx, 429).
- Fix fabricated mechanism reference: there is no `fallbacks` field on
  AlloyConfig. Describe the real mechanism (`ordered_models` returned
  from `select_plan` and iterated in `route_with_fallback`).
- CharRatio safety margin: explicitly flag that 10% is insufficient for
  CJK-heavy prompts; suggest remediations (tune chars_per_token, raise
  safety_margin, or switch to Tiktoken).
- Correct "streaming output doesn't count" — it DOES count against the
  combined context. Describe the input + max_tokens check approach and
  the default output budget callers must supply.
- Fix K-suffix math: 262K = 262*1024 = 268288, not 262144. Add
  clarifying example using "256K" → 262144.
- Remove stale "context_window=0 = unknown" sentinel note; PR #14
  rejects 0 explicitly at alloy validation.
- Call out [tokenizer], [model_defaults], [[models]] as PROPOSED
  schema additions, not current.

* docs(rfc): second round of Copilot review — new feedback on updated push

- Include `name` field in alloy TOML example (AlloyConfig still requires it).
- Reference `AlloyProvider::from_config()` (actual) instead of
  `AlloyProvider::new()` (non-existent).
- Clarify ordered_models determinism: round_robin deterministic; weighted
  is random sampling without replacement. Cascade, unlike alloy, is
  always deterministic (declaration order).
- Resolve safety_margin double-apply ambiguity: estimator returns a
  margin-applied count; caller never multiplies again. Fit-check becomes
  estimate > context_window × capacity_fraction (one multiplication, one
  comparison). Reworked the worked example accordingly.
- Fix `safety_margin 0.15–0.20` typo — the value is a multiplier, so
  "bump it" means 1.15–1.20, not 0.15 (which would shrink the estimate).

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(rfc): model-gateway primitives — alloy + cascade + dispatcher

Proposes three explicitly-scoped primitives for model-gateway routing,
each with distinct semantics, and a shared TokenEstimator trait so they
can reason about context-window fit consistently.

Problem motivating this: alloys today assume constituents are
interchangeable, which breaks when mixing models with wildly different
context windows (e.g., local Qwen at 32K and Kimi K2.6 at 262K). Using
an alloy for size-dependent routing leads to silent truncation.

Proposal:
- Alloy (today, + safety) blends equivalent models via sampling. New:
  min_context_window assertion + runtime fit-check rejection.
- Cascade (promoted to named primitive) tries members in order on error.
  New: skip-on-size when a cascade step can't fit the request.
- Dispatcher (new) picks by request shape, MVP rule type is
  max_input_tokens; extensible to other matchers.

Shared TokenEstimator trait:
- Default: CharRatioEstimator (chars-per-token configurable, 3.5 default)
- Safety margin (default 10%) to bias toward over-estimation and avoid
  silent truncation footgun.
- Pluggable for real tokenizers (tiktoken-rs, sentencepiece) as future
  opt-in crates behind feature flags.
- Configurable globally, per-primitive, and per-model with clear
  precedence.

Includes naming discussion (going with "dispatcher"), migration plan
(no breaking changes), edge cases (session-context growth, tool-use
inflation, streaming output), and open questions for reviewers.

Implementation split into focused follow-up PRs. RFC is the long-form
design; PRs execute.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(rfc): incorporate first-round review decisions

Captures reviewer resolutions:
- dispatcher confirmed as the size-routing primitive name
- cascade promoted to a named primitive
- safety margin split into two distinct knobs: estimator safety_margin
  (counting-accuracy pad) and per-model capacity_fraction (avoid the
  quality-degradation zone near a model's ceiling). Composition formula
  and rationale added.
- TiktokenEstimator included in v1 behind a feature flag; SentencePiece
  deferred to avoid C++ deps + per-model vocab plumbing for now
- dispatcher reevaluate default flipped to per_turn (task-completion
  flows benefit from auto-promotion over consistency); sticky and
  sticky_escalate documented as opt-ins
- dispatcher rule semantics simplified: default is "first target whose
  effective ceiling fits the request", computed per-target from
  context_window × capacity_fraction. Explicit rules remain for
  non-size routing.
- alloy context_window required on every constituent. No back-compat
  for missing fields — prototype phase, owned installations, worth the
  one-time config edit to eliminate silent truncation.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(rfc): address Copilot review on model-gateway-primitives

- Cascade semantics: reconcile "errors only" with "pre-skip unfit steps".
  Now distinguishes ELIGIBILITY (size-based, checked before attempt) from
  RETRY TRIGGER (errors: timeout, 5xx, 429).
- Fix fabricated mechanism reference: there is no `fallbacks` field on
  AlloyConfig. Describe the real mechanism (`ordered_models` returned
  from `select_plan` and iterated in `route_with_fallback`).
- CharRatio safety margin: explicitly flag that 10% is insufficient for
  CJK-heavy prompts; suggest remediations (tune chars_per_token, raise
  safety_margin, or switch to Tiktoken).
- Correct "streaming output doesn't count" — it DOES count against the
  combined context. Describe the input + max_tokens check approach and
  the default output budget callers must supply.
- Fix K-suffix math: 262K = 262*1024 = 268288, not 262144. Add
  clarifying example using "256K" → 262144.
- Remove stale "context_window=0 = unknown" sentinel note; PR #14
  rejects 0 explicitly at alloy validation.
- Call out [tokenizer], [model_defaults], [[models]] as PROPOSED
  schema additions, not current.

* docs(rfc): second round of Copilot review — new feedback on updated push

- Include `name` field in alloy TOML example (AlloyConfig still requires it).
- Reference `AlloyProvider::from_config()` (actual) instead of
  `AlloyProvider::new()` (non-existent).
- Clarify ordered_models determinism: round_robin deterministic; weighted
  is random sampling without replacement. Cascade, unlike alloy, is
  always deterministic (declaration order).
- Resolve safety_margin double-apply ambiguity: estimator returns a
  margin-applied count; caller never multiplies again. Fit-check becomes
  estimate > context_window × capacity_fraction (one multiplication, one
  comparison). Reworked the worked example accordingly.
- Fix `safety_margin 0.15–0.20` typo — the value is a multiplier, so
  "bump it" means 1.15–1.20, not 0.15 (which would shrink the estimate).

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(alloy): require context_window + min_context_window safety

Per RFC #13 review decision (no back-compat in prototype phase): every
alloy constituent must declare its context_window. Serde enforces the
field at config load, so misconfigured alloys fail with a clear parse
error instead of quietly accepting "unknown" sizes that could mask
routing bugs later.

## Config changes

AlloyConstituentConfig.context_window is now a required u32 (was an
optional field in the previous draft). Every existing config must be
updated to declare sizes; live config on .210 already patched in the
matching commit on infra.

AlloyConfig.min_context_window remains optional; when unset, it's
auto-computed as min(constituent.context_window). When set, validation
rejects any constituent whose declared size falls below it with a
clear error naming both the offender and the numbers.

## Runtime exposure

AlloyProvider::min_context_window() returns u32 (no longer Option),
since size declaration is always present.

## Tests

7 tests: round_robin/weighted/stats unchanged; new tests cover
auto-compute from mixed-size constituents, shared-size parity, explicit
min priority, and explanatory error on constituent-below-floor. The
"no declared size" test from the previous draft is deleted — that
state is now unreachable.

## Live config migration

Deployed alongside this PR: .210's kimi-for-coding alloy gets
context_window declared on both constituents (262144 for Kimi,
64000 for DeepSeek V3). No other nodes use [[alloys]] today.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(alloy): rustfmt + reject zero context_window + stale doc

- cargo fmt: collapse multi-line array in alloy.rs test (CI fmt gate)
- Reject context_window=0 on constituents (clear misconfig error)
- Reject min_context_window=0 at alloy build (same)
- Drop stale doc reference to docs/rfcs/model-gateway-primitives.md
  (lives in PR #13, not yet on main)
- Simplify min_context_window doc: context_window is required on
  constituents now, so "treated as unknown" qualifier is dead.

Addresses Copilot review feedback on #14.

* test(config): assert missing context_window fails to deserialize

Guards against silently reintroducing a serde default (Option<u32> or
#[serde(default)]) on AlloyConstituentConfig::context_window. Addresses
Copilot review feedback on #14.

* fix(config): use expect_err per clippy

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>