Merge planner (Task C) cost-model routing

Brings in `dfa/planner.rs` (~430 LOC): `ScanPlanner`, `ScanContext`,
`ScanPlan` (with reserved `ShiftOr` variant), `ArchProfile` (CPUID
once at construction), and a calibrated `estimated_cost_ns` cost
model. Refactors `FoldedContainsDfa`, `FlatContainsDfa`,
`MultiContainsDfa::scan_to_bitbuf` to dispatch via the planner
into per-path `run_*` helpers; `ssa_saturated` /
`escape_pair_targets` consolidated into the planner module.

Adds `test_planner_matches_legacy_cascade` (12 corpus × needle
pairs from `benches/fsst_like.rs`) plus 11 unit tests covering
each routing decision row. New `VORTEX_FSST_PLAN_TRACE=1` env var
prints planner inputs + chosen plan + estimated cost.

Conflicts resolved:
- `folded_contains.rs`: kept Fat Teddy's accessor methods
  (`bucketed_pair_codes_slice`, `single_step_accept_codes_slice`)
  AND the planner's `scan_plan_name` refactor.
- `tests.rs`: kept Fat Teddy's `MultiNeedleMatcher` test section
  AND the planner's `test_planner_matches_legacy_cascade`
  bench-parity regression test.

After all three subagent merges (Shift-Or + Fat Teddy + planner),
210 tests pass with `_test-harness`. `cargo +nightly fmt --all`
clean.

Deferred TODOs preserved:
- Cross-bucket FDR for ESCAPE_CODE in Fat Teddy.
- AVX-512 / NEON variants of `fat_teddy_pass_*`.
- Planner integration of the `ShiftOr` plan (reserved slot
  exists; routing decision is still made in `try_new_with`).

Signed-off-by: Claude <noreply@anthropic.com>

Author: Claude Agent

encodings/fsst/src/dfa/flat_contains.rs

@@ -36,6 +36,9 @@ use super::build_fused_table;
 use super::build_symbol_transitions;
 use super::kmp_byte_transitions;
 use super::needle_bytes_absent_from_all_symbols;
+use super::planner::ScanContext;
+use super::planner::ScanPlan;
+use super::planner::ScanPlanner;
 use super::scan_to_bitbuf_with;
 use super::skip::SkipStrategy;
 
@@ -58,6 +61,10 @@ pub(crate) struct FlatContainsDfa {
     /// with a single `memmem` over `all_bytes` rather than running the
     /// sentinel-branching per-code DFA on every row.
     escape_only_pattern: Option<Vec<u8>>,
+    /// Routing engine. The flat DFA only routes between `EscapeOnly`
+    /// and `RowLoop`, but going through the planner keeps the
+    /// dispatch surface uniform across the three contains DFAs.
+    planner: ScanPlanner,
 }
 
 impl FlatContainsDfa {
@@ -118,6 +125,7 @@ impl FlatContainsDfa {
             skip,
             anchor,
             escape_only_pattern,
+            planner: ScanPlanner::new(),
         })
     }
 
@@ -176,10 +184,18 @@ impl FlatContainsDfa {
     where
         T: vortex_array::dtype::IntegerPType,
     {
-        if let Some(pattern) = self.escape_only_pattern.as_deref() {
-            return self.scan_via_escape_only_memmem(n, offsets, all_bytes, pattern, negated);
+        let ctx = ScanContext::for_flat_or_multi(n, all_bytes, self.escape_only_pattern.is_some());
+        match self.planner.plan_flat_or_multi(&ctx) {
+            ScanPlan::EscapeOnly => {
+                let pattern = self
+                    .escape_only_pattern
+                    .as_deref()
+                    .vortex_expect("EscapeOnly plan requires escape_only_pattern");
+                self.scan_via_escape_only_memmem(n, offsets, all_bytes, pattern, negated)
+            }
+            // The planner only emits these two for the flat DFA today.
+            _ => scan_to_bitbuf_with(n, offsets, all_bytes, negated, |codes| self.matches(codes)),
         }
-        scan_to_bitbuf_with(n, offsets, all_bytes, negated, |codes| self.matches(codes))
     }
 
     /// Single-`memmem` prefilter for the escape-only regime. Each hit is