@qingflow-tech/qingflow-cli 1.1.61-beta.4 → 1.1.61-beta.5

package/src/qingflow_mcp/builder_facade/models.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import re
 from enum import Enum
-from typing import Any, Union
+from typing import Any, Literal, Union
 
 from pydantic import AliasChoices, Field, model_validator
 
@@ -2508,14 +2508,17 @@ class PortalInlineChartPatch(ChartUpsertPatch):
 
 
 class PortalComponentPositionPatch(StrictModel):
-    pc_x: int = Field(default=0, validation_alias=AliasChoices("pc_x", "pcX", "x"))
-    pc_y: int = Field(default=0, validation_alias=AliasChoices("pc_y", "pcY", "y"))
-    pc_w: int = Field(default=12, validation_alias=AliasChoices("pc_w", "pcW", "w"))
-    pc_h: int = Field(default=8, validation_alias=AliasChoices("pc_h", "pcH", "h"))
-    mobile_x: int = Field(default=0, validation_alias=AliasChoices("mobile_x", "mobileX"))
-    mobile_y: int = Field(default=0, validation_alias=AliasChoices("mobile_y", "mobileY"))
-    mobile_w: int = Field(default=6, validation_alias=AliasChoices("mobile_w", "mobileW"))
-    mobile_h: int = Field(default=8, validation_alias=AliasChoices("mobile_h", "mobileH"))
+    # 后端语义(DashSvcImpl 读/写链):position 各坐标可为 null——生产数据中筛选组件
+    # (type=6)的 x/y/cols/rows 原生为 NULL,读面透传 null、写链 setPosition 直存 null。
+    # 因此显式 null 必须原样透传(round-trip 保真);仅键缺省时才回落布局默认值。
+    pc_x: int | None = Field(default=0, validation_alias=AliasChoices("pc_x", "pcX", "x"))
+    pc_y: int | None = Field(default=0, validation_alias=AliasChoices("pc_y", "pcY", "y"))
+    pc_w: int | None = Field(default=12, validation_alias=AliasChoices("pc_w", "pcW", "w"))
+    pc_h: int | None = Field(default=8, validation_alias=AliasChoices("pc_h", "pcH", "h"))
+    mobile_x: int | None = Field(default=0, validation_alias=AliasChoices("mobile_x", "mobileX"))
+    mobile_y: int | None = Field(default=0, validation_alias=AliasChoices("mobile_y", "mobileY"))
+    mobile_w: int | None = Field(default=6, validation_alias=AliasChoices("mobile_w", "mobileW"))
+    mobile_h: int | None = Field(default=8, validation_alias=AliasChoices("mobile_h", "mobileH"))
     mobile_provided: bool = Field(default=False, exclude=True)
 
     @model_validator(mode="before")
@@ -2554,6 +2557,10 @@ class PortalChartRefPatch(StrictModel):
     app_key: str | None = None
     chart_id: str | None = None
     chart_name: str | None = None
+    # 引用面判别:后端有两类图表组件——轻流报表(DASH_CONTENT_TYPE_CHART=1,chart 表唯一键
+    # chartKey,写链 addChartInfos 按 chartKey 解析)与轻析 BI 报表(DASH_CONTENT_TYPE_BICHART=9,
+    # bi_chart 表整型 chart_id,写链 addBiChartInfo 直存)。缺省 bi_chart(向后兼容既有声明)。
+    ref_kind: Literal["chart", "bi_chart"] | None = None
 
     @model_validator(mode="before")
     @classmethod
@@ -2573,12 +2580,18 @@ class PortalChartRefPatch(StrictModel):
             payload["chart_name"] = payload.pop("name")
         if "appKey" in payload and "app_key" not in payload:
             payload["app_key"] = payload.pop("appKey")
+        if "refKind" in payload and "ref_kind" not in payload:
+            payload["ref_kind"] = payload.pop("refKind")
+        if "kind" in payload and "ref_kind" not in payload:
+            payload["ref_kind"] = payload.pop("kind")
         return payload
 
     @model_validator(mode="after")
     def validate_target(self) -> "PortalChartRefPatch":
         if not (self.chart_id or self.chart_name):
             raise ValueError("chart_ref requires chart_id or chart_name")
+        if self.ref_kind == "chart" and not self.chart_id:
+            raise ValueError("chart_ref with ref_kind=chart requires chart_id (chart 表唯一键 chartKey)")
         if self.chart_name and not self.chart_id and not self.app_key:
             raise ValueError("chart_ref.app_key is required when resolving by chart_name")
         return self
@@ -2604,17 +2617,49 @@ class PortalViewRefPatch(StrictModel):
 
 
 class PortalSectionPatch(StrictModel):
-    title: str
+    # title 语义=组件显示标题(draft_dash_chart.component_title / grid_config.gridTitle 等),
+    # 生产存量存在空标题形态(显示标题开但标题空,读链回退视图名/图表名)——None=不设标题,
+    # 编译对 None 不落库(后端透传 NULL),round-trip 保真;手写声明缺省 title=None(不设)。
+    title: str | None = None
     source_type: str = Field(validation_alias=AliasChoices("source_type", "sourceType"))
     role: str | None = Field(default=None, validation_alias=AliasChoices("role", "zone", "section_role", "sectionRole"))
+    # 显示标题开关(draft_dash_chart.being_show_title):提取侧读面必有值(True/False);
+    # 声明缺省 None 时编译回落产品默认 True(与既有创建语义兼容)。
+    show_title: bool | None = Field(
+        default=None,
+        validation_alias=AliasChoices("show_title", "showTitle", "being_show_title", "beingShowTitle"),
+    )
     position: PortalComponentPositionPatch | None = None
-    dash_style_config: dict[str, Any] | None = Field(default=None, validation_alias=AliasChoices("dash_style_config", "dashStyleConfigBO"))
+    dash_style_config: dict[str, Any] | None = Field(
+        default=None,
+        validation_alias=AliasChoices("dash_style_config", "style_config", "dashStyleConfigBO", "dashStyleConfig"),
+    )
     config: dict[str, Any] = Field(default_factory=dict)
     chart_ref: PortalChartRefPatch | None = None
     chart: PortalInlineChartPatch | None = Field(default=None, validation_alias=AliasChoices("chart", "inline_chart", "inlineChart", "create_chart", "createChart"))
     view_ref: PortalViewRefPatch | None = None
+    view_display: dict[str, Any] | None = Field(
+        default=None,
+        validation_alias=AliasChoices("view_display", "viewDisplay"),
+    )
     text: str | None = None
     url: str | None = None
+    login_auth: bool | None = Field(
+        default=None,
+        validation_alias=AliasChoices("login_auth", "loginAuth", "being_login_auth", "beingLoginAuth"),
+    )
+    carousel: dict[str, Any] | None = Field(
+        default=None,
+        validation_alias=AliasChoices("carousel", "carousel_config", "carouselConfig"),
+    )
+    task: dict[str, Any] | None = Field(
+        default=None,
+        validation_alias=AliasChoices("task", "task_config", "taskConfig"),
+    )
+    favourite: dict[str, Any] | None = Field(
+        default=None,
+        validation_alias=AliasChoices("favourite", "favourite_config", "favouriteConfig"),
+    )
 
     @model_validator(mode="before")
     @classmethod
@@ -2659,7 +2704,7 @@ class PortalSectionPatch(StrictModel):
 
     @model_validator(mode="after")
     def validate_shape(self) -> "PortalSectionPatch":
-        supported = {"chart", "view", "grid", "filter", "text", "link"}
+        supported = {"chart", "view", "grid", "filter", "text", "link", "carousel", "task", "favourite"}
         if self.source_type not in supported:
             raise ValueError(f"unsupported portal source_type '{self.source_type}'")
         if self.source_type == "chart" and self.chart_ref is None and self.chart is None:
@@ -2670,6 +2715,12 @@ class PortalSectionPatch(StrictModel):
             raise ValueError("text section requires text")
         if self.source_type == "link" and self.url is None:
             raise ValueError("link section requires url")
+        if self.source_type == "carousel" and self.carousel is None:
+            raise ValueError("carousel section requires carousel")
+        if self.source_type == "task" and self.task is None:
+            raise ValueError("task section requires task")
+        if self.source_type == "favourite" and self.favourite is None:
+            raise ValueError("favourite section requires favourite")
         return self
 
 
@@ -2685,8 +2736,20 @@ class PortalApplyRequest(StrictModel):
     icon: str | None = None
     color: str | None = None
     hide_copyright: bool | None = Field(default=None, validation_alias=AliasChoices("hide_copyright", "hideCopyright"))
-    dash_global_config: dict[str, Any] | None = Field(default=None, validation_alias=AliasChoices("dash_global_config", "dashGlobalConfig"))
+    global_config: dict[str, Any] | None = Field(
+        default=None,
+        validation_alias=AliasChoices("global_config", "globalConfig", "dash_global_config", "dashGlobalConfig"),
+    )
+    style_template_id: int | None = Field(
+        default=None,
+        validation_alias=AliasChoices("style_template_id", "styleTemplateId"),
+    )
+    overall_style: dict[str, Any] | None = Field(
+        default=None,
+        validation_alias=AliasChoices("overall_style", "overallStyle", "overallConfigBO"),
+    )
     config: dict[str, Any] = Field(default_factory=dict)
+    schema_version: str | None = Field(default=None, validation_alias=AliasChoices("schema_version", "schemaVersion"))
 
     @model_validator(mode="before")
     @classmethod
@@ -2694,8 +2757,14 @@ class PortalApplyRequest(StrictModel):
         if not isinstance(value, dict):
             return value
         payload = dict(value)
+        payload.pop("schema_version", None)
+        payload.pop("schemaVersion", None)
         if "dash_name" not in payload and "dashName" not in payload and "name" in payload:
             payload["dash_name"] = payload.pop("name")
+        if "dash_global_config" in payload and "global_config" not in payload:
+            payload["global_config"] = payload.pop("dash_global_config")
+        elif "dashGlobalConfig" in payload and "global_config" not in payload:
+            payload["global_config"] = payload.pop("dashGlobalConfig")
         if "sections" not in payload and "pages" in payload:
             pages = payload.pop("pages")
             if not isinstance(pages, list):
@@ -2730,6 +2799,88 @@ class PortalApplyRequest(StrictModel):
         return self
 
 
+def _public_portal_section_payload(section: PortalSectionPatch) -> dict[str, Any]:
+    """Dump one portal section with canonical naming for schema validation."""
+    payload: dict[str, Any] = {
+        "title": section.title,
+        "source_type": section.source_type,
+    }
+    if section.role is not None:
+        payload["role"] = section.role
+    if section.position is not None:
+        payload["position"] = {
+            "pc": {
+                "x": section.position.pc_x,
+                "y": section.position.pc_y,
+                "cols": section.position.pc_w,
+                "rows": section.position.pc_h,
+            },
+        }
+        if section.position.mobile_provided:
+            payload["position"]["mobile"] = {
+                "x": section.position.mobile_x,
+                "y": section.position.mobile_y,
+                "cols": section.position.mobile_w,
+                "rows": section.position.mobile_h,
+            }
+    if section.dash_style_config is not None:
+        payload["style_config"] = section.dash_style_config
+    if section.chart_ref is not None:
+        payload["chart_ref"] = section.chart_ref.model_dump(mode="json", exclude_none=True)
+    if section.chart is not None:
+        payload["chart"] = section.chart.model_dump(mode="json", exclude_none=True)
+    if section.view_ref is not None:
+        payload["view_ref"] = section.view_ref.model_dump(mode="json", exclude_none=True)
+    if section.view_display is not None:
+        payload["view_display"] = section.view_display
+    if section.text is not None:
+        payload["text"] = section.text
+    if section.url is not None:
+        payload["url"] = section.url
+    if section.login_auth is not None:
+        payload["login_auth"] = section.login_auth
+    if section.carousel is not None:
+        payload["carousel"] = section.carousel
+    if section.task is not None:
+        payload["task"] = section.task
+    if section.favourite is not None:
+        payload["favourite"] = section.favourite
+    if section.config:
+        payload["config"] = section.config
+    return payload
+
+
+def public_portal_apply_payload(request: PortalApplyRequest) -> dict[str, Any]:
+    """Canonical-named portal declaration used for schema validation."""
+    payload: dict[str, Any] = {}
+    if request.dash_key:
+        payload["dash_key"] = request.dash_key
+    if request.dash_name is not None:
+        payload["name"] = request.dash_name
+    if request.package_tag_id is not None:
+        payload["package_tag_id"] = request.package_tag_id
+    payload["publish"] = request.publish
+    if request.sections is not None:
+        payload["sections"] = [_public_portal_section_payload(section) for section in request.sections]
+    if request.layout_preset is not None:
+        payload["layout_preset"] = request.layout_preset
+    if request.visibility is not None:
+        payload["visibility"] = request.visibility.model_dump(mode="json", exclude_none=True)
+    if request.icon is not None:
+        payload["icon"] = request.icon
+    if request.color is not None:
+        payload["color"] = request.color
+    if request.hide_copyright is not None:
+        payload["hide_copyright"] = request.hide_copyright
+    if request.global_config is not None:
+        payload["global_config"] = request.global_config
+    if request.style_template_id is not None:
+        payload["style_template_id"] = request.style_template_id
+    if request.overall_style is not None:
+        payload["overall_style"] = request.overall_style
+    return payload
+
+
 FieldPatch.model_rebuild()
 FieldMutation.model_rebuild()
 FieldUpdatePatch.model_rebuild()

package/src/qingflow_mcp/builder_facade/portals_schema.py

@@ -0,0 +1,397 @@
+from __future__ import annotations
+
+import json
+import os
+from copy import deepcopy
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from jsonschema import Draft202012Validator, FormatChecker
+from referencing import Registry, Resource
+
+from .app_form_schema import compact_schema_errors, schema_error_message
+
+JSONObject = dict[str, Any]
+PORTALS_SCHEMA_ROOT = Path(__file__).with_name("schemas") / "portals"
+PORTALS_SUPPORTED_SCHEMA_KINDS = (
+    "summary",
+    "complete",
+    "chart",
+    "view",
+    "grid",
+    "filter",
+    "text",
+    "link",
+    "carousel",
+    "task",
+    "favourite",
+)
+
+
+class PortalsContractError(ValueError):
+    """Raised when a portals declaration violates the versioned schema contract."""
+
+    def __init__(self, error_code: str, message: str, *, path: str | None = None, details: JSONObject | None = None) -> None:
+        super().__init__(message)
+        self.error_code = error_code
+        self.message = message
+        self.path = path
+        self.details = details or {}
+
+
+def compact_none_values(value: Any) -> Any:
+    """Recursively drop None values so pydantic dumps match the JSON Schema contract."""
+    if isinstance(value, dict):
+        return {key: compact_none_values(item) for key, item in value.items() if item is not None}
+    if isinstance(value, list):
+        return [compact_none_values(item) for item in value]
+    return value
+
+
+@dataclass(frozen=True, slots=True)
+class PortalsSchemaContext:
+    """Resolved schema context for one portals schema version."""
+
+    schema_version: str
+    api_version: str
+    schemas: dict[str, JSONObject]
+    schema_files: dict[str, str]
+    ref_registry: Registry
+    supported_schema_kinds: tuple[str, ...]
+    contract_source: str
+    contract_version: str
+
+    @property
+    def summary_schema(self) -> JSONObject:
+        return self.schemas["summary"]
+
+    @property
+    def complete_schema(self) -> JSONObject:
+        return self.schemas["complete"]
+
+    def schema_for_kind(self, schema_kind: str) -> JSONObject:
+        requested = str(schema_kind or "").strip()
+        schema = self.schemas.get(requested)
+        if schema is not None:
+            return schema
+        raise PortalsContractError(
+            "UNSUPPORTED_SCHEMA_KIND",
+            f"unsupported portals schema kind: {requested}",
+            details={"supportedKinds": list(self.supported_schema_kinds)},
+        )
+
+    def _validate(self, payload: JSONObject, *, schema_kind: str) -> None:
+        schema = self.schema_for_kind(schema_kind)
+        validator = Draft202012Validator(schema, format_checker=FormatChecker(), registry=self.ref_registry)
+        errors = sorted(validator.iter_errors(payload), key=lambda item: (list(item.absolute_path), item.message))
+        if not errors:
+            return
+        compact_errors = compact_schema_errors(errors, schema)
+        error = compact_errors[0] if compact_errors else errors[0]
+        pointer = "".join(f"/{str(part).replace('~', '~0').replace('/', '~1')}" for part in error.absolute_path) or "/"
+        raise PortalsContractError(
+            "INVALID_SPEC",
+            schema_error_message(error),
+            path=pointer,
+            details={
+                "validator": error.validator,
+                "schemaPath": "/".join(str(part) for part in error.absolute_schema_path),
+                "schemaKind": schema_kind,
+            },
+        )
+
+    def validate_upsert(self, payload: JSONObject, *, schema_kind: str = "complete") -> None:
+        """Validate a single (alias-normalized) portal declaration."""
+        self._validate(payload, schema_kind=schema_kind)
+
+    def validate_declaration(self, payload: JSONObject, *, schema_kind: str = "complete") -> None:
+        """Validate one portal declaration used by ``portal_apply``."""
+        if not isinstance(payload, dict):
+            raise PortalsContractError("INVALID_SPEC", "portals declaration must be a JSON object", path="/")
+        self._validate(payload, schema_kind=schema_kind)
+
+
+class PortalsSchemaRegistry:
+    """Registry for versioned portals declaration schemas (mirrors ViewsSchemaRegistry)."""
+
+    def __init__(self, root: Path = PORTALS_SCHEMA_ROOT, *, enabled_versions: tuple[str, ...] | None = None) -> None:
+        self.root = root
+        self.manifest = self._read_json(root / "manifest.json")
+        versions = self.manifest.get("versions")
+        if not isinstance(versions, dict) or not versions:
+            raise RuntimeError("portals schema manifest must define versions")
+        env_versions = self._configured_versions()
+        defaults = tuple(
+            str(version)
+            for version, metadata in versions.items()
+            if isinstance(metadata, dict) and bool(metadata.get("enabledByDefault"))
+        )
+        configured = tuple(enabled_versions) if enabled_versions is not None else (env_versions or defaults)
+        self.stored_versions = tuple(str(version) for version in versions)
+        self.latest_version = str(self.manifest.get("latestVersion") or "")
+        self._stored_api_to_version: dict[str, str] = {}
+        for version, metadata in versions.items():
+            if not isinstance(metadata, dict):
+                raise RuntimeError(f"portals schema metadata must be an object: {version}")
+            api_version = str(metadata.get("apiVersion") or "")
+            if not api_version:
+                raise RuntimeError(f"portals schema version has no apiVersion: {version}")
+            if api_version in self._stored_api_to_version:
+                raise RuntimeError(f"duplicate portals apiVersion: {api_version}")
+            self._stored_api_to_version[api_version] = str(version)
+        self.enabled_versions = configured
+        if self.latest_version not in versions:
+            raise RuntimeError("portals latestVersion is not stored")
+        if self.latest_version not in self.enabled_versions:
+            raise RuntimeError("portals latestVersion must remain enabled")
+        self._contexts: dict[str, PortalsSchemaContext] = {}
+        self._api_to_version: dict[str, str] = {}
+        for version in self.enabled_versions:
+            metadata = versions.get(version)
+            if not isinstance(metadata, dict):
+                raise RuntimeError(f"enabled portals schema version is not stored: {version}")
+            api_version = str(metadata.get("apiVersion") or "")
+            schema_files = metadata.get("schemaFiles")
+            if not isinstance(schema_files, dict):
+                schema_files = {kind: f"{version}/{kind}.json" for kind in ("summary", "complete")}
+            supported_schema_kinds = tuple(str(item) for item in metadata.get("schemaKinds") or schema_files)
+            if not {"summary", "complete"}.issubset(supported_schema_kinds):
+                raise RuntimeError(f"portals schema version must support summary and complete kinds: {version}")
+            schemas: dict[str, JSONObject] = {}
+            paths: dict[str, Path] = {}
+            for name in supported_schema_kinds:
+                relative_path = schema_files.get(name)
+                if not isinstance(relative_path, str) or not relative_path:
+                    raise RuntimeError(f"portals schema kind has no schema file: {version}/{name}")
+                path = root / relative_path
+                schema = self._read_json(path)
+                schemas[name] = schema
+                paths[name] = path
+            ref_registry = Registry()
+            for name, schema in schemas.items():
+                schema_id = str(schema.get("$id") or "")
+                if version not in schema_id:
+                    raise RuntimeError(f"portals {name} schema $id mismatch for {version}: {schema_id}")
+                Draft202012Validator.check_schema(schema)
+                resource = Resource.from_contents(schema)
+                if schema_id:
+                    ref_registry = ref_registry.with_resource(schema_id, resource)
+                ref_registry = ref_registry.with_resource(paths[name].resolve().as_uri(), resource)
+            for name, schema in schemas.items():
+                self._validate_local_refs(schema, paths[name], schemas, paths)
+            context = PortalsSchemaContext(
+                version,
+                api_version,
+                schemas,
+                {name: str(schema_files[name]) for name in supported_schema_kinds},
+                ref_registry,
+                supported_schema_kinds,
+                str(metadata.get("contractSource") or "portal_apply"),
+                str(metadata.get("contractVersion") or version),
+            )
+            self._contexts[version] = context
+            self._api_to_version[api_version] = version
+
+    def schema(
+        self,
+        *,
+        schema_version: str | None = None,
+        schema_kind: str | None = None,
+    ) -> JSONObject:
+        context = self.resolve_schema_version(schema_version)
+        requested_kind = str(schema_kind or "summary").strip()
+        if requested_kind not in context.supported_schema_kinds:
+            raise PortalsContractError(
+                "UNSUPPORTED_SCHEMA_KIND",
+                f"unsupported portals schema kind: {requested_kind}",
+                details={"supportedKinds": list(context.supported_schema_kinds)},
+            )
+        schema, dependencies = self._bundle_schema(
+            context.schema_for_kind(requested_kind),
+            schema_path=(self.root / context.schema_files[requested_kind]),
+            schemas=context.schemas,
+            schema_files=context.schema_files,
+        )
+        return {
+            "schemaVersion": context.schema_version,
+            "apiVersion": context.api_version,
+            "latestVersion": self.latest_version,
+            "storedVersions": list(self.stored_versions),
+            "enabledVersions": list(self.enabled_versions),
+            "supportedSchemaKinds": list(context.supported_schema_kinds),
+            "schemaKind": requested_kind,
+            "schemaFile": context.schema_files[requested_kind],
+            "schemaBundled": bool(dependencies),
+            "schemaDependencies": dependencies,
+            "schema": schema,
+        }
+
+    @classmethod
+    def _bundle_schema(
+        cls,
+        schema: JSONObject,
+        *,
+        schema_path: Path,
+        schemas: dict[str, JSONObject],
+        schema_files: dict[str, str],
+    ) -> tuple[JSONObject, list[str]]:
+        """Inline reachable cross-file definitions for standalone consumers."""
+        bundled = deepcopy(schema)
+        definitions = bundled.get("$defs")
+        if not isinstance(definitions, dict):
+            definitions = {}
+        dependencies: set[str] = set()
+        # schema_path is <root>/<version>/components/<file> or <root>/<version>/<file>.
+        # Find the manifest root from the configured path instead of relying on
+        # a fixed components depth.
+        cls_root = schema_path.parent
+        for candidate in schema_path.parents:
+            if (candidate / "manifest.json").is_file():
+                cls_root = candidate
+                break
+        paths = {name: cls_root / relative for name, relative in schema_files.items()}
+
+        def resolve_pointer(document: JSONObject, fragment: str, *, ref: str) -> Any:
+            target: Any = document
+            for raw_part in fragment[1:].split("/") if fragment.startswith("/") else ():
+                part = raw_part.replace("~1", "/").replace("~0", "~")
+                if not isinstance(target, dict) or part not in target:
+                    raise RuntimeError(f"portals schema contains a dangling $ref in {schema_path}: {ref}")
+                target = target[part]
+            return target
+
+        pending: list[tuple[str, JSONObject, Path]] = []
+
+        def add_definition(name: str, source: JSONObject, source_path: Path) -> None:
+            if name in definitions:
+                return
+            source_definitions = source.get("$defs")
+            if not isinstance(source_definitions, dict) or name not in source_definitions:
+                raise RuntimeError(f"portals schema references an unknown definition: {name}")
+            definitions[name] = deepcopy(source_definitions[name])
+            pending.append((name, source, source_path))
+
+        def rewrite(value: Any, source: JSONObject, source_path: Path) -> None:
+            if isinstance(value, dict):
+                ref = value.get("$ref")
+                if isinstance(ref, str):
+                    ref_file, _, fragment = ref.partition("#")
+                    target_source = source
+                    target_path = source_path
+                    if ref_file:
+                        target_path = (source_path.parent / ref_file).resolve()
+                        target_name = next(
+                            (name for name, path in paths.items() if path.resolve() == target_path),
+                            None,
+                        )
+                        if target_name is None:
+                            raise RuntimeError(f"portals schema contains an external $ref in {source_path}: {ref}")
+                        target_source = schemas[target_name]
+                        dependencies.add(schema_files[target_name])
+                        value["$ref"] = f"#{fragment}"
+                    local_ref = str(value["$ref"])
+                    if local_ref.startswith("#/$defs/"):
+                        name = local_ref.removeprefix("#/$defs/").split("/", 1)[0]
+                        add_definition(name, target_source, target_path)
+                    else:
+                        resolve_pointer(target_source, fragment, ref=ref)
+                for child in value.values():
+                    rewrite(child, source, source_path)
+            elif isinstance(value, list):
+                for child in value:
+                    rewrite(child, source, source_path)
+
+        for key, value in bundled.items():
+            if key != "$defs":
+                rewrite(value, schema, schema_path)
+        while pending:
+            name, source, source_path = pending.pop()
+            rewrite(definitions[name], source, source_path)
+        if definitions:
+            bundled["$defs"] = definitions
+        return bundled, sorted(dependencies)
+
+    def resolve_schema_version(self, schema_version: str | None) -> PortalsSchemaContext:
+        version = str(schema_version or self.latest_version).strip()
+        if version not in self.stored_versions:
+            raise self._version_error("UNSUPPORTED_SCHEMA_VERSION", version)
+        if version not in self.enabled_versions:
+            raise self._version_error("SCHEMA_VERSION_DISABLED", version)
+        return self._contexts[version]
+
+    def resolve_api_version(self, api_version: str) -> PortalsSchemaContext:
+        version = self._api_to_version.get(api_version)
+        if version is not None:
+            return self._contexts[version]
+        stored = self._stored_api_to_version.get(api_version)
+        if stored is not None:
+            raise self._version_error("SCHEMA_VERSION_DISABLED", stored)
+        raise self._version_error("UNSUPPORTED_SCHEMA_VERSION", api_version)
+
+    def _version_error(self, error_code: str, requested: str) -> PortalsContractError:
+        return PortalsContractError(
+            error_code,
+            f"unsupported portals schema selection: {requested}",
+            details={
+                "requestedVersion": requested,
+                "latestVersion": self.latest_version,
+                "storedVersions": list(self.stored_versions),
+                "enabledVersions": list(self.enabled_versions),
+            },
+        )
+
+    @staticmethod
+    def _read_json(path: Path) -> JSONObject:
+        value = json.loads(path.read_text(encoding="utf-8"))
+        if not isinstance(value, dict):
+            raise RuntimeError(f"portals schema artifact must be an object: {path}")
+        return value
+
+    @staticmethod
+    def _validate_local_refs(
+        document: JSONObject,
+        path: Path,
+        documents: dict[str, JSONObject],
+        paths: dict[str, Path],
+    ) -> None:
+        stack: list[Any] = [document]
+        while stack:
+            value = stack.pop()
+            if isinstance(value, dict):
+                ref = value.get("$ref")
+                if ref is not None:
+                    if not isinstance(ref, str):
+                        raise RuntimeError(f"portals schema contains an invalid $ref in {path}: {ref}")
+                    ref_file, _, fragment = ref.partition("#")
+                    target_document = document
+                    if ref_file:
+                        target_path = (path.parent / ref_file).resolve()
+                        if target_path not in {item.resolve() for item in paths.values()}:
+                            raise RuntimeError(f"portals schema contains an external $ref in {path}: {ref}")
+                        target_name = next(name for name, item in paths.items() if item.resolve() == target_path)
+                        target_document = documents[target_name]
+                    target: Any = target_document
+                    for raw_part in fragment[1:].split("/") if fragment.startswith("/") else ():
+                        part = raw_part.replace("~1", "/").replace("~0", "~")
+                        if not isinstance(target, dict) or part not in target:
+                            raise RuntimeError(f"portals schema contains a dangling $ref in {path}: {ref}")
+                        target = target[part]
+                stack.extend(value.values())
+            elif isinstance(value, list):
+                stack.extend(value)
+
+    @staticmethod
+    def _configured_versions() -> tuple[str, ...]:
+        raw = os.environ.get("QINGFLOW_PORTALS_SCHEMA_VERSIONS", "")
+        return tuple(part.strip() for part in raw.split(",") if part.strip())
+
+
+_REGISTRY: PortalsSchemaRegistry | None = None
+
+
+def portals_schema_registry() -> PortalsSchemaRegistry:
+    global _REGISTRY
+    if _REGISTRY is None:
+        _REGISTRY = PortalsSchemaRegistry()
+    return _REGISTRY