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

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

@@ -1,5 +1,15 @@
 # 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,

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matelab-python-sdk
-Version: 0.1.0a14
+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.0a14`. `[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.0a14-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
@@ -658,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.0a14 → 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.0a14`. `[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.0a14-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
@@ -630,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.0a14 → matelab_python_sdk-0.1.0a15}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "matelab-python-sdk"
-version = "0.1.0a14"
+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.0a14 → 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 (
@@ -205,7 +204,6 @@ __all__ = [
     "PendingLiteratureShare",
     "PendingLiteratureShareComment",
     "PersonalLiteratureItemRef",
-    "PublicNotebookRef",
     "PublicNotebookSummary",
     "PublicRecordRef",
     "PublicRecordSummary",

{matelab_python_sdk-0.1.0a14 → 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.0a14 → 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

{matelab_python_sdk-0.1.0a14 → matelab_python_sdk-0.1.0a15}/tests/test_extended_records.py

@@ -10,7 +10,6 @@ from matelab import (
     MatelabProtocolError,
     MatelabUsageError,
     NotebookRef,
-    PublicNotebookRef,
     PublicRecordRef,
     RecordCommentRef,
     RecordLocator,
@@ -127,17 +126,11 @@ async def test_export_records_preserves_empty_result_and_rejects_invalid_selecti
         notebook=NotebookRef(notebook_id=12, title="Owned Example", owner_userid=101, scope="owned"),
         record=RecordRef(record_database_id=9001, record_uid="REC-EXAMPLE-001"),
     )
-    invalid = RecordLocator(
-        notebook=NotebookRef(notebook_id=12, title=None, owner_userid=101, scope="owned"),
-        record=RecordRef(record_database_id=9001, record_uid="REC-EXAMPLE-001"),
-    )
     async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
         client = AsyncMatelab("https://ignored.example", session=provider_session, http_client=http_client)
         result = await client.records.export([valid])
         with pytest.raises(MatelabUsageError, match="export selection"):
             _ = await client.records.export([])
-        with pytest.raises(MatelabUsageError, match="null Provider title"):
-            _ = await client.records.export([invalid])
 
     assert result.records == ()
     assert result.forwarded is False
@@ -231,7 +224,7 @@ async def test_search_records_preserves_empty_forwarded_result_and_rejects_ambig
 async def test_list_public_records_keeps_public_and_source_identity_distinct(
     provider_session: Session, provider_envelope: Callable[..., dict[str, object]]
 ) -> None:
-    notebook = PublicNotebookRef(public_notebook_id=7, title="Public Example", owner_userid=0)
+    notebook = NotebookRef(notebook_id=7, title="Public Example", owner_userid=0, scope="public")
 
     async def handler(request: Request) -> Response:
         assert request.method == "POST"
@@ -508,5 +501,20 @@ async def test_public_record_list_rejects_schema_mismatch(provider_session: Sess
         client = AsyncMatelab("https://ignored.example", session=provider_session, http_client=http_client)
         with pytest.raises(MatelabProtocolError, match="does not match"):
             _ = await client.records.list_public(
-                PublicNotebookRef(public_notebook_id=7, title="Public Example", owner_userid=0)
+                NotebookRef(notebook_id=7, title="Public Example", owner_userid=0, scope="public")
             )
+
+
+@pytest.mark.asyncio
+async def test_record_operations_reject_wrong_notebook_scope_before_http(provider_session: Session) -> None:
+    async def handler(_: Request) -> Response:
+        raise AssertionError("invalid notebook scope must be rejected before HTTP")
+
+    public = NotebookRef(notebook_id=7, title="Public Example", owner_userid=0, scope="public")
+    private = NotebookRef(notebook_id=12, title="Owned Example", owner_userid=101, scope="owned")
+    async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
+        client = AsyncMatelab("https://ignored.example", session=provider_session, http_client=http_client)
+        with pytest.raises(MatelabUsageError, match="owned or shared"):
+            _ = await client.records.list(notebook=public)
+        with pytest.raises(MatelabUsageError, match="public NotebookRef"):
+            _ = await client.records.list_public(private)

{matelab_python_sdk-0.1.0a14 → matelab_python_sdk-0.1.0a15}/tests/test_notebook_lifecycle.py

@@ -144,6 +144,22 @@ async def test_update_notebook_rejects_shared_scope_before_http(provider_session
             _ = await client.notebooks.update(notebook, title="Shared")
 
 
+@pytest.mark.asyncio
+async def test_private_and_owned_notebook_operations_reject_public_scope_before_http(
+    provider_session: Session,
+) -> None:
+    async def handler(_: Request) -> Response:
+        raise AssertionError("public scope must be rejected before HTTP")
+
+    notebook = NotebookRef(notebook_id=7, title="Public", owner_userid=0, scope="public")
+    async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
+        client = AsyncMatelab("https://ignored.example", session=provider_session, http_client=http_client)
+        with pytest.raises(MatelabUsageError, match="owned or shared"):
+            _ = await client.notebooks.shares(notebook)
+        with pytest.raises(MatelabUsageError, match="owned NotebookRef"):
+            _ = await client.notebooks.update(notebook, title="Public")
+
+
 @pytest.mark.asyncio
 async def test_list_notebook_shares_separates_stored_mask_from_effective_read(
     provider_session: Session, provider_envelope: Callable[..., dict[str, object]]

{matelab_python_sdk-0.1.0a14 → matelab_python_sdk-0.1.0a15}/tests/test_notebooks.py

@@ -3,7 +3,7 @@ from collections.abc import Callable
 import pytest
 from httpx2 import AsyncClient, MockTransport, Request, Response
 
-from matelab import AsyncMatelab, NotebookRef, PublicNotebookRef, Session
+from matelab import AsyncMatelab, MatelabProtocolError, NotebookRef, Session
 
 
 @pytest.mark.asyncio
@@ -27,7 +27,7 @@ async def test_list_notebooks_maps_pinned_contract_success_example(
     assert notebooks.shared[0].ref == NotebookRef(
         notebook_id=23, title="Shared Example", owner_userid=202, scope="shared"
     )
-    assert notebooks.public[0].ref == PublicNotebookRef(public_notebook_id=7, title="Public Example", owner_userid=0)
+    assert notebooks.public[0].ref == NotebookRef(notebook_id=7, title="Public Example", owner_userid=0, scope="public")
     assert len(notebooks.all) == 3
 
 
@@ -56,7 +56,11 @@ async def test_list_notebooks_maps_pinned_contract_nullable_example(
 
     async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
         client = AsyncMatelab("https://ignored.example", session=provider_session, http_client=http_client)
-        notebooks = await client.notebooks.list()
+        with pytest.raises(MatelabProtocolError, match="null notebook title"):
+            _ = await client.notebooks.list()
+
 
-    assert notebooks.owned[0].ref == NotebookRef(notebook_id=12, title=None, owner_userid=101, scope="owned")
-    assert notebooks.owned[0].created_at is None
+def test_notebook_ref_rejects_empty_title_without_stripping_provider_selector() -> None:
+    with pytest.raises(ValueError, match="Notebook title cannot be empty"):
+        _ = NotebookRef(notebook_id=12, title="", owner_userid=101, scope="owned")
+    assert NotebookRef(notebook_id=12, title=" ", owner_userid=101, scope="owned").title == " "

{matelab_python_sdk-0.1.0a14 → matelab_python_sdk-0.1.0a15}/tests/test_records.py

@@ -157,18 +157,6 @@ async def test_read_current_record_maps_pinned_contract_success_example(
     )
 
 
-@pytest.mark.asyncio
-async def test_list_records_rejects_null_notebook_selector_before_http() -> None:
-    async def handler(_: Request) -> Response:
-        raise AssertionError("null title must be rejected before HTTP")
-
-    notebook = NotebookRef(notebook_id=12, title=None, owner_userid=101, scope="owned")
-    async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
-        client = AsyncMatelab("https://ignored.example", session=_session(), http_client=http_client)
-        with pytest.raises(MatelabUsageError, match="title is null"):
-            _ = await client.records.list(notebook=notebook)
-
-
 @pytest.mark.asyncio
 async def test_read_current_record_maps_required_nullable_and_open_modules() -> None:
     async def handler(request: Request) -> Response:

{matelab_python_sdk-0.1.0a14 → matelab_python_sdk-0.1.0a15}/uv.lock

@@ -352,7 +352,7 @@ wheels = [
 
 [[package]]
 name = "matelab-python-sdk"
-version = "0.1.0a14"
+version = "0.1.0a15"
 source = { editable = "." }
 dependencies = [
     { name = "httpx2" },