feat(libsy): stateful FallThrough routing algorithm + composable building blocks for libsy

[messiaen]

Summary

Add FallThrough Algorithm and it's building blocks. The idea is that the building blocks Processor and Classifier are used to implement small, reusable utilities which are used across Algorithms. In general our routing algorithms fall into the pattern implemented in FallThrough

FallThrough
Uses a list of Classifiers to determine routing decision.
It calls each one in turn returning the the first non-ambiguous Classification

It also takes a list of Processors which observe the requests / responses / decisions.
(they run at the start and between classifiers)
Processors log State the Classifiers use.

often a thing will implement Processor and Classifier eg AffinityRouter so in that way the are aligned w.r.t. state reads and writes.

Checklist

• One class per file; filename = snake_case of the primary class.
• New public symbols exported from switchyard/__init__.py.__all__ if intended for downstream use.
• Unit tests added for new components / bug fixes.
• README / --help updated if customer-facing surface changed.
• Commits signed off (Signed-off-by: Your Name <email>) per the DCO.

Notes for reviewers

Anything reviewers should pay extra attention to — risky paths, follow-up tickets, intentional trade-offs.

Summary by CodeRabbit

• New Features
  • Added fall-through routing to select an LLM target using ordered classifiers and confidence scores.
  • Added processor support for request handling, decisions, model interactions, and persistent session state.
  • Exposed classifier, processor, and state APIs for extensible routing workflows.
  • Added typed state storage and default metadata construction.
• Bug Fixes
  • Improved routing behavior for abstentions, ties, and cascading classifier decisions.

[coderabbitai]

Walkthrough

Changes

Routing core

Layer / File(s)	Summary
Core state and event contracts crates/libsy/src/core/state.rs, crates/libsy/src/core/processor.rs, crates/libsy/src/core.rs	Adds typed session state, processor events and traits, associated tests, and crate-level re-exports.
Classification and scoring contract crates/libsy/src/core/classifier.rs	Adds scored and ambiguous classifications, deterministic argmax selection, the async classifier trait, and tests.
Fall-through routing execution crates/libsy/src/algorithms/fall_through.rs, crates/libsy/src/algorithms.rs	Adds fall-through classifier selection, processor replay, session persistence, target invocation, decision types, exports, and integration tests.

Protocol metadata default

Layer / File(s)	Summary
Metadata default construction crates/protocol/src/envelope.rs	Adds a derived Default implementation to Metadata.

Estimated code review effort: 4 (Complex) | ~45 minutes

Poem

I’m a rabbit routing through the hay,
Picking the clearest model today.
State hops forward, classifiers chime,
Processors remember turn by turn time.
With defaults tucked neatly in sight,
The fall-through path runs just right!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: a stateful FallThrough routing algorithm plus supporting libsy primitives.

---

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

[coderabbitai]

Actionable comments posted: 5

🧹 Nitpick comments (1)

crates/libsy/src/core/processor.rs (1)

17-17: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

BoxErr alias duplicated identically across three files. Same root cause: no single shared definition of the crate's boxed error type, so each new module redefines it.

• crates/libsy/src/core/processor.rs#L17: keep as the canonical definition (or move to core.rs) and have the other two use it.
• crates/libsy/src/core/classifier.rs#L17: replace this local alias with an import of the shared one.
• crates/libsy/src/algorithms/fall_through.rs#L13: replace this local alias with an import of the shared one.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@crates/libsy/src/core/processor.rs` at line 17, The boxed error alias is
duplicated across three modules instead of being shared. Keep type alias BoxErr
in crates/libsy/src/core/processor.rs as the canonical definition, then remove
the local aliases and import BoxErr in crates/libsy/src/core/classifier.rs and
crates/libsy/src/algorithms/fall_through.rs; update visibility as needed so both
modules can access it.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@crates/libsy/src/algorithms/fall_through.rs`:
- Around line 35-44: Add a module-level `//!` documentation comment in the
`fall_through` module explaining its purpose and design, including the processor
chain, classifier cascade, routed model call, and session state lifecycle, so
the existing `module docs` references from `FallThrough` resolve correctly. Keep
the documentation focused on what the module does rather than build or
temporary-status details.
- Around line 71-126: Prevent create_run_task from holding the session state
mutex across external driver calls: keep the lock for processor/classifier state
mutation and decision replay, then release it before driver.info and
driver.call_llm_target. Preserve serialized state updates while ensuring
network-bound driver operations cannot block subsequent session turns
indefinitely.

In `@crates/libsy/src/core/classifier.rs`:
- Around line 19-37: Add concise Rust `///` documentation to the public
`Classification` enum and its `argmax` method. Document the distinction between
`Scores` and `Ambiguous`, and specify that `ignore_ambiguous` controls whether
`argmax` returns the best score or `None` for ambiguous classifications.
- Around line 41-49: Update argmax to rank confidence values without unwrapping
partial_cmp, using total_cmp (or otherwise explicitly rejecting non-finite
values) so NaN confidences cannot panic. Preserve the existing reverse iteration
and tie-breaking behavior where the earliest-listed target wins.

In `@crates/libsy/src/core/state.rs`:
- Around line 15-38: The public methods get, get_mut, insert, and
entry_or_insert_with need concise Rust documentation. Add /// comments
describing type-keyed lookup and mutable lookup, insert’s overwrite behavior,
and entry_or_insert_with’s lazy initialization and returned mutable reference,
while preserving their existing behavior.

---

Nitpick comments:
In `@crates/libsy/src/core/processor.rs`:
- Line 17: The boxed error alias is duplicated across three modules instead of
being shared. Keep type alias BoxErr in crates/libsy/src/core/processor.rs as
the canonical definition, then remove the local aliases and import BoxErr in
crates/libsy/src/core/classifier.rs and
crates/libsy/src/algorithms/fall_through.rs; update visibility as needed so both
modules can access it.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 1663c88a-f48e-49b2-baec-7074cd9f48fb

📥 Commits

Reviewing files that changed from the base of the PR and between 5ae2a0f and 27ca37d.

📒 Files selected for processing (7)

• crates/libsy/src/algorithms.rs
• crates/libsy/src/algorithms/fall_through.rs
• crates/libsy/src/core.rs
• crates/libsy/src/core/classifier.rs
• crates/libsy/src/core/processor.rs
• crates/libsy/src/core/state.rs
• crates/protocol/src/envelope.rs