fix(collection): task #87 P1-D3 — convert vector_backend to computed_field

Per dongdong msg=fa88e97b BLOCKER + huangzhangshu msg=5b7cba0f /
msg=ee6e7af2 + Weston msg=057f642c re-final framing verify gate +
PM msg=03c821b0 fix-forward direction lock: the previous regular-field
``Optional[VectorBackendInfo]`` implementation leaked the deployment
projection onto every input shape that referenced ``Collection``,
including ``Collection-Input`` itself, ``Agent-Input.collections``,
and ``CreateTurnRequest.collections``. That contradicted the read-only
output projection lock from architect msg=0044261f.

Move ``Collection.vector_backend`` to a Pydantic v2 ``@computed_field``
property so OpenAPI input/output schemas auto-split:

- ``Collection-Output`` now lists ``vector_backend`` with
  ``readonly: true`` (verified in regenerated
  ``web/src/api-v2/schema.d.ts``).
- ``Collection-Input`` no longer carries ``vector_backend`` (verified
  by grep + new contract test).
- ``CollectionCreate`` / ``CollectionUpdate`` / ``Agent-Input.collections`` /
  ``CreateTurnRequest.collections`` all inherit the cleaned ``Collection-Input``,
  so the deployment-wide setting can no longer be passed as a
  per-collection override on agent / chat-turn requests.

The ``build_collection_response`` constructor no longer passes
``vector_backend`` (computed fields are not accepted as input); the
property reads ``settings.vector_db_type`` lazily on each serialization.

Two new contract tests:
- ``test_collection_input_schema_does_not_expose_vector_backend``: pin
  the input/output JSON Schema split + ``readOnly`` flag on the
  output side. Asserts ``CollectionCreate`` / ``CollectionUpdate``
  also do not surface ``vector_backend``.
- ``test_collection_constructor_ignores_vector_backend_input``:
  defensive — even if a malicious caller stuffs ``vector_backend``
  into a ``model_validate`` payload, Pydantic ignores it and the
  computed property still reflects the deployment setting.

Sediment: cuiwenbo own-up CR miss — implement-time only verified the
``CollectionConfig`` placement (one defense layer) and missed the
``Collection`` self-reuse-as-input second layer. dongdong + Weston +
huangzhangshu independently caught via OpenAPI generated-schema gate.
mini-pattern 19 layer 5 candidate: "Pydantic schema placement verify
must grep ``references Collection`` to catch input/output reuse risk,
not only direct form-input shape" (continuing the trust-framing-miss
family from PR #1935 / #1938 / #1940).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: earayu

aperag/domains/knowledge_base/schemas.py

@@ -37,7 +37,7 @@
 from datetime import datetime
 from typing import Any, Literal, Optional
 
-from pydantic import AnyUrl, BaseModel, Field, conint
+from pydantic import AnyUrl, BaseModel, Field, computed_field, conint
 
 from aperag.schema.common import (
     Chunk,
@@ -46,6 +46,7 @@
     PaginatedResponse,
     VectorBackendInfo,
     VisionChunk,
+    project_vector_backend_info,
 )
 
 __all__ = [
@@ -99,32 +100,40 @@ class Collection(BaseModel):
     # msg=e4120886 reproducer).
     summary: Optional[str] = Field(None, description="Auto-generated long-form knowledge-base summary")
     config: Optional[CollectionConfig] = None
-    # task #61 P1-D3 (PR for #87): read-only projection of the deployment
-    # vector backend identity + capability matrix. **Intentionally placed
-    # on Collection (read response) and NOT inside CollectionConfig.**
-    # ``CollectionConfig`` is reused as the create/update input shape, so
-    # putting vector_backend there would expose the field on the OpenAPI
-    # ``CollectionCreate``/``CollectionUpdate`` input schemas and let
-    # callers mistake a deployment-wide setting for a per-collection
-    # editable knob (per dongdong msg=c2593fdd + PM msg=caf7e4df + spec
-    # P1-D3 read-only projection lock). Projected by
-    # ``collection_service.build_collection_response()`` from
-    # ``settings.vector_db_type``; ``None`` for unknown backends so the FE
-    # can render a placeholder without a hard failure.
-    vector_backend: Optional[VectorBackendInfo] = Field(
-        None,
-        description=(
-            "Read-only deployment vector backend identity + static capability "
-            "matrix. Projected from ``settings.vector_db_type``; not editable "
-            "per collection."
-        ),
-    )
     status: Optional[Literal["ACTIVE", "INACTIVE", "DELETED"]] = None
     created: Optional[datetime] = None
     updated: Optional[datetime] = None
     is_published: Optional[bool] = Field(False, description="Whether the collection is published to marketplace")
     published_at: Optional[datetime] = Field(None, description="Publication time, null when not published")
 
+    # task #61 P1-D3 (PR for #87): read-only projection of the deployment
+    # vector backend identity + capability matrix. Modelled as a Pydantic
+    # v2 ``@computed_field`` so it is **only** present on the OpenAPI
+    # output schema (``Collection-Output``) and is **not** part of any
+    # input shape that reuses :class:`Collection` (e.g.
+    # ``CollectionCreate``/``CollectionUpdate``, plus the request-side
+    # composites ``Agent-Input.collections`` /
+    # ``CreateTurnRequest.collections`` that inherit ``Collection-Input``).
+    # Per dongdong msg=fa88e97b BLOCKER: marking ``vector_backend`` as a
+    # plain ``Optional[VectorBackendInfo]`` field would have leaked the
+    # deployment-wide setting onto every input shape that references
+    # ``Collection`` and let callers think they could submit a
+    # per-collection override on agent / chat requests — exactly the
+    # error this projection lock is meant to prevent (per architect
+    # msg=0044261f read-only output projection lock + PM msg=caf7e4df).
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def vector_backend(self) -> Optional[VectorBackendInfo]:
+        # Lazy import keeps the module import graph compatible with the
+        # G1 boundary rules: ``aperag.config`` is allowed from a domain
+        # schema, but importing it at module-load time on every domain
+        # schema introduces a settings-side-effect at import which a few
+        # tests intentionally avoid. Doing the import inside the property
+        # also matches the existing ``utils.py`` lazy-resolver style.
+        from aperag.config import settings
+
+        return project_vector_backend_info(settings.vector_db_type)
+
 
 class Document(BaseModel):
     id: Optional[str] = None

aperag/domains/knowledge_base/service/collection_service.py

@@ -67,9 +67,8 @@
     SearchResultItem,
     SearchResultList,
 )
-from aperag.config import settings
 from aperag.exceptions import ValidationException
-from aperag.schema.common import PageResult, project_vector_backend_info
+from aperag.schema.common import PageResult
 from aperag.schema.utils import dumpCollectionConfig, parseCollectionConfig
 from aperag.utils.constant import QuotaType
 from aperag.utils.utils import utc_now
@@ -176,7 +175,15 @@ async def validate_collection_models(self, user: str, config) -> None:
             )
 
     async def build_collection_response(self, instance: CollectionRow) -> Collection:
-        """Build Collection response object for API return."""
+        """Build Collection response object for API return.
+
+        ``Collection.vector_backend`` is a Pydantic v2 ``@computed_field``
+        (per task #61 P1-D3 / PR for #87 — read-only projection of the
+        deployment vector backend identity + capability matrix). It is
+        populated automatically on serialization, so it is intentionally
+        **not** passed as a constructor argument — passing it would also
+        not work because computed fields are not accepted as input.
+        """
         return Collection(
             id=instance.id,
             title=instance.title,
@@ -192,16 +199,6 @@ async def build_collection_response(self, instance: CollectionRow) -> Collection
             type=instance.type,
             status=getattr(instance, "status", None),
             config=parseCollectionConfig(instance.config),
-            # task #61 P1-D3 (PR for #87): static read-only projection of
-            # the deployment vector backend identity + capability matrix.
-            # The value is identical for every collection in the
-            # deployment because ``settings.vector_db_type`` is a
-            # deployment-wide env var (``aperag/config.py``); the
-            # projection is intentionally not persisted per row. Returns
-            # ``None`` when the configured backend is not in the static
-            # capability matrix so the FE can render a placeholder
-            # without a hard failure on misconfigured deployments.
-            vector_backend=project_vector_backend_info(settings.vector_db_type),
             created=instance.gmt_created.isoformat(),
             updated=instance.gmt_updated.isoformat(),
         )

tests/unit_test/contracts/test_vector_backend_capability_matrix.py

@@ -142,6 +142,107 @@ def test_project_vector_backend_info_returns_none_for_falsy_input() -> None:
     assert project_vector_backend_info("") is None
 
 
+def test_collection_input_schema_does_not_expose_vector_backend() -> None:
+    """Pin OpenAPI input/output split for the deployment vector-backend
+    projection.
+
+    ``Collection.vector_backend`` is a Pydantic v2 ``@computed_field``,
+    so the *input* JSON Schema generated by Pydantic must not list it
+    while the *output* JSON Schema must (with ``readOnly: true``). The
+    composite request shapes that reuse :class:`Collection`
+    (``CollectionCreate`` / ``CollectionUpdate``, plus the agent /
+    chat-turn request bodies whose ``collections`` field embeds
+    ``Collection-Input`` in the FastAPI / openapi-typescript output)
+    therefore inherit the same property automatically.
+
+    The dongdong msg=fa88e97b BLOCKER caught the previous
+    ``Optional[VectorBackendInfo]`` regular-field implementation
+    leaking onto every input shape that referenced ``Collection``; this
+    test pins the fix so a future refactor cannot regress to a regular
+    field without flipping the gate red.
+    """
+
+    from aperag.domains.knowledge_base.schemas import (
+        Collection,
+        CollectionCreate,
+        CollectionUpdate,
+    )
+
+    output_schema = Collection.model_json_schema(mode="serialization")
+    input_schema = Collection.model_json_schema(mode="validation")
+
+    output_props = output_schema.get("properties", {})
+    input_props = input_schema.get("properties", {})
+
+    # Output schema must surface the projection + mark it read-only.
+    assert "vector_backend" in output_props
+    assert output_props["vector_backend"].get("readOnly") is True
+
+    # Input schema must NOT surface the projection — calling
+    # ``Collection(vector_backend=...)`` is rejected anyway, but we
+    # still want OpenAPI consumers (FE typed schema, agent request
+    # body, chat turn request body) to never see it as an editable
+    # knob in the first place.
+    assert "vector_backend" not in input_props
+
+    # The composite request schemas embed Collection / CollectionConfig
+    # but never accept ``vector_backend`` directly either.
+    create_props = CollectionCreate.model_json_schema().get("properties", {})
+    update_props = CollectionUpdate.model_json_schema().get("properties", {})
+    assert "vector_backend" not in create_props
+    assert "vector_backend" not in update_props
+
+
+def test_collection_constructor_ignores_vector_backend_input() -> None:
+    """Defensive: even if a caller submits a ``vector_backend`` payload
+    on the input shape, Pydantic v2 silently ignores it (computed
+    fields cannot be set from input) and the resulting object's
+    ``vector_backend`` is still derived from the deployment setting.
+
+    The combination of:
+    * computed-field-only output (asserted by
+      :func:`test_collection_input_schema_does_not_expose_vector_backend`)
+    * input being silently ignored (this test)
+    means a malicious / mistaken caller cannot override the deployment
+    projection by stuffing ``vector_backend`` into a request body.
+    """
+
+    from aperag.domains.knowledge_base.schemas import Collection
+
+    instance = Collection.model_validate(
+        {
+            "id": "col1",
+            "vector_backend": {
+                "type": "qdrant",
+                "capabilities": {
+                    "supports_atomic_batch_upsert": False,
+                    "supports_filter_or_with_empty_parts": False,
+                    "supports_legacy_mode": True,
+                },
+            },
+        }
+    )
+
+    # The computed property is recomputed from settings on access; the
+    # input payload is discarded. We only assert that the value does
+    # NOT equal the malicious payload — the actual projection depends
+    # on the active ``settings.vector_db_type`` in the test runtime.
+    rendered = instance.model_dump()
+    assert rendered.get("vector_backend") != {
+        "type": "qdrant",
+        "capabilities": {
+            "supports_atomic_batch_upsert": False,
+            "supports_filter_or_with_empty_parts": False,
+            "supports_legacy_mode": True,
+        },
+    } or rendered.get("vector_backend") == project_vector_backend_info(
+        # If the test deployment happens to be qdrant the values may
+        # coincide; in that case the equality is fine because it came
+        # from the projection helper, not the input payload.
+        "qdrant"
+    ).model_dump()  # type: ignore[union-attr]
+
+
 def test_vector_backend_info_pydantic_round_trip() -> None:
     """Sanity: the Pydantic model round-trips through ``model_dump`` /
     ``model_validate`` so the generated OpenAPI schema mirrors the

web/src/api-v2/schema.d.ts

@@ -2843,8 +2843,6 @@ export interface components {
              */
             summary?: string | null;
             config?: components["schemas"]["CollectionConfig-Input"] | null;
-            /** @description Read-only deployment vector backend identity + static capability matrix. Projected from ``settings.vector_db_type``; not editable per collection. */
-            vector_backend?: components["schemas"]["VectorBackendInfo"] | null;
             /** Status */
             status?: ("ACTIVE" | "INACTIVE" | "DELETED") | null;
             /** Created */
@@ -2882,8 +2880,6 @@ export interface components {
              */
             summary?: string | null;
             config?: components["schemas"]["CollectionConfig-Output"] | null;
-            /** @description Read-only deployment vector backend identity + static capability matrix. Projected from ``settings.vector_db_type``; not editable per collection. */
-            vector_backend?: components["schemas"]["VectorBackendInfo"] | null;
             /** Status */
             status?: ("ACTIVE" | "INACTIVE" | "DELETED") | null;
             /** Created */
@@ -2901,6 +2897,7 @@ export interface components {
              * @description Publication time, null when not published
              */
             published_at?: string | null;
+            readonly vector_backend: components["schemas"]["VectorBackendInfo"] | null;
         };
         /** CollectionConfig */
         "CollectionConfig-Input": {