refactor(models): extract saved-routing authority

[decode2]

Summary

• Extract shared saved-routing types, normalization, and synchronous/asynchronous read authority into a production module.
• Route existing production callers through compatibility wrappers without changing current project-invalid or global-invalid behavior.
• Add focused authority tests for normalization, source states, source paths, sync/async parity, precedence, and wrapper compatibility.

Changes

File	Change
lib/model-routing-authority.ts	Add shared routing types, normalization, and sync/async file-read authority.
extensions/gentle-ai.ts	Replace duplicate helpers with production compatibility wrappers around the shared authority.
tests/model-routing-authority.test.ts	Cover normalization, missing/valid/invalid sources, paths, precedence, parity, and wrapper behavior.

Scope

• Diff: 275 additions and 107 deletions across 3 files (382 A+D).
• No direct export migration, apply behavior change, UI/status migration, canonical-name enforcement, durable write, or materialization.
• This is the first stacked-to-main slice; later work remains in refactor(models): isolate fail-closed saved-routing apply #396, refactor(models): migrate routing UI and lifecycle consumers #395, and refactor(models): enforce canonical routing names and target authority #391.

Strict TDD evidence

• RED: the absent authority module was captured as data and surfaced through an explicit assertion-level failure rather than an uncontrolled environment error.
• GREEN: focused authority tests passed after extracting the shared production module and compatibility wrappers.
• TRIANGULATE: covered missing, valid, and invalid global/project sources; source paths; sync/async parity; global precedence; project-invalid compatibility; null; inherit; and omissions.
• REFACTOR: removed superseded duplicate authority helpers and reran focused and package-wide verification.

Test plan

• node --experimental-strip-types --test tests/model-routing-authority.test.ts — 1/1 passed.
• node --experimental-strip-types --test tests/gentle-ai.test.ts — 8/8 passed.
• pnpm test — 1201 passed, 11 skipped, 0 failed.
• Syntax checks and git diff --check passed.

Contributor checklist

• Linked approved issue refactor(models): isolate saved-routing read authority #389.
• Selected exactly one PR type: code refactoring (type:refactor).
• Included tests with the implementation.
• Used a Conventional Commit message.
• Added no Co-Authored-By or AI attribution.
• Kept the review unit below 400 A+D.

Closes #389
Refs #382
Refs #381
Refs #396
Refs #395
Refs #391

Summary by CodeRabbit

• New Features

  • Added centralized model-routing configuration handling.
  • Supports consistent model ID, agent routing, and thinking-level normalization.
  • Added global and project configuration lookup with clear handling for missing or invalid files.
  • Added synchronous and asynchronous configuration loading.

• Bug Fixes

  • Preserved compatibility with invalid legacy project configurations by treating them as empty valid configurations.

• Tests

  • Added coverage for configuration precedence, normalization, file handling, environment-based resolution, and synchronous/asynchronous consistency.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: f80a5e75-9267-440a-af38-aa487d9ee52f

📥 Commits

Reviewing files that changed from the base of the PR and between 6338032 and cb54757.

📒 Files selected for processing (3)

• extensions/gentle-ai.ts
• lib/model-routing-authority.ts
• tests/model-routing-authority.test.ts

Included review availability: Your plan provides up to 2 included reviews per hour; 1 remains after this review.

---

📝 Walkthrough

Walkthrough

The change centralizes model-routing types, normalization, and configuration reads in a shared authority. gentle-ai.ts uses the shared implementation while preserving legacy invalid project-config handling. Tests cover normalization, file statuses, sync/async parity, precedence, and wrappers.

Changes

Model routing authority

Layer / File(s)	Summary
Routing contracts and normalization lib/model-routing-authority.ts	Defines shared thinking levels, routing types, model ID normalization, routing-entry normalization, and model-configuration normalization.
Configuration file authority lib/model-routing-authority.ts	Adds synchronous and asynchronous JSON readers with explicit missing, invalid, and valid results. Saved configuration lookup checks the global path before the project path.
Caller migration and authority validation extensions/gentle-ai.ts, tests/model-routing-authority.test.ts	Removes duplicated routing helpers from gentle-ai.ts, delegates saved-config loading to the shared authority, preserves project-invalid collapse, and adds authority behavior tests.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to cb547

This change centralizes saved-routing reads and normalization while preserving existing caller behavior; no actionable merge-blocking risk remains after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant gentle_ai
  participant modelRoutingAuthority
  participant FileSystem
  participant TestSuite
  gentle_ai->>modelRoutingAuthority: load saved model configuration
  modelRoutingAuthority->>FileSystem: read global configuration
  FileSystem-->>modelRoutingAuthority: file contents or status
  modelRoutingAuthority->>FileSystem: read project configuration when global is missing
  FileSystem-->>modelRoutingAuthority: file contents or status
  modelRoutingAuthority-->>gentle_ai: normalized configuration result
  TestSuite->>modelRoutingAuthority: validate sync and async readers
  modelRoutingAuthority-->>TestSuite: missing, invalid, or valid results

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 17 functions across 3 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes extracting saved model-routing authority.
Linked Issues check	✅ Passed	The changes implement issue #389 through shared normalization, sync/async reads, compatibility wrappers, and focused authority tests.
Out of Scope Changes check	✅ Passed	The changes stay within issue #389 and do not include export, apply, UI, status, canonical-name, write, or materialization work.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Alan-TheGentleman]

Reviewed: mechanical extraction into lib/model-routing-authority.ts, no behavior change, sync/async readers shared. Approving.