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

matelab/records.py

@@ -0,0 +1,2511 @@
+import hashlib
+import json
+import re
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from html.parser import HTMLParser
+from types import MappingProxyType
+from typing import IO, Literal, cast
+from urllib.parse import parse_qs, unquote
+
+from pydantic import ValidationError
+
+from matelab._generated.models import AddRelationRequest as WireAddRelationRequest
+from matelab._generated.models import BasicSuccessResponse as WireBasicSuccessResponse
+from matelab._generated.models import Code as WireSuccessCode
+from matelab._generated.models import CommentListResponse as WireCommentListResponse
+from matelab._generated.models import CopyRecordRequest as WireCopyRecordRequest
+from matelab._generated.models import CopyRecordResponse as WireCopyRecordResponse
+from matelab._generated.models import CreateRecordRequest as WireCreateRecordRequest
+from matelab._generated.models import Default as WirePageDefault
+from matelab._generated.models import DeletedRecordPageResponse as WireDeletedRecordPageResponse
+from matelab._generated.models import DeleteRecordCommentRequest as WireDeleteRecordCommentRequest
+from matelab._generated.models import DeleteRecordsRequest as WireDeleteRecordsRequest
+from matelab._generated.models import DeleteRelationRequest as WireDeleteRelationRequest
+from matelab._generated.models import DownloadRecordAttachmentParametersQuery as WireDownloadRecordAttachmentQuery
+from matelab._generated.models import (
+    DownloadRecordCommentAttachmentParametersQuery as WireDownloadRecordCommentAttachmentQuery,
+)
+from matelab._generated.models import ExportRecordsRequest as WireExportRecordsRequest
+from matelab._generated.models import ExportRecordsResponse as WireExportRecordsResponse
+from matelab._generated.models import ForwardableSuccessResponse as WireForwardableSuccessResponse
+from matelab._generated.models import ImportRecordsRequest as WireImportRecordsRequest
+from matelab._generated.models import ImportRecordsResponse as WireImportRecordsResponse
+from matelab._generated.models import ItemViewResponse as WireItemViewResponse
+from matelab._generated.models import ListDeletedRecordPageParametersQuery as WireDeletedRecordPageQuery
+from matelab._generated.models import ListNotebookRecordPageParametersQuery as WireRecordPageQuery
+from matelab._generated.models import ListRecordCommentsParametersQuery as WireRecordCommentsQuery
+from matelab._generated.models import ListRecordRelationsParametersQuery as WireRecordRelationsQuery
+from matelab._generated.models import ListRecordsRequest as WireListRecordsRequest
+from matelab._generated.models import OrderDesc as WireOrderDesc
+from matelab._generated.models import PublicRecordListRequest as WirePublicRecordListRequest
+from matelab._generated.models import PublicRecordListResponse as WirePublicRecordListResponse
+from matelab._generated.models import ReadRecordParametersQuery as WireReadRecordQuery
+from matelab._generated.models import RecordComment as WireRecordComment
+from matelab._generated.models import RecordListItem as WireRecordListItem
+from matelab._generated.models import RecordListResponse as WireRecordListResponse
+from matelab._generated.models import RecordPageResponse as WireRecordPageResponse
+from matelab._generated.models import RecordSubtype as WireRecordSubtype
+from matelab._generated.models import RelationListResponse as WireRelationListResponse
+from matelab._generated.models import RestoreRecordsRequest as WireRestoreRecordsRequest
+from matelab._generated.models import SaveRecordCommentRequest as WireSaveRecordCommentRequest
+from matelab._generated.models import SearchRecordsRequest as WireSearchRecordsRequest
+from matelab._generated.models import SearchRecordsResponse as WireSearchRecordsResponse
+from matelab._generated.models import UpdateRecordRequest as WireUpdateRecordRequest
+from matelab._generated.models import UploadAttachmentRequest as WireUploadAttachmentRequest
+from matelab._generated.models import UploadAttachmentResponse as WireUploadAttachmentResponse
+from matelab._generated.models import UploadRecordCommentAttachmentRequest as WireUploadRecordCommentAttachmentRequest
+from matelab._generated.models import UploadRecordCommentAttachmentResponse as WireUploadRecordCommentAttachmentResponse
+from matelab._transport import Encoding, Operation, SessionTransport, StreamOperation, multipart_fields
+from matelab.errors import MatelabError, MatelabProtocolError, MatelabUsageError, MatelabVerificationError
+from matelab.notebooks import NotebookRef, PublicNotebookRef
+from matelab.streaming import ByteRange, DownloadStream
+from matelab.templates import TemplateRef
+from matelab.uploads import UploadBindingRef
+from matelab.users import UserRef
+
+_LIST_RECORDS = Operation(
+    method="POST",
+    path="/eln_api/items",
+    encoding=Encoding.JSON,
+    response_model=WireRecordListResponse,
+    success_codes=frozenset({0, 10}),
+    retry_on_access_expired=True,
+)
+_CREATE_BLANK_RECORD = Operation(
+    method="POST",
+    path="/eln_api/create",
+    encoding=Encoding.JSON,
+    response_model=WireBasicSuccessResponse,
+    success_codes=frozenset({0}),
+)
+_IMPORT_RECORDS = Operation(
+    method="POST",
+    path="/eln_api/import",
+    encoding=Encoding.JSON,
+    response_model=WireImportRecordsResponse,
+    success_codes=frozenset({0}),
+)
+_DELETE_RECORDS = Operation(
+    method="POST",
+    path="/eln_api/delete",
+    encoding=Encoding.JSON,
+    response_model=WireBasicSuccessResponse,
+    success_codes=frozenset({0}),
+)
+_UPDATE_RECORD = Operation(
+    method="POST",
+    path="/eln_api/update",
+    encoding=Encoding.JSON,
+    response_model=WireBasicSuccessResponse,
+    success_codes=frozenset({0}),
+)
+_UPLOAD_RECORD_ATTACHMENT = Operation(
+    method="POST",
+    path="/eln_api/upload",
+    encoding=Encoding.MULTIPART,
+    response_model=WireUploadAttachmentResponse,
+    success_codes=frozenset({0}),
+)
+_READ_RECORD = Operation(
+    method="GET",
+    path="/eln_items/item_view",
+    encoding=Encoding.QUERY,
+    response_model=WireItemViewResponse,
+    success_codes=frozenset({0}),
+    retry_on_access_expired=True,
+)
+_EXPORT_RECORDS = Operation(
+    method="POST",
+    path="/eln_api/export",
+    encoding=Encoding.JSON,
+    response_model=WireExportRecordsResponse,
+    success_codes=frozenset({0, 10}),
+    retry_on_access_expired=True,
+)
+_SEARCH_RECORDS = Operation(
+    method="POST",
+    path="/eln_api/search",
+    encoding=Encoding.JSON,
+    response_model=WireSearchRecordsResponse,
+    success_codes=frozenset({0, 10}),
+    retry_on_access_expired=True,
+)
+_LIST_PUBLIC_RECORDS = Operation(
+    method="POST",
+    path="/eln_api/public_items",
+    encoding=Encoding.JSON,
+    response_model=WirePublicRecordListResponse,
+    success_codes=frozenset({0}),
+    retry_on_access_expired=True,
+)
+_LIST_RECORD_PAGE = Operation(
+    method="GET",
+    path="/eln_items/items",
+    encoding=Encoding.QUERY,
+    response_model=WireRecordPageResponse,
+    success_codes=frozenset({0}),
+    retry_on_access_expired=True,
+)
+_LIST_DELETED_RECORDS = Operation(
+    method="GET",
+    path="/eln_items/items_recycle",
+    encoding=Encoding.QUERY,
+    response_model=WireDeletedRecordPageResponse,
+    success_codes=frozenset({0, 10}),
+    retry_on_access_expired=True,
+)
+_LIST_RELATIONS = Operation(
+    method="GET",
+    path="/eln_items/related_list",
+    encoding=Encoding.QUERY,
+    response_model=WireRelationListResponse,
+    success_codes=frozenset({0}),
+    retry_on_access_expired=True,
+)
+_ADD_RELATION = Operation(
+    method="POST",
+    path="/eln_items/related_add",
+    encoding=Encoding.JSON,
+    response_model=WireForwardableSuccessResponse,
+    success_codes=frozenset({0, 10}),
+)
+_DELETE_RELATION = Operation(
+    method="POST",
+    path="/eln_items/related_del",
+    encoding=Encoding.JSON,
+    response_model=WireForwardableSuccessResponse,
+    success_codes=frozenset({0, 10}),
+)
+_RESTORE_RECORDS = Operation(
+    method="POST",
+    path="/eln_items/restore",
+    encoding=Encoding.JSON,
+    response_model=WireBasicSuccessResponse,
+    success_codes=frozenset({0}),
+)
+_COPY_RECORD = Operation(
+    method="POST",
+    path="/eln_items/copy",
+    encoding=Encoding.JSON,
+    response_model=WireCopyRecordResponse,
+    success_codes=frozenset({0, 10}),
+)
+_LIST_COMMENTS = Operation(
+    method="GET",
+    path="/eln_items/mores",
+    encoding=Encoding.QUERY,
+    response_model=WireCommentListResponse,
+    success_codes=frozenset({0}),
+    retry_on_access_expired=True,
+)
+_SAVE_COMMENT = Operation(
+    method="POST",
+    path="/eln_items/more",
+    encoding=Encoding.MULTIPART,
+    response_model=WireForwardableSuccessResponse,
+    success_codes=frozenset({0, 10}),
+)
+_UPLOAD_COMMENT_ATTACHMENT = Operation(
+    method="POST",
+    path="/eln_items/more_upload",
+    encoding=Encoding.MULTIPART,
+    response_model=WireUploadRecordCommentAttachmentResponse,
+    success_codes=frozenset({0}),
+)
+_DELETE_COMMENT = Operation(
+    method="POST",
+    path="/eln_items/more_del",
+    encoding=Encoding.MULTIPART,
+    response_model=WireForwardableSuccessResponse,
+    success_codes=frozenset({0, 10}),
+)
+_DOWNLOAD_RECORD_ATTACHMENT = StreamOperation(method="GET", path="/eln_url/eln", retry_on_access_expired=True)
+_DOWNLOAD_COMMENT_ATTACHMENT = StreamOperation(method="GET", path="/eln_url/eln_more", retry_on_access_expired=True)
+_SEARCH_RESERVED_FIELDS = frozenset({"id", "eln_id", "uid", "title", "eln_name"})
+_ELNURL_PATTERN = re.compile(r"^elnurl://h=([a-f0-9]{64})&s=([0-9]+)&f=(.+)$", re.IGNORECASE)
+_ATTACHMENT_MARKER_PATTERN = re.compile(r"matelab-attachment:([A-Za-z0-9_.-]{1,64})")
+_NATIVE_ATTACHMENT_PATTERN = re.compile(r"#(?:hash|file|base64)\{", re.IGNORECASE)
+_COMMENT_TEMP_URL_PATTERN = re.compile(r"https?://[^\"']+/eln_url/eln_temp\?", re.IGNORECASE)
+_DATABASE_UPDATE_MESSAGES = frozenset({"数据库数据更新成功", "Database data update successful"})
+_COLLABORATION_UPDATE_MESSAGES = frozenset({"协同编辑数据更新完成", "Collaboration data update completed"})
+
+
+@dataclass(frozen=True, slots=True)
+class RecordRef:
+    """Record identity with distinct database and wire identifiers."""
+
+    record_database_id: int
+    record_uid: str
+
+
+@dataclass(frozen=True, slots=True)
+class RecordLocator:
+    notebook: NotebookRef
+    record: RecordRef
+
+
+@dataclass(frozen=True, slots=True)
+class DeletedRecordRef:
+    record_database_id: int
+    record_uid: str
+
+
+@dataclass(frozen=True, slots=True)
+class RecordVersionRef:
+    """Historical version identity derived from an authorized current record read."""
+
+    notebook_id: int
+    record_database_id: int
+    record_uid: str
+    version_id: int
+
+
+@dataclass(frozen=True, slots=True)
+class RecordSummary:
+    ref: RecordRef
+    title: str
+    summary: str | None
+    created_at: str
+    modified_at: str
+    keywords: tuple[str, ...]
+    template_id: int | None
+    subtype_id: int | None
+    encrypted: bool
+    audit_count: int | None
+
+
+@dataclass(frozen=True, slots=True)
+class RecordSubtypeSummary:
+    subtype_id: int
+    title: str
+    parent_subtype_id: int
+    record_count: int | None
+    child_subtype_count: int | None
+
+
+@dataclass(frozen=True, slots=True)
+class RecordCollection:
+    records: tuple[RecordSummary, ...]
+    subtypes: tuple[RecordSubtypeSummary, ...]
+    trash_count: int
+
+
+@dataclass(frozen=True, slots=True)
+class BlankRecordCreateResult:
+    notebook: NotebookRef
+    title: str
+    requested_record_uid: str | None
+    observed: RecordSummary | None
+    confirmation: Literal[
+        "observed_by_requested_uid", "not_observed_by_requested_uid", "provider_generated_identity_not_returned"
+    ]
+
+
+@dataclass(frozen=True, slots=True)
+class RecordImportTemplate:
+    template: TemplateRef
+    title: str
+    owner: UserRef | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class RecordImportItem:
+    record_uid: str
+    title: str
+    data: Mapping[str, object]
+    keyword: str | None = None
+    path: tuple[str, ...] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class RecordImportResult:
+    notebook: NotebookRef
+    template: RecordImportTemplate
+    requested_record_uids: tuple[str, ...]
+    created_record_database_ids: tuple[int, ...]
+    provider_notebook_id: int
+    per_item_mapping: None = None
+    identity_count_status: Literal["one_id_per_item", "fewer_ids_than_items", "more_ids_than_items"] = "one_id_per_item"
+    atomicity: Literal["provider_unspecified"] = "provider_unspecified"
+    field_persistence: Literal["provider_not_verified"] = "provider_not_verified"
+    known_limitations: tuple[Literal["PVD-023"], Literal["PVD-024"]] = ("PVD-023", "PVD-024")
+
+
+@dataclass(frozen=True, slots=True)
+class RecordCopyResult:
+    source: RecordLocator
+    target_notebook: NotebookRef
+    record_database_id: int
+    record: RecordRef | None
+    observed: RecordSummary | None
+    forwarded: bool
+    confirmation: Literal["observed_by_returned_id", "returned_id_not_observed"]
+
+
+@dataclass(frozen=True, slots=True)
+class RecordDeleteResult:
+    notebook: NotebookRef
+    requested: tuple[RecordRef, ...]
+    no_longer_active: tuple[RecordRef, ...]
+    still_active: tuple[RecordRef, ...]
+    observed_in_recycle_bin: tuple[DeletedRecordRef, ...]
+    unresolved: tuple[RecordRef, ...]
+    operation_semantics: Literal["move_to_recycle_bin"] = "move_to_recycle_bin"
+    observation_scope: Literal["active_list_and_first_256_deleted_rows"] = "active_list_and_first_256_deleted_rows"
+
+
+@dataclass(frozen=True, slots=True)
+class RecordRestoreResult:
+    notebook: NotebookRef
+    requested: tuple[DeletedRecordRef, ...]
+    observed_active: tuple[RecordRef, ...]
+    still_deleted: tuple[DeletedRecordRef, ...]
+    unresolved: tuple[DeletedRecordRef, ...]
+    provider_per_item_results_available: Literal[False] = False
+    observation_scope: Literal["active_list_and_first_256_deleted_rows"] = "active_list_and_first_256_deleted_rows"
+
+
+@dataclass(frozen=True, slots=True)
+class ExportedRecord:
+    ref: RecordRef
+    notebook_title: str | None
+    title: str
+    summary: str | None
+    data: tuple[object, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class RecordExport:
+    records: tuple[ExportedRecord, ...]
+    forwarded: bool
+
+
+@dataclass(frozen=True, slots=True)
+class RecordFieldExtraction:
+    alias: str
+    path: tuple[str | int, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class RecordSearchMatch:
+    ref: RecordRef
+    notebook_id: int
+    notebook_title: str
+    title: str
+    extracted: Mapping[str, object]
+    missing_extractions: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class RecordSearchResult:
+    matches: tuple[RecordSearchMatch, ...]
+    forwarded: bool
+    ordering: Literal["provider_unspecified"] = "provider_unspecified"
+
+
+@dataclass(frozen=True, slots=True)
+class PublicRecordRef:
+    public_entry_id: int
+    source_notebook_id: int
+    source_record_database_id: int
+    record_uid: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class PublicRecordSummary:
+    ref: PublicRecordRef
+    title: str | None
+    summary: str | None
+    locked: bool
+    source_notebook_title: str | None
+    owner: UserRef | None
+    owner_name: str | None
+    owner_email: str | None
+    owned_by_caller: bool
+
+
+@dataclass(frozen=True, slots=True)
+class PublicRecordCollection:
+    notebook: PublicNotebookRef
+    records: tuple[PublicRecordSummary, ...]
+    ordering: Literal["provider_unspecified"] = "provider_unspecified"
+
+
+@dataclass(frozen=True, slots=True)
+class RecordPagePermissions:
+    editable: bool
+    can_create: bool
+    can_delete: bool
+    can_manage_subtypes: bool
+    can_read_audit: bool
+    can_manage_users: bool
+    can_sign: bool
+
+
+@dataclass(frozen=True, slots=True)
+class RecordPageContext:
+    notebook: NotebookRef
+    notebook_title: str | None
+    owner_name: str | None
+    template_id: int | None
+    data_server: str
+    permissions: RecordPagePermissions
+    effective_page_size: int
+
+
+@dataclass(frozen=True, slots=True)
+class RecordPage:
+    records: tuple[RecordSummary, ...]
+    subtypes: tuple[RecordSubtypeSummary, ...]
+    context: RecordPageContext
+    page: int
+    total_count: int
+    matching_record_database_ids: tuple[int, ...]
+    trash_count: int
+    has_more: bool
+    keywords: tuple[object, ...]
+    has_more_basis: Literal["derived_from_matching_ids"] = "derived_from_matching_ids"
+    ordering: Literal["provider_configured_unstable"] = "provider_configured_unstable"
+
+
+@dataclass(frozen=True, slots=True)
+class DeletedRecordSummary:
+    ref: DeletedRecordRef
+    title: str
+    summary: str | None
+    created_at: str
+    modified_at: str
+    deleted_at: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class DeletedRecordPage:
+    notebook: NotebookRef
+    records: tuple[DeletedRecordSummary, ...]
+    page: int
+    requested_page_size: int
+    total_count: int
+    has_more: bool
+    forwarded: bool
+    has_more_basis: Literal["derived_from_total"] = "derived_from_total"
+    ordering: Literal["provider_unspecified"] = "provider_unspecified"
+
+
+@dataclass(frozen=True, slots=True)
+class RecordCommentRef:
+    comment_id: int
+
+
+@dataclass(frozen=True, slots=True)
+class RecordAttachmentLocation:
+    """One observed attachment occurrence in canonical record content."""
+
+    kind: Literal["form_file", "table_file", "files_module", "images_module", "richtext"]
+    module: str
+    field: str | None
+    position: int
+
+
+@dataclass(frozen=True, slots=True)
+class RecordAttachmentRef:
+    """Attachment metadata observed in an authorized record read."""
+
+    source: RecordLocator
+    sha256: str = field(repr=False)
+    filename: str
+    size: int
+    observed_version: RecordVersionRef | None = None
+    location: RecordAttachmentLocation | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class StagedRecordAttachment:
+    """A completed record upload that has not yet been bound by a record update."""
+
+    source: RecordLocator
+    temporary_file_id: int
+    binding: UploadBindingRef
+    filename: str
+    size: int
+    sha256: str = field(repr=False)
+    binding_state: Literal["staged_not_bound"] = "staged_not_bound"
+
+
+@dataclass(frozen=True, slots=True)
+class RecordValueUpdate:
+    path: tuple[str | int, ...]
+    value: object
+
+
+@dataclass(frozen=True, slots=True)
+class RecordValueDeletion:
+    path: tuple[str | int, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class RecordModuleCreation:
+    name: str
+    module_type: Literal["form", "table", "files", "richtext", "code"]
+    data: str | None = None
+    language: (
+        Literal["json", "python", "javascript", "html", "css", "xml", "php", "java", "cpp", "sql", "latex", "other"]
+        | None
+    ) = None
+    style: Literal["ternary", "echarts"] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class RecordModuleDeletion:
+    name: str
+
+
+@dataclass(frozen=True, slots=True)
+class RecordValueAddition:
+    module: str
+    value: object = None
+    name: str | None = None
+    value_type: Literal["text", "richtext", "multiline", "number", "date", "time", "file", "bool"] | None = None
+    row: Literal[0, -1] | None = None
+    path: tuple[str, ...] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class RecordFormAttachmentRemoval:
+    attachment: RecordAttachmentRef
+
+
+@dataclass(frozen=True, slots=True)
+class RecordTableAttachmentReplacement:
+    existing: RecordAttachmentRef
+    replacement: StagedRecordAttachment
+
+
+@dataclass(frozen=True, slots=True)
+class RecordFilesAttachmentAppend:
+    module: str
+    attachment: StagedRecordAttachment
+    caption: str | None = None
+    path: tuple[str, ...] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class RecordFilesAttachmentReplacement:
+    existing: RecordAttachmentRef
+    replacement: StagedRecordAttachment
+    caption: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class RecordFilesAttachmentRemoval:
+    attachment: RecordAttachmentRef
+
+
+def _empty_record_attachment_bindings() -> Mapping[str, StagedRecordAttachment]:
+    return {}
+
+
+@dataclass(frozen=True, slots=True)
+class RecordRichTextUpdate:
+    module: str
+    html: str
+    attachments: Mapping[str, StagedRecordAttachment] = field(default_factory=_empty_record_attachment_bindings)
+
+
+@dataclass(frozen=True, slots=True)
+class RecordPatch:
+    value_updates: tuple[RecordValueUpdate, ...] = ()
+    value_deletions: tuple[RecordValueDeletion, ...] = ()
+    module_creations: tuple[RecordModuleCreation, ...] = ()
+    module_deletions: tuple[RecordModuleDeletion, ...] = ()
+    value_additions: tuple[RecordValueAddition, ...] = ()
+    attachment_changes: tuple[
+        RecordFormAttachmentRemoval
+        | RecordTableAttachmentReplacement
+        | RecordFilesAttachmentAppend
+        | RecordFilesAttachmentReplacement
+        | RecordFilesAttachmentRemoval,
+        ...,
+    ] = ()
+    rich_text_updates: tuple[RecordRichTextUpdate, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class RecordVersionSummary:
+    ref: RecordVersionRef
+    locked_at_ms: int
+    modified_at_ms: int
+    locked: bool
+    author_userid: int
+    author_name: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class RecordSignature:
+    signer_userid: int
+    username: str | None
+    photo_signature: str | None
+    signed_at: str | None
+    timestamp_result: str
+    user_result: str
+
+
+@dataclass(frozen=True, slots=True)
+class Record:
+    ref: RecordRef
+    notebook: NotebookRef
+    selected_version: RecordVersionRef | None
+    selected_record_uid: str | None
+    title: str | None
+    keywords: tuple[str, ...] | None
+    modules: tuple[dict[str, object], ...]
+    template_id: int | None
+    modified_at_ms: int
+    author_name: str | None
+    versions: tuple[RecordVersionSummary, ...]
+    current_version: RecordVersionRef | None
+    locked_at_ms: int
+    locked: bool
+    signatures: tuple[RecordSignature, ...]
+    signed: bool
+    owner: bool
+    editable: bool
+    notebook_title: str | None
+    data_server: str
+    notebook_keywords: tuple[object, ...]
+    pdf_enabled: bool
+    template_render_metadata: str
+    template_title: str
+    template_intro: str
+    attachments: tuple[RecordAttachmentRef, ...]
+    content_sha256: str
+
+
+@dataclass(frozen=True, slots=True)
+class RecordUpdateResult:
+    source: RecordLocator
+    before: Record
+    observed_after: Record | None
+    persistence: Literal["persisted", "pending_browser_save", "provider_acknowledged_unclassified"]
+    confirmation: Literal["observed_changed", "observed_unchanged", "pending_browser_save_not_read_back"]
+    requested_operation_count: int
+    provider_message: str
+    atomicity: Literal["provider_unspecified"] = "provider_unspecified"
+    concurrency_control: Literal["client_read_precondition_not_provider_cas"] = (
+        "client_read_precondition_not_provider_cas"
+    )
+    retryable: Literal[False] = False
+
+
+@dataclass(frozen=True, slots=True)
+class RecordCommentAttachmentRef:
+    """Attachment metadata observed in an authorized comment read.
+
+    This reference preserves its record/comment context for correct request
+    construction. It is not a Provider-side authorization credential: current
+    Providers do not verify that the file belongs to that context (PVD-038).
+    """
+
+    source: RecordLocator
+    comment: RecordCommentRef
+    sha256: str = field(repr=False)
+    filename: str
+    size: int
+
+
+@dataclass(frozen=True, slots=True)
+class StagedRecordCommentAttachment:
+    source: RecordLocator
+    binding: UploadBindingRef
+    temporary_file_id: int
+    filename: str
+    size: int
+    sha256: str = field(repr=False)
+    abort_supported: Literal[False] = False
+    binding_user_verified_on_save: Literal[False] = False
+    _temporary_url: str = field(repr=False, compare=False, default="")
+    _canonical_reference: str = field(repr=False, compare=False, default="")
+
+
+def _empty_comment_attachment_bindings() -> Mapping[str, StagedRecordCommentAttachment]:
+    return {}
+
+
+@dataclass(frozen=True, slots=True)
+class RecordCommentDraft:
+    html: str
+    attachments: Mapping[str, StagedRecordCommentAttachment] = field(default_factory=_empty_comment_attachment_bindings)
+
+
+@dataclass(frozen=True, slots=True)
+class RecordComment:
+    source: RecordLocator
+    ref: RecordCommentRef
+    modified_at: str
+    body: str
+    author_name: str | None
+    owned_by_caller: bool
+    attachments: tuple[RecordCommentAttachmentRef, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class RecordComments:
+    source: RecordLocator
+    comments: tuple[RecordComment, ...]
+    ordering: Literal["provider_unspecified"] = "provider_unspecified"
+
+
+@dataclass(frozen=True, slots=True)
+class RecordCommentSaveResult:
+    source: RecordLocator
+    action: Literal["create", "update"]
+    requested_comment: RecordCommentRef | None
+    observed: tuple[RecordComment, ...]
+    confirmation: Literal[
+        "unique_created_comment_observed",
+        "created_comment_identity_ambiguous",
+        "created_comment_not_observed",
+        "updated_comment_observed_matching",
+        "updated_comment_observed_mismatched",
+        "updated_comment_not_observed",
+    ]
+    identity_source: Literal["readback", "unknown"]
+    forwarded: bool
+    provider_returned_identity: Literal[False] = False
+    retryable: Literal[False] = False
+
+
+@dataclass(frozen=True, slots=True)
+class RecordCommentDeleteResult:
+    comment: RecordCommentRef
+    source: RecordLocator
+    confirmation: Literal["not_observed_after_delete", "still_observed_after_delete"]
+    forwarded: bool
+    affected_row_count: None = None
+    retryable: Literal[False] = False
+
+
+@dataclass(frozen=True, slots=True)
+class RelatedRecordIdentity:
+    declared_notebook_id: int | None
+    resolved_notebook_id: int | None
+    record_database_id: int
+    record_uid: str | None
+    notebook_title: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class RecordRelationRef:
+    relation_id: int
+    source: RecordLocator
+
+
+@dataclass(frozen=True, slots=True)
+class RecordRelation:
+    ref: RecordRelationRef
+    target: RelatedRecordIdentity
+    title: str | None
+    summary: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class RecordRelations:
+    relations: tuple[RecordRelation, ...]
+    legacy_comments: tuple[RecordComment, ...]
+    editable: bool
+    ordering: Literal["provider_unspecified"] = "provider_unspecified"
+
+
+@dataclass(frozen=True, slots=True)
+class RecordRelationAddResult:
+    source: RecordLocator
+    target: RecordLocator
+    observed: tuple[RecordRelation, ...]
+    confirmation: Literal["observed_after_add", "not_observed_after_add"]
+    forwarded: bool
+    provider_returned_identity: Literal[False] = False
+    preflight: Literal["client_verified_non_atomic"] = "client_verified_non_atomic"
+    retryable: Literal[False] = False
+
+
+@dataclass(frozen=True, slots=True)
+class RecordRelationDeleteResult:
+    requested: RecordRelation
+    confirmation: Literal["not_observed_after_delete", "still_observed_after_delete"]
+    other_relations_missing_after_write: tuple[RecordRelationRef, ...]
+    forwarded: bool
+    affected_row_count: None = None
+    preflight: Literal["client_verified_non_atomic"] = "client_verified_non_atomic"
+    retryable: Literal[False] = False
+
+
+@dataclass(frozen=True, slots=True)
+class _ParsedAttachment:
+    sha256: str
+    filename: str
+    size: int
+
+
+class _RichTextAttachmentParser(HTMLParser):
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self.attachments: list[_ParsedAttachment] = []
+
+    def handle_starttag(  # pyright: ignore[reportImplicitOverride]
+        self, tag: str, attrs: list[tuple[str, str | None]]
+    ) -> None:
+        target_attribute = "src" if tag.casefold() == "img" else "href" if tag.casefold() == "a" else None
+        if target_attribute is None:
+            return
+        value = next((value for name, value in attrs if name.casefold() == target_attribute), None)
+        if value is None:
+            return
+        attachment = _parse_elnurl(value)
+        if attachment is not None:
+            self.attachments.append(attachment)
+
+
+def _parse_elnurl(value: str) -> _ParsedAttachment | None:
+    match = _ELNURL_PATTERN.fullmatch(value)
+    if match is None:
+        return None
+    filename = unquote(match.group(3))
+    if not filename:
+        return None
+    return _ParsedAttachment(sha256=match.group(1).lower(), filename=filename, size=int(match.group(2)))
+
+
+def _rich_text_attachments(value: str) -> tuple[_ParsedAttachment, ...]:
+    parser = _RichTextAttachmentParser()
+    parser.feed(value)
+    parser.close()
+    return tuple(parser.attachments)
+
+
+def _nested_record_attachments(value: object) -> tuple[_ParsedAttachment, ...]:
+    attachments: list[_ParsedAttachment] = []
+
+    def visit(item: object) -> None:
+        if isinstance(item, str):
+            attachments.extend(_rich_text_attachments(item))
+            return
+        if isinstance(item, list):
+            for child in cast(list[object], item):
+                visit(child)
+            return
+        if not isinstance(item, dict):
+            return
+        mapping = cast(dict[str, object], item)
+        sha256 = mapping.get("hash")
+        filename = mapping.get("filename")
+        size = mapping.get("size")
+        if (
+            isinstance(sha256, str)
+            and _ELNURL_PATTERN.fullmatch(f"elnurl://h={sha256}&s=0&f=x") is not None
+            and isinstance(filename, str)
+            and filename
+            and type(size) is int
+            and size >= 0
+        ):
+            attachments.append(_ParsedAttachment(sha256=sha256.lower(), filename=filename, size=size))
+        for child in mapping.values():
+            visit(child)
+
+    visit(value)
+    return tuple(attachments)
+
+
+def _content_sha256(modules: Sequence[Mapping[str, object]]) -> str:
+    encoded = json.dumps(list(modules), ensure_ascii=False, sort_keys=True, separators=(",", ":")).encode()
+    return hashlib.sha256(encoded).hexdigest()
+
+
+def _contains_native_attachment_reference(value: object) -> bool:
+    if isinstance(value, str):
+        return _NATIVE_ATTACHMENT_PATTERN.search(value) is not None
+    if isinstance(value, Mapping):
+        return any(
+            _contains_native_attachment_reference(item) for item in cast(Mapping[object, object], value).values()
+        )
+    if isinstance(value, (list, tuple)):
+        return any(
+            _contains_native_attachment_reference(item) for item in cast(list[object] | tuple[object, ...], value)
+        )
+    return False
+
+
+def _record_attachment_refs(
+    modules: Sequence[Mapping[str, object]], *, source: RecordLocator, version: RecordVersionRef | None
+) -> tuple[RecordAttachmentRef, ...]:
+    located: list[tuple[_ParsedAttachment, RecordAttachmentLocation]] = []
+
+    def add_structured(
+        value: object,
+        *,
+        kind: Literal["form_file", "table_file", "files_module", "images_module"],
+        module: str,
+        field_name: str | None,
+        position: int,
+    ) -> None:
+        if not isinstance(value, dict):
+            return
+        mapping = cast(dict[str, object], value)
+        sha256 = mapping.get("hash")
+        filename = mapping.get("filename")
+        size = mapping.get("size")
+        if (
+            isinstance(sha256, str)
+            and re.fullmatch(r"[0-9a-f]{64}", sha256) is not None
+            and isinstance(filename, str)
+            and filename
+            and type(size) is int
+            and size >= 0
+        ):
+            located.append(
+                (
+                    _ParsedAttachment(sha256=sha256, filename=filename, size=size),
+                    RecordAttachmentLocation(kind=kind, module=module, field=field_name, position=position),
+                )
+            )
+
+    for module in modules:
+        module_name = module.get("name")
+        module_type = module.get("type")
+        if not isinstance(module_name, str) or not module_name or not isinstance(module_type, str):
+            continue
+        values = module.get("data")
+        if module_type in {"form", "table"} and isinstance(values, list):
+            kind: Literal["form_file", "table_file"] = "form_file" if module_type == "form" else "table_file"
+            for raw_field in cast(list[object], values):
+                if not isinstance(raw_field, dict):
+                    continue
+                field_mapping = cast(dict[str, object], raw_field)
+                field_name = field_mapping.get("name")
+                field_values = field_mapping.get("data")
+                if (
+                    field_mapping.get("type") != "file"
+                    or not isinstance(field_name, str)
+                    or not field_name
+                    or not isinstance(field_values, list)
+                ):
+                    continue
+                for position, value in enumerate(cast(list[object], field_values)):
+                    add_structured(value, kind=kind, module=module_name, field_name=field_name, position=position)
+        elif module_type in {"files", "images"} and isinstance(values, list):
+            file_kind: Literal["files_module", "images_module"] = (
+                "files_module" if module_type == "files" else "images_module"
+            )
+            for position, value in enumerate(cast(list[object], values)):
+                add_structured(value, kind=file_kind, module=module_name, field_name=None, position=position)
+        elif module_type == "richtext" and isinstance(values, str):
+            for position, attachment in enumerate(_rich_text_attachments(values)):
+                located.append(
+                    (
+                        attachment,
+                        RecordAttachmentLocation(kind="richtext", module=module_name, field=None, position=position),
+                    )
+                )
+
+    known_values = {(attachment.sha256, attachment.filename, attachment.size) for attachment, _ in located}
+    unlocated = [
+        attachment
+        for attachment in _nested_record_attachments(list(modules))
+        if (attachment.sha256, attachment.filename, attachment.size) not in known_values
+    ]
+    return tuple(
+        RecordAttachmentRef(
+            source=source,
+            sha256=attachment.sha256,
+            filename=attachment.filename,
+            size=attachment.size,
+            observed_version=version,
+            location=location,
+        )
+        for attachment, location in located
+    ) + tuple(
+        RecordAttachmentRef(
+            source=source,
+            sha256=attachment.sha256,
+            filename=attachment.filename,
+            size=attachment.size,
+            observed_version=version,
+        )
+        for attachment in unlocated
+    )
+
+
+class Records:
+    """Record-oriented Matelab operations."""
+
+    def __init__(self, transport: SessionTransport) -> None:
+        self._transport: SessionTransport = transport
+
+    async def list(
+        self,
+        *,
+        notebook: NotebookRef,
+        date_start: str | None = None,
+        date_end: str | None = None,
+        keywords: Sequence[str] | None = None,
+        content: str | None = None,
+    ) -> RecordCollection:
+        if notebook.title is None:
+            raise MatelabUsageError("Cannot list records for a notebook whose Provider title is null.")
+        try:
+            request = WireListRecordsRequest(
+                eln=notebook.title,
+                user=notebook.owner_userid if notebook.scope == "shared" else None,
+                date_start=date_start if date_start is not None else "",
+                date_end=date_end if date_end is not None else "",
+                keywords=list(keywords) if keywords is not None else [],
+                content=content if content is not None else "",
+            )
+        except ValidationError:
+            raise MatelabUsageError("Record-list filters do not satisfy the Integration Contract.") from None
+        response = await self._transport.request(
+            _LIST_RECORDS, payload=request.model_dump(mode="json", exclude_defaults=True, exclude_none=True)
+        )
+        return RecordCollection(
+            records=tuple(self._record_summary(item) for item in response.items),
+            subtypes=tuple(self._subtype_summary(item) for item in response.subtypes),
+            trash_count=response.trash_num,
+        )
+
+    async def create_blank(
+        self,
+        *,
+        notebook: NotebookRef,
+        title: str,
+        summary: str | None = None,
+        record_uid: str | None = None,
+        path: Sequence[str] | None = None,
+    ) -> BlankRecordCreateResult:
+        notebook_title = self._notebook_title(notebook)
+        requested_uid = record_uid or None
+        try:
+            request = WireCreateRecordRequest(
+                eln=notebook_title,
+                title=title,
+                describe=summary,
+                uid=requested_uid,
+                user=notebook.owner_userid if notebook.scope == "shared" else None,
+                path=list(path) if path is not None else None,
+            )
+        except ValidationError:
+            raise MatelabUsageError("Blank-record input does not satisfy the Integration Contract.") from None
+        _ = await self._transport.request(_CREATE_BLANK_RECORD, payload=request.model_dump(mode="json"))
+        if requested_uid is None:
+            return BlankRecordCreateResult(
+                notebook=notebook,
+                title=title,
+                requested_record_uid=None,
+                observed=None,
+                confirmation="provider_generated_identity_not_returned",
+            )
+        after = await self._verified_list(notebook, "blank-record creation")
+        observed = next((item for item in after.records if item.ref.record_uid == requested_uid), None)
+        return BlankRecordCreateResult(
+            notebook=notebook,
+            title=title,
+            requested_record_uid=requested_uid,
+            observed=observed,
+            confirmation="observed_by_requested_uid" if observed is not None else "not_observed_by_requested_uid",
+        )
+
+    async def import_dataset(
+        self, *, notebook: NotebookRef, template: RecordImportTemplate, items: Sequence[RecordImportItem]
+    ) -> RecordImportResult:
+        notebook_title = self._notebook_title(notebook)
+        selected = tuple(items)
+        if template.template.template_id < 1 or not selected or len(selected) > 100:
+            raise MatelabUsageError("Record import requires a valid template and one through one hundred items.")
+        if len({item.record_uid for item in selected}) != len(selected):
+            raise MatelabUsageError("Imported record UIDs must be distinct within the batch.")
+        payload: dict[str, object] = {
+            "eln": notebook_title,
+            "template": template.title,
+            "dataset": [
+                {
+                    "uid": item.record_uid,
+                    "title": item.title,
+                    "data": dict(item.data),
+                    "keyword": item.keyword,
+                    "path": list(item.path) if item.path is not None else None,
+                }
+                for item in selected
+            ],
+            "user": notebook.owner_userid if notebook.scope == "shared" else None,
+            "template_user": template.owner.userid if template.owner is not None else None,
+        }
+        try:
+            request = WireImportRecordsRequest.model_validate(payload)
+            _ = json.dumps(request.model_dump(mode="json"), ensure_ascii=False)
+        except (ValidationError, TypeError, ValueError):
+            raise MatelabUsageError("Record import dataset does not satisfy the Integration Contract.") from None
+        response = await self._transport.request(_IMPORT_RECORDS, payload=request.model_dump(mode="json"))
+        if response.eln_id != notebook.notebook_id:
+            raise MatelabProtocolError("Matelab returned a different target notebook for the record import.")
+        return RecordImportResult(
+            notebook=notebook,
+            template=template,
+            requested_record_uids=tuple(item.record_uid for item in selected),
+            created_record_database_ids=tuple(item.root for item in response.id),
+            provider_notebook_id=response.eln_id,
+            identity_count_status=(
+                "one_id_per_item"
+                if len(response.id) == len(selected)
+                else "fewer_ids_than_items"
+                if len(response.id) < len(selected)
+                else "more_ids_than_items"
+            ),
+        )
+
+    async def copy(
+        self,
+        source: RecordLocator,
+        *,
+        title: str,
+        target_notebook: NotebookRef | None = None,
+        record_uid: str | None = None,
+    ) -> RecordCopyResult:
+        target = target_notebook or source.notebook
+        _ = self._notebook_title(target)
+        try:
+            request = WireCopyRecordRequest(
+                eln=source.notebook.notebook_id,
+                eln_to=0 if target.notebook_id == source.notebook.notebook_id else target.notebook_id,
+                id=source.record.record_database_id,
+                uid=record_uid,
+                title=title,
+            )
+        except ValidationError:
+            raise MatelabUsageError("Record copy input does not satisfy the Integration Contract.") from None
+        response = await self._transport.request(_COPY_RECORD, payload=request.model_dump(mode="json"))
+        after = await self._verified_list(target, "record copy")
+        observed = next((item for item in after.records if item.ref.record_database_id == response.id), None)
+        if observed is not None and record_uid and observed.ref.record_uid != record_uid:
+            raise MatelabProtocolError("Matelab returned a different UID for the copied record.")
+        return RecordCopyResult(
+            source=source,
+            target_notebook=target,
+            record_database_id=response.id,
+            record=observed.ref if observed is not None else None,
+            observed=observed,
+            forwarded=response.code is WireSuccessCode.int_10,
+            confirmation="observed_by_returned_id" if observed is not None else "returned_id_not_observed",
+        )
+
+    async def delete(self, *, notebook: NotebookRef, records: Sequence[RecordRef]) -> RecordDeleteResult:
+        _ = self._notebook_title(notebook)
+        selected = tuple(records)
+        uids = tuple(record.record_uid for record in selected)
+        if not selected or len(uids) != len(set(uids)):
+            raise MatelabUsageError("Record deletion requires a non-empty set of distinct record UIDs.")
+        try:
+            request = WireDeleteRecordsRequest.model_validate(
+                {
+                    "eln": notebook.title,
+                    "uids": list(uids),
+                    "user": notebook.owner_userid if notebook.scope == "shared" else None,
+                }
+            )
+        except ValidationError:
+            raise MatelabUsageError("Record deletion input does not satisfy the Integration Contract.") from None
+        _ = await self._transport.request(_DELETE_RECORDS, payload=request.model_dump(mode="json"))
+        active, deleted = await self._verified_lifecycle_state(notebook, "record deletion")
+        active_uids = {item.ref.record_uid for item in active.records}
+        deleted_by_identity = {(item.ref.record_database_id, item.ref.record_uid): item.ref for item in deleted.records}
+        still_active = tuple(record for record in selected if record.record_uid in active_uids)
+        no_longer_active = tuple(record for record in selected if record.record_uid not in active_uids)
+        observed_deleted = tuple(
+            deleted_by_identity[(record.record_database_id, record.record_uid)]
+            for record in selected
+            if (record.record_database_id, record.record_uid) in deleted_by_identity
+        )
+        unresolved = tuple(
+            record
+            for record in no_longer_active
+            if (record.record_database_id, record.record_uid) not in deleted_by_identity
+        )
+        return RecordDeleteResult(
+            notebook=notebook,
+            requested=selected,
+            no_longer_active=no_longer_active,
+            still_active=still_active,
+            observed_in_recycle_bin=observed_deleted,
+            unresolved=unresolved,
+        )
+
+    async def restore(self, *, notebook: NotebookRef, records: Sequence[DeletedRecordRef]) -> RecordRestoreResult:
+        _ = self._notebook_title(notebook)
+        selected = tuple(records)
+        ids = tuple(record.record_database_id for record in selected)
+        if not selected or any(record_id < 1 for record_id in ids) or len(ids) != len(set(ids)):
+            raise MatelabUsageError("Record restoration requires distinct positive deleted-record identities.")
+        try:
+            request = WireRestoreRecordsRequest(eln=notebook.notebook_id, ids=json.dumps(ids, separators=(",", ":")))
+        except ValidationError:
+            raise MatelabUsageError("Record restore input does not satisfy the Integration Contract.") from None
+        _ = await self._transport.request(_RESTORE_RECORDS, payload=request.model_dump(mode="json"))
+        active, deleted = await self._verified_lifecycle_state(notebook, "record restoration")
+        active_by_identity = {(item.ref.record_database_id, item.ref.record_uid): item.ref for item in active.records}
+        deleted_identities = {(item.ref.record_database_id, item.ref.record_uid) for item in deleted.records}
+        observed_active = tuple(
+            active_by_identity[(item.record_database_id, item.record_uid)]
+            for item in selected
+            if (item.record_database_id, item.record_uid) in active_by_identity
+        )
+        still_deleted = tuple(
+            item for item in selected if (item.record_database_id, item.record_uid) in deleted_identities
+        )
+        observed_identities = {(item.record_database_id, item.record_uid) for item in observed_active}
+        unresolved = tuple(
+            item
+            for item in selected
+            if (item.record_database_id, item.record_uid) not in observed_identities
+            and (item.record_database_id, item.record_uid) not in deleted_identities
+        )
+        return RecordRestoreResult(
+            notebook=notebook,
+            requested=selected,
+            observed_active=observed_active,
+            still_deleted=still_deleted,
+            unresolved=unresolved,
+        )
+
+    async def upload_attachment(
+        self,
+        source: RecordLocator,
+        *,
+        filename: str,
+        content: IO[bytes] | bytes,
+        size: int,
+        sha256: str,
+        binding: UploadBindingRef | None = None,
+        content_type: str = "application/octet-stream",
+    ) -> StagedRecordAttachment:
+        notebook_title = self._notebook_title(source.notebook)
+        selected_binding = binding or UploadBindingRef.new()
+        self._validate_upload_metadata(
+            filename=filename, content=content, size=size, sha256=sha256, content_type=content_type
+        )
+        try:
+            request = WireUploadAttachmentRequest.model_validate(
+                {
+                    "eln": notebook_title,
+                    "user": source.notebook.owner_userid if source.notebook.scope == "shared" else None,
+                    "uid": source.record.record_uid,
+                    "name": selected_binding.uid,
+                    "hash": sha256,
+                    "last": 1,
+                    "file": b"validation-placeholder",
+                }
+            )
+        except ValidationError:
+            raise MatelabUsageError("Record attachment upload does not satisfy the Integration Contract.") from None
+        response = await self._transport.request(
+            _UPLOAD_RECORD_ATTACHMENT,
+            payload=request.model_dump(mode="json", exclude={"file"}, exclude_none=True),
+            files={"file": (filename, content, content_type)},
+        )
+        if (
+            response.hash.root != sha256
+            or response.size != size
+            or response.filename != filename
+            or response.name != selected_binding.uid
+        ):
+            raise MatelabProtocolError(
+                "Matelab staged the record attachment but returned different upload metadata; "
+                + "the temporary upload may remain."
+            )
+        return StagedRecordAttachment(
+            source=source,
+            temporary_file_id=response.id,
+            binding=selected_binding,
+            filename=response.filename,
+            size=response.size,
+            sha256=response.hash.root,
+        )
+
+    async def update(
+        self,
+        source: RecordLocator,
+        patch: RecordPatch,
+        *,
+        expected_content_sha256: str | None = None,
+        password: str | None = None,
+    ) -> RecordUpdateResult:
+        before = await self.read(notebook=source.notebook, record=source.record)
+        if expected_content_sha256 is not None:
+            if re.fullmatch(r"[0-9a-f]{64}", expected_content_sha256) is None:
+                raise MatelabUsageError("Expected record content fingerprint must be a lowercase SHA-256.")
+            if before.content_sha256 != expected_content_sha256:
+                raise MatelabUsageError(
+                    "Record content changed before the update; this client-side precondition is not Provider CAS."
+                )
+        mutation_payload, operation_count = self._record_patch_payload(source, before, patch)
+        try:
+            request = WireUpdateRecordRequest.model_validate(
+                {
+                    "eln": self._notebook_title(source.notebook),
+                    "uid": source.record.record_uid,
+                    "user": source.notebook.owner_userid if source.notebook.scope == "shared" else None,
+                    "password": password,
+                    **mutation_payload,
+                }
+            )
+            _ = json.dumps(request.model_dump(mode="json", by_alias=True), ensure_ascii=False)
+        except (ValidationError, TypeError, ValueError):
+            raise MatelabUsageError("Record patch does not satisfy the Integration Contract.") from None
+        response = await self._transport.request(
+            _UPDATE_RECORD, payload=request.model_dump(mode="json", by_alias=True, exclude_none=True)
+        )
+        message = response.msg.strip()
+        if message in _COLLABORATION_UPDATE_MESSAGES:
+            return RecordUpdateResult(
+                source=source,
+                before=before,
+                observed_after=None,
+                persistence="pending_browser_save",
+                confirmation="pending_browser_save_not_read_back",
+                requested_operation_count=operation_count,
+                provider_message=response.msg,
+            )
+        after = await self._verified_read(source, "record update")
+        return RecordUpdateResult(
+            source=source,
+            before=before,
+            observed_after=after,
+            persistence="persisted" if message in _DATABASE_UPDATE_MESSAGES else "provider_acknowledged_unclassified",
+            confirmation="observed_changed" if after.content_sha256 != before.content_sha256 else "observed_unchanged",
+            requested_operation_count=operation_count,
+            provider_message=response.msg,
+        )
+
+    async def export(self, records: Sequence[RecordLocator]) -> RecordExport:
+        try:
+            request = WireExportRecordsRequest.model_validate(
+                {
+                    "uids": [
+                        {"uid": record.record.record_uid, "eln": self._notebook_selector(record.notebook)}
+                        for record in records
+                    ]
+                }
+            )
+        except ValidationError:
+            raise MatelabUsageError("Record export selection does not satisfy the Integration Contract.") from None
+        response = await self._transport.request(_EXPORT_RECORDS, payload=request.model_dump(mode="json"))
+        return RecordExport(
+            records=tuple(
+                ExportedRecord(
+                    ref=RecordRef(record_database_id=item.id, record_uid=item.uid),
+                    notebook_title=item.eln_name,
+                    title=item.title,
+                    summary=item.comm,
+                    data=tuple(cast(list[object], item.data)),
+                )
+                for item in response.dataset
+            ),
+            forwarded=response.code is WireSuccessCode.int_10,
+        )
+
+    async def search(
+        self,
+        *,
+        extractions: Sequence[RecordFieldExtraction],
+        notebooks: Sequence[NotebookRef] | None = None,
+        date_start: str | None = None,
+        date_end: str | None = None,
+        keywords: Sequence[str] | None = None,
+    ) -> RecordSearchResult:
+        aliases = tuple(extraction.alias for extraction in extractions)
+        if len(aliases) != len(set(aliases)) or any(alias in _SEARCH_RESERVED_FIELDS for alias in aliases):
+            raise MatelabUsageError("Record extraction aliases must be unique and cannot replace identity fields.")
+        try:
+            request = WireSearchRecordsRequest.model_validate(
+                {
+                    "eln": [self._notebook_selector(notebook) for notebook in notebooks or ()],
+                    "requests": [
+                        {"uid": extraction.alias, "path": list(extraction.path)} for extraction in extractions
+                    ],
+                    "date_start": date_start,
+                    "date_end": date_end,
+                    "keywords": list(keywords) if keywords is not None else None,
+                }
+            )
+        except ValidationError:
+            raise MatelabUsageError("Record search input does not satisfy the Integration Contract.") from None
+        response = await self._transport.request(
+            _SEARCH_RECORDS, payload=request.model_dump(mode="json", exclude_defaults=True, exclude_none=True)
+        )
+        matches: list[RecordSearchMatch] = []
+        for item in response.data:
+            extra = cast(dict[str, object], item.model_extra or {})
+            extracted = {alias: extra[alias] for alias in aliases if alias in extra}
+            matches.append(
+                RecordSearchMatch(
+                    ref=RecordRef(record_database_id=item.id, record_uid=item.uid),
+                    notebook_id=item.eln_id,
+                    notebook_title=item.eln_name,
+                    title=item.title,
+                    extracted=MappingProxyType(extracted),
+                    missing_extractions=tuple(alias for alias in aliases if alias not in extra),
+                )
+            )
+        return RecordSearchResult(matches=tuple(matches), forwarded=response.code is WireSuccessCode.int_10)
+
+    async def list_public(self, notebook: PublicNotebookRef) -> PublicRecordCollection:
+        try:
+            request = WirePublicRecordListRequest(eln=notebook.title)
+        except ValidationError:
+            raise MatelabUsageError("Public notebook selector does not satisfy the Integration Contract.") from None
+        response = await self._transport.request(_LIST_PUBLIC_RECORDS, payload=request.model_dump(mode="json"))
+        return PublicRecordCollection(
+            notebook=notebook,
+            records=tuple(
+                PublicRecordSummary(
+                    ref=PublicRecordRef(
+                        public_entry_id=item.id,
+                        source_notebook_id=item.eln_id,
+                        source_record_database_id=item.item_id,
+                        record_uid=item.uid,
+                    ),
+                    title=item.title,
+                    summary=item.comm,
+                    locked=item.locked,
+                    source_notebook_title=item.eln_name,
+                    owner=UserRef(userid=item.userid) if item.userid is not None and item.userid > 0 else None,
+                    owner_name=item.username,
+                    owner_email=item.email,
+                    owned_by_caller=item.owner,
+                )
+                for item in response.items
+            ),
+        )
+
+    async def page(
+        self,
+        notebook: NotebookRef,
+        *,
+        page: int = 1,
+        subtype_id: int = -1,
+        date_start: str = "",
+        date_end: str = "",
+        content: str = "",
+        keywords: Sequence[str] = (),
+    ) -> RecordPage:
+        encoded_keywords = json.dumps(list(keywords), ensure_ascii=False, separators=(",", ":")) if keywords else ""
+        try:
+            request = WireRecordPageQuery(
+                eln=notebook.notebook_id,
+                page=page,
+                page_size=0,
+                subtype=subtype_id,
+                default=WirePageDefault.integer_1,
+                order_desc=WireOrderDesc.integer_1,
+                ds=date_start,
+                de=date_end,
+                content=content,
+                keywords=encoded_keywords,
+            )
+        except ValidationError:
+            raise MatelabUsageError("Record-page filters do not satisfy the Integration Contract.") from None
+        response = await self._transport.request(_LIST_RECORD_PAGE, payload=request.model_dump(mode="json"))
+        if response.eln.id != notebook.notebook_id:
+            raise MatelabProtocolError("Matelab returned a different notebook for the record page.")
+        matching_ids = tuple(item.root for item in response.ids)
+        effective_page_size = response.eln.page_size
+        return RecordPage(
+            records=tuple(self._record_summary(item) for item in response.items),
+            subtypes=tuple(self._subtype_summary(item) for item in response.subtypes),
+            context=RecordPageContext(
+                notebook=notebook,
+                notebook_title=response.eln.eln_text,
+                owner_name=response.eln.username,
+                template_id=response.eln.template_id,
+                data_server=response.eln.server,
+                permissions=RecordPagePermissions(
+                    editable=response.eln.editable,
+                    can_create=response.eln.create,
+                    can_delete=response.eln.delete,
+                    can_manage_subtypes=response.eln.subtype,
+                    can_read_audit=response.eln.readlog,
+                    can_manage_users=response.eln.user,
+                    can_sign=response.eln.sign,
+                ),
+                effective_page_size=effective_page_size,
+            ),
+            page=response.page,
+            total_count=len(matching_ids),
+            matching_record_database_ids=matching_ids,
+            trash_count=response.trash_num,
+            has_more=response.page * effective_page_size < len(matching_ids),
+            keywords=tuple(cast(list[object], response.keywords)),
+        )
+
+    async def recycle_bin(self, notebook: NotebookRef, *, page: int = 1, page_size: int = 24) -> DeletedRecordPage:
+        if not 10 <= page_size <= 256:
+            raise MatelabUsageError("Recycle-bin page size must be between 10 and 256.")
+        try:
+            request = WireDeletedRecordPageQuery(eln=notebook.notebook_id, page=page, page_size=page_size)
+        except ValidationError:
+            raise MatelabUsageError("Recycle-bin page input does not satisfy the Integration Contract.") from None
+        response = await self._transport.request(_LIST_DELETED_RECORDS, payload=request.model_dump(mode="json"))
+        if response.eln.id != notebook.notebook_id:
+            raise MatelabProtocolError("Matelab returned a different notebook for the recycle bin.")
+        return DeletedRecordPage(
+            notebook=notebook,
+            records=tuple(
+                DeletedRecordSummary(
+                    ref=DeletedRecordRef(record_database_id=item.id, record_uid=item.sn),
+                    title=item.title,
+                    summary=item.comm,
+                    created_at=item.datetime_create,
+                    modified_at=item.datetime_modify,
+                    deleted_at=item.deleted_dtime,
+                )
+                for item in response.items
+            ),
+            page=response.page,
+            requested_page_size=request.page_size,
+            total_count=response.count,
+            has_more=response.page * request.page_size < response.count,
+            forwarded=response.code is WireSuccessCode.int_10,
+        )
+
+    async def relations(self, *, notebook: NotebookRef, record: RecordRef) -> RecordRelations:
+        try:
+            request = WireRecordRelationsQuery(eln=notebook.notebook_id, item_id=record.record_database_id)
+        except ValidationError:
+            raise MatelabUsageError("Record relation source does not satisfy the Integration Contract.") from None
+        response = await self._transport.request(_LIST_RELATIONS, payload=request.model_dump(mode="json"))
+        source = RecordLocator(notebook=notebook, record=record)
+        return RecordRelations(
+            relations=tuple(
+                RecordRelation(
+                    ref=RecordRelationRef(relation_id=item.id, source=source),
+                    target=RelatedRecordIdentity(
+                        declared_notebook_id=item.related_eln,
+                        resolved_notebook_id=item.eln_id,
+                        record_database_id=item.related_id,
+                        record_uid=item.uid,
+                        notebook_title=item.eln,
+                    ),
+                    title=item.title,
+                    summary=item.comm,
+                )
+                for item in response.items
+            ),
+            legacy_comments=tuple(self._comment(item, source=source) for item in response.more),
+            editable=response.editable,
+        )
+
+    async def add_relation(self, *, source: RecordLocator, target: RecordLocator) -> RecordRelationAddResult:
+        source_record = await self.read(notebook=source.notebook, record=source.record)
+        source_relations = await self.relations(notebook=source.notebook, record=source.record)
+        if not source_relations.editable:
+            raise MatelabUsageError("The selected source record is not currently editable.")
+        target_record = (
+            source_record if target == source else await self.read(notebook=target.notebook, record=target.record)
+        )
+        if source_record.data_server != target_record.data_server:
+            raise MatelabUsageError(
+                "Record relation endpoints resolve to different data servers; Provider validation is insufficient."
+            )
+        try:
+            request = WireAddRelationRequest(
+                eln_id=source.notebook.notebook_id,
+                item_id=source.record.record_database_id,
+                related_eln=target.notebook.notebook_id,
+                related_id=target.record.record_database_id,
+            )
+        except ValidationError:
+            raise MatelabUsageError("Record relation endpoints do not satisfy the Integration Contract.") from None
+        response = await self._transport.request(_ADD_RELATION, payload=request.model_dump(mode="json"))
+        after = await self._verified_relations(source, "record relation addition")
+        observed = tuple(
+            relation
+            for relation in after.relations
+            if relation.target.declared_notebook_id == target.notebook.notebook_id
+            and relation.target.resolved_notebook_id == target.notebook.notebook_id
+            and relation.target.record_database_id == target.record.record_database_id
+            and relation.target.record_uid == target.record.record_uid
+        )
+        return RecordRelationAddResult(
+            source=source,
+            target=target,
+            observed=observed,
+            confirmation="observed_after_add" if observed else "not_observed_after_add",
+            forwarded=response.code is WireSuccessCode.int_10,
+        )
+
+    async def delete_relation(self, relation: RecordRelation) -> RecordRelationDeleteResult:
+        source = relation.ref.source
+        before = await self.relations(notebook=source.notebook, record=source.record)
+        if not before.editable:
+            raise MatelabUsageError("The selected source record is not currently editable.")
+        current = next((item for item in before.relations if item.ref == relation.ref), None)
+        if current is None or current.target != relation.target:
+            raise MatelabUsageError("The selected relation is no longer present with the observed target identity.")
+        colliding_targets = tuple(
+            item
+            for item in before.relations
+            if item.ref != relation.ref
+            and item.target.record_database_id == relation.target.record_database_id
+            and item.target.declared_notebook_id != relation.target.declared_notebook_id
+        )
+        if colliding_targets:
+            raise MatelabUsageError(
+                "Relation deletion is unsafe because the Provider ignores target notebook identity (PVD-020)."
+            )
+        try:
+            request = WireDeleteRelationRequest(
+                eln=source.notebook.notebook_id,
+                item_id=source.record.record_database_id,
+                related_id=relation.target.record_database_id,
+            )
+        except ValidationError:
+            raise MatelabUsageError("Record relation identity does not satisfy the Integration Contract.") from None
+        response = await self._transport.request(_DELETE_RELATION, payload=request.model_dump(mode="json"))
+        after = await self._verified_relations(source, "record relation deletion")
+        remaining_refs = {item.ref for item in after.relations}
+        other_missing = tuple(
+            item.ref for item in before.relations if item.ref != relation.ref and item.ref not in remaining_refs
+        )
+        return RecordRelationDeleteResult(
+            requested=relation,
+            confirmation=(
+                "still_observed_after_delete" if relation.ref in remaining_refs else "not_observed_after_delete"
+            ),
+            other_relations_missing_after_write=other_missing,
+            forwarded=response.code is WireSuccessCode.int_10,
+        )
+
+    async def comments(self, *, notebook: NotebookRef, record: RecordRef) -> RecordComments:
+        try:
+            request = WireRecordCommentsQuery(eln=notebook.notebook_id, item_id=record.record_database_id)
+        except ValidationError:
+            raise MatelabUsageError("Record comment source does not satisfy the Integration Contract.") from None
+        response = await self._transport.request(_LIST_COMMENTS, payload=request.model_dump(mode="json"))
+        source = RecordLocator(notebook=notebook, record=record)
+        return RecordComments(
+            source=source, comments=tuple(self._comment(item, source=source) for item in response.mores)
+        )
+
+    async def upload_comment_attachment(
+        self,
+        source: RecordLocator,
+        *,
+        filename: str,
+        content: IO[bytes] | bytes,
+        size: int,
+        sha256: str,
+        binding: UploadBindingRef | None = None,
+        content_type: str = "application/octet-stream",
+    ) -> StagedRecordCommentAttachment:
+        selected_binding = binding or UploadBindingRef.new()
+        self._validate_upload_metadata(
+            filename=filename, content=content, size=size, sha256=sha256, content_type=content_type
+        )
+        try:
+            request = WireUploadRecordCommentAttachmentRequest.model_validate(
+                {
+                    "uid": selected_binding.uid,
+                    "eln": source.notebook.notebook_id,
+                    "i": source.record.record_database_id,
+                    "upload": b"validation-placeholder",
+                }
+            )
+        except ValidationError:
+            raise MatelabUsageError(
+                "Record-comment attachment upload does not satisfy the Integration Contract."
+            ) from None
+        response = await self._transport.request(
+            _UPLOAD_COMMENT_ATTACHMENT,
+            payload=request.model_dump(mode="json", exclude={"upload"}),
+            files={"upload": (filename, content, content_type)},
+        )
+        returned_notebook_id, temporary_id, returned_sha256, returned_size, returned_filename, canonical_reference = (
+            self._parse_comment_upload_query(response.query)
+        )
+        if (
+            returned_notebook_id != source.notebook.notebook_id
+            or response.filename != filename
+            or returned_filename != filename
+            or returned_sha256 != sha256
+            or returned_size != size
+        ):
+            raise MatelabProtocolError(
+                "Matelab staged the comment attachment but returned different upload metadata; "
+                + "the temporary upload cannot be aborted through this Contract."
+            )
+        return StagedRecordCommentAttachment(
+            source=source,
+            binding=selected_binding,
+            temporary_file_id=temporary_id,
+            filename=filename,
+            size=size,
+            sha256=sha256,
+            _temporary_url=self._transport.absolute_url(response.path, response.query),
+            _canonical_reference=canonical_reference,
+        )
+
+    async def create_comment(self, source: RecordLocator, draft: RecordCommentDraft) -> RecordCommentSaveResult:
+        before = await self.comments(notebook=source.notebook, record=source.record)
+        wire_html, canonical_html, binding_uid = self._render_comment_draft(source, draft)
+        response = await self._save_comment_request(
+            source=source, comment_id=0, html=wire_html, binding_uid=binding_uid
+        )
+        after = await self._verified_comments(source, "record comment creation")
+        previous_ids = {comment.ref.comment_id for comment in before.comments}
+        observed = tuple(
+            comment
+            for comment in after.comments
+            if comment.ref.comment_id not in previous_ids and comment.owned_by_caller and comment.body == canonical_html
+        )
+        if len(observed) == 1:
+            confirmation: Literal[
+                "unique_created_comment_observed", "created_comment_identity_ambiguous", "created_comment_not_observed"
+            ] = "unique_created_comment_observed"
+        elif observed:
+            confirmation = "created_comment_identity_ambiguous"
+        else:
+            confirmation = "created_comment_not_observed"
+        return RecordCommentSaveResult(
+            source=source,
+            action="create",
+            requested_comment=None,
+            observed=observed,
+            confirmation=confirmation,
+            identity_source="readback" if len(observed) == 1 else "unknown",
+            forwarded=response.code is WireSuccessCode.int_10,
+        )
+
+    async def update_comment(self, comment: RecordComment, draft: RecordCommentDraft) -> RecordCommentSaveResult:
+        source = comment.source
+        before = await self.comments(notebook=source.notebook, record=source.record)
+        current = next((item for item in before.comments if item.ref == comment.ref), None)
+        if current is None or not current.owned_by_caller:
+            raise MatelabUsageError("Only a currently observed caller-owned comment can be updated.")
+        wire_html, canonical_html, binding_uid = self._render_comment_draft(source, draft)
+        response = await self._save_comment_request(
+            source=source, comment_id=comment.ref.comment_id, html=wire_html, binding_uid=binding_uid
+        )
+        after = await self._verified_comments(source, "record comment update")
+        observed = tuple(item for item in after.comments if item.ref == comment.ref)
+        confirmation: Literal[
+            "updated_comment_observed_matching", "updated_comment_observed_mismatched", "updated_comment_not_observed"
+        ]
+        if not observed:
+            confirmation = "updated_comment_not_observed"
+        elif observed[0].body == canonical_html:
+            confirmation = "updated_comment_observed_matching"
+        else:
+            confirmation = "updated_comment_observed_mismatched"
+        return RecordCommentSaveResult(
+            source=source,
+            action="update",
+            requested_comment=comment.ref,
+            observed=observed,
+            confirmation=confirmation,
+            identity_source="readback" if observed else "unknown",
+            forwarded=response.code is WireSuccessCode.int_10,
+        )
+
+    async def delete_comment(self, comment: RecordComment) -> RecordCommentDeleteResult:
+        source = comment.source
+        before = await self.comments(notebook=source.notebook, record=source.record)
+        current = next((item for item in before.comments if item.ref == comment.ref), None)
+        if current is None or not current.owned_by_caller:
+            raise MatelabUsageError("Only a currently observed caller-owned comment can be deleted.")
+        try:
+            request = WireDeleteRecordCommentRequest(
+                eln=source.notebook.notebook_id, item_id=source.record.record_database_id, id=comment.ref.comment_id
+            )
+        except ValidationError:
+            raise MatelabUsageError("Record comment identity does not satisfy the Integration Contract.") from None
+        response = await self._transport.request(
+            _DELETE_COMMENT, files=multipart_fields(request.model_dump(mode="json"))
+        )
+        after = await self._verified_comments(source, "record comment deletion")
+        still_observed = any(item.ref == comment.ref for item in after.comments)
+        return RecordCommentDeleteResult(
+            comment=comment.ref,
+            source=source,
+            confirmation="still_observed_after_delete" if still_observed else "not_observed_after_delete",
+            forwarded=response.code is WireSuccessCode.int_10,
+        )
+
+    async def download_attachment(
+        self, attachment: RecordAttachmentRef, *, byte_range: ByteRange | None = None
+    ) -> DownloadStream:
+        try:
+            request = WireDownloadRecordAttachmentQuery.model_validate(
+                {
+                    "eln": attachment.source.notebook.notebook_id,
+                    "i": attachment.source.record.record_database_id,
+                    "u": attachment.source.record.record_uid,
+                    "h": attachment.sha256,
+                    "f": attachment.filename,
+                    "s": attachment.size,
+                    "c": 0,
+                    "thumb": 0,
+                }
+            )
+        except ValidationError:
+            raise MatelabUsageError("Record attachment reference does not satisfy the Integration Contract.") from None
+        return await self._transport.stream(
+            _DOWNLOAD_RECORD_ATTACHMENT,
+            payload=request.model_dump(mode="json"),
+            range_header=byte_range.to_header() if byte_range is not None else None,
+        )
+
+    async def download_comment_attachment(
+        self, attachment: RecordCommentAttachmentRef, *, byte_range: ByteRange | None = None
+    ) -> DownloadStream:
+        """Download an observed comment attachment despite Provider issue PVD-038.
+
+        The SDK preserves the source notebook, record, and comment association,
+        but the current Provider only authorizes the supplied notebook and does
+        not independently verify that the attachment belongs to it.
+        """
+        try:
+            request = WireDownloadRecordCommentAttachmentQuery.model_validate(
+                {
+                    "eln": attachment.source.notebook.notebook_id,
+                    "i": attachment.comment.comment_id,
+                    "h": attachment.sha256,
+                    "s": attachment.size,
+                    "f": attachment.filename,
+                }
+            )
+        except ValidationError:
+            raise MatelabUsageError(
+                "Record-comment attachment reference does not satisfy the Integration Contract."
+            ) from None
+        return await self._transport.stream(
+            _DOWNLOAD_COMMENT_ATTACHMENT,
+            payload=request.model_dump(mode="json"),
+            range_header=byte_range.to_header() if byte_range is not None else None,
+        )
+
+    async def read(
+        self, *, notebook: NotebookRef, record: RecordRef, version: RecordVersionRef | None = None
+    ) -> Record:
+        if version is not None and (
+            version.notebook_id != notebook.notebook_id
+            or version.record_database_id != record.record_database_id
+            or version.record_uid != record.record_uid
+        ):
+            raise MatelabUsageError("Record version ref does not belong to the selected notebook and record.")
+        if version is not None:
+            current = await self.read(notebook=notebook, record=record)
+            if version not in (item.ref for item in current.versions):
+                raise MatelabUsageError("Record version is no longer present in the current modify_log.")
+        try:
+            request = WireReadRecordQuery(
+                eln=notebook.notebook_id,
+                id=record.record_database_id,
+                version=version.version_id if version is not None else 0,
+            )
+        except ValidationError:
+            raise MatelabUsageError("Record identity does not satisfy the Integration Contract.") from None
+        response = await self._transport.request(
+            _READ_RECORD, payload=request.model_dump(mode="json", exclude_defaults=True, exclude_none=True)
+        )
+        if response.eln_id != notebook.notebook_id or response.item_id != record.record_database_id:
+            raise MatelabProtocolError("Matelab returned a different notebook or record identity.")
+        if version is None and response.uid != record.record_uid:
+            raise MatelabProtocolError("Matelab returned a different record UID.")
+
+        versions = tuple(
+            RecordVersionSummary(
+                ref=RecordVersionRef(
+                    notebook_id=notebook.notebook_id,
+                    record_database_id=record.record_database_id,
+                    record_uid=record.record_uid,
+                    version_id=item.id,
+                ),
+                locked_at_ms=item.datetime_locked,
+                modified_at_ms=item.datetime_modify,
+                locked=bool(item.locked),
+                author_userid=item.userid,
+                author_name=item.username,
+            )
+            for item in response.modify_log
+        )
+        current_version = next((item.ref for item in versions if item.ref.version_id == response.current_version), None)
+        modules = tuple(cast(dict[str, object], item.model_dump(mode="json")) for item in response.modules)
+        source = RecordLocator(notebook=notebook, record=record)
+        return Record(
+            ref=record,
+            notebook=notebook,
+            selected_version=version,
+            selected_record_uid=response.uid,
+            title=response.title,
+            keywords=tuple(response.keywords) if response.keywords is not None else None,
+            modules=modules,
+            template_id=response.template_id,
+            modified_at_ms=response.datetime_modify,
+            author_name=response.username,
+            versions=versions,
+            current_version=current_version,
+            locked_at_ms=response.datetime_locked,
+            locked=response.locked,
+            signatures=tuple(
+                RecordSignature(
+                    signer_userid=item.userid,
+                    username=item.username,
+                    photo_signature=item.photo_sign,
+                    signed_at=item.datetime_sign,
+                    timestamp_result=item.timestamp_result,
+                    user_result=item.user_result,
+                )
+                for item in response.signs
+            ),
+            signed=response.signed,
+            owner=response.owner,
+            editable=response.editable,
+            notebook_title=response.eln_text,
+            data_server=response.eln_server,
+            notebook_keywords=tuple(cast(list[object], response.keyword_eln)),
+            pdf_enabled=response.pdf_enable,
+            template_render_metadata=response.template_show,
+            template_title=response.template_text,
+            template_intro=response.template_intro,
+            attachments=_record_attachment_refs(modules, source=source, version=version),
+            content_sha256=_content_sha256(modules),
+        )
+
+    def _record_patch_payload(
+        self, source: RecordLocator, before: Record, patch: RecordPatch
+    ) -> tuple[dict[str, object], int]:
+        modules: dict[str, Mapping[str, object]] = {}
+        for module in before.modules:
+            name = module.get("name")
+            if not isinstance(name, str) or not name or name in modules:
+                raise MatelabUsageError("Current record modules do not have unique non-empty names.")
+            modules[name] = module
+
+        modify: list[dict[str, object]] = []
+        delete_values: list[dict[str, object]] = []
+        create_modules: list[dict[str, object]] = []
+        delete_modules: list[dict[str, object]] = []
+        add_values: list[dict[str, object]] = []
+        claimed_paths: set[tuple[str | int, ...]] = set()
+        used_staged: set[tuple[int, str]] = set()
+
+        def claim(path: tuple[str | int, ...]) -> None:
+            if path in claimed_paths:
+                raise MatelabUsageError("A record patch cannot mutate the same path more than once.")
+            claimed_paths.add(path)
+
+        for update in patch.value_updates:
+            self._validate_nonattachment_path(update.path, modules)
+            if update.value is None:
+                raise MatelabUsageError("Record value replacement cannot use null; use a deletion operation.")
+            if _contains_native_attachment_reference(update.value):
+                raise MatelabUsageError("Provider-native attachment references require a staged attachment object.")
+            claim(update.path)
+            modify.append({"path": list(update.path), "data": update.value})
+
+        for deletion in patch.value_deletions:
+            self._validate_nonattachment_path(deletion.path, modules)
+            claim(deletion.path)
+            delete_values.append({"path": list(deletion.path)})
+
+        created_types: dict[str, str] = {}
+        for creation in patch.module_creations:
+            if creation.name in modules or creation.name in created_types:
+                raise MatelabUsageError("A record patch cannot create an existing or duplicate module name.")
+            if creation.module_type == "code" and creation.language is None:
+                raise MatelabUsageError("A new code module requires a language.")
+            if creation.data is not None and _ATTACHMENT_MARKER_PATTERN.search(creation.data):
+                raise MatelabUsageError(
+                    "New rich-text attachments must use a dedicated rich-text update after the module exists."
+                )
+            if creation.data is not None and _contains_native_attachment_reference(creation.data):
+                raise MatelabUsageError("Provider-native attachment references require a staged attachment object.")
+            created_types[creation.name] = creation.module_type
+            create_modules.append(
+                {
+                    "name": creation.name,
+                    "type": creation.module_type,
+                    "data": creation.data,
+                    "language": creation.language,
+                    "style": creation.style,
+                }
+            )
+
+        deleted_names: set[str] = set()
+        for deletion in patch.module_deletions:
+            if deletion.name in deleted_names or deletion.name not in modules:
+                raise MatelabUsageError("A record patch can delete each existing module at most once.")
+            if any(
+                attachment.location is not None and attachment.location.module == deletion.name
+                for attachment in before.attachments
+            ):
+                raise MatelabUsageError(
+                    "A module containing attachments cannot be deleted through the safe record patch interface."
+                )
+            deleted_names.add(deletion.name)
+            delete_modules.append({"name": deletion.name})
+
+        for addition in patch.value_additions:
+            module_type = self._module_type(addition.module, modules, created_types)
+            if module_type in {"files", "images", "richtext"} or addition.value_type == "file":
+                raise MatelabUsageError("Attachment-bearing additions require a dedicated attachment operation.")
+            if (
+                addition.name is not None
+                and module_type in {"form", "table"}
+                and self._module_field_type(modules.get(addition.module), addition.name) == "file"
+            ):
+                raise MatelabUsageError("File fields require a dedicated attachment operation.")
+            if _contains_native_attachment_reference(addition.value):
+                raise MatelabUsageError("Provider-native attachment references require a staged attachment object.")
+            add_values.append(
+                {
+                    "module": addition.module,
+                    "name": addition.name,
+                    "type": addition.value_type,
+                    "row": addition.row,
+                    "data": addition.value,
+                    "path": list(addition.path) if addition.path is not None else None,
+                }
+            )
+
+        for change in patch.attachment_changes:
+            if isinstance(change, RecordFormAttachmentRemoval):
+                current = self._current_attachment(source, before, change.attachment)
+                location = current.location
+                if location is None or location.kind != "form_file" or location.field is None:
+                    raise MatelabUsageError("Form attachment removal requires an observed form-file occurrence.")
+                if (
+                    sum(
+                        isinstance(other, RecordFormAttachmentRemoval)
+                        and other.attachment.location is not None
+                        and other.attachment.location.module == location.module
+                        and other.attachment.location.field == location.field
+                        for other in patch.attachment_changes
+                    )
+                    > 1
+                ):
+                    raise MatelabUsageError(
+                        "Remove multiple form-file occurrences in separate read/patch cycles to avoid index shifts."
+                    )
+                path = (location.module, location.field, location.position)
+                claim(path)
+                delete_values.append({"path": list(path)})
+                continue
+
+            if isinstance(change, RecordTableAttachmentReplacement):
+                current = self._current_attachment(source, before, change.existing)
+                location = current.location
+                if location is None or location.kind != "table_file" or location.field is None:
+                    raise MatelabUsageError("Table attachment replacement requires an observed table-file occurrence.")
+                if any(
+                    deletion.path
+                    and deletion.path[0] == location.module
+                    and isinstance(deletion.path[1] if len(deletion.path) > 1 else None, int)
+                    for deletion in patch.value_deletions
+                ):
+                    raise MatelabUsageError(
+                        "Table-row deletion and table-file replacement require separate read/patch cycles."
+                    )
+                self._claim_staged_attachment(source, change.replacement, used_staged)
+                path = (location.module, location.field, location.position)
+                claim(path)
+                modify.append({"path": list(path), "data": self._native_attachment_ref(change.replacement)})
+                continue
+
+            if isinstance(change, RecordFilesAttachmentAppend):
+                if self._module_type(change.module, modules, created_types) != "files":
+                    raise MatelabUsageError("Files attachment append requires a canonical files module.")
+                self._claim_staged_attachment(source, change.attachment, used_staged)
+                add_values.append(
+                    {
+                        "module": change.module,
+                        "data": {"file": self._native_attachment_ref(change.attachment), "text": change.caption},
+                        "path": list(change.path) if change.path is not None else None,
+                    }
+                )
+                continue
+
+            if isinstance(change, RecordFilesAttachmentReplacement):
+                current = self._current_attachment(source, before, change.existing)
+                location = current.location
+                if location is None or location.kind != "files_module":
+                    raise MatelabUsageError(
+                        "Files attachment replacement requires an observed canonical files-module occurrence."
+                    )
+                if any(
+                    isinstance(other, RecordFilesAttachmentRemoval)
+                    and other.attachment.location is not None
+                    and other.attachment.location.module == location.module
+                    for other in patch.attachment_changes
+                ):
+                    raise MatelabUsageError(
+                        "Files removal and positional replacement require separate read/patch cycles."
+                    )
+                self._claim_staged_attachment(source, change.replacement, used_staged)
+                path = (location.module, location.position)
+                claim(path)
+                modify.append(
+                    {
+                        "path": list(path),
+                        "data": {"file": self._native_attachment_ref(change.replacement), "text": change.caption},
+                    }
+                )
+                continue
+
+            current = self._current_attachment(source, before, change.attachment)
+            location = current.location
+            if location is None or location.kind not in {"files_module", "images_module"}:
+                raise MatelabUsageError("Files attachment removal requires an observed files/images-module occurrence.")
+            same_hash = tuple(
+                attachment
+                for attachment in before.attachments
+                if attachment.location is not None
+                and attachment.location.kind == location.kind
+                and attachment.location.module == location.module
+                and attachment.sha256 == current.sha256
+            )
+            if len(same_hash) != 1:
+                raise MatelabUsageError(
+                    "The Provider deletes files by hash, so a duplicate-hash occurrence is unsafe (PVD-016)."
+                )
+            path = (location.module, current.sha256)
+            claim(path)
+            delete_values.append({"path": list(path)})
+
+        for rich_text in patch.rich_text_updates:
+            module = modules.get(rich_text.module)
+            if module is None or module.get("type") != "richtext":
+                raise MatelabUsageError("Rich-text attachment updates require an existing richtext module.")
+            path = (rich_text.module,)
+            claim(path)
+            modify.append({"path": list(path), "data": self._render_record_rich_text(source, rich_text, used_staged)})
+
+        operation_count = len(modify) + len(delete_values) + len(create_modules) + len(delete_modules) + len(add_values)
+        if operation_count == 0:
+            raise MatelabUsageError("Record patch must contain at least one mutation.")
+        payload: dict[str, object] = {}
+        if modify:
+            payload["modify"] = modify
+        if delete_values:
+            payload["del"] = delete_values
+        if create_modules:
+            payload["addModule"] = create_modules
+        if delete_modules:
+            payload["delModule"] = delete_modules
+        if add_values:
+            payload["add"] = add_values
+        return payload, operation_count
+
+    @staticmethod
+    def _module_type(name: str, modules: Mapping[str, Mapping[str, object]], created_types: Mapping[str, str]) -> str:
+        if name in created_types:
+            return created_types[name]
+        module = modules.get(name)
+        module_type = module.get("type") if module is not None else None
+        if not isinstance(module_type, str):
+            raise MatelabUsageError("Record patch targets a module that is not currently present.")
+        return module_type
+
+    @staticmethod
+    def _module_field_type(module: Mapping[str, object] | None, field_name: str) -> str | None:
+        if module is None or not isinstance(raw_fields := module.get("data"), list):
+            return None
+        for raw_field in cast(list[object], raw_fields):
+            if not isinstance(raw_field, dict):
+                continue
+            field_mapping = cast(dict[str, object], raw_field)
+            if field_mapping.get("name") == field_name and isinstance(field_mapping.get("type"), str):
+                return cast(str, field_mapping["type"])
+        return None
+
+    @classmethod
+    def _validate_nonattachment_path(
+        cls, path: tuple[str | int, ...], modules: Mapping[str, Mapping[str, object]]
+    ) -> None:
+        if not path or not isinstance(path[0], str) or not path[0]:
+            raise MatelabUsageError("Record patch paths must begin with an exact module name.")
+        module = modules.get(path[0])
+        if module is None:
+            raise MatelabUsageError("Record patch path targets a module that is not currently present.")
+        module_type = module.get("type")
+        if module_type in {"files", "images", "richtext"}:
+            raise MatelabUsageError("Attachment-bearing modules require a dedicated mutation type.")
+        if (
+            module_type in {"form", "table"}
+            and len(path) >= 2
+            and isinstance(path[1], str)
+            and cls._module_field_type(module, path[1]) == "file"
+        ):
+            raise MatelabUsageError("File fields require a dedicated attachment mutation type.")
+
+    @staticmethod
+    def _current_attachment(
+        source: RecordLocator, before: Record, requested: RecordAttachmentRef
+    ) -> RecordAttachmentRef:
+        if requested.source != source or requested.observed_version is not None or requested.location is None:
+            raise MatelabUsageError("Attachment mutation requires a current occurrence observed on the target record.")
+        current = next(
+            (
+                attachment
+                for attachment in before.attachments
+                if attachment.location == requested.location
+                and attachment.sha256 == requested.sha256
+                and attachment.filename == requested.filename
+                and attachment.size == requested.size
+            ),
+            None,
+        )
+        if current is None:
+            raise MatelabUsageError("The selected attachment occurrence changed before the mutation.")
+        return current
+
+    @staticmethod
+    def _claim_staged_attachment(
+        source: RecordLocator, attachment: StagedRecordAttachment, used: set[tuple[int, str]]
+    ) -> None:
+        if attachment.source != source:
+            raise MatelabUsageError("Staged record attachment belongs to a different record.")
+        if (
+            attachment.temporary_file_id < 1
+            or not attachment.binding.uid
+            or len(attachment.binding.uid) > 45
+            or not attachment.filename
+            or "\r" in attachment.filename
+            or "\n" in attachment.filename
+            or attachment.size < 0
+            or re.fullmatch(r"[0-9a-f]{64}", attachment.sha256) is None
+        ):
+            raise MatelabUsageError("Staged record attachment metadata is invalid.")
+        identity = (attachment.temporary_file_id, attachment.binding.uid)
+        if identity in used:
+            raise MatelabUsageError("One staged record attachment can be consumed only once in a patch.")
+        used.add(identity)
+
+    @staticmethod
+    def _native_attachment_ref(attachment: StagedRecordAttachment) -> str:
+        if "\r" in attachment.filename or "\n" in attachment.filename:
+            raise MatelabUsageError("Attachment filename cannot contain line breaks.")
+        return f"#hash{{{attachment.filename}, {attachment.sha256}}}"
+
+    def _render_record_rich_text(
+        self, source: RecordLocator, update: RecordRichTextUpdate, used_staged: set[tuple[int, str]]
+    ) -> str:
+        attachments = dict(update.attachments)
+        if _contains_native_attachment_reference(update.html):
+            raise MatelabUsageError("Provider-native attachment references require a staged attachment object.")
+        markers = set(_ATTACHMENT_MARKER_PATTERN.findall(update.html))
+        if markers != set(attachments):
+            raise MatelabUsageError("Rich-text attachment names must exactly match matelab-attachment:<name> markers.")
+        rendered = update.html
+        for name, attachment in attachments.items():
+            self._claim_staged_attachment(source, attachment, used_staged)
+            rendered = rendered.replace(f"matelab-attachment:{name}", self._native_attachment_ref(attachment))
+        if _ATTACHMENT_MARKER_PATTERN.search(rendered):
+            raise MatelabUsageError("Rich-text content contains an unresolved attachment marker.")
+        return rendered
+
+    @staticmethod
+    def _validate_upload_metadata(
+        *, filename: str, content: IO[bytes] | bytes, size: int, sha256: str, content_type: str
+    ) -> None:
+        if (
+            not filename
+            or len(filename) > 1000
+            or "\r" in filename
+            or "\n" in filename
+            or type(size) is not int
+            or size < 0
+            or re.fullmatch(r"[0-9a-f]{64}", sha256) is None
+            or not content_type
+            or "\r" in content_type
+            or "\n" in content_type
+        ):
+            raise MatelabUsageError("Attachment metadata does not satisfy the Integration Contract.")
+        if isinstance(content, bytes) and (len(content) != size or hashlib.sha256(content).hexdigest() != sha256):
+            raise MatelabUsageError("Attachment bytes do not match the declared size and SHA-256.")
+
+    @staticmethod
+    def _parse_comment_upload_query(query: str) -> tuple[int, int, str, int, str, str]:
+        try:
+            parsed = parse_qs(query, keep_blank_values=True, strict_parsing=True)
+        except ValueError:
+            raise MatelabProtocolError("Matelab returned an invalid comment attachment reference.") from None
+        if any(len(values) != 1 for values in parsed.values()) or not {"eln", "id", "h", "s", "f"} <= parsed.keys():
+            raise MatelabProtocolError("Matelab returned an invalid comment attachment reference.")
+        try:
+            notebook_id = int(parsed["eln"][0])
+            temporary_id = int(parsed["id"][0])
+            size = int(parsed["s"][0])
+        except ValueError:
+            raise MatelabProtocolError("Matelab returned an invalid comment attachment reference.") from None
+        sha256 = parsed["h"][0]
+        filename = parsed["f"][0]
+        if (
+            notebook_id < 1
+            or temporary_id < 1
+            or size < 0
+            or re.fullmatch(r"[0-9a-f]{64}", sha256) is None
+            or not filename
+        ):
+            raise MatelabProtocolError("Matelab returned an invalid comment attachment reference.")
+        raw_filename = next((part.partition("=")[2] for part in query.split("&") if part.partition("=")[0] == "f"), "")
+        canonical_reference = f"elnurl://h={sha256}&s={size}&f={raw_filename}"
+        return notebook_id, temporary_id, sha256, size, filename, canonical_reference
+
+    def _render_comment_draft(self, source: RecordLocator, draft: RecordCommentDraft) -> tuple[str, str, str]:
+        attachments = dict(draft.attachments)
+        if _COMMENT_TEMP_URL_PATTERN.search(draft.html):
+            raise MatelabUsageError("Temporary comment URLs require a staged attachment object.")
+        markers = set(_ATTACHMENT_MARKER_PATTERN.findall(draft.html))
+        if markers != set(attachments):
+            raise MatelabUsageError("Comment attachment names must exactly match matelab-attachment:<name> markers.")
+        binding_uids = {attachment.binding.uid for attachment in attachments.values()}
+        if len(binding_uids) > 1:
+            raise MatelabUsageError("All attachments in one comment save must use the same upload binding.")
+        wire_html = draft.html
+        canonical_html = draft.html
+        for name, attachment in attachments.items():
+            if (
+                attachment.source != source
+                or attachment.temporary_file_id < 1
+                or not attachment.binding.uid
+                or len(attachment.binding.uid) > 45
+                or not attachment._temporary_url  # pyright: ignore[reportPrivateUsage]
+                or not attachment._canonical_reference  # pyright: ignore[reportPrivateUsage]
+                or attachment.size < 0
+                or re.fullmatch(r"[0-9a-f]{64}", attachment.sha256) is None
+            ):
+                raise MatelabUsageError("Staged comment attachment belongs to a different record.")
+            marker = f"matelab-attachment:{name}"
+            wire_html = wire_html.replace(
+                marker,
+                attachment._temporary_url,  # pyright: ignore[reportPrivateUsage]
+            )
+            canonical_html = canonical_html.replace(
+                marker,
+                attachment._canonical_reference,  # pyright: ignore[reportPrivateUsage]
+            )
+        if _ATTACHMENT_MARKER_PATTERN.search(wire_html):
+            raise MatelabUsageError("Comment content contains an unresolved attachment marker.")
+        return wire_html.strip(), canonical_html.strip(), next(iter(binding_uids), "")
+
+    async def _save_comment_request(
+        self, *, source: RecordLocator, comment_id: int, html: str, binding_uid: str
+    ) -> WireForwardableSuccessResponse:
+        try:
+            request = WireSaveRecordCommentRequest(
+                id=comment_id,
+                eln=source.notebook.notebook_id,
+                item_id=source.record.record_database_id,
+                more=html,
+                uid=binding_uid,
+            )
+        except ValidationError:
+            raise MatelabUsageError("Record comment does not satisfy the Integration Contract.") from None
+        return await self._transport.request(_SAVE_COMMENT, files=multipart_fields(request.model_dump(mode="json")))
+
+    async def _verified_read(self, source: RecordLocator, action: str) -> Record:
+        try:
+            return await self.read(notebook=source.notebook, record=source.record)
+        except MatelabError as exc:
+            raise MatelabVerificationError(
+                f"Matelab acknowledged the {action}, but readback failed; the mutation may have persisted."
+            ) from exc
+
+    async def _verified_relations(self, source: RecordLocator, action: str) -> RecordRelations:
+        try:
+            return await self.relations(notebook=source.notebook, record=source.record)
+        except MatelabError as exc:
+            raise MatelabVerificationError(
+                f"Matelab acknowledged the {action}, but readback failed; the mutation may have persisted."
+            ) from exc
+
+    async def _verified_comments(self, source: RecordLocator, action: str) -> RecordComments:
+        try:
+            return await self.comments(notebook=source.notebook, record=source.record)
+        except MatelabError as exc:
+            raise MatelabVerificationError(
+                f"Matelab acknowledged the {action}, but readback failed; the mutation may have persisted."
+            ) from exc
+
+    @staticmethod
+    def _notebook_selector(notebook: NotebookRef) -> str | dict[str, object]:
+        title = Records._notebook_title(notebook)
+        if notebook.scope == "shared":
+            return {"title": title, "user": notebook.owner_userid}
+        return title
+
+    @staticmethod
+    def _notebook_title(notebook: NotebookRef) -> str:
+        if notebook.title is None:
+            raise MatelabUsageError("Notebook selector cannot use a null Provider title.")
+        return notebook.title
+
+    async def _verified_list(self, notebook: NotebookRef, action: str) -> RecordCollection:
+        try:
+            return await self.list(notebook=notebook)
+        except MatelabError as exc:
+            raise MatelabVerificationError(
+                f"Matelab acknowledged the {action}, but readback failed; the mutation may have persisted."
+            ) from exc
+
+    async def _verified_lifecycle_state(
+        self, notebook: NotebookRef, action: str
+    ) -> tuple[RecordCollection, DeletedRecordPage]:
+        try:
+            return (await self.list(notebook=notebook), await self.recycle_bin(notebook, page=1, page_size=256))
+        except MatelabError as exc:
+            raise MatelabVerificationError(
+                f"Matelab acknowledged the {action}, but readback failed; the mutation may have persisted."
+            ) from exc
+
+    @staticmethod
+    def _record_summary(item: WireRecordListItem) -> RecordSummary:
+        return RecordSummary(
+            ref=RecordRef(record_database_id=item.id, record_uid=item.sn),
+            title=item.title,
+            summary=item.comm,
+            created_at=item.datetime_create,
+            modified_at=item.datetime_modify,
+            keywords=tuple(item.keywords),
+            template_id=item.template_id,
+            subtype_id=item.subtype,
+            encrypted=bool(item.encrypt),
+            audit_count=item.log,
+        )
+
+    @staticmethod
+    def _subtype_summary(wire: WireRecordSubtype) -> RecordSubtypeSummary:
+        return RecordSubtypeSummary(
+            subtype_id=wire.id,
+            title=wire.showtext,
+            parent_subtype_id=wire.parent,
+            record_count=wire.items_num,
+            child_subtype_count=wire.subtype_num,
+        )
+
+    @staticmethod
+    def _comment(wire: WireRecordComment, *, source: RecordLocator) -> RecordComment:
+        ref = RecordCommentRef(comment_id=wire.id)
+        attachments = tuple(
+            RecordCommentAttachmentRef(
+                source=source, comment=ref, sha256=attachment.sha256, filename=attachment.filename, size=attachment.size
+            )
+            for attachment in _rich_text_attachments(wire.data)
+            if attachment.size >= 1 and len(attachment.filename) <= 1000
+        )
+        return RecordComment(
+            source=source,
+            ref=ref,
+            modified_at=wire.datetime,
+            body=wire.data,
+            author_name=wire.username,
+            owned_by_caller=wire.owner,
+            attachments=attachments,
+        )