feat(BA-6555): AppConfig merge engine + resolve service (service layer)

[jopemachine]

📚 Stacked PRs

Part of the AppConfigFragment / AppConfig stack under BEP-1052 (epic BA-5781). Merge in order:

1. ✅ feat(BA-6552): add app_config_fragments DB model and Alembic migration #12306 — feat(BA-6552): app_config_fragments DB model and Alembic migration
2. ✅ feat(BA-6553): add app_config_fragments repository layer #12307 — feat(BA-6553): repository layer
3. ✅ refactor(BA-6619): consolidate AppConfigScopeType into common.data (single definition) #12403 — refactor(BA-6619): consolidate AppConfigScopeType into common.data
4. ✅ refactor(BA-6620): ExistsQuerier ops primitive + AppConfigAllowList.exists #12405 — refactor(BA-6620): ExistsQuerier + AppConfigAllowList.exists
5. ✅ feat(BA-6554): add app_config_fragment service layer #12358 — feat(BA-6554): AppConfigFragment service layer
6. ✅ feat(BA-6702): move fragment rank to the allow list with scope defaults #12516 — feat(BA-6702): move fragment rank to the allow list with scope defaults
7. ✅ feat(BA-6701): expose allow-list rank on the v2 API surface #12517 — feat(BA-6701): expose allow-list rank on the v2 API surface
8. ✅ feat(BA-6704): cascade app config subtree deletion from the definition #12518 — feat(BA-6704): cascade app config subtree deletion from the definition
9. ✅ feat(BA-6626): app_config_fragment bulk repository layer #12426 — feat(BA-6626): app_config_fragment bulk repository layer
10. ✅ feat(BA-6618): app_config_fragment bulk CRUD service layer #12401 — feat(BA-6618): app_config_fragment bulk CRUD service layer
11. ✅ feat(BA-6810): AppConfigFragment visible-fragments query (repository layer) #12706 — feat(BA-6810): AppConfigFragment visible-fragments query (repository layer)
12. feat(BA-6886): register APP_CONFIG_FRAGMENT as an RBAC resource type #12856 — feat(BA-6886): register APP_CONFIG_FRAGMENT as an RBAC resource type + permission backfill
13. feat(BA-6859): bind AppConfig fragments to their RBAC scope on write (repository layer) #12826 — feat(BA-6859): bind fragments to their RBAC scope on write (repository layer)
14. fix(BA-6872): seed APP_CONFIG_FRAGMENT permissions into the RBAC role fixture #12837 — fix(BA-6872): seed APP_CONFIG_FRAGMENT permissions into the RBAC role fixture
15. chore(BA-6873): drop the dead APP_CONFIG RBAC entity type #12839 — chore(BA-6873): drop the dead APP_CONFIG RBAC entity type
16. 👉 feat(BA-6555): AppConfig merge engine + resolve service (service layer) #12359 — feat(BA-6555): AppConfig merge engine + resolve service (service layer) ← you are here
17. feat(BA-6556): AppConfig REST v2 API (raw fragments and merged read/update) #12377 — feat(BA-6556): AppConfig REST v2 API
18. feat(BA-6860): RBAC-gate app_config fragment writes at the processors #12759 — feat(BA-6860): fragment write API routes + bulk write authz

Access model: fragment create/update/purge are gated by RBAC (a user writes their own user-scope fragment, a domain admin their domain's, a superadmin any — public is superadmin-only); reads are gated by the allow list (existence = readable layer, rank = merge order) plus scope visibility, with no RBAC on the read path; app_config_definitions / app_config_allow_list themselves are superadmin-only (REST + GQL). Closed / superseded: #12794 · #12756 · #12764.

Summary

Adds the service / merge layer of the merged AppConfig read (BA-6555), on top of the repository query in #12706. Resolves the merged AppConfig for a (user, config_name) principal by deep-merging, in rank order, the fragments that #12706's list_visible_fragments returns. This is the read foundation the REST/GQL endpoints (BA-6556, #12377) build on.

Split from the original combined PR: the repository read (visibility conditions, AppConfigScopeArguments, list_visible_fragments[_bulk], real-DB query tests) now lives in #12706; this PR is the service/merge layer only.

What's included

• Merged view type (data/app_config/types.py): AppConfigData — the ordered contributing fragments (rank low → high) plus their deep-merged merged_config. merged_config is None when no fragment contributes (a defined-but-unconfigured name), distinct from a fragment that merges to an empty {}.
• Merge engine (AppConfigService._merge_configs / _deep_merge_replace): fragments deep-merged in ascending rank — nested dicts recurse, but lists and scalars are replaced wholesale by the higher-rank fragment (a user's list fully overrides the lower scope's, not element-by-index). Intentionally not common.utils.deep_merge, which index-merges lists.
• Service actions: resolve (one config_name) and resolve_bulk (several names for one principal, one query per distinct scope). Both are USER-scope GET actions returning AppConfigData in request order; a name repeated in resolve_bulk is repeated in the output.
• Tests: deep-merge semantics (recurse / wholesale list replace / None-projection / rank order), plus the resolve / resolve_bulk service paths against a mocked repository.

The HTTP surface (raw fragments + merged read/update) lands in BA-6556 (REST v2, #12377).

---

📚 Documentation preview 📚: https://sorna--12359.org.readthedocs.build/en/12359/

---

📚 Documentation preview 📚: https://sorna-ko--12359.org.readthedocs.build/ko/12359/

---

📚 Documentation preview 📚: https://sorna--12359.org.readthedocs.build/en/12359/

---

📚 Documentation preview 📚: https://sorna-ko--12359.org.readthedocs.build/ko/12359/

---

📚 Documentation preview 📚: https://sorna--12359.org.readthedocs.build/en/12359/

---

📚 Documentation preview 📚: https://sorna-ko--12359.org.readthedocs.build/ko/12359/

[Copilot]

Pull request overview

This PR (BA-6555) adds the read side of the AppConfig stack under BEP-1052: a service that resolves the merged AppConfig for a (user, config_name) principal by deep-merging the visible public / domain / user fragments in allow-list rank order. It is the read foundation for the upcoming REST v2 API (#12377) and introduces no HTTP surface itself.

Changes:

• New AppConfigService with resolve / resolve_bulk actions, processors, and a _merge_configs helper built on common.utils.deep_merge.
• New repository/db_source methods list_visible_fragments / list_visible_fragments_bulk (single OR-filtered query joined to the allow-list for rank), plus per-scope visibility conditions and the AppConfigScopeArguments value object.
• New AppConfigData merged-view type and unit/real-DB tests.

Reviewed changes

Copilot reviewed 14 out of 18 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
services/app_config/service.py	Merge engine (_merge_configs) and resolve / resolve_bulk service methods.
services/app_config/actions/{base,resolve,resolve_bulk}.py	USER-scope GET actions/results carrying merged AppConfigData.
services/app_config/processors.py	Processor package wiring the two resolve actions.
data/app_config/types.py	AppConfigData merged-view dataclass.
repositories/app_config_fragment/repository.py	Delegates the two visible-fragment reads to the db_source.
repositories/app_config_fragment/db_source/db_source.py	Builds the joined, rank-ordered visible-fragments query.
repositories/app_config_fragment/types.py	Adds AppConfigScopeArguments.
models/app_config_fragment/conditions.py	by_public/domain/user_visibility conditions.
tests/.../services/app_config/*, tests/.../repositories/app_config_fragment/test_repository.py	Service + real-DB repository tests.
changes/12359.feature.md	Changelog fragment.

Key points raised: the deep_merge list-merge behavior diverges from the described "wholesale-replace" semantics (and is untested), the config empty-case returns {} rather than the None the description claims, and the "single query" read path actually issues a discarded extra COUNT(*).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 13 changed files in this pull request and generated 3 comments.

[seedspirit]

Is it assuming that it only handles items within the same scope?