matelab-python-sdk 0.1.0a1__py3-none-any.whl

matelab/templates.py

@@ -0,0 +1,737 @@
+import json
+from collections.abc import Iterable, Mapping, Sequence
+from dataclasses import dataclass
+from enum import StrEnum
+from types import MappingProxyType
+from typing import Literal, cast
+
+from pydantic import ValidationError
+
+from matelab._generated.models import AddGroupTemplateRequest as WireAddGroupTemplateRequest
+from matelab._generated.models import BasicSuccessResponse as WireBasicSuccessResponse
+from matelab._generated.models import CopyTemplateRequest as WireCopyTemplateRequest
+from matelab._generated.models import DeleteGroupTemplateRequest as WireDeleteGroupTemplateRequest
+from matelab._generated.models import ListTemplateStoreParametersQuery as WireListTemplateStoreQuery
+from matelab._generated.models import OwnedTemplateListItem as WireOwnedTemplateListItem
+from matelab._generated.models import ReadTemplateContentParametersQuery as WireReadTemplateContentQuery
+from matelab._generated.models import RemoveUserTemplateRelationRequest as WireRemoveUserTemplateRelationRequest
+from matelab._generated.models import SaveTemplateContentRequest as WireSaveTemplateContentRequest
+from matelab._generated.models import SaveTemplateMetadataRequest as WireSaveTemplateMetadataRequest
+from matelab._generated.models import SaveTemplateMetadataResponse as WireSaveTemplateMetadataResponse
+from matelab._generated.models import ShareMultipleTemplatesRequest as WireShareMultipleTemplatesRequest
+from matelab._generated.models import TemplateContentResponse as WireTemplateContentResponse
+from matelab._generated.models import TemplateIdRequest as WireTemplateIdRequest
+from matelab._generated.models import TemplateListResponse as WireTemplateListResponse
+from matelab._generated.models import TemplateModule as WireTemplateModule
+from matelab._generated.models import TemplateStoreListResponse as WireTemplateStoreListResponse
+from matelab._generated.models import UpdateTemplateIntroRequest as WireUpdateTemplateIntroRequest
+from matelab._generated.models import UpdateTemplateIntroResponse as WireUpdateTemplateIntroResponse
+from matelab._transport import Encoding, Operation, SessionTransport, multipart_fields
+from matelab.errors import MatelabError, MatelabProtocolError, MatelabUsageError, MatelabVerificationError
+from matelab.groups import GroupRef
+from matelab.uploads import UploadBindingRef
+from matelab.users import UserRef
+
+_LIST_TEMPLATES = Operation(
+    method="GET",
+    path="/eln_template/list",
+    encoding=Encoding.NONE,
+    response_model=WireTemplateListResponse,
+    success_codes=frozenset({0}),
+    retry_on_access_expired=True,
+)
+_LIST_TEMPLATE_MARKET = Operation(
+    method="GET",
+    path="/eln_template/store_list",
+    encoding=Encoding.QUERY,
+    response_model=WireTemplateStoreListResponse,
+    success_codes=frozenset({0}),
+    retry_on_access_expired=True,
+)
+_READ_TEMPLATE = Operation(
+    method="GET",
+    path="/eln_template/content",
+    encoding=Encoding.QUERY,
+    response_model=WireTemplateContentResponse,
+    success_codes=frozenset({0}),
+    retry_on_access_expired=True,
+)
+_SHARE_TEMPLATES = Operation(
+    method="POST",
+    path="/eln_template/share_multiple",
+    encoding=Encoding.MULTIPART,
+    response_model=WireBasicSuccessResponse,
+    success_codes=frozenset({0}),
+)
+_REMOVE_USER_LIBRARY_ENTRY = Operation(
+    method="POST",
+    path="/eln_template/refuse",
+    encoding=Encoding.MULTIPART,
+    response_model=WireBasicSuccessResponse,
+    success_codes=frozenset({0}),
+)
+_ADD_GROUP_TEMPLATE = Operation(
+    method="POST",
+    path="/eln_template/group_add",
+    encoding=Encoding.MULTIPART,
+    response_model=WireBasicSuccessResponse,
+    success_codes=frozenset({0}),
+)
+_REMOVE_GROUP_TEMPLATE = Operation(
+    method="POST",
+    path="/eln_template/group_del",
+    encoding=Encoding.MULTIPART,
+    response_model=WireBasicSuccessResponse,
+    success_codes=frozenset({0}),
+)
+_ACQUIRE_MARKET_TEMPLATE = Operation(
+    method="POST",
+    path="/eln_template/store_buy",
+    encoding=Encoding.JSON,
+    response_model=WireBasicSuccessResponse,
+    success_codes=frozenset({0}),
+)
+_SAVE_TEMPLATE_METADATA = Operation(
+    method="POST",
+    path="/eln_template/edit",
+    encoding=Encoding.JSON,
+    response_model=WireSaveTemplateMetadataResponse,
+    success_codes=frozenset({0}),
+)
+_SAVE_TEMPLATE_CONTENT = Operation(
+    method="POST",
+    path="/eln_items/templateSave",
+    encoding=Encoding.JSON,
+    response_model=WireBasicSuccessResponse,
+    success_codes=frozenset({0}),
+)
+_COPY_TEMPLATE = Operation(
+    method="POST",
+    path="/eln_template/saveas",
+    encoding=Encoding.JSON,
+    response_model=WireBasicSuccessResponse,
+    success_codes=frozenset({0}),
+)
+_UPDATE_TEMPLATE_INTRO = Operation(
+    method="POST",
+    path="/eln_template/edit_intro",
+    encoding=Encoding.JSON,
+    response_model=WireUpdateTemplateIntroResponse,
+    success_codes=frozenset({0}),
+)
+_SUBMIT_TEMPLATE = Operation(
+    method="POST",
+    path="/eln_template/pub",
+    encoding=Encoding.JSON,
+    response_model=WireBasicSuccessResponse,
+    success_codes=frozenset({0}),
+)
+_MODULE_RESERVED_FIELDS = frozenset({"name", "type", "data", "language", "style"})
+
+
+class TemplateSource(StrEnum):
+    OWNED = "owned"
+    SHARED = "shared"
+    MARKET_ACQUIRED = "market_acquired"
+    GROUP = "group"
+    DEFAULT = "default"
+    PENDING_MARKET_REVIEW = "pending_market_review"
+
+
+class TemplateLibraryRelationKind(StrEnum):
+    DIRECT_SHARE = "direct_share"
+    MARKET_ACQUISITION = "market_acquisition"
+    GROUP = "group"
+
+
+@dataclass(frozen=True, slots=True)
+class TemplateRef:
+    template_id: int
+
+
+@dataclass(frozen=True, slots=True)
+class TemplateLibraryEntryRef:
+    """A relation identity kept distinct from its template database identity."""
+
+    relation_id: int
+    template: TemplateRef
+    kind: TemplateLibraryRelationKind
+
+
+@dataclass(frozen=True, slots=True)
+class TemplateSummary:
+    ref: TemplateRef
+    source: TemplateSource
+    title: str | None
+    summary: str | None
+    library_entry: TemplateLibraryEntryRef | None = None
+    owner: UserRef | None = None
+    owner_name: str | None = None
+    group: GroupRef | None = None
+    group_name: str | None = None
+    group_admin: bool | None = None
+    intro: str | None = None
+    modified_at: str | None = None
+    keywords: tuple[object, ...] | None = None
+    version: int | None = None
+    market_version: int | None = None
+    publication_reason: str | None = None
+    render_metadata: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class TemplateCollection:
+    owned: tuple[TemplateSummary, ...]
+    shared: tuple[TemplateSummary, ...]
+    market_acquired: tuple[TemplateSummary, ...]
+    group: tuple[TemplateSummary, ...]
+    default: tuple[TemplateSummary, ...]
+    pending_market_review: tuple[TemplateSummary, ...]
+    ordering: Literal["provider_unspecified"] = "provider_unspecified"
+
+    @property
+    def all(self) -> tuple[TemplateSummary, ...]:
+        return (
+            *self.owned,
+            *self.shared,
+            *self.market_acquired,
+            *self.group,
+            *self.default,
+            *self.pending_market_review,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class TemplateMarketEntry:
+    ref: TemplateRef
+    title: str
+    summary: str | None
+    intro: str | None
+    modified_at: str | None
+    published_at: str | None
+    publisher_name: str | None
+    acquisition_count: int | None
+    acquired: bool
+
+
+@dataclass(frozen=True, slots=True)
+class TemplateMarketPage:
+    items: tuple[TemplateMarketEntry, ...]
+    page: int
+    requested_page_size: int
+    effective_page_size: int
+    total_count: int
+    has_more: bool
+    has_more_basis: Literal["derived_from_total"] = "derived_from_total"
+    ordering: Literal["provider_unspecified"] = "provider_unspecified"
+
+
+@dataclass(frozen=True, slots=True)
+class TemplateModule:
+    name: str
+    module_type: str
+    data: object
+    data_present: bool
+    language: str | None
+    style: object
+    attributes: Mapping[str, object]
+
+
+@dataclass(frozen=True, slots=True)
+class TemplateContent:
+    ref: TemplateRef
+    modules: tuple[TemplateModule, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class TemplateMetadata:
+    title: str
+    summary: str | None = None
+    keywords: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class TemplateShareResult:
+    templates: tuple[TemplateRef, ...]
+    recipients: tuple[UserRef, ...]
+    affected_relations: None = None
+    result_scope: Literal["provider_acknowledged_without_relation_results"] = (
+        "provider_acknowledged_without_relation_results"
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class TemplateLibraryRemovalResult:
+    entry: TemplateLibraryEntryRef
+    absence_confirmed: bool
+    provider_semantics: Literal["idempotent_acknowledgement"] = "idempotent_acknowledgement"
+
+
+@dataclass(frozen=True, slots=True)
+class TemplateGroupAddResult:
+    template: TemplateRef
+    group: GroupRef
+    observed_entry: TemplateLibraryEntryRef | None
+    observation: Literal["relation_observed", "relation_not_observed"]
+
+
+@dataclass(frozen=True, slots=True)
+class TemplateGroupRemoveResult:
+    entry: TemplateLibraryEntryRef
+    absence_confirmed: bool
+
+
+@dataclass(frozen=True, slots=True)
+class TemplateMarketAcquireResult:
+    template: TemplateRef
+    observed_entry: TemplateLibraryEntryRef | None
+    observation: Literal["relation_observed", "relation_not_observed"]
+
+
+@dataclass(frozen=True, slots=True)
+class TemplateMetadataResult:
+    template: TemplateRef
+    requested: TemplateMetadata
+    action: Literal["created", "updated"]
+    observed: TemplateSummary | None
+    confirmation: Literal["observed_matching", "observed_mismatch", "not_observed"]
+    publication_revision_advanced: Literal[False] = False
+
+
+@dataclass(frozen=True, slots=True)
+class TemplateContentSaveResult:
+    template: TemplateRef
+    requested: tuple[TemplateModule, ...]
+    observed: TemplateContent
+    confirmation: Literal["observed_matching", "observed_mismatch"]
+
+
+@dataclass(frozen=True, slots=True)
+class TemplateCopyResult:
+    source: TemplateRef
+    requested_title: str
+    copied_template: None = None
+    identity_status: Literal["provider_did_not_return_identity"] = "provider_did_not_return_identity"
+
+
+@dataclass(frozen=True, slots=True)
+class TemplateIntroUpdateResult:
+    template: TemplateRef
+    intro: str
+    upload_binding: UploadBindingRef
+    publication_revision_advanced: Literal[False] = False
+    binding_authorization: Literal["provider_does_not_verify_uploader"] = "provider_does_not_verify_uploader"
+
+
+@dataclass(frozen=True, slots=True)
+class TemplateMarketSubmissionResult:
+    template: TemplateRef
+    observed_pending_review: bool
+    observation: Literal["pending_entry_observed", "pending_entry_not_observed"]
+
+
+class Templates:
+    """Template discovery, market search, and canonical content reads."""
+
+    def __init__(self, transport: SessionTransport) -> None:
+        self._transport: SessionTransport = transport
+
+    async def list(self) -> TemplateCollection:
+        response = await self._transport.request(_LIST_TEMPLATES)
+        return TemplateCollection(
+            owned=tuple(
+                TemplateSummary(
+                    ref=TemplateRef(template_id=item.template_id),
+                    source=TemplateSource.OWNED,
+                    title=item.template_name,
+                    summary=item.comm,
+                    owner=UserRef(userid=item.userid_from) if item.userid_from else None,
+                    owner_name=item.username,
+                    intro=item.intro,
+                    modified_at=item.datetime,
+                    keywords=tuple(cast(list[object], item.keyword)),
+                    version=item.version,
+                    market_version=item.store_version,
+                    publication_reason=self._publication_reason(item),
+                    render_metadata=item.template_show,
+                )
+                for item in response.my
+            ),
+            shared=tuple(
+                TemplateSummary(
+                    ref=TemplateRef(template_id=item.template_id),
+                    source=TemplateSource.SHARED,
+                    title=item.template_name,
+                    summary=item.comm,
+                    library_entry=TemplateLibraryEntryRef(
+                        relation_id=item.id,
+                        template=TemplateRef(template_id=item.template_id),
+                        kind=TemplateLibraryRelationKind.DIRECT_SHARE,
+                    ),
+                    owner=UserRef(userid=item.userid_from) if item.userid_from is not None else None,
+                    owner_name=item.username,
+                )
+                for item in response.share
+            ),
+            market_acquired=tuple(
+                TemplateSummary(
+                    ref=TemplateRef(template_id=item.template_id),
+                    source=TemplateSource.MARKET_ACQUIRED,
+                    title=item.template_name,
+                    summary=item.comm,
+                    library_entry=TemplateLibraryEntryRef(
+                        relation_id=item.id,
+                        template=TemplateRef(template_id=item.template_id),
+                        kind=TemplateLibraryRelationKind.MARKET_ACQUISITION,
+                    ),
+                    owner_name=item.username,
+                )
+                for item in response.stores
+            ),
+            group=tuple(
+                TemplateSummary(
+                    ref=TemplateRef(template_id=item.template_id),
+                    source=TemplateSource.GROUP,
+                    title=item.template_name,
+                    summary=item.comm,
+                    library_entry=TemplateLibraryEntryRef(
+                        relation_id=item.id,
+                        template=TemplateRef(template_id=item.template_id),
+                        kind=TemplateLibraryRelationKind.GROUP,
+                    ),
+                    owner=UserRef(userid=item.userid) if item.userid is not None else None,
+                    owner_name=item.username,
+                    group=GroupRef(group_id=item.group_id),
+                    group_name=item.group_name,
+                    group_admin=item.admin,
+                    modified_at=item.datetime,
+                )
+                for item in response.group
+            ),
+            default=tuple(
+                TemplateSummary(
+                    ref=TemplateRef(template_id=item.template_id),
+                    source=TemplateSource.DEFAULT,
+                    title=item.template_name,
+                    summary=item.comm,
+                )
+                for item in response.default
+            ),
+            pending_market_review=tuple(
+                TemplateSummary(
+                    ref=TemplateRef(template_id=item.template_id),
+                    source=TemplateSource.PENDING_MARKET_REVIEW,
+                    title=item.template_name,
+                    summary=item.comm,
+                    owner_name=item.username,
+                )
+                for item in response.pending
+            ),
+        )
+
+    async def search_market(self, search: str = "", *, page: int = 1, page_size: int = 10) -> TemplateMarketPage:
+        try:
+            request = WireListTemplateStoreQuery(search=search, page=page, page_size=page_size)
+        except ValidationError:
+            raise MatelabUsageError("Template-market filters do not satisfy the Integration Contract.") from None
+        response = await self._transport.request(_LIST_TEMPLATE_MARKET, payload=request.model_dump(mode="json"))
+        effective_page_size = max(10, request.page_size)
+        return TemplateMarketPage(
+            items=tuple(
+                TemplateMarketEntry(
+                    ref=TemplateRef(template_id=item.id),
+                    title=item.showtext,
+                    summary=item.comm,
+                    intro=item.intro,
+                    modified_at=item.datetime_modify,
+                    published_at=item.dtime_pub,
+                    publisher_name=item.username,
+                    acquisition_count=item.buy_count,
+                    acquired=bool(item.my),
+                )
+                for item in response.items
+            ),
+            page=request.page,
+            requested_page_size=request.page_size,
+            effective_page_size=effective_page_size,
+            total_count=response.count,
+            has_more=request.page * effective_page_size < response.count,
+        )
+
+    async def read(self, template: TemplateRef) -> TemplateContent:
+        try:
+            request = WireReadTemplateContentQuery(id=template.template_id)
+        except ValidationError:
+            raise MatelabUsageError("Template identity does not satisfy the Integration Contract.") from None
+        response = await self._transport.request(_READ_TEMPLATE, payload=request.model_dump(mode="json"))
+        return TemplateContent(ref=template, modules=tuple(self._module(module) for module in response.content))
+
+    async def share(self, templates: Sequence[TemplateRef], recipients: Sequence[UserRef]) -> TemplateShareResult:
+        selected = tuple(templates)
+        targets = tuple(recipients)
+        template_ids = self._bounded_unique_ids(
+            (template.template_id for template in selected), subject="Template share selection"
+        )
+        userids = self._bounded_unique_ids(
+            (recipient.userid for recipient in targets), subject="Template share recipients"
+        )
+        try:
+            request = WireShareMultipleTemplatesRequest(
+                templates=json.dumps(template_ids, separators=(",", ":")),
+                users=json.dumps(userids, separators=(",", ":")),
+            )
+        except ValidationError:
+            raise MatelabUsageError("Template share request does not satisfy the Integration Contract.") from None
+        _ = await self._transport.request(_SHARE_TEMPLATES, files=multipart_fields(request.model_dump(mode="json")))
+        return TemplateShareResult(templates=selected, recipients=targets)
+
+    async def unshare(self, entry: TemplateLibraryEntryRef) -> TemplateLibraryRemovalResult:
+        if entry.kind is not TemplateLibraryRelationKind.DIRECT_SHARE:
+            raise MatelabUsageError("Template unshare requires a direct-share library relation.")
+        return await self._remove_user_library_entry(entry)
+
+    async def remove_market_acquisition(self, entry: TemplateLibraryEntryRef) -> TemplateLibraryRemovalResult:
+        if entry.kind is not TemplateLibraryRelationKind.MARKET_ACQUISITION:
+            raise MatelabUsageError("Removing a market acquisition requires a market-acquisition relation.")
+        return await self._remove_user_library_entry(entry)
+
+    async def add_to_group(self, template: TemplateRef, group: GroupRef) -> TemplateGroupAddResult:
+        try:
+            request = WireAddGroupTemplateRequest(template_id=template.template_id, group_id=group.group_id)
+        except ValidationError:
+            raise MatelabUsageError("Template/group identity does not satisfy the Integration Contract.") from None
+        _ = await self._transport.request(_ADD_GROUP_TEMPLATE, files=multipart_fields(request.model_dump(mode="json")))
+        after = await self._verified_list("template group addition")
+        observed = next(
+            (
+                item.library_entry
+                for item in after.group
+                if item.ref == template and item.group == group and item.library_entry is not None
+            ),
+            None,
+        )
+        return TemplateGroupAddResult(
+            template=template,
+            group=group,
+            observed_entry=observed,
+            observation="relation_observed" if observed is not None else "relation_not_observed",
+        )
+
+    async def remove_from_group(self, entry: TemplateLibraryEntryRef) -> TemplateGroupRemoveResult:
+        if entry.kind is not TemplateLibraryRelationKind.GROUP:
+            raise MatelabUsageError("Removing a group template requires a group library relation.")
+        try:
+            request = WireDeleteGroupTemplateRequest(id=entry.relation_id)
+        except ValidationError:
+            raise MatelabUsageError("Group-template relation does not satisfy the Integration Contract.") from None
+        _ = await self._transport.request(
+            _REMOVE_GROUP_TEMPLATE, files=multipart_fields(request.model_dump(mode="json"))
+        )
+        after = await self._verified_list("template group removal")
+        return TemplateGroupRemoveResult(entry=entry, absence_confirmed=not self._relation_present(after.group, entry))
+
+    async def acquire_from_market(self, template: TemplateRef) -> TemplateMarketAcquireResult:
+        try:
+            request = WireTemplateIdRequest(id=template.template_id)
+        except ValidationError:
+            raise MatelabUsageError("Template identity does not satisfy the Integration Contract.") from None
+        _ = await self._transport.request(_ACQUIRE_MARKET_TEMPLATE, payload=request.model_dump(mode="json"))
+        after = await self._verified_list("template market acquisition")
+        observed = next(
+            (
+                item.library_entry
+                for item in after.market_acquired
+                if item.ref == template and item.library_entry is not None
+            ),
+            None,
+        )
+        return TemplateMarketAcquireResult(
+            template=template,
+            observed_entry=observed,
+            observation="relation_observed" if observed is not None else "relation_not_observed",
+        )
+
+    async def create(self, metadata: TemplateMetadata) -> TemplateMetadataResult:
+        return await self._save_metadata(template=None, metadata=metadata)
+
+    async def update(self, template: TemplateRef, metadata: TemplateMetadata) -> TemplateMetadataResult:
+        return await self._save_metadata(template=template, metadata=metadata)
+
+    async def save_content(self, template: TemplateRef, modules: Sequence[TemplateModule]) -> TemplateContentSaveResult:
+        requested = tuple(modules)
+        payloads = self._module_payloads(requested)
+        try:
+            request = WireSaveTemplateContentRequest(
+                id=template.template_id, data=json.dumps(payloads, ensure_ascii=False, separators=(",", ":"))
+            )
+        except (ValidationError, TypeError, ValueError):
+            raise MatelabUsageError("Template content does not satisfy the Integration Contract.") from None
+        _ = await self._transport.request(_SAVE_TEMPLATE_CONTENT, payload=request.model_dump(mode="json"))
+        observed = await self._verified_read(template, "template content replacement")
+        return TemplateContentSaveResult(
+            template=template,
+            requested=requested,
+            observed=observed,
+            confirmation="observed_matching" if observed.modules == requested else "observed_mismatch",
+        )
+
+    async def copy(self, template: TemplateRef, *, title: str) -> TemplateCopyResult:
+        try:
+            request = WireCopyTemplateRequest(id=template.template_id, template_name=title)
+        except ValidationError:
+            raise MatelabUsageError("Template copy input does not satisfy the Integration Contract.") from None
+        _ = await self._transport.request(_COPY_TEMPLATE, payload=request.model_dump(mode="json"))
+        return TemplateCopyResult(source=template, requested_title=title)
+
+    async def update_intro(
+        self, template: TemplateRef, *, intro: str | None, upload_binding: UploadBindingRef
+    ) -> TemplateIntroUpdateResult:
+        try:
+            request = WireUpdateTemplateIntroRequest(id=template.template_id, intro=intro, uid=upload_binding.uid)
+        except ValidationError:
+            raise MatelabUsageError("Template intro input does not satisfy the Integration Contract.") from None
+        response = await self._transport.request(_UPDATE_TEMPLATE_INTRO, payload=request.model_dump(mode="json"))
+        return TemplateIntroUpdateResult(template=template, intro=response.intro, upload_binding=upload_binding)
+
+    async def submit_to_market(self, template: TemplateRef) -> TemplateMarketSubmissionResult:
+        try:
+            request = WireTemplateIdRequest(id=template.template_id)
+        except ValidationError:
+            raise MatelabUsageError("Template identity does not satisfy the Integration Contract.") from None
+        _ = await self._transport.request(_SUBMIT_TEMPLATE, payload=request.model_dump(mode="json"))
+        after = await self._verified_list("template market submission")
+        observed = any(item.ref == template for item in after.pending_market_review)
+        return TemplateMarketSubmissionResult(
+            template=template,
+            observed_pending_review=observed,
+            observation="pending_entry_observed" if observed else "pending_entry_not_observed",
+        )
+
+    async def _remove_user_library_entry(self, entry: TemplateLibraryEntryRef) -> TemplateLibraryRemovalResult:
+        try:
+            request = WireRemoveUserTemplateRelationRequest(id=entry.relation_id)
+        except ValidationError:
+            raise MatelabUsageError("Template library relation does not satisfy the Integration Contract.") from None
+        _ = await self._transport.request(
+            _REMOVE_USER_LIBRARY_ENTRY, files=multipart_fields(request.model_dump(mode="json"))
+        )
+        after = await self._verified_list("template library removal")
+        scope = after.shared if entry.kind is TemplateLibraryRelationKind.DIRECT_SHARE else after.market_acquired
+        return TemplateLibraryRemovalResult(entry=entry, absence_confirmed=not self._relation_present(scope, entry))
+
+    async def _save_metadata(
+        self, *, template: TemplateRef | None, metadata: TemplateMetadata
+    ) -> TemplateMetadataResult:
+        if any(not isinstance(keyword, str) for keyword in cast(tuple[object, ...], metadata.keywords)):
+            raise MatelabUsageError("Template keywords must be strings.")
+        try:
+            request = WireSaveTemplateMetadataRequest(
+                id=template.template_id if template is not None else 0,
+                showtext=metadata.title,
+                comm=metadata.summary,
+                keyword=json.dumps(metadata.keywords, ensure_ascii=False, separators=(",", ":")),
+            )
+        except (ValidationError, TypeError, ValueError):
+            raise MatelabUsageError("Template metadata does not satisfy the Integration Contract.") from None
+        response = await self._transport.request(_SAVE_TEMPLATE_METADATA, payload=request.model_dump(mode="json"))
+        expected_action = "edit" if template is not None else "add"
+        if response.action.value != expected_action or (template is not None and response.id != template.template_id):
+            raise MatelabProtocolError("Matelab returned an inconsistent template metadata action or identity.")
+        result_ref = TemplateRef(template_id=response.id)
+        after = await self._verified_list("template metadata save")
+        observed = next((item for item in after.owned if item.ref == result_ref), None)
+        if observed is None:
+            confirmation: Literal["observed_matching", "observed_mismatch", "not_observed"] = "not_observed"
+        elif self._metadata_matches(observed, metadata):
+            confirmation = "observed_matching"
+        else:
+            confirmation = "observed_mismatch"
+        return TemplateMetadataResult(
+            template=result_ref,
+            requested=metadata,
+            action="updated" if template is not None else "created",
+            observed=observed,
+            confirmation=confirmation,
+        )
+
+    async def _verified_list(self, action: str) -> TemplateCollection:
+        try:
+            return await self.list()
+        except MatelabError as exc:
+            raise MatelabVerificationError(
+                f"Matelab acknowledged the {action}, but readback failed; the mutation may have persisted."
+            ) from exc
+
+    async def _verified_read(self, template: TemplateRef, action: str) -> TemplateContent:
+        try:
+            return await self.read(template)
+        except MatelabError as exc:
+            raise MatelabVerificationError(
+                f"Matelab acknowledged the {action}, but readback failed; the mutation may have persisted."
+            ) from exc
+
+    @staticmethod
+    def _bounded_unique_ids(values: Iterable[int], *, subject: str) -> tuple[int, ...]:
+        selected = tuple(values)
+        if (
+            not 1 <= len(selected) <= 10
+            or any(type(value) is not int or value < 1 for value in selected)
+            or len(selected) != len(set(selected))
+        ):
+            raise MatelabUsageError(f"{subject} must contain one through ten distinct positive ids.")
+        return selected
+
+    @staticmethod
+    def _relation_present(scope: Sequence[TemplateSummary], entry: TemplateLibraryEntryRef) -> bool:
+        return any(item.library_entry == entry for item in scope)
+
+    @staticmethod
+    def _metadata_matches(observed: TemplateSummary, requested: TemplateMetadata) -> bool:
+        return (
+            observed.title == requested.title
+            and (observed.summary or "") == (requested.summary or "")
+            and observed.keywords == requested.keywords
+        )
+
+    @staticmethod
+    def _module_payloads(modules: tuple[TemplateModule, ...]) -> tuple[dict[str, object], ...]:
+        if len({module.name for module in modules}) != len(modules):
+            raise MatelabUsageError("Template module names must be unique.")
+        payloads: list[dict[str, object]] = []
+        try:
+            for module in modules:
+                attributes = dict(module.attributes)
+                if _MODULE_RESERVED_FIELDS & attributes.keys():
+                    raise MatelabUsageError("Template module attributes cannot replace canonical fields.")
+                payload: dict[str, object] = {**attributes, "name": module.name, "type": module.module_type}
+                if module.data_present:
+                    payload["data"] = module.data
+                if module.language is not None:
+                    payload["language"] = module.language
+                if module.style is not None:
+                    payload["style"] = module.style
+                wire = WireTemplateModule.model_validate(payload)
+                payloads.append(wire.model_dump(mode="json", exclude_unset=True))
+            _ = json.dumps(payloads, ensure_ascii=False)
+        except (ValidationError, TypeError, ValueError):
+            raise MatelabUsageError("Template modules do not satisfy the Integration Contract.") from None
+        return tuple(payloads)
+
+    @staticmethod
+    def _publication_reason(item: WireOwnedTemplateListItem) -> str:
+        extra = cast(dict[str, object], item.model_extra or {})
+        stable_alias = extra.get("pub_reason")
+        return stable_alias if isinstance(stable_alias, str) else item.Ifnull_pub_reason_____
+
+    @staticmethod
+    def _module(module: WireTemplateModule) -> TemplateModule:
+        attributes = MappingProxyType(cast(dict[str, object], dict(module.model_extra or {})))
+        return TemplateModule(
+            name=module.name,
+            module_type=module.type,
+            data=cast(object, module.data),
+            data_present="data" in module.model_fields_set,
+            language=module.language,
+            style=cast(object, module.style),
+            attributes=attributes,
+        )