digitalkin 1.0.4.dev0__tar.gz → 1.0.4.dev2__tar.gz

{digitalkin-1.0.4.dev0 → digitalkin-1.0.4.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: digitalkin
-Version: 1.0.4.dev0
+Version: 1.0.4.dev2
 Summary: SDK to build kin used in DigitalKin
 Author-email: "DigitalKin.ai" <contact@digitalkin.ai>
 License: Attribution-NonCommercial-ShareAlike 4.0 International
@@ -453,7 +453,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: ag-ui-protocol==0.1.21.dev1787220377
-Requires-Dist: agentic-mesh-protocol==1.0.2.dev1
+Requires-Dist: agentic-mesh-protocol==1.0.2.dev2
 Requires-Dist: agno<3,>=2.8.0
 Requires-Dist: anyio>=4.13.0
 Requires-Dist: grpcio-health-checking==1.82.1

{digitalkin-1.0.4.dev0 → digitalkin-1.0.4.dev2}/pyproject.toml

@@ -31,7 +31,7 @@
         # which is how a nested run's output is attributed to its author. Pinned exactly
         # because it is a dated prerelease; move to >=0.1.21 once that ships stable.
         "ag-ui-protocol==0.1.21.dev1787220377",
-        "agentic-mesh-protocol==1.0.2.dev1",
+        "agentic-mesh-protocol==1.0.2.dev2",
         "agno>=2.8.0,<3",
         "anyio>=4.13.0",
         "grpcio-health-checking==1.82.1",
@@ -41,7 +41,7 @@
         "pydantic>=2.12.4",
         "redis[hiredis]>=7.4.0,<9",
     ]
-    version = "1.0.4.dev0"
+    version = "1.0.4.dev2"
 
     [project.optional-dependencies]
         agno = [ "agno>=2.6" ]

{digitalkin-1.0.4.dev0 → digitalkin-1.0.4.dev2}/src/digitalkin/__version__.py

@@ -5,4 +5,4 @@ from importlib.metadata import PackageNotFoundError, version
 try:
     __version__ = version("digitalkin")
 except PackageNotFoundError:
-    __version__ = "1.0.4.dev0"
+    __version__ = "1.0.4.dev2"

{digitalkin-1.0.4.dev0 → digitalkin-1.0.4.dev2}/src/digitalkin/community/agno/toolkits/registry/action.py

@@ -23,6 +23,7 @@ from digitalkin.models.services.registry import (
 
 if TYPE_CHECKING:
     from digitalkin.community.agno.toolkits.registry.base import RegistryActionCtx
+    from digitalkin.models.services.registry import SetupSummary
 
 
 class GetAction(RegistryAction):
@@ -124,26 +125,36 @@ class SearchAction(RegistryAction):
         # would both contradict ``total_returned`` and, at exactly ``cap`` rows, promise an empty
         # next page.
         truncated = len(usable) > cap
-        rows = [
-            {
-                "setup_id": setup.setup_id,
-                "name": setup.name,
-                "module_name": setup.module_name,
-                "version": setup.setup_version,
-                # Echoed because they are filterable: a caller cannot use the ``tags``,
-                # ``visibilities`` or ``statuses`` filters without first seeing the values in use.
-                "tags": setup.tags,
-                "visibility": setup.visibility.value if setup.visibility else None,
-                "status": setup.status.value if setup.status else None,
-                "description": (setup.documentation or "")[: self._DOC_PREVIEW_CHARS],
-                # The shape of the configuration, so choosing a scope needs no second call:
-                # read a key from here and pass it to ``load``.
-                "structure": setup.structure,
-            }
-            for setup in usable[:cap]
-        ]
+        rows = [self._row(setup) for setup in usable[:cap]]
         return {"total_returned": len(rows), "truncated": truncated, "offset": self.offset, "setups": rows}
 
+    def _row(self, setup: SetupSummary) -> dict[str, Any]:
+        """Trim one search hit to the fields a caller can act on.
+
+        Args:
+            setup: The summary returned by the registry.
+
+        Returns:
+            The rendered row.
+        """
+        row: dict[str, Any] = {
+            "setup_id": setup.setup_id,
+            "name": setup.name,
+            "module_name": setup.module_name,
+            "version": setup.setup_version,
+            # Echoed because they are filterable: a caller cannot use the ``tags``,
+            # ``visibilities`` or ``statuses`` filters without first seeing the values in use.
+            "tags": setup.tags,
+            "visibility": setup.visibility.value if setup.visibility else None,
+            "status": setup.status.value if setup.status else None,
+            "description": (setup.documentation or "")[: self._DOC_PREVIEW_CHARS],
+        }
+        # Only service setups carry a map. Omitting the key rather than rendering an empty
+        # one keeps the feature out of the tools and kins surfaces entirely.
+        if setup.structure:
+            row["structure"] = setup.structure
+        return row
+
 
 class UpdateAction(RegistryAction):
     """Update an instance: cut a new version of its configuration, and rename it.
@@ -169,16 +180,21 @@ class UpdateAction(RegistryAction):
         "without changing what the instance currently serves, then activate it later with "
         "``set_version``.",
     )
-    structure: dict[str, str] | None = Field(
+    documentation: str | None = Field(
         default=None,
-        description="Refreshed map of key path -> one-line summary of what lives at it, "
-        "describing the content this call carries. Same form as on create: summarise what each "
-        'key is FOR, join nested keys with "." (llm.model), bracket-quote a key containing '
-        '. [ ] " or \\ (limits["max.tokens"]), index a list element (tools[0]). Omitting it '
-        "replaces the stored map with one derived from the raw values, losing every written "
-        "summary — supply it whenever the instance had one.",
+        description="Free text describing what this instance is for, indexed by ``search``. "
+        "Omit to keep the text the instance already has; pass a string to replace it, or an "
+        "empty string to clear it.",
     )
 
+    def _type_payload(self) -> dict[str, Any]:  # ruff: ignore[no-self-use]
+        """Fields this object type adds to the update.
+
+        Returns:
+            Nothing by default; ``services_manager`` overrides it to refresh the structure map.
+        """
+        return {}
+
     async def execute(self, ctx: RegistryActionCtx) -> Any:
         """Cut a new version of the setup's content and rename it.
 
@@ -196,7 +212,10 @@ class UpdateAction(RegistryAction):
             "name": self.name,
             "content": self.content,
             "set_as_current": self.set_as_current,
-            "structure": self.structure,
+            "documentation": (
+                setup.current_setup_version.documentation if self.documentation is None else self.documentation
+            ),
+            **self._type_payload(),
         })
 
 

{digitalkin-1.0.4.dev0 → digitalkin-1.0.4.dev2}/src/digitalkin/community/agno/toolkits/registry/base.py

@@ -171,22 +171,23 @@ class RegistryAction(BaseAction[RegistryActionCtx], ABC):
 
     writes: ClassVar[bool] = False
 
-    @field_validator("name", check_fields=False)
+    @field_validator("name", "documentation", check_fields=False)
     @classmethod
-    def _name_has_no_control_chars(cls, value: str) -> str:
-        """Reject control characters in a user-facing ``name`` so it fails loudly, not silently.
+    def _text_has_no_control_chars(cls, value: str | None) -> str | None:
+        """Reject control characters in user-facing free text so it fails loudly, not silently.
 
-        The action's ``name`` bypasses the content validator, so without this a NUL byte or ANSI
-        escape would reach persistence and be stripped there, altering the value without telling
-        the caller. Applies to any action declaring ``name`` (update, service create).
+        ``name`` and ``documentation`` bypass the content validator, so without this a NUL byte
+        or ANSI escape would reach persistence and be stripped there, altering the value without
+        telling the caller. Applies to any action declaring either (update, service create).
+        ``None`` is the "leave unchanged" marker on update and has nothing to check.
 
         Returns:
-            The name unchanged when clean.
+            The value unchanged when clean.
 
         Raises:
-            ValueError: The name carries a control character.
+            ValueError: The value carries a control character.
         """
-        return SetupContentValidator.reject_control_chars(value)
+        return value if value is None else SetupContentValidator.reject_control_chars(value)
 
     @field_validator("content", check_fields=False)
     @classmethod

{digitalkin-1.0.4.dev0 → digitalkin-1.0.4.dev2}/src/digitalkin/community/agno/toolkits/registry/services/action.py

@@ -24,7 +24,6 @@ from digitalkin.community.agno.toolkits.registry.action import (
     UpdateAction,
 )
 from digitalkin.community.agno.toolkits.registry.base import RegistryAction
-from digitalkin.utils.json_structure import JsonStructure
 
 if TYPE_CHECKING:
     from digitalkin.community.agno.toolkits.registry.base import RegistryActionCtx
@@ -50,6 +49,12 @@ class CreateServiceAction(RegistryAction):
         description="The service configuration (a non-empty JSON object). "
         "Note: JSON numbers round-trip as floats over the wire.",
     )
+    documentation: str = Field(
+        default="",
+        description="Free text describing what this service is for and when to use it. It is "
+        "what ``search`` matches on and previews back, so a service created without it is "
+        "findable only by name.",
+    )
     structure: dict[str, str] = Field(
         ...,
         description="Map of key path -> one-line summary of what lives at it. This is what "
@@ -58,17 +63,19 @@ class CreateServiceAction(RegistryAction):
         "content it describes. Cover each key worth finding on its own; point at a whole "
         "section instead when it is only ever read as a unit. Path syntax: join nested keys "
         'with "." (llm.model); bracket-quote a key containing . [ ] " or \\ '
-        '(limits["max.tokens"]); index a list element (tools[0]). Paths that do not exist in '
-        "content are dropped.",
+        '(limits["max.tokens"]); index a list element (tools[0]). Keep each description under '
+        "512 characters — longer ones are trimmed.",
     )
 
     async def execute(self, ctx: RegistryActionCtx) -> Any:
-        """Create the service setup from its name, content and authored key map.
+        """Create the service setup from its name, content, documentation and authored key map.
 
         Returns:
             The created service setup.
         """
-        return await ctx.setup.create_service_setup(self.name, self.content, self.structure)
+        return await ctx.setup.create_service_setup(
+            self.name, self.content, documentation=self.documentation, structure=self.structure
+        )
 
 
 class StructureServiceAction(RegistryAction):
@@ -106,8 +113,9 @@ class LoadServiceAction(RegistryAction):
     key: str | None = Field(
         default=None,
         description="One key path copied verbatim from the service's structure map, to read just "
-        "that part of the configuration. Omit to load the whole document — do that only when the "
-        "configuration is small or genuinely needed in full.",
+        "that part of the configuration. Copy it, do not compose it: a key the configuration "
+        "does not have is not an error, it returns the whole document. Omit the key to load "
+        "everything deliberately, when the configuration is small or genuinely needed in full.",
     )
 
     async def execute(self, ctx: RegistryActionCtx) -> Any:
@@ -115,25 +123,41 @@ class LoadServiceAction(RegistryAction):
 
         Guards the object type first: without it ``load`` would happily return a tool's
         internal configuration — the most dangerous type-confusion, since the response
-        carries no field the caller could use to notice it read the wrong kind. That guard
-        already reads the whole setup, so the key is applied to the content in hand rather
-        than costing a second scoped fetch.
+        carries no field the caller could use to notice it read the wrong kind. The read
+        itself passes ``key`` to the setup service, so the narrowing happens where the
+        document lives; a key the configuration does not have returns the whole document
+        rather than an error, which is what the wire does.
 
         Returns:
-            The value at ``key``, or the whole configuration JSON object when no key is given.
+            ``{key: value}`` for a key that resolves, otherwise the whole configuration.
+        """
+        await ctx.ensure_kind(self.setup_id)
+        setup = await ctx.setup.get_setup({"setup_id": self.setup_id, "structure_key": self.key or ""})
+        return setup.current_setup_version.content
+
+
+class UpdateServiceAction(UpdateAction):
+    """Update a service, refreshing the key map alongside the configuration.
+
+    The map belongs to the content it describes, so a new revision needs a new one; the
+    stored map is replaced by whatever this call carries.
+    """
+
+    structure: dict[str, str] | None = Field(
+        default=None,
+        description="Refreshed map of key path -> one-line description of what lives at that "
+        "leaf, describing the content this call carries. Same form and same 512-character limit "
+        "as on create. Omitting it leaves the new revision without a map, so other agents can no "
+        "longer see the service's shape — resupply it whenever the service had one.",
+    )
+
+    def _type_payload(self) -> dict[str, Any]:
+        """Carry the refreshed map onto the new revision.
 
-        Raises:
-            ValueError: ``key`` names a path the configuration does not have.
+        Returns:
+            The ``structure`` entry for the update payload.
         """
-        setup = await ctx.ensure_kind(self.setup_id)
-        content = setup.current_setup_version.content
-        if self.key is None:
-            return content
-        found = JsonStructure.resolve(content, [self.key])
-        if self.key not in found:
-            msg = f"{self.key!r} is not a key of this configuration; copy one from its structure"
-            raise ValueError(msg)
-        return found[self.key]
+        return {"structure": self.structure}
 
 
 ServiceActions = Annotated[
@@ -142,7 +166,7 @@ ServiceActions = Annotated[
     | SearchAction
     | StructureServiceAction
     | LoadServiceAction
-    | UpdateAction
+    | UpdateServiceAction
     | DeleteAction
     | ChangeVisibilityAction
     | ListVersionsAction

{digitalkin-1.0.4.dev0 → digitalkin-1.0.4.dev2}/src/digitalkin/community/agno/toolkits/registry/services/kit.py

@@ -43,8 +43,10 @@ class ServicesManager(RegistryObjectToolKit):
                 "Configurations can be large, so read them in two steps: 'search' returns each "
                 "result with a 'structure' map of key path -> what lives there ('structure' fetches "
                 "the same map for an id you already hold), then 'load' with a key copied verbatim "
-                "from it returns just that part. Load without a key only when the whole document is "
-                "genuinely needed. On create and update you write that map yourself, describing what "
+                "from it returns just that part. Copy the key, never invent one: a key the "
+                "configuration does not have quietly returns everything. Load without a key only when "
+                "the whole document is genuinely needed. On create and update you write that map "
+                "yourself, describing what "
                 "each key is for — it is how other agents find their way around the configuration."
             ),
             entrypoint=self.services_manager,

{digitalkin-1.0.4.dev0 → digitalkin-1.0.4.dev2}/src/digitalkin/grpc_servers/module_servicer.py

@@ -16,6 +16,7 @@ from agentic_mesh_protocol.module.v1 import (
 )
 from agentic_mesh_protocol.user_profile.v1 import user_profile_pb2
 from google.protobuf import json_format, struct_pb2
+from pydantic import ValidationError
 
 from digitalkin.core.job_manager.base_job_manager import BaseJobManager
 from digitalkin.core.job_manager.single_job_manager import SingleJobManager
@@ -393,11 +394,29 @@ class ModuleServicer(module_service_pb2_grpc.ModuleServiceServicer, ArgParser):
             return lifecycle_pb2.ConfigSetupModuleResponse(success=False)
         # Invalidate cached setup so concurrent/subsequent starts refetch the reconfigured version
         self._setup_cache.pop(setup_version.setup_id, None)
-        config_setup_data = self.module_class.create_config_setup_model(json_format.MessageToDict(request.content))
-        setup_version_data = await self.module_class.create_setup_model(
-            json_format.MessageToDict(request.setup_version.content),
-            config_fields=True,
-        )
+        try:
+            config_setup_data = self.module_class.create_config_setup_model(json_format.MessageToDict(request.content))
+            setup_version_data = await self.module_class.create_setup_model(
+                json_format.MessageToDict(request.setup_version.content),
+                config_fields=True,
+            )
+        except ValidationError as error:
+            # Without this the pydantic error escapes the servicer and grpc reports UNKNOWN
+            # with a stack trace, so a malformed setup reads as an SDK crash. Name the fields
+            # instead: the sender is the only one who can fix them.
+            fields = ", ".join(".".join(str(part) for part in item["loc"]) for item in error.errors())
+            msg = (
+                f"setup version {setup_version.id} does not match the module's setup model (missing/invalid: {fields})"
+            )
+            logger.error(
+                "ConfigSetupModule rejected setup_version=%s: %s",
+                setup_version.id,
+                error,
+                extra={"mission_id": request.mission_id},
+            )
+            context.set_code(grpc.StatusCode.INVALID_ARGUMENT)
+            context.set_details(msg)
+            return lifecycle_pb2.ConfigSetupModuleResponse(success=False)
 
         if not setup_version_data:
             msg = "No setup data returned."

{digitalkin-1.0.4.dev0 → digitalkin-1.0.4.dev2}/src/digitalkin/services/setup/default_setup.py

@@ -18,6 +18,7 @@ from digitalkin.services.setup.setup_strategy import (
     SetupVersionPage,
 )
 from digitalkin.utils.json_structure import JsonStructure
+from digitalkin.utils.setup_content_validator import SetupContentValidator
 
 
 class DefaultSetup(SetupStrategy):
@@ -70,30 +71,66 @@ class DefaultSetup(SetupStrategy):
                 'structure_key'.
 
         Returns:
-            The setup with its current version populated. With a non-empty
-            'structure_key', the version content is replaced by the {key path: value}
-            projection of that one path — the local mirror of server-side projection.
-            An empty key is treated as absent, because GetSetupRequest.structure_key has
-            no proto3 presence and the wire cannot tell the two apart.
+            The setup shaped as ``GetSetupResponse`` would carry it — see
+            :meth:`_as_wire_read` for the three ways that differs from the stored record.
 
         Raises:
             SetupServiceError: setup_id does not exist.
         """
         setup = self._get_or_raise(setup_dict.get("setup_id", ""))
-        key = setup_dict.get("structure_key")
+        return self._as_wire_read(setup, setup_dict.get("structure_key") or "")
+
+    @classmethod
+    def _as_wire_read(cls, setup: SetupData, key: str) -> SetupData:
+        """Copy a stored setup down to what a read can actually return.
+
+        Two ways a read differs from the record, both forced by the protocol:
+        the content is projected to ``key``, and the structure map is dropped because
+        ``GetSetupResponse`` has no field to carry it. Mirroring the second matters as much
+        as the first — serving a map here that the gRPC strategy cannot would let code work
+        locally and lose the map in production.
+
+        Args:
+            setup: The stored setup.
+            key: The requested key path; empty means the whole document.
+
+        Returns:
+            A copy safe to hand back; the stored record is untouched.
+        """
+        version = setup.current_setup_version
+        return setup.model_copy(
+            update={
+                "current_setup_version": version.model_copy(
+                    update={"content": cls._project(version.content, key), "structure": {}}
+                )
+            }
+        )
+
+    @staticmethod
+    def _project(content: dict[str, Any], key: str) -> dict[str, Any]:
+        """Narrow a version's content to one key path.
+
+        Args:
+            content: The stored content.
+            key: The requested key path; empty means the whole document.
+
+        Returns:
+            ``{key: value}`` when the path resolves, otherwise the whole document — an
+            empty key and an unresolvable one both return everything, which is what the
+            backend sends and what ``structure_key``'s lack of proto3 presence forces.
+        """
         if not key:
-            return setup
-        projected = setup.model_copy(deep=True)
-        projected.current_setup_version.content = JsonStructure.resolve(setup.current_setup_version.content, [key])
-        return projected
+            return content
+        return JsonStructure.resolve(content, [key]) or content
 
     async def create_setup(self, setup_dict: dict[str, Any]) -> SetupData:
         """Create a new setup; identifiers are generated locally.
 
         Args:
-            setup_dict: Dictionary with 'name', 'content' and optional 'structure' — the
-                authored ``{key path: summary}`` map, filtered to the paths that resolve
-                in ``content``. Absent, it is derived from ``content``.
+            setup_dict: Dictionary with 'name', 'content', optional 'documentation' and
+                optional 'structure' — the ``{key path: description}`` map the agent
+                wrote for ``content``, stored as written with only each description's
+                length bounded.
 
         Returns:
             The created setup with its initial version.
@@ -101,6 +138,7 @@ class DefaultSetup(SetupStrategy):
         Raises:
             ValueError: If name or content is invalid.
         """
+        SetupContentValidator.reject_oversized_output_format_spec(setup_dict.get("content") or {})
         setup_id = self._new_id()
         try:
             setup = SetupData(
@@ -115,12 +153,9 @@ class DefaultSetup(SetupStrategy):
                     id=self._new_id(),
                     setup_id=setup_id,
                     version="1.0.0",
+                    documentation=setup_dict.get("documentation") or "",
                     content=setup_dict.get("content") or {},
-                    structure=(
-                        JsonStructure.check(setup_dict.get("content") or {}, setup_dict["structure"])
-                        if setup_dict.get("structure")
-                        else JsonStructure.describe(setup_dict.get("content") or {})
-                    ),
+                    structure=JsonStructure.clip(setup_dict.get("structure") or {}),
                     creation_date=datetime.datetime.now(datetime.timezone.utc),
                 ),
             )
@@ -141,9 +176,11 @@ class DefaultSetup(SetupStrategy):
 
         Args:
             setup_dict: Dictionary with 'setup_id', 'name', 'content', optional
-                'set_as_current' (defaults to True) and optional 'structure' — the authored
-                ``{key path: summary}`` map for the new content. Omitting it falls back to
-                a derived map, discarding any authored summaries.
+                'set_as_current' (defaults to True), optional 'documentation' and optional
+                'structure'. The map belongs to the content it describes, so a revision
+                carries only the map its own call supplied; omitting it leaves the new
+                revision without one. Omitting the documentation clears
+                it, matching the wire.
 
         Returns:
             The updated setup with its current version.
@@ -158,6 +195,7 @@ class DefaultSetup(SetupStrategy):
         if not name or not isinstance(content, dict):
             msg = "setup_id, name and content (object) are required"
             raise ValueError(msg)
+        SetupContentValidator.reject_oversized_output_format_spec(content)
         setup.name = name
         # A new revision rather than an in-place edit, matching UpdateSetup on the wire.
         history = self.versions.setdefault(setup.id, [setup.current_setup_version])
@@ -165,12 +203,11 @@ class DefaultSetup(SetupStrategy):
             id=self._new_id(),
             setup_id=setup.id,
             version=f"1.0.{len(history)}",
+            # No presence on UpdateSetupRequest, so an omitted value clears it server-side.
+            # Mirror that rather than preserving the old text: same input, same result.
+            documentation=setup_dict.get("documentation") or "",
             content=content,
-            structure=(
-                JsonStructure.check(content, setup_dict["structure"])
-                if setup_dict.get("structure")
-                else JsonStructure.describe(content)
-            ),
+            structure=JsonStructure.clip(setup_dict.get("structure") or {}),
             creation_date=datetime.datetime.now(datetime.timezone.utc),
         )
         history.append(version)

{digitalkin-1.0.4.dev0 → digitalkin-1.0.4.dev2}/src/digitalkin/services/setup/grpc_setup.py

@@ -20,6 +20,7 @@ from digitalkin.services.setup.exceptions import SetupServiceError
 from digitalkin.services.setup.setup_strategy import SetupData, SetupStrategy, SetupVersionData, SetupVersionPage
 from digitalkin.utils.json_structure import JsonStructure
 from digitalkin.utils.proto_utils import ProtoUtils
+from digitalkin.utils.setup_content_validator import SetupContentValidator
 
 
 class GrpcSetup(SetupStrategy, GrpcClientWrapper):
@@ -133,15 +134,30 @@ class GrpcSetup(SetupStrategy, GrpcClientWrapper):
             The validated ``SetupData``.
 
         Raises:
-            SetupServiceError: If neither carries a setup version.
+            SetupServiceError: Neither field carries a setup version, or the one that does
+                carries no content.
         """
-        if setup_msg.HasField("current_setup_version"):
-            version_msg = setup_msg.current_setup_version
-        elif not version_msg.id:
+        embedded = setup_msg.current_setup_version if setup_msg.HasField("current_setup_version") else None
+        chosen = version_msg if embedded is None else embedded
+        if not chosen.id:
             msg = f"setup '{setup_msg.id}' returned without a setup version"
             raise SetupServiceError(msg)
         data = ProtoUtils.proto_to_dict(setup_msg, with_defaults=True)
-        data["current_setup_version"] = ProtoUtils.proto_to_dict(version_msg, with_defaults=True)
+        version = ProtoUtils.proto_to_dict(chosen, with_defaults=True)
+        # An unset content Struct is dropped by proto_to_dict rather than rendered as {},
+        # so SetupData would fail with a bare "Field required" naming neither the setup nor
+        # which of the response's two SetupVersion fields was read. Say both instead: the
+        # message carries the version twice and only one of them may hold the payload.
+        if "content" not in version:
+            source = "setup.current_setup_version" if embedded is not None else "setup_version"
+            other = version_msg if embedded is not None else None
+            sibling = "not populated" if other is None else ("carries content" if other.content.fields else "empty too")
+            msg = (
+                f"setup '{setup_msg.id}' version '{chosen.id}' arrived with no content "
+                f"(read from {source}; sibling setup_version {sibling})"
+            )
+            raise SetupServiceError(msg)
+        data["current_setup_version"] = version
         if structure is not None:
             data["current_setup_version"]["structure"] = dict(structure)
         return SetupData(**data)
@@ -183,34 +199,33 @@ class GrpcSetup(SetupStrategy, GrpcClientWrapper):
 
         Args:
             setup_dict: Dictionary with 'name', 'content', optional 'documentation' and
-                optional 'structure' — the authored ``{key path: summary}`` map, filtered
-                to the paths that resolve in ``content``. Absent, it is derived from
-                ``content`` so a writer with no author still stores one.
+                optional 'structure' — the ``{key path: description}`` map the agent
+                wrote for ``content``, stored as written with only each description's
+                length bounded.
 
         Returns:
             The created setup with its initial version and structure.
 
         Raises:
-            ValueError: If name or content is missing.
+            ValueError: If name or content is missing, or output_format_spec is oversized.
             ServerError: If gRPC operation fails.
             SetupServiceError: If the server reports failure or an unexpected error occurs.
         """
         if not setup_dict.get("name") or not isinstance(setup_dict.get("content"), dict):
             msg = "name and content (object) are required"
             raise ValueError(msg)
+        # Outside handle_grpc_errors: an input guard must stay a ValueError, not become a
+        # SetupServiceError via the catch-all.
+        SetupContentValidator.reject_oversized_output_format_spec(setup_dict["content"])
         async with self.handle_grpc_errors("Setup Creation"):
             content_struct = Struct()
             content_struct.update(setup_dict["content"])
             structure_struct = Struct()
-            structure_struct.update(
-                JsonStructure.check(setup_dict["content"], setup_dict["structure"])
-                if setup_dict.get("structure")
-                else JsonStructure.describe(setup_dict["content"])
-            )
+            structure_struct.update(JsonStructure.clip(setup_dict.get("structure") or {}))
             request = setup_pb2.CreateSetupRequest(
                 name=setup_dict["name"],
                 content=content_struct,
-                documentation=setup_dict.get("documentation", ""),
+                documentation=setup_dict.get("documentation") or "",
                 structure=structure_struct,
             )
             response = await self.exec_grpc_query("CreateSetup", request)
@@ -226,16 +241,15 @@ class GrpcSetup(SetupStrategy, GrpcClientWrapper):
         Args:
             setup_dict: Dictionary with 'setup_id', 'name', 'content', optional
                 'set_as_current' (defaults to True), optional 'documentation' and optional
-                'structure' — the authored ``{key path: summary}`` map for the new content.
-                It is always rewritten, so it cannot drift from what is stored; omitting it
-                falls back to a derived map, which discards any authored summaries the
-                previous version carried.
+                'structure'. The map belongs to the content it describes, so a revision
+                carries only the map its own call supplied; omitting it leaves the new
+                revision without one.
 
         Returns:
             The updated setup with its current version and structure.
 
         Raises:
-            ValueError: If setup_id, name or content is missing.
+            ValueError: If setup_id, name or content is missing, or output_format_spec is oversized.
             ServerError: If gRPC operation fails.
             SetupServiceError: If the server reports failure or an unexpected error occurs.
         """
@@ -246,15 +260,12 @@ class GrpcSetup(SetupStrategy, GrpcClientWrapper):
         ):
             msg = "setup_id, name and content (object) are required"
             raise ValueError(msg)
+        SetupContentValidator.reject_oversized_output_format_spec(setup_dict["content"])
         async with self.handle_grpc_errors("Setup Update"):
             content_struct = Struct()
             content_struct.update(setup_dict["content"])
             structure_struct = Struct()
-            structure_struct.update(
-                JsonStructure.check(setup_dict["content"], setup_dict["structure"])
-                if setup_dict.get("structure")
-                else JsonStructure.describe(setup_dict["content"])
-            )
+            structure_struct.update(JsonStructure.clip(setup_dict.get("structure") or {}))
             # UpdateSetup cuts a new version rather than editing in place; without
             # set_as_current the setup would keep serving the old content.
             request = setup_pb2.UpdateSetupRequest(
@@ -262,7 +273,7 @@ class GrpcSetup(SetupStrategy, GrpcClientWrapper):
                 name=setup_dict["name"],
                 content=content_struct,
                 set_as_current=bool(setup_dict.get("set_as_current", True)),
-                documentation=setup_dict.get("documentation", ""),
+                documentation=setup_dict.get("documentation") or "",
                 structure=structure_struct,
             )
             response = await self.exec_grpc_query("UpdateSetup", request)