matelab-python-sdk 0.1.0a13__tar.gz → 0.1.0a15__tar.gz

{matelab_python_sdk-0.1.0a13 → matelab_python_sdk-0.1.0a15}/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.1.0a15 - 2026-08-10
+
+- Breaking: removes `PublicNotebookRef` and uses one `NotebookRef` with `scope="owned"`, `"shared"`, or `"public"`.
+  Public `notebook_id` values identify `eln_public` catalog rows rather than source ELNs; public record results retain
+  their separate source notebook identity.
+- Centralizes notebook-scope validation: public record listing accepts only a public ref with a non-empty title,
+  private operations reject public refs, and owned-only notebook mutations reject shared/public refs. `NotebookRef.title`
+  is a non-empty `str` preserved without whitespace normalization; an unexpected null from the wider owned/shared wire
+  contract is reported as a protocol violation, matching Provider write validation and audited runtime data.
+
+## 0.1.0a14 - 2026-08-10
+
+- Adds immutable semantic template modules, editable `TemplateDocument` values, ordered name-based patch intents,
+  stable content fingerprints, and `Templates.read_document()`, `save_document()`, and `patch_content()` while
+  retaining the low-level `TemplateModule`, `read()`, and `save_content()` interface.
+
 ## 0.1.0a13 - 2026-08-08
 
 - Breaking: `Identity.username` now removes surrounding whitespace and rejects values that become empty.

{matelab_python_sdk-0.1.0a13 → matelab_python_sdk-0.1.0a15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matelab-python-sdk
-Version: 0.1.0a13
+Version: 0.1.0a15
 Summary: Reusable async Python client for the Matelab Integration Contract
 Author-email: 朱天念 <zhutiannian@gmail.com>
 License-Expression: Apache-2.0
@@ -30,7 +30,7 @@ Description-Content-Type: text/markdown
 
 Reusable async Python client for the Matelab Integration Contract.
 
-The current alpha is `0.1.0a13`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a15`. `[project].version` in `pyproject.toml` is the sole SDK version source;
 `uv.lock` only mirrors that source.
 
 The SDK is pinned to the immutable `matelab-spec v0.4.0` Contract Release. The sole release pin is
@@ -59,7 +59,7 @@ To test the same artifact a downstream Consumer will install, build and install
 
 ```bash
 uv build --no-build-isolation --out-dir dist/release
-python -m pip install dist/release/matelab_python_sdk-0.1.0a13-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a15-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -450,6 +450,52 @@ market = await client.templates.search_market("calibration", page=1, page_size=2
 modules = await client.templates.read(templates.owned[0].ref)
 ```
 
+Semantic template documents hide canonical `uid`, `width`, `data`, `rows`, `folders`, and option encoding:
+
+```python
+from matelab import (
+    TemplateDocument,
+    TemplateFieldAdd,
+    TemplateFormField,
+    TemplateFormModule,
+    TemplatePatch,
+    TemplateRichTextModule,
+)
+
+document = TemplateDocument.create(
+    (
+        TemplateFormModule(
+            name="Basic",
+            fields=(TemplateFormField(name="Temperature", field_type="number", required=True, unit="K"),),
+        ),
+        TemplateRichTextModule(name="Notes", content="<p>Instructions</p>"),
+    )
+)
+template = await client.templates.create(title="Measurement")
+await client.templates.save_document(template, document)
+
+observed = await client.templates.read_document(template)
+await client.templates.patch_content(
+    template,
+    TemplatePatch(
+        changes=(
+            TemplateFieldAdd(
+                module="Basic",
+                field=TemplateFormField(name="Operator", field_type="text", required=True),
+            ),
+        )
+    ),
+    expected_fingerprint=observed.fingerprint,
+)
+updated = await client.templates.read_document(template)
+```
+
+`TemplateDocument` is immutable at its interface, preserves unknown canonical properties, keeps existing UIDs stable,
+and converts losslessly back to `TemplateModule`. Patches are ordered name-based intents and reject missing, duplicate,
+or incompatible targets before saving. The fingerprint preflight detects a stale prior read, but is client-side only:
+the current Provider has no atomic template patch or CAS (PCG-007). `patch_content()` returns `None`; explicitly
+re-read before using a new fingerprint because the mutation response contains no saved representation.
+
 The market result reports the Provider `total_count`, the requested and effective page sizes, and a `has_more`
 value derived from the total; it does not claim a stable order or continuation token. Canonical
 modules are mapped to public `TemplateModule` values and retain additive module attributes. Template reads remain
@@ -612,8 +658,18 @@ deletion is named `permanently_delete_files` and is non-recoverable. Cloud downl
 resolve bytes from the final file identity and reuse `DownloadStream`, thumbnail/preview choices and the PVD-002-safe
 range subset. Cloud mutations are not automatically retried.
 
-Owned/shared `NotebookRef`, public `PublicNotebookRef`, `RecordRef`, and `RecordVersionRef` keep
-Provider identifiers distinct. Historical reads first re-read the authorized current record and confirm
+Owned, shared, and public catalog notebooks use one `NotebookRef`, distinguished by its
+`scope` (`"owned"`, `"shared"`, or `"public"`). For owned/shared refs, `notebook_id` is the source `eln.id`;
+for public refs it is the distinct `eln_public.id` catalog identity and must not be treated as a source ELN ID.
+Public record entries expose that source identity separately as `PublicRecordRef.source_notebook_id`.
+`NotebookRef.title` is a non-empty `str` preserved exactly as returned, without whitespace normalization. The pinned
+owned/shared wire field remains nullable because the database column allows null, but Provider writes require a
+non-empty title and a runtime database audit found no null or empty titles; the SDK therefore treats a null
+notebook-list title as a protocol violation instead of exposing it publicly. Public
+record listing additionally requires a non-empty title selector. Private operations reject public scope, and
+public record listing accepts only public scope, while
+owned-only notebook mutations continue to reject shared/public refs. `RecordRef` and `RecordVersionRef` keep
+their Provider identifiers distinct. Historical reads first re-read the authorized current record and confirm
 that the requested version is still present in its `modify_log`; both reads write Provider audit entries.
 
 Errors are separated into semantic Provider errors, authentication errors, HTTP/transport errors,

{matelab_python_sdk-0.1.0a13 → matelab_python_sdk-0.1.0a15}/README.md

@@ -2,7 +2,7 @@
 
 Reusable async Python client for the Matelab Integration Contract.
 
-The current alpha is `0.1.0a13`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a15`. `[project].version` in `pyproject.toml` is the sole SDK version source;
 `uv.lock` only mirrors that source.
 
 The SDK is pinned to the immutable `matelab-spec v0.4.0` Contract Release. The sole release pin is
@@ -31,7 +31,7 @@ To test the same artifact a downstream Consumer will install, build and install
 
 ```bash
 uv build --no-build-isolation --out-dir dist/release
-python -m pip install dist/release/matelab_python_sdk-0.1.0a13-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a15-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -422,6 +422,52 @@ market = await client.templates.search_market("calibration", page=1, page_size=2
 modules = await client.templates.read(templates.owned[0].ref)
 ```
 
+Semantic template documents hide canonical `uid`, `width`, `data`, `rows`, `folders`, and option encoding:
+
+```python
+from matelab import (
+    TemplateDocument,
+    TemplateFieldAdd,
+    TemplateFormField,
+    TemplateFormModule,
+    TemplatePatch,
+    TemplateRichTextModule,
+)
+
+document = TemplateDocument.create(
+    (
+        TemplateFormModule(
+            name="Basic",
+            fields=(TemplateFormField(name="Temperature", field_type="number", required=True, unit="K"),),
+        ),
+        TemplateRichTextModule(name="Notes", content="<p>Instructions</p>"),
+    )
+)
+template = await client.templates.create(title="Measurement")
+await client.templates.save_document(template, document)
+
+observed = await client.templates.read_document(template)
+await client.templates.patch_content(
+    template,
+    TemplatePatch(
+        changes=(
+            TemplateFieldAdd(
+                module="Basic",
+                field=TemplateFormField(name="Operator", field_type="text", required=True),
+            ),
+        )
+    ),
+    expected_fingerprint=observed.fingerprint,
+)
+updated = await client.templates.read_document(template)
+```
+
+`TemplateDocument` is immutable at its interface, preserves unknown canonical properties, keeps existing UIDs stable,
+and converts losslessly back to `TemplateModule`. Patches are ordered name-based intents and reject missing, duplicate,
+or incompatible targets before saving. The fingerprint preflight detects a stale prior read, but is client-side only:
+the current Provider has no atomic template patch or CAS (PCG-007). `patch_content()` returns `None`; explicitly
+re-read before using a new fingerprint because the mutation response contains no saved representation.
+
 The market result reports the Provider `total_count`, the requested and effective page sizes, and a `has_more`
 value derived from the total; it does not claim a stable order or continuation token. Canonical
 modules are mapped to public `TemplateModule` values and retain additive module attributes. Template reads remain
@@ -584,8 +630,18 @@ deletion is named `permanently_delete_files` and is non-recoverable. Cloud downl
 resolve bytes from the final file identity and reuse `DownloadStream`, thumbnail/preview choices and the PVD-002-safe
 range subset. Cloud mutations are not automatically retried.
 
-Owned/shared `NotebookRef`, public `PublicNotebookRef`, `RecordRef`, and `RecordVersionRef` keep
-Provider identifiers distinct. Historical reads first re-read the authorized current record and confirm
+Owned, shared, and public catalog notebooks use one `NotebookRef`, distinguished by its
+`scope` (`"owned"`, `"shared"`, or `"public"`). For owned/shared refs, `notebook_id` is the source `eln.id`;
+for public refs it is the distinct `eln_public.id` catalog identity and must not be treated as a source ELN ID.
+Public record entries expose that source identity separately as `PublicRecordRef.source_notebook_id`.
+`NotebookRef.title` is a non-empty `str` preserved exactly as returned, without whitespace normalization. The pinned
+owned/shared wire field remains nullable because the database column allows null, but Provider writes require a
+non-empty title and a runtime database audit found no null or empty titles; the SDK therefore treats a null
+notebook-list title as a protocol violation instead of exposing it publicly. Public
+record listing additionally requires a non-empty title selector. Private operations reject public scope, and
+public record listing accepts only public scope, while
+owned-only notebook mutations continue to reject shared/public refs. `RecordRef` and `RecordVersionRef` keep
+their Provider identifiers distinct. Historical reads first re-read the authorized current record and confirm
 that the requested version is still present in its `modify_log`; both reads write Provider audit entries.
 
 Errors are separated into semantic Provider errors, authentication errors, HTTP/transport errors,

{matelab_python_sdk-0.1.0a13 → matelab_python_sdk-0.1.0a15}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "matelab-python-sdk"
-version = "0.1.0a13"
+version = "0.1.0a15"
 description = "Reusable async Python client for the Matelab Integration Contract"
 readme = "README.md"
 requires-python = ">=3.11"

{matelab_python_sdk-0.1.0a13 → matelab_python_sdk-0.1.0a15}/src/matelab/__init__.py

@@ -42,7 +42,6 @@ from matelab.domains.notebooks import (
     NotebookShareRef,
     NotebookShares,
     NotebookSummary,
-    PublicNotebookRef,
     PublicNotebookSummary,
 )
 from matelab.domains.records import (
@@ -99,13 +98,38 @@ from matelab.domains.records import (
     StagedRecordAttachment,
     StagedRecordCommentAttachment,
 )
+from matelab.domains.template_documents import (
+    TemplateChange,
+    TemplateCodeLanguage,
+    TemplateCodeModule,
+    TemplateCodeStyle,
+    TemplateDocument,
+    TemplateFieldAdd,
+    TemplateFieldRemove,
+    TemplateFieldRename,
+    TemplateFieldUpdate,
+    TemplateFilesModule,
+    TemplateFormField,
+    TemplateFormFieldType,
+    TemplateFormModule,
+    TemplateModule,
+    TemplateModuleAdd,
+    TemplateModuleContentUpdate,
+    TemplateModuleDefinition,
+    TemplateModuleRemove,
+    TemplateModuleRename,
+    TemplatePatch,
+    TemplateRichTextModule,
+    TemplateTableColumn,
+    TemplateTableColumnType,
+    TemplateTableModule,
+)
 from matelab.domains.templates import (
     TemplateCollection,
     TemplateLibraryEntryRef,
     TemplateLibraryRelationKind,
     TemplateMarketEntry,
     TemplateMarketPage,
-    TemplateModule,
     TemplateRef,
     TemplateSource,
     TemplateSummary,
@@ -180,7 +204,6 @@ __all__ = [
     "PendingLiteratureShare",
     "PendingLiteratureShareComment",
     "PersonalLiteratureItemRef",
-    "PublicNotebookRef",
     "PublicNotebookSummary",
     "PublicRecordRef",
     "PublicRecordSummary",
@@ -235,15 +258,38 @@ __all__ = [
     "StagedRecordAttachment",
     "StagedRecordCommentAttachment",
     "StagedUploadSession",
+    "TemplateChange",
+    "TemplateCodeLanguage",
+    "TemplateCodeModule",
+    "TemplateCodeStyle",
     "TemplateCollection",
+    "TemplateDocument",
+    "TemplateFieldAdd",
+    "TemplateFieldRemove",
+    "TemplateFieldRename",
+    "TemplateFieldUpdate",
+    "TemplateFilesModule",
+    "TemplateFormField",
+    "TemplateFormFieldType",
+    "TemplateFormModule",
     "TemplateLibraryEntryRef",
     "TemplateLibraryRelationKind",
     "TemplateMarketEntry",
     "TemplateMarketPage",
     "TemplateModule",
+    "TemplateModuleAdd",
+    "TemplateModuleContentUpdate",
+    "TemplateModuleDefinition",
+    "TemplateModuleRemove",
+    "TemplateModuleRename",
+    "TemplatePatch",
     "TemplateRef",
+    "TemplateRichTextModule",
     "TemplateSource",
     "TemplateSummary",
+    "TemplateTableColumn",
+    "TemplateTableColumnType",
+    "TemplateTableModule",
     "Token",
     "UploadBindingRef",
     "UserRef",

{matelab_python_sdk-0.1.0a13 → matelab_python_sdk-0.1.0a15}/src/matelab/domains/notebooks.py

@@ -10,7 +10,7 @@ from matelab._transport import Encoding, Operation, SessionTransport
 from matelab._wire_validation import encode_json_field, validate_request
 from matelab.domains.groups import GroupRef
 from matelab.domains.users import UserRef
-from matelab.errors import MatelabUsageError
+from matelab.errors import MatelabProtocolError, MatelabUsageError
 
 _LIST_NOTEBOOKS = Operation(
     method="GET",
@@ -60,21 +60,39 @@ _DELETE_SHARE = Operation(
 
 @dataclass(frozen=True, slots=True)
 class NotebookRef:
-    """Identity and exact Provider selector for an owned or shared notebook."""
+    """Notebook identity and exact Provider selector across all visibility scopes.
+
+    ``notebook_id`` is an ``eln.id`` for owned/shared scopes, but an
+    ``eln_public.id`` catalog identity for public scope. It is not the source
+    ELN identity returned by public record entries. ``title`` is intentionally
+    non-empty and preserved verbatim: Provider writes require it and runtime
+    data contains no null or empty titles, even though the pinned owned/shared
+    wire field remains nullable.
+    """
 
     notebook_id: int
-    title: str | None
+    title: str
     owner_userid: int
-    scope: Literal["owned", "shared"]
+    scope: Literal["owned", "shared", "public"]
 
+    def __post_init__(self) -> None:
+        if not self.title:
+            raise ValueError("Notebook title cannot be empty.")
 
-@dataclass(frozen=True, slots=True)
-class PublicNotebookRef:
-    """Identity and title selector for a public-catalog notebook."""
 
-    public_notebook_id: int
-    title: str
-    owner_userid: int
+def require_private_notebook(notebook: NotebookRef) -> None:
+    if notebook.scope == "public":
+        raise MatelabUsageError("This operation requires an owned or shared NotebookRef, not public scope.")
+
+
+def _require_owned_notebook(notebook: NotebookRef) -> None:
+    if notebook.scope != "owned":
+        raise MatelabUsageError("This operation requires an owned NotebookRef.")
+
+
+def require_public_notebook(notebook: NotebookRef) -> None:
+    if notebook.scope != "public":
+        raise MatelabUsageError("Public record listing requires a public NotebookRef.")
 
 
 @dataclass(frozen=True, slots=True)
@@ -99,7 +117,7 @@ class NotebookSummary:
 
 @dataclass(frozen=True, slots=True)
 class PublicNotebookSummary:
-    ref: PublicNotebookRef
+    ref: NotebookRef
     summary: str
     record_count: int
     created_at: str
@@ -204,6 +222,8 @@ def _parse_display_fields(raw: str | None) -> tuple[tuple[NotebookListField, ...
 
 
 def _owned_or_shared(item: wire_models.ElnNotebook, *, scope: Literal["owned", "shared"]) -> NotebookSummary:
+    if item.showtext is None:
+        raise MatelabProtocolError("Matelab returned a null notebook title, violating the SDK runtime invariant.")
     display_fields, configuration_valid = _parse_display_fields(item.requests)
     return NotebookSummary(
         ref=NotebookRef(notebook_id=item.id, title=item.showtext, owner_userid=item.userid, scope=scope),
@@ -232,7 +252,7 @@ class Notebooks:
             shared=tuple(_owned_or_shared(item, scope="shared") for item in response.share),
             public=tuple(
                 PublicNotebookSummary(
-                    ref=PublicNotebookRef(public_notebook_id=item.id, title=item.showtext, owner_userid=item.userid),
+                    ref=NotebookRef(notebook_id=item.id, title=item.showtext, owner_userid=item.userid, scope="public"),
                     summary=item.comm,
                     record_count=item.num,
                     created_at=item.datetime_create,
@@ -270,8 +290,7 @@ class Notebooks:
         notebook_types: tuple[JsonValue, ...] = (),
         display_fields: tuple[NotebookListField, ...] | None = None,
     ) -> None:
-        if notebook.scope != "owned":
-            raise MatelabUsageError("Notebook metadata can only be updated through an owned NotebookRef.")
+        _require_owned_notebook(notebook)
         request = _save_request(
             title=title,
             summary=summary,
@@ -282,6 +301,7 @@ class Notebooks:
         _ = await self._transport.request(_SAVE_NOTEBOOK, payload=request.model_dump(mode="json", exclude_unset=True))
 
     async def shares(self, notebook: NotebookRef) -> NotebookShares:
+        require_private_notebook(notebook)
         request = validate_request(
             wire_models.ListNotebookSharesParametersQuery,
             {"id": notebook.notebook_id},
@@ -309,6 +329,7 @@ class Notebooks:
         )
 
     async def share(self, notebook: NotebookRef, recipients: Sequence[UserRef]) -> None:
+        _require_owned_notebook(notebook)
         request = validate_request(
             wire_models.AddNotebookShareRequest,
             {
@@ -331,6 +352,7 @@ class Notebooks:
         read_audit_log: bool = False,
         manage_shares: bool = False,
     ) -> None:
+        _require_owned_notebook(ref.notebook)
         request = validate_request(
             wire_models.UpdateNotebookSharePermissionsRequest,
             {
@@ -348,6 +370,7 @@ class Notebooks:
         _ = await self._transport.request(_UPDATE_SHARE, payload=request)
 
     async def unshare(self, ref: NotebookShareRef) -> None:
+        _require_owned_notebook(ref.notebook)
         request = validate_request(
             wire_models.DeleteNotebookShareRequest,
             {"id": ref.share_row_id},

{matelab_python_sdk-0.1.0a13 → matelab_python_sdk-0.1.0a15}/src/matelab/domains/records.py

@@ -15,7 +15,7 @@ from matelab._generated import models as wire_models
 from matelab._transport import Encoding, Operation, SessionTransport, StreamOperation
 from matelab._wire_validation import encode_json_field, validate_request
 from matelab.domains._attachment_content import validated_attachment_content
-from matelab.domains.notebooks import NotebookRef, PublicNotebookRef
+from matelab.domains.notebooks import NotebookRef, require_private_notebook, require_public_notebook
 from matelab.domains.uploads import UploadBindingRef
 from matelab.domains.users import UserRef
 from matelab.errors import MatelabProtocolError, MatelabUsageError
@@ -1135,14 +1135,13 @@ def _render_comment(
     return wire_html.strip(), canonical_html.strip(), next(iter(binding_uids), "")
 
 
-def _notebook_title(notebook: NotebookRef) -> str:
-    if notebook.title is None:
-        raise MatelabUsageError("Notebook selector cannot use a null Provider title.")
+def _private_notebook_title(notebook: NotebookRef) -> str:
+    require_private_notebook(notebook)
     return notebook.title
 
 
 def _notebook_selector(notebook: NotebookRef) -> str | dict[str, JsonValue]:
-    title = _notebook_title(notebook)
+    title = _private_notebook_title(notebook)
     if notebook.scope == "shared":
         return {"title": title, "user": notebook.owner_userid}
     return title
@@ -1213,12 +1212,11 @@ class Records:
         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.")
+        title = _private_notebook_title(notebook)
         request = validate_request(
             wire_models.ListRecordsRequest,
             {
-                "eln": notebook.title,
+                "eln": 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 "",
@@ -1245,7 +1243,7 @@ class Records:
         record_uid: str | None = None,
         path: Sequence[str] | None = None,
     ) -> None:
-        notebook_title = _notebook_title(notebook)
+        notebook_title = _private_notebook_title(notebook)
         request = validate_request(
             wire_models.CreateRecordRequest,
             {
@@ -1268,7 +1266,7 @@ class Records:
         items: Sequence[RecordImportItem],
         template_owner: UserRef | None = None,
     ) -> RecordImportResult:
-        notebook_title = _notebook_title(notebook)
+        notebook_title = _private_notebook_title(notebook)
         staged_attachments: set[_StagedNotebookAttachmentIdentity] = set()
         payload: dict[str, JsonValue] = {
             "eln": notebook_title,
@@ -1316,6 +1314,8 @@ class Records:
         record_uid: str | None = None,
     ) -> RecordCopyResult:
         target = target_notebook or source.notebook
+        require_private_notebook(source.notebook)
+        require_private_notebook(target)
         request = validate_request(
             wire_models.CopyRecordRequest,
             {
@@ -1331,7 +1331,7 @@ class Records:
         return RecordCopyResult(record_database_id=response.id)
 
     async def delete(self, *, notebook: NotebookRef, records: Sequence[RecordRef]) -> None:
-        notebook_title = _notebook_title(notebook)
+        notebook_title = _private_notebook_title(notebook)
         request = validate_request(
             wire_models.DeleteRecordsRequest,
             {
@@ -1344,6 +1344,7 @@ class Records:
         _ = await self._transport.request(_DELETE_RECORDS, payload=request)
 
     async def restore(self, *, notebook: NotebookRef, records: Sequence[DeletedRecordRef]) -> None:
+        require_private_notebook(notebook)
         request = validate_request(
             wire_models.RestoreRecordsRequest,
             {
@@ -1365,6 +1366,7 @@ class Records:
         binding: UploadBindingRef | None = None,
         content_type: str = "application/octet-stream",
     ) -> StagedRecordAttachment:
+        require_private_notebook(source.notebook)
         selected_binding = binding or UploadBindingRef.new()
         response, actual_size, actual_sha256 = await self._upload_record_attachment(
             notebook=source.notebook,
@@ -1403,6 +1405,7 @@ class Records:
         one safe form-file-field update.
         """
 
+        require_private_notebook(notebook)
         uploader = self._authenticated_uploader()
         selected_binding = binding or UploadBindingRef.new()
         response, actual_size, actual_sha256 = await self._upload_record_attachment(
@@ -1440,6 +1443,7 @@ class Records:
         expected_content_sha256: str | None = None,
         password: str | None = None,
     ) -> Literal["provider_reported_persisted", "pending_browser_save", "provider_acknowledged_unclassified"]:
+        require_private_notebook(source.notebook)
         if expected_content_sha256 is not None and re.fullmatch(r"[0-9a-f]{64}", expected_content_sha256) is None:
             raise MatelabUsageError("Expected record content fingerprint must be a lowercase SHA-256.")
         selected_value_updates = dict(value_updates or {})
@@ -1497,7 +1501,7 @@ class Records:
             request = validate_request(
                 wire_models.UpdateRecordRequest,
                 {
-                    "eln": _notebook_title(source.notebook),
+                    "eln": _private_notebook_title(source.notebook),
                     "uid": source.record.record_uid,
                     "user": source.notebook.owner_userid if source.notebook.scope == "shared" else None,
                     "password": password,
@@ -1588,7 +1592,8 @@ class Records:
             )
         return RecordSearchResult(matches=tuple(matches), forwarded=response.code == 10)
 
-    async def list_public(self, notebook: PublicNotebookRef) -> tuple[PublicRecordSummary, ...]:
+    async def list_public(self, notebook: NotebookRef) -> tuple[PublicRecordSummary, ...]:
+        require_public_notebook(notebook)
         request = validate_request(
             wire_models.PublicRecordListRequest,
             {"eln": notebook.title},
@@ -1626,6 +1631,7 @@ class Records:
         content: str = "",
         keywords: Sequence[str] = (),
     ) -> RecordPage:
+        require_private_notebook(notebook)
         encoded_keywords = encode_json_field(list(keywords), ensure_ascii=False) if keywords else ""
         request = validate_request(
             wire_models.ListNotebookRecordPageParametersQuery,
@@ -1677,6 +1683,7 @@ class Records:
         )
 
     async def recycle_bin(self, notebook: NotebookRef, *, page: int = 1, page_size: int = 24) -> DeletedRecordPage:
+        require_private_notebook(notebook)
         if not 10 <= page_size <= 256:
             raise MatelabUsageError("Recycle-bin page size must be between 10 and 256.")
         request = validate_request(
@@ -1708,6 +1715,7 @@ class Records:
         )
 
     async def relations(self, *, notebook: NotebookRef, record: RecordRef) -> RecordRelations:
+        require_private_notebook(notebook)
         request = validate_request(
             wire_models.ListRecordRelationsParametersQuery,
             {"eln": notebook.notebook_id, "item_id": record.record_database_id},
@@ -1736,6 +1744,8 @@ class Records:
         )
 
     async def add_relation(self, *, source: RecordLocator, target: RecordLocator) -> None:
+        require_private_notebook(source.notebook)
+        require_private_notebook(target.notebook)
         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:
@@ -1761,6 +1771,7 @@ class Records:
 
     async def delete_relation(self, relation: RecordRelation) -> None:
         source = relation.ref.source
+        require_private_notebook(source.notebook)
         before = await self.relations(notebook=source.notebook, record=source.record)
         if not before.editable:
             raise MatelabUsageError("The selected source record is not currently editable.")
@@ -1788,6 +1799,7 @@ class Records:
         _ = await self._transport.request(_DELETE_RELATION, payload=request)
 
     async def comments(self, *, notebook: NotebookRef, record: RecordRef) -> tuple[RecordComment, ...]:
+        require_private_notebook(notebook)
         request = validate_request(
             wire_models.ListRecordCommentsParametersQuery,
             {"eln": notebook.notebook_id, "item_id": record.record_database_id},
@@ -1808,6 +1820,7 @@ class Records:
         binding: UploadBindingRef | None = None,
         content_type: str = "application/octet-stream",
     ) -> StagedRecordCommentAttachment:
+        require_private_notebook(source.notebook)
         selected_binding = binding or UploadBindingRef.new()
         _validate_upload_metadata(filename=filename, size=size, sha256=sha256, content_type=content_type)
         async with validated_attachment_content(content, size=size, sha256=sha256) as prepared:
@@ -1864,6 +1877,7 @@ class Records:
         html: str,
         attachments: Mapping[str, StagedRecordCommentAttachment] | None = None,
     ) -> None:
+        require_private_notebook(source.notebook)
         wire_html, _, binding_uid = _render_comment(source, html=html, attachments=attachments)
         await self._save_comment_request(source=source, comment_id=0, html=wire_html, binding_uid=binding_uid)
 
@@ -1904,6 +1918,7 @@ class Records:
     async def download_attachment(
         self, attachment: RecordAttachmentRef, *, byte_range: ByteRange | None = None
     ) -> DownloadStream:
+        require_private_notebook(attachment.source.notebook)
         request = validate_request(
             wire_models.DownloadRecordAttachmentParametersQuery,
             {
@@ -1933,6 +1948,7 @@ class Records:
         but the current Provider only authorizes the supplied notebook and does
         not independently verify that the attachment belongs to it.
         """
+        require_private_notebook(attachment.source.notebook)
         request = validate_request(
             wire_models.DownloadRecordCommentAttachmentParametersQuery,
             {
@@ -1953,6 +1969,7 @@ class Records:
     async def read(
         self, *, notebook: NotebookRef, record: RecordRef, version: RecordVersionRef | None = None
     ) -> Record:
+        require_private_notebook(notebook)
         if version is not None and (
             version.notebook_id != notebook.notebook_id
             or version.record_database_id != record.record_database_id
@@ -2622,7 +2639,7 @@ class Records:
         sha256: str | None,
         content_type: str,
     ) -> tuple[wire_models.UploadAttachmentResponse, int, str]:
-        notebook_title = _notebook_title(notebook)
+        notebook_title = _private_notebook_title(notebook)
         _validate_upload_metadata(filename=filename, size=size, sha256=sha256, content_type=content_type)
         async with validated_attachment_content(content, size=size, sha256=sha256) as prepared:
             prepared_content, actual_size, actual_sha256 = prepared