Model Route Naming Convention — LOCKED

Datum: 2026-04-22 Sprint: 11 · Track B · Task B3 follow-up Authority: PM (Marko Marković via Cowork ratification 2026-04-22 PM) Source artifact: docs/reports/opus-4-6-route-audit-2026-04-22.md §5 (CC B3 audit, commit 151113f) Status: LOCKED — supersedes any prior ad-hoc naming convention in litellm-config.yaml, anthropic-proxy.ts, workspace-templates.ts, and test fixtures Scope: All packages/server/, packages/cli/, apps/www/, harness configs, and litellm route declarations

1. Decision

Two distinct naming surfaces are LOCKED, each with non-overlapping purpose:

Surface A — Floating alias. Used in runtime code paths: proxy mapping, workspace template defaults, agent harness defaults, UI model picker labels. Format: {provider}/{family}-{tier} (e.g., anthropic/claude-sonnet-4-6, anthropic/claude-haiku-4-5, xai/grok-4.20). The provider rotates the underlying snapshot; the alias keeps pointing to the latest stable.

Surface B — Dated snapshot. Used ONLY in benchmark configs, regression test fixtures, audit replay manifests, and decision docs that need to pin model behavior at a moment in time. Format: {provider}/{family}-{tier}-{YYYYMMDD} (e.g., anthropic/claude-sonnet-4-6-20260101). Dated snapshots MUST be valid at the time of writing — verified against the provider's published snapshot list before commit.

Provider prefix is mandatory in litellm-config.yaml for all routes. Bare model names (gpt-5.4, qwen3.6-35b-a3b) without prefix are deprecated; new routes must declare provider explicitly.

2. Rationale

The B3 audit surfaced a real runtime defect: 9 of 11 dated-snapshot references in packages/server/ use -20250514, which was never a valid Claude 4.6 family snapshot. Production code paths that send these IDs to Anthropic return 404 model_not_found. The defect persisted because:

Naming convention was implicit, not LOCKED in any decision doc.
Floating alias and dated snapshot were used interchangeably, with no separation of concerns between runtime defaults (which should auto-track provider rotation) and benchmark reproducibility (which must pin a specific snapshot).
Test mocks hid the defect from CI signal.

The LOCK enforces semantic separation: runtime code never hardcodes a snapshot ID; benchmark code never uses a floating alias. Drift between the two surfaces becomes detectable.

3. Authorization — Cleanup ticket

PM hereby authorizes a cleanup ticket scoped to the B3 audit findings, executable by CC-1 in a single tranche before C2 Stage 1 mikro-eval kickoff (or immediately after, at CC-1's discretion). Budget: $0 (read/edit only, no LLM calls).

HIGH priority — surgical fix, in-scope before C2:

packages/server/src/<…>/anthropic-proxy.ts:43-44 — replace floating-alias-to-invalid-dated-snapshot mapping. Two acceptable resolutions: (a) drop the mapping entirely so floating aliases pass through to Anthropic unchanged (preferred — Anthropic resolves them server-side); (b) map floating alias to a verified-valid current dated snapshot. Choose (a) unless there is a documented reason to pin.

MEDIUM priority — in-scope before C2:

packages/server/src/<…>/workspace-templates.ts:406 — change new-workspace default from claude-sonnet-4-20250514 (invalid) to anthropic/claude-sonnet-4-6 (floating alias). New users must not bounce on first message.

LOW priority — fold into Sprint 11 close commit or first Day-3 commit:

3 test files referenced in B3 report §3 — replace hardcoded -20250514 with floating alias. Tests pass currently only because providers are mocked; the values are misleading documentation. Update to floating alias for clarity.
packages/server/src/<…>/litellm.ts:65 — rename pricing table entry claude-haiku-4-6 → claude-haiku-4-5. Haiku 4.6 does not exist; current Haiku is 4.5. This is a misname, not a routing bug.

4. Validation gates

CC-1 must satisfy before commit:

pnpm test — zero regressions across affected suites.
tsc --noEmit clean on packages/server/tsconfig.json.
New unit test in packages/server/tests/<…>/anthropic-proxy.test.ts asserting that the proxy does NOT inject -20250514 (or any invalid dated snapshot) into outbound requests.
Grep guard added to a new lint script scripts/check-no-invalid-snapshots.mjs that fails CI if -20250514 appears anywhere in packages/server/src/. This freezes the regression.
Commit message references this decision doc.

5. Naming policy in new code

For all new routes added after this LOCK:

Runtime defaults, proxy mappings, workspace templates, agent harness defaults: use floating alias {provider}/{family}-{tier}.
Benchmark configs (benchmarks/harness/, litellm-config.yaml benchmark section, evaluation manifests): use dated snapshot {provider}/{family}-{tier}-{YYYYMMDD} AND verify the date against provider's published snapshot list at PR review time.
Decision docs and ratification artifacts: cite both forms when relevant — floating alias for what the system uses today, dated snapshot for what was tested at the time of decision.

6. Out of scope

Renaming routes in user-facing UI labels (model picker dropdown). That is a copy decision for design team, not a naming convention LOCK.
Migrating existing benchmark JSONL records to retroactively cite snapshot IDs. Historical records keep whatever they have; Stage 2 onward records cite per the new convention.
Provider rotation policy (when to upgrade floating alias from N to N+1). Separate decision, owned by harness maintainer.

docs/reports/opus-4-6-route-audit-2026-04-22.md — B3 audit report (waggle-os repo)
PM-Waggle-OS/sessions/2026-04-22-sprint-11-b3-opus46-audit-exit.md — B3 exit ping
PM-Waggle-OS/decisions/2026-04-22-tie-break-policy-locked.md — sibling LOCK; uses the same xai/grok-4.20 floating alias convention this doc formalizes
litellm-config.yaml — primary config surface affected by §3 cleanup

LOCKED. CC-1 authorized to execute the §3 cleanup ticket. HIGH + MEDIUM in-scope before C2 kickoff; LOW may slot into Sprint 11 close commit. New unit test + lint guard required per §4.

6.2 KiB Raw Permalink Blame History