refactor(routing): D17 — alias-aware getProviderForModel as routing SPOT (Findings 12 + 13)

cold-audit catch from 2026-05-23

Cold-audit Findings 12 + 13 (both P3, both routing layer). F12: mistral
plugin's models[] included canonical IDs + aliases while anthropic/codex
were canonical-only — inconsistent routing surface (request "sonnet"
returned 503 from anthropic but request "devstral" worked for mistral).
F13: getProviderForModel imported but never called; buildDefaultChain
duplicated the lookup loop — two SPOT-candidate code paths.

Per cold-audit reviewer's option (a): standardize models[] on canonical-
only across all 3 plugins; getProviderForModel becomes alias-aware via
models-registry.json; buildDefaultChain uses getProviderForModel as SPOT.

Changes (4 files, +242 / -50):

1. lib/providers/index.mjs:
   - At module load, builds `_aliasMap: Map<aliasString, {providerName,
     canonicalModel}>` by walking models-registry.json's providers[*].aliases
   - getProviderForModel signature extended: returns `{provider, name,
     canonicalModel}` (was `{provider, name}`). The canonicalModel field is
     the resolved canonical ID for callers that need to use it downstream
     (cache key, observability headers, log events)
   - 3-step resolution order: (1) alias map lookup → if hit AND provider
     loaded → return with canonicalModel; (2) direct canonical scan → return
     with canonicalModel = modelString; (3) null
   - "Alias known but provider not loaded" case correctly falls through
     to step 2 (which will also miss for an alias string) → returns null

2. lib/providers/mistral.mjs:
   - _registryModels stripped to canonical-only: removed the
     `...Object.keys(_registryEntry.aliases ?? {})` spread
   - mistral.models[] now matches anthropic/codex shape (canonical IDs only)
   - Comment block updated to point future readers at getProviderForModel
     as the SPOT

3. lib/fallback/engine.mjs:
   - buildDefaultChain's inline `for ([name, provider] of loadedProviders)`
     scan loop replaced with a single getProviderForModel() call
   - Chain hop's `model` field is now `match.canonicalModel` (was `modelString`)
     — so downstream consumers receive canonical
   - Explicit-chain config path unchanged (kept its pre-existing behavior;
     alias resolution in routing.chains config is a known limitation, tracked
     as a future improvement)

4. test-features.mjs:
   - 17 new tests in `D17 — alias-aware getProviderForModel` describe block:
     anthropic alias coverage (sonnet/opus/haiku/claude), openai aliases
     (codex/codex-spark/gpt5/gpt5-mini), mistral aliases (devstral/
     devstral-2/devstral-small/devstral-small-2), canonical pass-through,
     unknown model → null, alias-to-disabled-provider → null,
     buildDefaultChain integration with alias resolution
   - 3 existing mistral tests rewritten — they were asserting the pre-D17
     inconsistent shape (aliases in mistral.models[]). Now assert the
     post-D17 invariant (aliases NOT in models[]; routing via
     getProviderForModel instead)

Tests: 300 → 317 (+17 new). All pass on Node 20.

Pre-commit fold-in (per evidence-first checkpoint #4 — fold-ins themselves
need second-pass review):

- **D17 reviewer flagged C10**: original engine.mjs comment said
  "downstream (cache key, X-OLP-Model-Used, provider.spawn) receives the
  canonical ID rather than the alias string". The provider.spawn portion
  is incorrect — spawn reads `irRequest.model` (the user's original input),
  which is NEVER rewritten to canonical. Each provider CLI accepts its own
  aliases natively (claude accepts sonnet/opus/haiku; vibe accepts
  devstral/devstral-2; codex accepts its model IDs), so runtime behavior
  is fine, but the comment overstated what D17 actually changes.
  Folded in: corrected comment to honestly describe the canonical flow
  (cache key + X-OLP-Model-Used + logs receive canonical; spawn continues
  to receive irRequest.model). Same class of doc-code drift fix as D11's
  B1 (false maxConcurrent enforcement claim) and D16's "bypasses
  getOrCompute" drift — the discipline is maturing across D-days.

Authority:
- ADR 0002 § Provider contract (`models: string[]` is "models this provider
  serves")
  https://github.com/dtzp555-max/olp/blob/main/docs/adr/0002-plugin-architecture.md
- models-registry.json — single source of truth for (provider, model)
  metadata + alias→canonical mappings per AGENTS.md SPOT policy
- AGENTS.md § Project-specific constraints — "models-registry.json is the
  only place to add/edit (provider, model) metadata"
- CC 开发铁律 v1.6 § 10.x — Cold Audit Findings 12 + 13

Reviewer (Iron Rule v1.6 § 10.x Mode A, fresh-context opus, independent
of drafter): APPROVE_WITH_MINOR. Highest-value verification: walked
chain[0].model from buildDefaultChain through all downstream consumers
(computeCacheKey, X-OLP-Model-Used, log events) to confirm canonical
flow; then verified provider.spawn paths in anthropic.mjs:231 and
codex.mjs:248 read irRequest.model (user input), confirming the comment
overstatement (now fixed). Verified no alias-canonical collision exists
in current registry (12 aliases vs 10 canonical IDs, zero intersection).
Verified empty-registry edge case + provider-with-model-not-in-registry
edge case.

Follow-up items (reviewer's non-blocking observations, NOT in this PR):
- server.mjs:32 dead import of getProviderForModel — defer to D19 cleanup
- explicit-chain config path doesn't run alias resolution (routing.chains
  in ~/.olp/config.json) — pre-existing limitation, file as future issue

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

test-features.mjs

@@ -533,6 +533,7 @@ describe('Plugin registry', () => {
     const r = getProviderForModel(m, 'alpha-v1');
     assert.ok(r !== null);
     assert.equal(r.name, 'alpha');
+    assert.equal(r.canonicalModel, 'alpha-v1', 'D17: canonicalModel must equal modelString on direct lookup');
   });
 
   it('getProviderForModel returns null for unknown model', () => {
@@ -600,6 +601,133 @@ function makeMockSpawn(stdoutChunks, exitCode = 0) {
   };
 }
 
+// ── Suite D17: Alias-aware getProviderForModel (Finding 12 + 13) ─────────────
+//
+// Tests that getProviderForModel resolves aliases from models-registry.json
+// to canonical IDs and routes to the correct (enabled) provider.
+
+describe('D17 — alias-aware getProviderForModel', () => {
+
+  // ── Anthropic aliases ────────────────────────────────────────────────
+  it('D17: alias "sonnet" → anthropic, canonical claude-sonnet-4-6', () => {
+    const loaded = new Map([['anthropic', anthropic]]);
+    const r = getProviderForModel(loaded, 'sonnet');
+    assert.ok(r !== null);
+    assert.equal(r.name, 'anthropic');
+    assert.equal(r.canonicalModel, 'claude-sonnet-4-6');
+  });
+
+  it('D17: alias "claude" → anthropic, canonical claude-sonnet-4-6', () => {
+    const loaded = new Map([['anthropic', anthropic]]);
+    const r = getProviderForModel(loaded, 'claude');
+    assert.ok(r !== null);
+    assert.equal(r.name, 'anthropic');
+    assert.equal(r.canonicalModel, 'claude-sonnet-4-6');
+  });
+
+  it('D17: alias "opus" → anthropic, canonical claude-opus-4-7', () => {
+    const loaded = new Map([['anthropic', anthropic]]);
+    const r = getProviderForModel(loaded, 'opus');
+    assert.ok(r !== null);
+    assert.equal(r.name, 'anthropic');
+    assert.equal(r.canonicalModel, 'claude-opus-4-7');
+  });
+
+  it('D17: alias "haiku" → anthropic, canonical claude-haiku-4-5', () => {
+    const loaded = new Map([['anthropic', anthropic]]);
+    const r = getProviderForModel(loaded, 'haiku');
+    assert.ok(r !== null);
+    assert.equal(r.name, 'anthropic');
+    assert.equal(r.canonicalModel, 'claude-haiku-4-5');
+  });
+
+  // ── OpenAI aliases ────────────────────────────────────────────────────
+  it('D17: alias "codex" → openai, canonical gpt-5.3-codex', () => {
+    const loaded = new Map([['openai', codex]]);
+    const r = getProviderForModel(loaded, 'codex');
+    assert.ok(r !== null);
+    assert.equal(r.name, 'openai');
+    assert.equal(r.canonicalModel, 'gpt-5.3-codex');
+  });
+
+  it('D17: alias "gpt5" → openai, canonical gpt-5.5', () => {
+    const loaded = new Map([['openai', codex]]);
+    const r = getProviderForModel(loaded, 'gpt5');
+    assert.ok(r !== null);
+    assert.equal(r.name, 'openai');
+    assert.equal(r.canonicalModel, 'gpt-5.5');
+  });
+
+  // ── Mistral aliases ───────────────────────────────────────────────────
+  it('D17: alias "devstral" → mistral, canonical devstral-2-25-12', () => {
+    const loaded = new Map([['mistral', mistral]]);
+    const r = getProviderForModel(loaded, 'devstral');
+    assert.ok(r !== null);
+    assert.equal(r.name, 'mistral');
+    assert.equal(r.canonicalModel, 'devstral-2-25-12');
+  });
+
+  it('D17: alias "devstral-small" → mistral, canonical devstral-small-2-25-12', () => {
+    const loaded = new Map([['mistral', mistral]]);
+    const r = getProviderForModel(loaded, 'devstral-small');
+    assert.ok(r !== null);
+    assert.equal(r.name, 'mistral');
+    assert.equal(r.canonicalModel, 'devstral-small-2-25-12');
+  });
+
+  // ── Canonical pass-through ────────────────────────────────────────────
+  it('D17: canonical "claude-sonnet-4-6" → anthropic, canonicalModel unchanged', () => {
+    const loaded = new Map([['anthropic', anthropic]]);
+    const r = getProviderForModel(loaded, 'claude-sonnet-4-6');
+    assert.ok(r !== null);
+    assert.equal(r.name, 'anthropic');
+    assert.equal(r.canonicalModel, 'claude-sonnet-4-6');
+  });
+
+  // ── Unknown model → null ──────────────────────────────────────────────
+  it('D17: unknown model "gpt-4-imaginary" → null', () => {
+    const loaded = new Map([['anthropic', anthropic], ['openai', codex], ['mistral', mistral]]);
+    assert.equal(getProviderForModel(loaded, 'gpt-4-imaginary'), null);
+  });
+
+  // ── Alias points to disabled provider → null ─────────────────────────
+  it('D17: alias "devstral" with only anthropic loaded → null (mistral not enabled)', () => {
+    // The alias is known (devstral → mistral) but mistral is not in loadedProviders.
+    const loaded = new Map([['anthropic', anthropic]]);
+    assert.equal(getProviderForModel(loaded, 'devstral'), null);
+  });
+
+  it('D17: alias "sonnet" with only mistral loaded → null (anthropic not enabled)', () => {
+    const loaded = new Map([['mistral', mistral]]);
+    assert.equal(getProviderForModel(loaded, 'sonnet'), null);
+  });
+
+  // ── buildDefaultChain with alias ──────────────────────────────────────
+  it('D17: buildDefaultChain("sonnet") → chain carries canonical claude-sonnet-4-6', () => {
+    const loaded = new Map([['anthropic', anthropic]]);
+    const chain = buildDefaultChain('sonnet', loaded, {}, {});
+    assert.ok(chain !== null);
+    assert.equal(chain.length, 1);
+    assert.equal(chain[0].provider, 'anthropic');
+    assert.equal(chain[0].model, 'claude-sonnet-4-6');
+  });
+
+  it('D17: buildDefaultChain("devstral") → chain carries canonical devstral-2-25-12', () => {
+    const loaded = new Map([['mistral', mistral]]);
+    const chain = buildDefaultChain('devstral', loaded, {}, {});
+    assert.ok(chain !== null);
+    assert.equal(chain.length, 1);
+    assert.equal(chain[0].provider, 'mistral');
+    assert.equal(chain[0].model, 'devstral-2-25-12');
+  });
+
+  it('D17: buildDefaultChain("unknown-alias") with no providers → null', () => {
+    const loaded = new Map();
+    assert.equal(buildDefaultChain('unknown-alias', loaded, {}, {}), null);
+  });
+
+});
+
 describe('Anthropic plugin (D4)', () => {
 
   // ── Test 1: Contract conformance ──────────────────────────────────────
@@ -2692,51 +2820,65 @@ describe('Mistral Vibe plugin (D8)', () => {
     assert.ok(mistral.displayName.toLowerCase().includes('mistral'));
   });
 
-  // ── Test 4: models include all registry IDs + aliases ────────────────
-  it('mistral.models includes every canonical registry id AND every alias', () => {
-    // The plugin merges canonical IDs and alias keys into models[] so that
-    // getProviderForModel routes either form. Test that the registry's
-    // canonical IDs are a subset, and the aliases are all included too.
+  // ── Test 4: models is canonical-only (D17 Finding 12 fix) ───────────
+  it('mistral.models contains only canonical registry IDs — no alias strings', () => {
+    // D17 fix: models[] is canonical-only across all plugins. Alias routing
+    // is the responsibility of getProviderForModel() in lib/providers/index.mjs.
     const registryIds = modelsRegistry.providers.mistral.models.map(m => m.id);
     const registryAliases = Object.keys(modelsRegistry.providers.mistral.aliases ?? {});
     for (const id of registryIds) {
       assert.ok(mistral.models.includes(id), `canonical id ${id} missing from mistral.models`);
     }
     for (const alias of registryAliases) {
-      assert.ok(mistral.models.includes(alias), `alias ${alias} missing from mistral.models`);
+      assert.ok(!mistral.models.includes(alias), `alias ${alias} must NOT appear in mistral.models (D17)`);
     }
-    assert.equal(mistral.models.length, registryIds.length + registryAliases.length);
+    assert.equal(mistral.models.length, registryIds.length, `Expected ${registryIds.length} canonical IDs, got ${mistral.models.length}`);
   });
 
-  it('mistral.models contains canonical IDs + short-form aliases', () => {
-    // Per canonical models registry (docs.mistral.ai/getting-started/models/
-    // models_overview, D8 review-2 finding): canonical IDs are date-stamped
-    // (devstral-2-25-12, devstral-small-2-25-12). Vibe config.toml uses short
-    // forms (devstral-2, devstral-small-2). Plugin exposes BOTH so
-    // getProviderForModel routes either form.
+  it('mistral.models contains exactly the two canonical date-stamped IDs', () => {
+    // D17 fix: canonical-only shape. Length: 2 canonical IDs.
     assert.ok(mistral.models.includes('devstral-2-25-12'), 'missing canonical devstral-2-25-12');
     assert.ok(mistral.models.includes('devstral-small-2-25-12'), 'missing canonical devstral-small-2-25-12');
-    assert.ok(mistral.models.includes('devstral-2'), 'missing short-form alias devstral-2');
-    assert.ok(mistral.models.includes('devstral-small-2'), 'missing short-form alias devstral-small-2');
-    assert.ok(mistral.models.includes('devstral'), 'missing alias devstral');
-    assert.ok(mistral.models.includes('devstral-small'), 'missing alias devstral-small');
-    // Length: 2 canonical + 4 aliases = 6 total
-    assert.equal(mistral.models.length, 6, `Expected 6 entries (2 canonical + 4 aliases), got ${mistral.models.length}`);
+    assert.ok(!mistral.models.includes('devstral-2'), 'alias devstral-2 must NOT be in models[] (D17)');
+    assert.ok(!mistral.models.includes('devstral-small-2'), 'alias devstral-small-2 must NOT be in models[] (D17)');
+    assert.ok(!mistral.models.includes('devstral'), 'alias devstral must NOT be in models[] (D17)');
+    assert.ok(!mistral.models.includes('devstral-small'), 'alias devstral-small must NOT be in models[] (D17)');
+    // Length: 2 canonical only
+    assert.equal(mistral.models.length, 2, `Expected 2 canonical IDs, got ${mistral.models.length}`);
   });
 
   // ── Test 5: getProviderForModel finds mistral for each model ──────────
-  it('getProviderForModel finds mistral for devstral-2', () => {
+  it('getProviderForModel finds mistral for canonical devstral-2-25-12', () => {
+    const loaded = new Map([['mistral', mistral]]);
+    const result = getProviderForModel(loaded, 'devstral-2-25-12');
+    assert.ok(result !== null);
+    assert.equal(result.name, 'mistral');
+    assert.equal(result.canonicalModel, 'devstral-2-25-12');
+  });
+
+  it('getProviderForModel finds mistral for alias devstral-2 → canonical devstral-2-25-12 (D17)', () => {
+    // D17: alias resolution now handled in getProviderForModel, not in models[].
     const loaded = new Map([['mistral', mistral]]);
     const result = getProviderForModel(loaded, 'devstral-2');
     assert.ok(result !== null);
     assert.equal(result.name, 'mistral');
+    assert.equal(result.canonicalModel, 'devstral-2-25-12');
   });
 
-  it('getProviderForModel finds mistral for devstral-small-2', () => {
+  it('getProviderForModel finds mistral for alias devstral → canonical devstral-2-25-12 (D17)', () => {
+    const loaded = new Map([['mistral', mistral]]);
+    const result = getProviderForModel(loaded, 'devstral');
+    assert.ok(result !== null);
+    assert.equal(result.name, 'mistral');
+    assert.equal(result.canonicalModel, 'devstral-2-25-12');
+  });
+
+  it('getProviderForModel finds mistral for alias devstral-small-2 → canonical devstral-small-2-25-12 (D17)', () => {
     const loaded = new Map([['mistral', mistral]]);
     const result = getProviderForModel(loaded, 'devstral-small-2');
     assert.ok(result !== null);
     assert.equal(result.name, 'mistral');
+    assert.equal(result.canonicalModel, 'devstral-small-2-25-12');
   });
 
   // ── Test 6: irToMistral translation ──────────────────────────────────
@@ -3224,7 +3366,11 @@ describe('Mistral Vibe plugin (D8)', () => {
     const p = loaded.get('mistral');
     const { valid, errors } = validateProvider(p);
     assert.equal(valid, true, `Contract errors: ${errors.join('; ')}`);
-    assert.ok(p.models.includes('devstral-2'));
+    // D17: models[] is canonical-only. Verify via getProviderForModel instead of direct inclusion.
+    assert.ok(p.models.includes('devstral-2-25-12'), 'canonical devstral-2-25-12 must be in models[]');
+    const r = getProviderForModel(loaded, 'devstral-2');
+    assert.ok(r !== null, 'alias devstral-2 must route to mistral via getProviderForModel (D17)');
+    assert.equal(r.name, 'mistral');
   });
 
   // ── Test 16: auth artifact reading helpers ────────────────────────────