refactor: package UI runtime and propose Python quality gates (incomplete checkpoint)

[Paulo Lacerda (placerda)]

Resumed UI implementation for Azure/GPT-RAG#681

Draft targeting develop, head ee35c9ffea67902b4dc935e287beb5d4640ce6d6.
Coordination: Azure/GPT-RAG#689. Canonical documentation: Azure/GPT-RAG#688.
This supersedes the frozen 871106d checkpoint; it is implementation, not another audit-only handoff.

The remaining code-feasible UI work is implemented. Quality-policy adoption is still blocked: 28 exact application-boundary proposals are not approved, and the protected base has no adopted policy. No approvals, settings, merges, release/tag/image publication, deployment or VERSION change were performed.

Delivered changes

• 653660e31daa2de8219bf38a571e8bd97f227a8a: bounded U1 history split. api.history owns the Chainlit BaseDataLayer callbacks, fresh factory, registration, ambient session lookup/update and consume-once request metadata. services.history.HistoryService owns history/user operations, explicit HistoryOperationContext, orchestrator calls and the sole _users cache. Ownership precedes session selection and rename token resolution. Legacy datalayer.OrchestratorDataLayer/get_data_layer exports and value types remain compatible; no service-to-API edge, DTO hierarchy, storage rewrite or factory-semantic change.
• 1ef7539d7a04e388afe850b09e53f5fb12be3a76: concrete dependency-failure contracts and Q6 isolation. Repair the actual unbound Tenacity retry callback; do not retry absent in-memory keys or hide unexpected nested provider RetryError. Add config.errors.ConfigurationError. Narrow HTTP/JSON, Blob, JWT, VERSION and optional logging catches while retaining documented failures and surfacing programming defects. Resolve all 20 previously reported runtime Ruff findings.
• Protected static tools now use an independent environment installed from protected runtime/tool requirements, not candidate packaging/build code. Ruff/mypy use -I; Grimp/Import Linter use an isolated explicit source-directory graph without importing candidate application code. A Windows subprocess-environment regression also preserves explicit empty values after environment-restoring tests.
• ee35c9ffea67902b4dc935e287beb5d4640ce6d6: individual proposed-boundary records, exact refreshed observational inventory and reconciled contributor documentation. Broad sites decrease from 63 to 28. Every proposal includes the exact fingerprint/caught types, boundary-specific reason, outcome, diagnostic path, failure-test selector, review stage and expiry 2026-10-06. All remain proposed; none is an active waiver.

Actual evidence

CI: https://github.com/Azure/gpt-rag-ui/actions/runs/34050677391

GitHub evaluated merge commit d76bfc1b3ae878d63dd737b97e3f23301024cbcf, whose parents are protected base c635bc6696714b543feec24b4a062a8a8f3ff6d0 and PR head ee35c9ffea67902b4dc935e287beb5d4640ce6d6. Its tree c14d673a8be755c9bba6dd8d9952c7aa991ebd98 is identical to the PR head.

Execution	Observed result
Ubuntu full source unittest / same-run receipt	521 passed, zero skips, 75.755s; includes 52 quality fixtures and 11 clean installed-package methods
Ubuntu ephemeral Docker / offline behavioral suite	455 passed, 5.000s, including all original 410 behavioral cases; installed canonical origins, staged assets and actual Uvicorn listener readiness/not-ready smoke also passed
CI lint / typing / architecture	Passed, zero findings each
CI exception policy	28 violations: proposed application boundaries have no protected active approvals
CI policy / aggregate	1 bootstrap-review finding; aggregate correctly fails because protected policy is absent
Local combined resumed regression batch	171 passed, 57.341s
New local clean-wheel startup/download/OpenAPI acceptance	1 passed, 285.547s
Local full suite / gate	521 passed, zero skips, 385.571s, at head ee35c9f; same-source gate exit 1: lint/type/architecture passed with zero findings, 28 unapproved-handler findings and 1 bootstrap-review finding
Agentic assets	Existing validator passed: 3 agents, 5 skills and scoped instructions

The CI receipt records all 521 methods as passed with unchanged source. All 28 proposed sites match current source and all referenced failure tests passed in that receipt. Those facts do not approve any record.

The first local full attempt timed out during clean runtime-dependency installation. Its failed log/receipt were preserved; the unchanged retry passed without increasing timeouts or changing dependencies. The final local receipt and quality report share run ID 114b8ef9-a191-4d03-bb42-bb9781da229f, head ee35c9ffea67902b4dc935e287beb5d4640ce6d6 and unchanged source.

Typing is deliberately staged: 52 blocking identities of 80 discovered modules; the three original seeds are canonical config.chat_backend, config.panel_config, config.hosted_continuity_config, plus new modules/adapters. The other 28 moved identities remain explicitly uncovered; the CI report retains 108 nonblocking imported diagnostics. typing-baseline.json is empty. This is not a claim of full-repository type cleanliness.

Regression and task mapping

Tasks / requirement	Source and executable evidence
T004/T008/T011/T014/T017	Frozen migration inventory; four closed .quality schemas; pinned development tools; protected lint/type policy, workflow and CODEOWNERS; real-tool/protected-fixture/aggregate cases in test_quality_policy.py
T020/T026 / Q6	52 quality methods: cycles/private ownership, exact adapter exports, move/split debt identity, annotation/signature/suppression tampering, dynamic import targets/evidence, exception binding/expiry/status, actually executed non-skipped receipts and independent aggregation. New shadowing, explicit graph and candidate-installation-isolation fixtures exercise real pinned tools
Three independently reproduced earlier bypasses	test_real_mypy_qualified_suppression_disables_untyped_body_checking, test_exception_alias_rebinding_invalidates_existing_approval, test_root_namespace_sources_cannot_disappear_as_external_imports, plus lexical/qualified/class-member controls
T023/T030-T036 / U1	All 32 researched runtime files have canonical owners and thin public adapters. test_history_boundary.py adds 12 focused cases for API/service ownership, task-local consume-once metadata, shared users, ordered session updates, denial, explicit citations and propagated backend/framework defects
T029 / public failures	18 test_failure_contracts.py methods; 7 test_boundary_failures.py methods; 8 added socket failure methods; existing download/panel/continuity/security suites. Exact per-handler selectors live in .quality/exceptions.json
T030/T038 / U4	11 clean non-editable acceptance methods; copied behavioral tests only, canonical import origins, both import orders/single registration, classic lazy loading, hosted/panel activation, real auth order, uploads/write/cleanup, missing OAuth/not-ready and standalone download/OpenAPI failure behavior
T037	Existing Dockerfile package install and tests/container_smoke.py; Ubuntu ephemeral build, read-only mounted tests, --network none; no image push
T041 / UI portion of T045	Updated AGENTS.md, docs/python-development.md, Unreleased changelog and this immutable evidence handoff; parent owns canonical docs/umbrella reconciliation and human acceptance

Reproducible commands

Use Python 3.12 (local 3.12.9). Runtime requirements and Chainlit 2.9.4 remain unchanged. Development pins: Ruff 0.16.5, mypy 2.3.1, Import Linter 2.14, Grimp 3.16; setuptools 80.9.0 for packaging.

python -m pip install -r requirements.txt
python -m pip install -r requirements-quality.txt
python -m pip install --no-deps -e .
python -m unittest discover -s tests -v
python -m unittest discover -s tests -p test_quality_policy.py -v
python -m unittest discover -s tests -p test_installed_package.py -v
python .github\scripts\validate-agentic-assets.py

Same-source PowerShell receipt and gate, with no intervening source edits:

$env:QUALITY_RUN_ID = [guid]::NewGuid().ToString()
python .github\scripts\run-unittest.py --base-ref c635bc6696714b543feec24b4a062a8a8f3ff6d0 --report .artifacts\unittest.json
python .github\scripts\check-quality.py --check all --base-ref c635bc6696714b543feec24b4a062a8a8f3ff6d0 --test-evidence .artifacts\unittest.json --report .artifacts\quality.json

--check: all|lint|typing|architecture|exceptions|policy. Exit 0 = passed, 1 = violations, 2 = invalid/incomplete execution. Runner also supports --pattern for targeted work; the aggregate requires complete test_*.py discovery.

Non-editable code installation and unchanged operator startup:

python -m pip install --no-deps .
uvicorn main:app --host 0.0.0.0 --port 8080

For a wheel, build with python -m pip wheel --no-deps --wheel-dir .artifacts\wheel ., install that wheel into the target runtime environment after the unchanged runtime requirements, and start from the staged application root. The installed artifact is code plus externally staged .chainlit, public, chainlit.config.yaml, chainlit.md, VERSION; use existing CHAINLIT_APP_ROOT or that cwd. Uploads/config/assets stay in the writable application root, never site-packages. Docker retains /app and uvicorn main:app; no runtime dependency-list duplication or sys.path/sys.modules compatibility workaround.

Remaining acceptance and recovery

No further identified UI implementation repair remains in this scoped phase. Review/acceptance is not represented as completed: maintainers must decide each of the 28 proposed boundaries and adopt protected policy through PRs; administrators must activate required-check/code-owner enforcement and collect controlled positive/negative PR eligibility evidence. Live orchestrator v4.1.1 / ingestion v2.7.3 integration and production recovery acceptance are not substituted by these offline suites. These are genuine review/admin/live acceptance activities, not fabricated approvals.

The feature branch remains independent, draft and unmerged. Generated build/venv/wheel/egg-info/receipt artifacts are ignored; tracked status is clean. Restore the previous UI artifact built from c635bc6696714b543feec24b4a062a8a8f3ff6d0 (researched v2.6.2-equivalent runtime) through the existing release process if recovery is needed; no data, configuration-key, RBAC or backend contract migration is introduced. Do not disable the gate to bypass its adoption failure.