feat(BA-6556): AppConfig REST v2 API (fragments + merged read)

DI wiring (Repositories/Services/Processors/factory), the public/anonymous resolve
(resolve_public + list_public_fragments), and the REST v2 surface: admin fragment CRUD +
admin_search (superadmin), scoped-search keyed by domain/user scope (auth), merged
resolve (auth, with the temporary user_id==caller guard), and anonymous public read.

Scoped-search uses the domain/user scope targets from BA-6554 (audit_log pattern): the
request carries a scope of domain ids and/or user ids, OR-combined — no config_name or
RBAC validator (per the BA-6614 decision).

Squash of the BA-6556 development history, re-based onto the updated BA-6555.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: jopemachine

changes/12377.feature.md

@@ -0,0 +1 @@
+Add the AppConfig REST v2 API: admin CRUD and paginated search of raw config fragments, principal-scoped fragment search, the merged `(user, config_name)` resolve, and an anonymous public-only merged read (BEP-1052).

src/ai/backend/common/dto/manager/v2/app_config/__init__.py

@@ -0,0 +1,25 @@
+"""Request DTOs for the merged app_config v2 read."""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import Field
+
+from ai.backend.common.api_handlers import BaseRequestModel
+
+__all__ = ("ResolveAppConfigInput",)
+
+
+class ResolveAppConfigInput(BaseRequestModel):
+    """Input for resolving the merged AppConfig for one ``(user, config_name)``.
+
+    ``user_id`` must match the authenticated caller (enforced by the adapter until an RBAC
+    validator is in place).
+    """
+
+    config_name: str = Field(
+        min_length=1, max_length=128, description="Config name to resolve the merged view for."
+    )
+    domain_id: UUID = Field(description="The resolving user's domain id.")
+    user_id: UUID = Field(description="The resolving user's id (must be the caller).")

src/ai/backend/common/dto/manager/v2/app_config/request.py

@@ -0,0 +1,33 @@
+"""Response DTOs for the merged app_config v2 read."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import Field
+
+from ai.backend.common.api_handlers import BaseResponseModel
+from ai.backend.common.dto.manager.v2.app_config_fragment.response import AppConfigFragmentNode
+
+__all__ = (
+    "AppConfigNode",
+    "ResolveAppConfigPayload",
+)
+
+
+class AppConfigNode(BaseResponseModel):
+    """The merged AppConfig view for one config name."""
+
+    config_name: str = Field(description="Config name this merged view is for.")
+    config: dict[str, Any] | None = Field(
+        description="Deep-merged config in ascending rank order; null when no fragments apply."
+    )
+    fragments: list[AppConfigFragmentNode] = Field(
+        description="The fragments that contributed to the merge, in ascending rank order."
+    )
+
+
+class ResolveAppConfigPayload(BaseResponseModel):
+    """Payload for a merged AppConfig resolve."""
+
+    app_config: AppConfigNode = Field(description="The merged AppConfig view.")

src/ai/backend/common/dto/manager/v2/app_config/response.py

@@ -0,0 +1,137 @@
+"""Request DTOs for app_config_fragment v2."""
+
+from __future__ import annotations
+
+from typing import Any, Self
+from uuid import UUID
+
+from pydantic import Field, model_validator
+
+from ai.backend.common.api_handlers import BaseRequestModel
+from ai.backend.common.data.app_config.types import AppConfigScopeType
+from ai.backend.common.dto.manager.query import DateTimeFilter, StringFilter
+from ai.backend.common.dto.manager.v2.app_config_fragment.types import (
+    AppConfigFragmentOrderField,
+    AppConfigScopeTypeFilter,
+)
+from ai.backend.common.dto.manager.v2.common import OrderDirection
+
+__all__ = (
+    "AppConfigFragmentFilter",
+    "AppConfigFragmentOrder",
+    "AppConfigFragmentScope",
+    "CreateAppConfigFragmentInput",
+    "PurgeAppConfigFragmentInput",
+    "ScopedSearchAppConfigFragmentInput",
+    "SearchAppConfigFragmentInput",
+    "UpdateAppConfigFragmentInput",
+)
+
+
+class CreateAppConfigFragmentInput(BaseRequestModel):
+    """Input for creating a new app config fragment at a given scope (superadmin only)."""
+
+    config_name: str = Field(
+        min_length=1,
+        max_length=128,
+        description="Registered config name (FK to app_config_definitions).",
+    )
+    scope_type: AppConfigScopeType = Field(
+        description="Scope the fragment is written at (public | domain | user)."
+    )
+    scope_id: str = Field(
+        description="Scope identifier: 'public' for public, the domain name, or the user id.",
+    )
+    config: dict[str, Any] = Field(description="The fragment's JSON config document.")
+
+
+class UpdateAppConfigFragmentInput(BaseRequestModel):
+    """Input for updating an app config fragment's config document."""
+
+    config: dict[str, Any] = Field(description="The replacement JSON config document.")
+
+
+class PurgeAppConfigFragmentInput(BaseRequestModel):
+    """Input for purging an app config fragment."""
+
+    id: UUID = Field(description="App config fragment id to purge.")
+
+
+class AppConfigFragmentFilter(BaseRequestModel):
+    """Filter for app config fragment search."""
+
+    config_name: StringFilter | None = Field(default=None, description="Filter by config name.")
+    scope_type: AppConfigScopeTypeFilter | None = Field(
+        default=None, description="Filter by scope type."
+    )
+    created_at: DateTimeFilter | None = Field(
+        default=None, description="Filter by creation datetime."
+    )
+    updated_at: DateTimeFilter | None = Field(
+        default=None, description="Filter by last update datetime."
+    )
+
+
+class AppConfigFragmentOrder(BaseRequestModel):
+    """Order specifier for app config fragment search."""
+
+    field: AppConfigFragmentOrderField = Field(description="Field to order by.")
+    direction: OrderDirection = Field(default=OrderDirection.ASC, description="Order direction.")
+
+
+class SearchAppConfigFragmentInput(BaseRequestModel):
+    """Input for paginated app config fragment search (superadmin only)."""
+
+    filter: AppConfigFragmentFilter | None = Field(default=None, description="Filter conditions.")
+    order: list[AppConfigFragmentOrder] | None = Field(
+        default=None, description="Order specifiers, applied in sequence."
+    )
+    first: int | None = Field(default=None, ge=1, description="Cursor-forward page size.")
+    after: str | None = Field(default=None, description="Cursor-forward start cursor.")
+    last: int | None = Field(default=None, ge=1, description="Cursor-backward page size.")
+    before: str | None = Field(default=None, description="Cursor-backward end cursor.")
+    limit: int | None = Field(
+        default=None, ge=1, description="Offset-based: maximum number of results."
+    )
+    offset: int | None = Field(
+        default=None, ge=0, description="Offset-based: number of results to skip."
+    )
+
+
+class AppConfigFragmentScope(BaseRequestModel):
+    """Scope for a scoped fragment search — OR across all domain/user items.
+
+    Raises if every category is empty.
+    """
+
+    domain: list[UUID] | None = Field(
+        default=None, description="Domain ids whose fragments to search."
+    )
+    user: list[UUID] | None = Field(default=None, description="User ids whose fragments to search.")
+
+    @model_validator(mode="after")
+    def _require_non_empty(self) -> Self:
+        if not self.domain and not self.user:
+            raise ValueError(
+                "AppConfigFragmentScope requires a non-empty value for 'domain' or 'user'"
+            )
+        return self
+
+
+class ScopedSearchAppConfigFragmentInput(BaseRequestModel):
+    """Input for a scoped fragment search keyed by domain/user scope (OR-combined)."""
+
+    scope: AppConfigFragmentScope = Field(description="Scope (OR across all items).")
+    order: list[AppConfigFragmentOrder] | None = Field(
+        default=None, description="Order specifiers, applied in sequence."
+    )
+    first: int | None = Field(default=None, ge=1, description="Cursor-forward page size.")
+    after: str | None = Field(default=None, description="Cursor-forward start cursor.")
+    last: int | None = Field(default=None, ge=1, description="Cursor-backward page size.")
+    before: str | None = Field(default=None, description="Cursor-backward end cursor.")
+    limit: int | None = Field(
+        default=None, ge=1, description="Offset-based: maximum number of results."
+    )
+    offset: int | None = Field(
+        default=None, ge=0, description="Offset-based: number of results to skip."
+    )

src/ai/backend/common/dto/manager/v2/app_config_fragment/__init__.py

@@ -0,0 +1,60 @@
+"""Response DTOs for app_config_fragment v2."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+from uuid import UUID
+
+from pydantic import Field
+
+from ai.backend.common.api_handlers import BaseResponseModel
+from ai.backend.common.data.app_config.types import AppConfigScopeType
+
+__all__ = (
+    "AppConfigFragmentNode",
+    "CreateAppConfigFragmentPayload",
+    "PurgeAppConfigFragmentPayload",
+    "SearchAppConfigFragmentPayload",
+    "UpdateAppConfigFragmentPayload",
+)
+
+
+class AppConfigFragmentNode(BaseResponseModel):
+    """Node model representing one app config fragment."""
+
+    id: UUID = Field(description="App config fragment UUID.")
+    config_name: str = Field(description="Config name the fragment belongs to.")
+    scope_type: AppConfigScopeType = Field(description="Scope the fragment is written at.")
+    scope_id: str = Field(description="Scope identifier (public / domain name / user id).")
+    rank: int = Field(description="Merge rank (lower merges first, higher overrides).")
+    config: dict[str, Any] = Field(description="The fragment's JSON config document.")
+    created_at: datetime = Field(description="Creation timestamp (UTC).")
+    updated_at: datetime = Field(description="Last update timestamp (UTC).")
+
+
+class CreateAppConfigFragmentPayload(BaseResponseModel):
+    """Payload for app config fragment creation."""
+
+    app_config_fragment: AppConfigFragmentNode = Field(description="Created app config fragment.")
+
+
+class UpdateAppConfigFragmentPayload(BaseResponseModel):
+    """Payload for app config fragment update."""
+
+    app_config_fragment: AppConfigFragmentNode = Field(description="Updated app config fragment.")
+
+
+class PurgeAppConfigFragmentPayload(BaseResponseModel):
+    """Payload for app config fragment purge."""
+
+    id: UUID = Field(description="UUID of the purged app config fragment.")
+
+
+class SearchAppConfigFragmentPayload(BaseResponseModel):
+    """Payload for paginated app config fragment search results."""
+
+    items: list[AppConfigFragmentNode] = Field(description="App config fragment nodes.")
+    total_count: int = Field(description="Total count matching the query.")
+    has_next_page: bool = Field(description="Whether there is a next page.")
+    has_previous_page: bool = Field(description="Whether there is a previous page.")

src/ai/backend/common/dto/manager/v2/app_config_fragment/request.py

@@ -0,0 +1,38 @@
+"""Enum types and filters for app_config_fragment v2 DTOs."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+from pydantic import Field
+
+from ai.backend.common.api_handlers import BaseRequestModel
+from ai.backend.common.data.app_config.types import AppConfigScopeType
+
+__all__ = (
+    "AppConfigScopeTypeFilter",
+    "AppConfigFragmentOrderField",
+)
+
+
+class AppConfigScopeTypeFilter(BaseRequestModel):
+    """Filter for the scope_type enum field."""
+
+    equals: AppConfigScopeType | None = Field(default=None, description="Exact scope type match.")
+    in_: list[AppConfigScopeType] | None = Field(
+        default=None, alias="in", description="Match any of the provided scope types."
+    )
+    not_equals: AppConfigScopeType | None = Field(
+        default=None, description="Exclude exact scope type match."
+    )
+    not_in: list[AppConfigScopeType] | None = Field(
+        default=None, description="Exclude any of the provided scope types."
+    )
+
+
+class AppConfigFragmentOrderField(StrEnum):
+    CONFIG_NAME = "config_name"
+    SCOPE_TYPE = "scope_type"
+    RANK = "rank"
+    CREATED_AT = "created_at"
+    UPDATED_AT = "updated_at"