Tie mixed-source behavior to Enhanced Citations and describe its settings

[Paul Lizer (paullizer)]

Summary

V2 Admin Settings showed five undescribed "Mixed source ..." switches under Knowledge > Web & Research > Deep Research. Nothing declared them, so the enable_* fallback scan filed them there because they share the word "source". Two of them did nothing. The switches that actually gate mixed document and spreadsheet behavior had no control anywhere and defaulted off, so for example comparing a PDF with an XLSX failed with "temporarily unavailable while cross-format Compare is disabled".

• Behaviors that should always be on now follow Enhanced Citations. Mixed-source Chat and Search, follow-up source continuity, and cross-format Compare (including one-to-many) are rewritten to match enable_enhanced_citations on every settings load and save, because the spreadsheet engine they need only exists while Enhanced Citations is on. They stay hidden in V2. SIMPLECHAT_DISABLE_MIXED_SOURCE=true is an emergency kill switch, applied when settings are read and never saved.
• The two real choices are described in the right sections, in both V1 and V2:
  • "Look for relevant spreadsheets when no files are selected" (enable_mixed_source_relevance_candidates, default on) is under Chat > Citations > Enhanced.
  • "Record mixed document and spreadsheet metrics" (enable_mixed_source_development_telemetry, default off) is under Operations > Logging & Health > Application Insights.
  • A one-time upgrade, tracked by mixed_source_settings_version, turns relevance candidates on once. An administrator's later "off" is kept.
• Switches that did nothing are removed.
  • enable_mixed_source_analyze has had no effect since 0.250.071.
  • enable_mixed_source_manifest resolved shadow manifests and then discarded them.
  • Both are now in RETIRED_SETTING_KEYS, and the shadow-manifest code is deleted.
  • enable_mixed_source_analyze_all stays off and hidden, because no chat or workflow screen can request it.
• Clearer messages. The Enhanced Citations description now says it also turns on spreadsheet analysis. Refused mixed Compare requests name Enhanced Citations instead of a hidden flag.

Before: Knowledge > Web & Research > Deep Research	After: Chat > Citations > Enhanced

After: Operations > Logging & Health > Application Insights

Notes for reviewers

• Behavior change. Deployments with Enhanced Citations on start using mixed-source Chat, Search, continuity and cross-format Compare on the first settings load after upgrading. With Enhanced Citations off, behavior is unchanged apart from the Compare message.
• One-time settings rewrite. The first load rewrites the settings document once. Saved orchestration runs are tied to a fingerprint of the full settings, so a run paused across the upgrade may report recovery_changed, the same as after any admin save.
• Global logging switch moved. enable_appinsights_global_logging is now declared in application-insights-section too. The fallback scan had filed it under Debug Logging.
• Out of scope. With Enhanced Citations off, the classic chat page still ignores selected documents while its Search Documents panel is closed.
• Merge commit. This merges paullizer-react-v2-ui at e66f8f4 (Fix V2 admin Web Search test failing for saved Foundry connections #1662, Hide always-on tabular preflight switches from V2 Admin Settings #1663, V2 media galleries, a media viewer and a richer drawer Media section (0.261.262) #1664, Explain the search result cache under Azure AI Search in V2 admin #1665, Fix Video Indexer deployer region, app permissions, and settings erasure #1667, V2 admin: Enhanced Extraction section with Content Understanding nested #1668) and renumbers the version to 0.261.266. The conflicts were additive: the fixes index, the V2 suppressed-keys table, and the placement test's lists.

Linked issue

N/A (no tracking issue). Related initiative: Refs #1055

Release Notes & Latest Features

• New Feature
• Bug Fix
• UI Enhancement
• Breaking Change
• Internal only

Is this visible to end users?

• Yes
• No

Is this admin-facing (Admin Settings, governance, deployment, config)?

• Yes
• No

Should this become a Latest Feature card?

• Yes
• No
• Already added

Screenshot needed for the card?

• Yes
• No
• Attached

Version bump

• application/single_app/config.py VERSION third segment bumped, or not needed because this is docs-only (0.261.266)
• deployers/version.txt bumped, or not needed because deployers/ was not changed

Testing / validation

All run on the merged branch head, locally on Windows with Python 3.12 and Chromium via Playwright.

• python functional_tests/test_mixed_source_settings_derivation.py (new): passed, 9/9
• python functional_tests/test_v2_admin_capability_placement.py: passed, 9/9
• python -m pytest on the 11 ui_tests files that use AdminSettingsFixture, including the new ui_tests/test_v2_admin_mixed_source_settings.py: 94 passed
• python functional_tests/test_docs_app_surface_coverage.py: passed, 7/7
• python functional_tests/test_docs_site_quality.py: passed, 6/6
• python scripts/build_docs_inventory.py --check: passed, inventory in sync
• python functional_tests/route_tests/test_route_blueprint_policy_inventory.py: passed, 12/12
• python functional_tests/route_tests/test_route_unauthenticated_policy_contract.py: passed, 7/7
• python functional_tests/route_tests/test_route_policy_test_coverage.py: passed, 2/2
• python scripts/check_xss_sinks.py --base-sha origin/paullizer-react-v2-ui --head-sha HEAD on the changed application/ files: passed (9 files)
• python scripts/check_broken_access_control.py --base-sha origin/paullizer-react-v2-ui --head-sha HEAD on the changed Python files: passed (6 files)
• Comparison with the target branch: 0 new failures.
  • Ran python -m pytest <file> on 20 related functional test files, covering mixed-source, the settings store and writers, the orchestration upgrade, and tabular.
  • Ran one python -m pytest batch of the 30 functional_tests/test_v2_admin_*.py files plus test_docs_link_integrity.py.
  • Both ran on this branch and on a clean worktree of paullizer-react-v2-ui (e66f8f4).
  • The remaining failures are identical on the target in this environment: a missing content_screening module, a pyOpenSSL/cryptography mismatch, and existing failures such as 11 broken relative links in test_docs_link_integrity.py.
• Regression proof. With the target's admin_settings_fields.py swapped in, the built V2 page shows all five "Mixed source ..." rows under Deep Research (the Before screenshot). With this change, none appear.

Documentation

• Release notes updated, or not needed (not yet; an entry for 0.261.266 can be added)
• Feature documentation updated, or not needed
• Fix documentation updated, or not needed

Docs changed:

• New fix doc: docs/explanation/fixes/MIXED_SOURCE_ADMIN_SETTINGS_FIX.md
• "Settings Update" notes: the MIXED_SOURCE_* feature docs, CROSS_FORMAT_COMPARE.md, and V2_ADMIN_CHAT_SETTINGS.md
• Admin pages: docs/admin/chat.md and docs/admin/operations.md
• Other: docs/admin_configuration.md, docs/reference/application-workflows.md, docs/_data/features.yml, and the regenerated docs/_data/app_surface.yml

Security checklist

• New Flask routes include @swagger_route(security=get_auth_security()) (no new routes)
• Settings sent to non-admin frontends use sanitize_settings_for_user() (no change to what non-admin pages receive)
• Browser JavaScript is served from local SimpleChat static assets only; no CDN-hosted JS (no JavaScript changes)
• No secrets, keys, connection strings, or local-only artifacts are included