matelab-python-sdk 0.2.0a1__py3-none-any.whl → 0.2.0a3__py3-none-any.whl

matelab/_generated/models.py

@@ -2,7 +2,7 @@
 #
 # @generated by datamodel-codegen:
 #   filename:  openapi.yaml
-#   version:   0.71.0
+#   version:   0.83.0
 
 from enum import Enum, StrEnum
 from typing import Annotated, Any, Literal

matelab/_transport.py

@@ -80,7 +80,7 @@ def _provider_error(code: int) -> MatelabAuthenticationError | MatelabProviderEr
 
 
 def _header(response: Response, name: str) -> str:
-    return cast(str, response.headers.get(name, ""))
+    return response.headers.get(name, "")
 
 
 def _parse_content_length(response: Response) -> int | None:
@@ -293,7 +293,8 @@ class SessionTransport:
                 raise MatelabTransportError("Could not exchange data with the Matelab Provider.") from None
 
             if response.status_code not in {200, 206}:
-                await response.aclose()
+                with suppress(RequestError):
+                    await response.aclose()
                 raise MatelabTransportError(
                     f"Matelab returned HTTP {response.status_code}.", status_code=response.status_code
                 )
@@ -321,7 +322,8 @@ class SessionTransport:
                     continue
                 raise _provider_error(code)
             if operation.media_types is not None and media_type not in operation.media_types:
-                await response.aclose()
+                with suppress(RequestError):
+                    await response.aclose()
                 raise MatelabProtocolError("Matelab returned an unexpected download media type.")
 
             content_length = _parse_content_length(response)
@@ -331,6 +333,7 @@ class SessionTransport:
                 or not _CONTENT_RANGE_PATTERN.fullmatch(_header(response, "Content-Range"))
                 or not _header(response, "Content-Disposition")
             ):
-                await response.aclose()
+                with suppress(RequestError):
+                    await response.aclose()
                 raise MatelabProtocolError("Matelab returned invalid partial-download metadata.")
             return DownloadStream(response, content_length=content_length)

matelab/domains/records.py

@@ -976,10 +976,9 @@ def _encode_record_rich_text(update: RecordRichTextUpdate) -> str:
     markers = set(_ATTACHMENT_MARKER_PATTERN.findall(update.html))
     if markers != set(update.attachments):
         raise MatelabUsageError("Rich-text attachment names must exactly match matelab-attachment:<name> markers.")
-    encoded = update.html
-    for name, attachment in update.attachments.items():
-        encoded = encoded.replace(f"matelab-attachment:{name}", _encode_record_attachment_reference(attachment))
-    return encoded
+    return _ATTACHMENT_MARKER_PATTERN.sub(
+        lambda match: _encode_record_attachment_reference(update.attachments[match.group(1)]), update.html
+    )
 
 
 def _validate_upload_filename(filename: str) -> None:
@@ -1001,15 +1000,15 @@ def _bind_comment_attachments(
 
     first = next(iter(selected_attachments.values()))
     binding_uid = first._binding_uid  # pyright: ignore[reportPrivateUsage]
-    for name, attachment in selected_attachments.items():
+    for attachment in selected_attachments.values():
         attachment_binding_uid = attachment._binding_uid  # pyright: ignore[reportPrivateUsage]
         if attachment.source != source or attachment_binding_uid != binding_uid:
             raise MatelabUsageError("Comment attachments must belong to the same record and upload batch.")
-        body = body.replace(
-            f"matelab-attachment:{name}",
-            attachment._temporary_url,  # pyright: ignore[reportPrivateUsage]
-        )
-    return body, binding_uid
+    bound_body = _ATTACHMENT_MARKER_PATTERN.sub(
+        lambda match: selected_attachments[match.group(1)]._temporary_url,  # pyright: ignore[reportPrivateUsage]
+        body,
+    )
+    return bound_body, binding_uid
 
 
 def _notebook_selector(notebook: NotebookRef) -> str | dict[str, JsonValue]:

matelab_python_sdk-0.2.0a3.dist-info/METADATA

@@ -0,0 +1,26 @@
+Metadata-Version: 2.5
+Name: matelab-python-sdk
+Version: 0.2.0a3
+Summary: Reusable async Python client for the Matelab Integration Contract
+Author: CMPDC, Institute of Physics, Chinese Academy of Sciences
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: asyncio,electronic-lab-notebook,eln,matelab,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx2<3,>=2.13.1
+Requires-Dist: jsonschema<5,>=4.26.0
+Requires-Dist: pydantic<3,>=2.13.5
+Requires-Dist: typing-extensions<5,>=4.16.0

{matelab_python_sdk-0.2.0a1.dist-info → matelab_python_sdk-0.2.0a3.dist-info}/RECORD

@@ -1,6 +1,6 @@
 matelab/__init__.py,sha256=C3CXRwVFMfaeyb55jl-MsNJtyUURKfuvVNlb_0mLxwM,5055
 matelab/_hashes.py,sha256=ImrLHx9wvcU6R-xGOrUCVDN_30sYA2UMn-NLwFrmFtU,163
-matelab/_transport.py,sha256=FdxpvEu9Fa4PPwBJ0LixlhUPR9NLCcdhuzRpE2PkGD4,14727
+matelab/_transport.py,sha256=hdDxNsVnEYoZvhtkD4hQLzsVhlOTKsU4wvCdOpHVDuI,14863
 matelab/_wire_validation.py,sha256=Z_PpxwLS0S18kCC8ah6CmxUEjzvQ-iP8_XBOoQ46Wt4,4752
 matelab/client.py,sha256=SXlrTX8ekf7ympTxCXlrt4tE3UHqM5adDj4EFUXGwWg,5068
 matelab/errors.py,sha256=CJjZH12nca_-41msyLYMrIDpIaQO4CDgz2LaQRVBzpQ,1630
@@ -8,19 +8,19 @@ matelab/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
 matelab/session.py,sha256=D8i9uyAt32-bADotS-Lrb7RpmWRNYNIkIpZUijTYvy4,899
 matelab/streaming.py,sha256=36epH2josWk87Ors_JY0YsjNmtiq3NZa2iB9djLmlnY,3792
 matelab/_generated/__init__.py,sha256=jmGbXLLe3JorsGU7OUdF8iKGewFMRqkCzgyFAw7C15w,79
-matelab/_generated/models.py,sha256=-73A-w2DdvQY300uzkIGWS2WYX7uzSQDguTA55t6Dg0,168733
+matelab/_generated/models.py,sha256=TzVbDt0NRx8R9i6GvRe5PVZpRKBgVDg5miKl6oNWKxc,168733
 matelab/domains/__init__.py,sha256=C34IWsGoCAwP7r6uYKJ79DJkToZyrZ4LWA87ufc1i0Q,65
 matelab/domains/_attachment_content.py,sha256=z26hwFpdgAk2x1w8EGe00XBLtJ3QFDX8BPS35Zc5SoE,1461
 matelab/domains/cloud_drive.py,sha256=EoqAYWvLVUfVOsic3g-TxsQEtAI3wTp5h0_vB79KpwY,10406
 matelab/domains/groups.py,sha256=H8-Da2WTm2Ui4m3Nr1bhMNMn7stbzbRa3EmpkTRmkBU,1300
 matelab/domains/literature.py,sha256=1KZPakc20ExorVV4gsBlcQJ9CspZY3KkdF77Z0WO5rk,27485
 matelab/domains/notebooks.py,sha256=_SvffaViECSEOkN5iwXtSv6El3fK2OYaR4RJvUCXfGk,13477
-matelab/domains/records.py,sha256=_LRmiQhYDys_QOFnvW60WszS4CBy_sD4U3_rjU8DBfY,92355
+matelab/domains/records.py,sha256=n-YfsBbGZOjj1j2keqjHyckHAJ6ZLfYB9J1bto__q9g,92322
 matelab/domains/templates.py,sha256=AsnayIc72J9pPTgcFpo8IfaM2a2C-acL6k8sdRH3rt8,17386
 matelab/domains/uploads.py,sha256=J9YveZIHq03YQuWwRZwayP1-tz7cE0F17RIgWByLcvc,7368
 matelab/domains/users.py,sha256=ZhlLzC_AadwYqNqxQrqkUBgIUqL7MJ6FgMyxwq-az8s,1445
-matelab_python_sdk-0.2.0a1.dist-info/METADATA,sha256=a1CgAGTSrMMgM4WdjFISYU1YcUs12ZNdelz5b_AReYQ,63475
-matelab_python_sdk-0.2.0a1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-matelab_python_sdk-0.2.0a1.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-matelab_python_sdk-0.2.0a1.dist-info/licenses/NOTICE,sha256=Hc4scCJTof5VL3JCPI2aaewnnzCejIHUGuBVYBf-klc,98
-matelab_python_sdk-0.2.0a1.dist-info/RECORD,,
+matelab_python_sdk-0.2.0a3.dist-info/METADATA,sha256=wdiO0RLndPd6fjQHtHo7WfW63JYLQYtey1BiVvZ4yeo,1086
+matelab_python_sdk-0.2.0a3.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+matelab_python_sdk-0.2.0a3.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+matelab_python_sdk-0.2.0a3.dist-info/licenses/NOTICE,sha256=Hc4scCJTof5VL3JCPI2aaewnnzCejIHUGuBVYBf-klc,98
+matelab_python_sdk-0.2.0a3.dist-info/RECORD,,

{matelab_python_sdk-0.2.0a1.dist-info → matelab_python_sdk-0.2.0a3.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.31.0
+Generator: hatchling 1.32.4
 Root-Is-Purelib: true
 Tag: py3-none-any

matelab_python_sdk-0.2.0a1.dist-info/METADATA

@@ -1,993 +0,0 @@
-Metadata-Version: 2.4
-Name: matelab-python-sdk
-Version: 0.2.0a1
-Summary: Reusable async Python client for the Matelab Integration Contract
-Author-email: 朱天念 <zhutiannian@gmail.com>
-License-Expression: Apache-2.0
-License-File: LICENSE
-License-File: NOTICE
-Keywords: asyncio,electronic-lab-notebook,eln,matelab,sdk
-Classifier: Development Status :: 3 - Alpha
-Classifier: Framework :: AsyncIO
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: Scientific/Engineering
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Typing :: Typed
-Requires-Python: >=3.11
-Requires-Dist: httpx2<3,>=2.9.1
-Requires-Dist: jsonschema<5,>=4.26
-Requires-Dist: pydantic<3,>=2.13.4
-Requires-Dist: typing-extensions<5,>=4.14.1
-Description-Content-Type: text/markdown
-
-# matelab-python-sdk
-
-Reusable async Python client for the Matelab Integration Contract.
-
-This README describes the current SDK interface, integration semantics, examples, and runnable workflows. See
-[CONTEXT.md](CONTEXT.md) for domain terminology, [CHANGELOG.md](CHANGELOG.md) for version deltas,
-[AGENTS.md](AGENTS.md) for durable maintenance rules, and `docs/operation-coverage.yaml` for the machine-readable
-operation inventory.
-
-The current alpha is `0.2.0a1`. `[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 v2026.10.1` Contract Release. The sole pin,
-`contracts/matelab-integration-v1.lock.json`, records peeled commit `9941e2d623a1c2633adb459b823d78d4e62d3802`,
-source `openapi/matelab-integration-v1.openapi.yaml`, the local snapshot path, and SHA-256
-`a07997128c1df17a03724c5af8e11b45a34166f9d6e15558e66e0a301f2e0813`. The annotated tag object is
-`ae8098e1b5178b69706bddd8b70c1b4cfe3e09ba`.
-
-## Installation
-
-Python 3.11 or newer is required. Install the alpha from a package index with either:
-
-```bash
-uv add matelab-python-sdk
-```
-
-```bash
-python -m pip install matelab-python-sdk
-```
-
-Development installs use the locked checkout:
-
-```bash
-uv sync --frozen
-```
-
-To test the same artifact a downstream Consumer will install, build and install the wheel:
-
-```bash
-uv build --no-build-isolation --out-dir dist/release
-python -m pip install dist/release/matelab_python_sdk-0.2.0a1-py3-none-any.whl
-```
-
-Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
-tag, commit, and checksum recorded below.
-
-The Contract uses Provider source evidence from `3f39d47b7ad43bed618b029a7d9cc51fab852eb6`; v2026.10.1 validation ran
-against an isolated test instance and does not establish production behavior. The corresponding Front Consumer evidence
-is `0c985f5b6da8e8ef4627ca7065cea85e408ae981`; it informs cross-Consumer capability review but does not define the SDK
-interface. Provider limitations that remain relevant to integrations are documented alongside the affected interfaces
-below.
-
-Contract releases now use calendar versions to identify Provider-specific snapshots. This snapshot covers the
-Workerman runtime with the `localhost` data-server branch for ELN records and attachments; remote data-server
-forwarding is outside its verified callable scope (PVD-049).
-
-## Versioning
-
-SDK versions express compatibility of the public Python interface and behavior. Python prerelease spelling follows
-PEP 440: `0.2.0a1` is the first alpha candidate for `0.2.0`. During `0.x` development, incompatible changes advance
-the minor version. From `1.0.0`, compatible fixes advance patch, compatible additions advance minor, and incompatible
-changes advance major. Successive candidates for the same target version use `aN`, `bN`, or `rcN`.
-
-Contract calendar versions identify Provider wire snapshots independently. Each SDK release records its exact
-Contract tag, commit and checksum in the lock; multiple SDK fixes can use the same Contract release. Adopting a new
-Contract changes the SDK version according to its public impact. See [CHANGELOG.md](CHANGELOG.md) for migration details.
-
-## Design
-
-The public module is intentionally small:
-
-```python
-from matelab import AsyncMatelab, RecordLocator
-
-async with AsyncMatelab() as client:
-    session = await client.authenticate("user@example.org", "password")
-    assert client.session is session
-    notebooks = await client.notebooks.list()
-    notebook = notebooks.owned[0].ref
-    records = await client.records.list(notebook=notebook)
-    source = RecordLocator(notebook=notebook, record=records.records[0].ref)
-    record = await client.records.read(source)
-```
-
-`AsyncMatelab()` uses `https://matelab.iphy.ac.cn/api` by default. Pass another Provider API root
-explicitly when needed, for example `AsyncMatelab("https://custom.example/api")`.
-
-### Error handling
-
-Catch `MatelabError` once at an integration seam. Every instance exposes a stable `category: MatelabErrorCategory` and
-`retryable: bool`. `MatelabProviderError` additionally exposes `provider_code: int` and `provider_message: str`, so a
-gateway can retain a stable diagnostic code and safe summary while routing recovery through the integration-level
-category:
-
-| Error | Category | Retryable | Meaning and normal response |
-|---|---|---:|---|
-| `MatelabAuthenticationError` | `AUTHENTICATION` | No | The Session or credentials cannot authenticate; obtain valid authentication before making a new call. |
-| `MatelabUsageError` | `VALIDATION` | No | The call cannot be represented safely; correct its arguments. |
-| `MatelabProviderError` | `BUSINESS`, `VALIDATION`, or `UPSTREAM` | No | The Provider rejected the request; record `provider_code` and route recovery by `category`; `provider_message` is an SDK-owned safe summary. |
-| `MatelabTransportError` | `UPSTREAM` | No | The HTTP exchange failed; `status_code` is present for HTTP failures, and a mutation outcome may be unknown. |
-| `MatelabProtocolError` | `UPSTREAM` | No | The response violates the pinned Contract or cannot supply the structured result required by the SDK operation; inspect the Provider result or SDK boundary. |
-
-For `MatelabProviderError`, the SDK maps Provider wire code `2` to `BUSINESS`, `4` to `VALIDATION`, and `3` or an
-unknown code to `UPSTREAM`. `provider_code` is diagnostic metadata, not a stable routing identifier, and integrations
-must not reinterpret it instead of `category`. `provider_message` and the exception string are SDK-owned safe summaries
-selected from the code mapping; they do not reproduce Provider-authored text. Authentication codes remain hidden behind
-`MatelabAuthenticationError`; code `5`
-triggers at most one refresh and replay only for authenticated operations that explicitly enable
-`retry_on_access_expired`, otherwise codes `1` and `5` raise `MatelabAuthenticationError` directly.
-Record operations accept business code `0`. Provider-internal forwarding code `10` is outside the pinned
-callable Contract and raises `MatelabProtocolError` rather than assigning an error category.
-`MatelabTransportError.status_code` remains available for HTTP failures. Provider response bodies, top-level `msg`,
-legacy `errmsg`, opaque `errs`, uncontracted debug fields, and request payloads are not attached to exceptions because
-Provider-authored diagnostics may contain stack traces, credentials, or submitted values.
-The pinned v2026.10.1 Contract also declares optional code-4 `errs`, but PVD-029 and PCG-010 record opaque array/object
-containers and insufficient evidence for requiredness, cardinality, or exclusion from other codes. The SDK
-therefore keeps those diagnostics wire-only and does not expose `errs` as stable public metadata. A typed detail
-interface remains blocked until a future Contract release can define one from stronger Provider evidence. `retryable`
-means the identical SDK call is safe to replay without further interpretation. It is conservatively `False` for every
-current SDK error because the Contract does not guarantee mutation idempotency or outcome; an integration may add a
-narrower operation-specific retry policy only when it owns that evidence.
-
-### Session ownership
-
-Each `AsyncMatelab` instance owns at most one current, process-local `Session`. The SDK injects its bearer
-token, refreshes it under a per-instance async lock, performs bounded safe retries, and exposes every token
-rotation through `client.session`. If refresh succeeds but the subsequent business request fails,
-`client.session` still contains the refreshed token pair.
-
-| SDK responsibility | Integrator responsibility |
-|---|---|
-| Bearer injection, expiry checks, refresh and bounded retry | Redis/database/file persistence and encryption |
-| Per-instance, in-process refresh serialization | Cross-process locking and conflict handling |
-| Contract validation of token and identity responses | Mapping `userid`/`session_id` to a persisted `Session` |
-| Latest immutable `Session` through `client.session` | Revocation, cleanup, and saving after each call |
-
-`Session`, `Token`, and `Identity` are frozen Pydantic models and form the stable, normalized SDK Session contract.
-Their JSON fields are `access`, `refresh`, and `identity`; tokens contain `value` and `expires_at_ms`, while identity
-contains `userid`, `username`, and `email`. Provider envelope fields are not part of this model. An `Identity` requires
-a positive userid and non-empty username; its email may be `None`.
-
-Token values are excluded from model representations but intentionally remain present in `model_dump()` and
-`model_dump_json()` so an integration can persist and restore the complete Session:
-
-```python
-serialized = session.model_dump_json()
-restored = Session.model_validate_json(serialized)
-assert restored == session
-```
-
-The serialized result contains live credentials. Encrypt it at rest and never write it to logs or send it to an
-untrusted party. The SDK does not read tokens from environment variables and does not provide a session store.
-
-Credential authentication installs the returned Session on the client:
-
-```python
-async with AsyncMatelab() as client:
-    session = await client.authenticate(username, password)
-    assert client.session is session
-```
-
-Restore a previously validated Session by passing it to the constructor. Construction performs no network request:
-
-```python
-persisted_session = await session_store.load(userid, session_id)
-
-async with AsyncMatelab(session=persisted_session) as client:
-    result = await handle_request(client)
-```
-
-Every Session contains a validated identity, and refreshing a restored Session preserves it. Integrations that
-construct a Session from an external assertion are responsible for validating that assertion and the identity-token
-association before passing the complete Session to the SDK; the SDK does not accept bare external token pairs.
-
-A Web or MCP integration should create one client for one logical session, then save the latest Session in
-`finally`, including when a business call fails after refresh:
-
-```python
-persisted_session = await session_store.load(userid, session_id)
-client = AsyncMatelab(session=persisted_session, http_client=shared_http_client)
-
-try:
-    result = await handle_request(client)
-finally:
-    latest_session = client.session
-    try:
-        if latest_session is not None:
-            await session_store.save(userid, session_id, latest_session)
-    finally:
-        await client.aclose()
-```
-
-If several processes can use the same persisted session, the integration must place its own distributed lock
-around load, use, and save. The SDK lock only coordinates refreshes inside one `AsyncMatelab` instance.
-
-Different logical sessions require different clients. They may reuse the same externally managed HTTP connection
-pool, but must never share one global `AsyncMatelab` singleton:
-
-```python
-alice_client = AsyncMatelab(session=alice_session, http_client=shared_http_client)
-bob_client = AsyncMatelab(session=bob_session, http_client=shared_http_client)
-```
-
-An injected `http_client` must be an `httpx2.AsyncClient`. The independently distributed `httpx.AsyncClient` has
-similar methods but uses incompatible request, response, transport, and exception types.
-
-`src/matelab/_generated` is a private wire layer. Applications should not depend on its file
-layout or generated class names. The distribution includes `py.typed`, so type checkers can consume the
-public annotations directly from an installed wheel.
-
-The current public domain scope includes authentication, group/user discovery, template and notebook
-lifecycle operations, record discovery/lifecycle operations, comment reads, and streaming record or
-comment attachment downloads, resumable file staging, literature discovery/lifecycle workflows, and
-personal cloud-drive management.
-
-### Uploading a record attachment
-
-`records.upload_attachment()` prepares a file without choosing a target record. The returned `StagedAttachment` can
-be supplied to one later `import_dataset()` or `update()` in the same notebook by the same authenticated uploader:
-
-```python
-from matelab import RecordImportItem
-
-content = b"measurement data"
-staged = await client.records.upload_attachment(notebook, filename="measurement.csv", content=content)
-record_ids = await client.records.import_dataset(
-    notebook=notebook,
-    template_title="Example Template",
-    items=(
-        RecordImportItem(
-            record_uid="REC-IMPORT-001",
-            title="Imported measurement",
-            data={"Attachments": {"File": [staged]}},
-            keywords=("measurement", "calibration"),
-        ),
-    ),
-)
-```
-
-`RecordImportItem.data` uses the recursive `RecordImportValue` type: JSON-compatible scalars and nested mappings,
-lists, or tuples may contain a `StagedAttachment` wherever the template expects a file. Arbitrary Python
-objects are outside the interface and are also rejected at runtime before a Provider request.
-
-`content` accepts `bytes`, a synchronous `IO[bytes]`, or an `AsyncIterable[bytes]`. Callers do not supply a size,
-checksum, or multipart content type. The SDK calculates the SHA-256 itself; streams are fully consumed into a
-`SpooledTemporaryFile`, rewound, and only then sent to the Provider. Temporary-file write, seek, read, and close
-operations run outside the event-loop thread, including after the spool rolls to disk. The Contract fixes attachment
-parts to `application/octet-stream`.
-
-An exception raised by an async source is propagated unchanged after the SDK closes its temporary file. The SDK reads
-streams through end-of-file and imposes no upload-size policy; callers remain responsible for limits such as an HTTP
-endpoint's maximum accepted body size. `records.upload_comment_attachment()` uses the same content interface and also
-generates its Provider binding internally. When multiple new attachments will be saved into one comment, pass the
-first staged comment attachment as `batch=` on each later upload; callers never handle the Provider UID directly.
-`uploads.stage()` remains a separate resumable-fragment interface and does not accept async content because its
-per-fragment offset and completion semantics are different.
-
-`StagedAttachment` carries the upload notebook selector, uploader, Provider-resolved binding, filename, and hash.
-Callers do not supply a staging identity; the SDK generates the upload-event value and uses the validated response
-metadata as the completed staging result. The handle deliberately carries no `RecordLocator`: the Provider staging row
-is not bound to a record, so record identity belongs only to the later import or update operation. Provider temporary
-row IDs are not exposed.
-
-The Provider supplies no staging status, abort, TTL, atomicity, idempotency, or retry guarantee. Integrations that
-persist handles must durably claim their own `uploaded -> finalizing/indeterminate` transition before calling a
-finalizer.
-
-### Attachment-bearing record update boundary
-
-`records.update(source, changes, ...)` accepts one non-empty sequence of `RecordChange` intents. Value updates and
-deletions, module changes, attachments, file structure, and rich text all cross this single interface; the SDK reads
-the current record, validates conflicts, and compiles them into the Provider's `modify`, `del`, `addModule`,
-`delModule`, and `add` operation families. The input sequence groups update intent; it is not an execution-order DSL,
-because the Provider operation families determine wire ordering.
-
-For an existing record, upload against its notebook and pass the same `StagedAttachment` type as one change; callers
-never construct Provider attachment paths or attachment strings:
-
-```python
-from matelab import RecordFormAttachmentFieldAddition, RecordTableFileCellSet, RecordTableRowAttachmentAppend
-
-uploaded = await client.records.upload_attachment(source.notebook, filename="measurement.csv", content=content)
-
-await client.records.update(
-    source, (RecordFormAttachmentFieldAddition(module="Attachments", name="Measurement", attachment=uploaded),)
-)
-
-# Each of the following is a separate update with a fresh upload.
-await client.records.update(
-    source, (RecordTableFileCellSet(table="Measurements", column="Evidence", row=0, attachment=another_uploaded),)
-)
-
-await client.records.update(
-    source,
-    (
-        RecordTableRowAttachmentAppend(
-            table="Measurements", file_column="Evidence", values={"Label": "Sample C"}, attachment=third_uploaded
-        ),
-    ),
-)
-```
-
-These three operations use the Provider's staged-name finalizer and must be the only mutation in their update request.
-`RecordTableFileCellSet` requires an existing file column and a cell whose immediate canonical value is exactly
-`null`. `RecordTableRowAttachmentAppend` addresses the new row by the row count from the SDK's immediate read and
-supports one file column. A locally rejected target does not spend the handle; once transport starts, an ambiguous
-result cannot be retried through the same client.
-
-Files-module append at the module root and table/files replacement may be combined with other non-conflicting record
-changes. `RecordFilesAttachmentAppend.folder_path` optionally selects folders within the files module. A non-empty
-path uses the staged-name finalizer and must be the only mutation in its update request; the SDK validates every
-segment before writing to avoid the Provider's malformed-path fallback to the module root (PVD-030):
-
-```python
-from matelab import RecordAttachmentReplacement, RecordFilesAttachmentAppend, RecordValueUpdate
-
-await client.records.update(
-    source,
-    (
-        RecordValueUpdate(path=("Metadata", "Reviewed"), value=True),
-        RecordFilesAttachmentAppend(module="Files", attachment=files_uploaded, caption="Evidence"),
-    ),
-)
-```
-
-To append within a folder, use a fresh upload in a separate update:
-
-```python
-await client.records.update(
-    source,
-    (RecordFilesAttachmentAppend(module="Files", attachment=folder_uploaded, folder_path=("Evidence", "Raw Data")),),
-)
-```
-
-For `RecordModuleCreation(module_type="code", language="json", style="echarts")`, omitted, null, and empty `data` all
-produce an empty string; explicit `"0"` stays `"0"`. Send the desired initial chart configuration as a JSON code string.
-Richtext/code module creation defaults missing `data` to `""`; form/table/files creation ignores it and initializes
-content as `[]`.
-
-A replacement starts with an occurrence returned by `records.read()`; applications must not fabricate a
-`RecordAttachmentRef`. The same `RecordAttachmentReplacement` covers both table-file and files-module occurrences:
-
-```python
-record = await client.records.read(source)
-existing = next(
-    attachment
-    for attachment in record.attachments
-    if attachment.location is not None and attachment.location.kind == "files_module"
-)
-await client.records.update(
-    source, (RecordAttachmentReplacement(existing=existing, replacement=replacement, caption=None),)
-)
-```
-
-For a files occurrence, `caption=None` preserves the observed string caption (an observed null caption normalizes to
-the required empty string). Table replacement requires exactly one current attachment in the selected cell and does
-not accept a caption. Record reads likewise accept only one canonical attachment object or `null` in a table file cell;
-an attachment array violates the pinned response contract. Both replacement forms require the replacement hash to
-differ from the current occurrence.
-
-As a temporary Provider-compatibility exception, `records.read()` also accepts a table file attachment object whose
-otherwise valid `filename`, `hash`, and `size` are present but whose Contract-required `timestamp` is omitted. The SDK
-preserves that omission in `Record.modules` and does not invent a timestamp; null timestamps and all other malformed
-attachment shapes remain response errors. This exception can be removed after the Provider canonicalizes current and
-historical record content.
-
-All record attachment intents reject handles from another notebook or authenticated uploader, duplicate use within one
-finalization request, and raw Provider attachment references. Row/index-based operations use an immediate SDK read and
-must not be called while a concurrent editor is known to be active. The Provider offers no expected hash or revision,
-so the SDK does not present its read-before-write checks as concurrency control.
-
-File-bearing structure changes do not consume staging:
-
-```python
-from matelab import RecordFormFileFieldDeletion, RecordTableFileColumnAddition, RecordTableFileColumnDeletion
-
-await client.records.update(
-    source,
-    (
-        RecordTableFileColumnAddition(table="Measurements", name="Additional evidence"),
-        RecordFormFileFieldDeletion(form="Attachments", name="Obsolete evidence"),
-        RecordTableFileColumnDeletion(table="Measurements", name="Old evidence"),
-    ),
-)
-```
-
-The SDK emits the v0.1.2 dedicated operations: a new file column omits wire `data`; whole
-form-field/table-column deletion uses a strict two-segment target. It does not expose a three-segment delete as
-table-cell clearing.
-
-Deleting a complete canonical module is also supported even when the current read observes attachments in it:
-
-```python
-from matelab import RecordModuleDeletion
-
-result = await client.records.update(source, (RecordModuleDeletion("Raw files"),))
-```
-
-This requests only a canonical record-content mutation. A successful response acknowledges the submitted mutation;
-it does not prove attachment-quote cleanup or byte deletion. Collaboration-pending is reported as
-`"pending"`, not persisted.
-
-`RecordRichTextUpdate` accepts the same `StagedAttachment` as import and other update intents. Attachment-bearing
-multi-record import is forbidden, so callers must split it into single-record imports with a fresh staged attachment
-for each request. Once an import or update request using a staged attachment starts, that handle cannot be retried or
-used for the other finalizer through the same client.
-
-## Operation coverage
-
-The SDK tracks all 71 Contract operations and exposes 69 through public domain interfaces; identity bootstrap and the
-frontend literature-creation template are intentionally unexposed. It deliberately excludes MCP migration,
-adjacent-repository changes, external publishing, and automatic mutation against a real Provider.
-
-Machine-readable status lives in
-`docs/operation-coverage.yaml`. An exact-coverage test keeps its 71
-operation IDs, methods, paths, states, public interfaces, and Provider issue references aligned with the pinned
-OpenAPI snapshot.
-
-| Domain | Implemented | Planned | Current public surface |
-|---|---:|---:|---|
-| Authentication | 3 | 0 | `authenticate`, `refresh`, `exchange_chat_sso_code`; identity bootstrap intentionally unexposed |
-| Groups and users | 2 | 0 | `groups.list`, `users.search` |
-| Notebooks | 6 | 0 | `notebooks.list/create/update/shares/share/update_share/unshare` |
-| Records | 18 | 0 | Discovery, reads, lifecycle, typed patch/attachments, relations, and downloads |
-| Comments | 5 | 0 | Read, staged attachment upload, create/update/delete, and download |
-| Templates | 13 | 0 | Discovery, content, lifecycle, sharing, groups, and marketplace |
-| File staging | 1 | 0 | Resumable fragment staging and compensating abort request |
-| Literature | 12 | 0 | Libraries, items, canonical metadata, comments, sharing, PDF lifecycle and streaming |
-| Cloud drive | 9 | 0 | Personal root/folders/files, staged binding, metadata, move/delete and streaming |
-| **Total** | **69** | **0** | Two operations are intentionally unexposed |
-
-### Stability and known capability limits
-
-Coverage currently contains 13 `stable`, 56 `experimental`, and two `not_applicable` operations. The stable operation
-IDs are `loginTokenSet`, `refreshTokenSet`, `exchangeChatSsoCode`,
-`shareMultipleTemplatesWithUsers`, `removeTemplateFromGroup`, `deleteNotebookShare`, `listNotebooks`,
-`listNotebookRecords`, `exportRecords`, `deleteRecordsByUid`, `copyRecord`, `readRecord`,
-and `deletePersonalLiteratureItem`.
-
-Every other implemented operation is explicitly `experimental`; the exact per-operation list and its
-PVD/PCG references live in
-`docs/operation-coverage.yaml`. `readApplicationBootstrap` is intentionally unexposed because it returns the Provider
-application environment and menu model, including required `data_express_enable` and `data_express_text` fields, while
-SDK identity is sourced from token issuance. `readLiteratureCreateTemplate`
-is intentionally unexposed because it returns a frontend form definition and an optional deployment flag rather than
-a resource needed by the SDK interface. There are no `planned` operations. Experimental support means the SDK
-validates and exposes the pinned Contract while preserving limitations such as unstable ordering/pagination,
-incomplete mutation acknowledgements, missing batch atomicity or idempotency, weak attachment ownership binding, and known
-Provider authorization gaps. It does not turn those limitations into SDK guarantees.
-
-Chat iframe SSO consumes a one-time code and shared key. Both arguments are treated as secrets, the request is never
-automatically retried, and the returned token set is stored in the same in-memory `Session` shape as credential login:
-
-```python
-session = await client.exchange_chat_sso_code(code="chat-sanitizedcode123", key="sanitized-shared-key")
-```
-
-The code suffix must be non-empty and the shared key must be non-blank. The Provider rejects a code after the current
-user's `active_datetime` plus 300 seconds; that timestamp can change through other user activity, so Consumers must not
-derive a deadline from the code or automatically retry an uncertain exchange. A sequential replay is rejected, but the
-Provider's read-then-clear implementation does not guarantee that concurrent exchanges have only one winner.
-Ordinary credential login does not expose the non-empty WeChat binding code branch, which can reassign another account's
-OpenID (PVD-032).
-
-Group and user discovery expose sharing identities without inventing Provider pagination:
-
-```python
-groups = await client.groups.list()
-targets = await client.users.search("Example Researcher", global_scope=False)
-```
-
-`groups.list()` returns the `GroupSummary` tuple directly. Ordering remains Provider-unspecified and is documented
-rather than repeated as a constant result field. The Provider's members for an unstable first group remain wire-only;
-`users.search()` is the public recipient-discovery interface. These two discovery interfaces are experimental because
-group order is unstable and user search is unpaged, unordered and not field-minimized (PVD-017, PVD-025).
-`GroupSummary.notebook_creation_available` expresses whether the group can currently host notebook creation without
-exposing the Provider's data-server routing value.
-An observed dangling group membership has `GroupSummary.ref=None` and no usable group identity. If such a membership
-is selected as the Provider's first group, the whole request can fail with a Provider error (PVD-048).
-
-Notebook create and direct sharing use the Provider acknowledgement without an automatic follow-up read:
-
-```python
-from dataclasses import replace
-
-await client.notebooks.create(title="Example Notebook")
-shares = await client.notebooks.shares(notebook)
-await client.notebooks.share(notebook, [target.ref])
-share = shares.shares[0]
-await client.notebooks.update_share(
-    share.ref, replace(share.permissions, can_write_records=True, can_create_records=True)
-)
-```
-
-Create, update, share, permission update, and unshare return `None` because their Provider responses contain no new
-resource representation. Updating notebook metadata first reads the current owned-notebook wire snapshot so the SDK
-can preserve the Provider's UI-only type tags and list-display configuration, which the public SDK does not expose.
-Consequently, update performs one list pre-read followed by the write. This preservation is best effort because the
-Provider offers no compare-and-swap or atomic read-modify-write operation. Call `list()` or `shares()` explicitly when
-the application needs current state. `NotebookPermissions` normalizes the Provider's stored and effective masks and
-is reused by record pages instead of maintaining a second nearly identical permission model. Direct shares always
-have implicit read access even when every optional permission is false (PVD-037).
-`provider_signing_allowed` only represents Provider policy, not an SDK signing operation. Share-list order remains
-unspecified.
-Stored notebook type configuration may decode to any non-null JSON value, but metadata writes accept arrays only.
-If the stored configuration or display extraction requests cannot be preserved within the write Contract, update
-raises `MatelabProtocolError` before sending a mutation instead of silently replacing them (PVD-046).
-
-Template discovery keeps a template database identity separate from direct-share, market-acquisition, and group
-relation identities:
-
-```python
-templates = await client.templates.list()
-market = await client.templates.search_market("calibration", page=1, page_size=20)
-owned = next(template for template in templates if template.scope == "owned")
-modules = await client.templates.read(owned.ref)
-```
-
-Template content is exposed as canonical `TemplateModule` values and saved as a complete replacement:
-
-```python
-modules = await client.templates.read(template)
-# Build the complete replacement from these canonical modules.
-await client.templates.save_content(template, modules)
-```
-
-`TemplateModule.data_present` distinguishes a missing `data` property from an explicit null value, while
-`attributes` prevents additive canonical properties from being dropped during a read/save cycle. The SDK does not
-synthesize frontend editor UIDs, layout widths, rows, folders, option encoding, or a fixed set of display module
-types. A JSON-language code module's `data` remains code text and may be empty, null, or invalid JSON;
-`language=json` does not imply that Consumers can parse it. When template content contains a code module with
-`language=json` and non-null `style`, its code text must be valid JSON to save. Number and boolean table cells preserve
-the Provider's empty string as distinct from scalar and `null` values. The Provider accepts some
-non-canonical module roots and arbitrary table file arrays, but the SDK does not expose that behavior: saved content
-must remain a canonical module list, and a table file cell must be one canonical attachment object or `null` (PVD-013).
-The Provider supports only whole-content replacement and has no atomic patch or compare-and-swap operation (PCG-008),
-so a read-modify-save sequence can overwrite a concurrent change.
-
-The market result retains the Provider's `total_count` and derives `has_more` without echoing the caller's page
-arguments; it does not claim a stable order or continuation token. Template reads remain experimental
-because Provider discovery ordering/pagination and historical `images` compatibility are not fully stable
-(PCG-011, PCG-012, PVD-038, PVD-022).
-
-`templates.list()` returns one tuple. `TemplateSummary.scope` is limited to `owned`, `shared`, `group`, and `public`;
-Provider marketplace acquisitions and system defaults are both public templates. An acquired public template carries
-a user-library relation while a default does not. Provider `pending[]` is an administrator review queue rather than a
-visibility scope and is not returned as an ordinary template. Owned rows expose their actual submission state through
-`market_review_pending`. User-library and group-library relations occupy different identity spaces;
-`TemplateLibraryEntryRef.kind` records that distinction and `remove_from_library()` routes to the correct Provider
-operation. Direct shares and marketplace acquisitions intentionally share the same user-library removal semantics.
-
-Template writes remain separate operations: metadata, canonical modules, and usage HTML are not presented as one
-transaction. Creation returns the new `TemplateRef`; metadata replacement and other mutations return `None` because
-the Provider supplies no new resource representation. `update()` therefore requires the complete title, summary, and
-keyword set rather than implying a partial patch. `update_usage()` generates the Provider's required fresh hidden
-correlation value internally. Usage attachments remain unsupported until their staging and binding lifecycle is
-contracted safely (PVD-003). Marketplace revision limitations remain explicit through `content_version`,
-`published_content_version`, and `market_review_reason` (PVD-021).
-
-Extended record reads stay behind the same `records` interface:
-
-```python
-from matelab import RecordLocator
-
-source = RecordLocator(notebook=notebook, record=record)
-exported = await client.records.export([source])
-matches = await client.records.search({"notes": ("Notes",)}, notebooks=[notebook])
-page = await client.records.page(notebook, search="voltage")
-deleted = await client.records.recycle_bin(notebook)
-relations = await client.records.relations(source)
-```
-
-`records.export()` returns `ExportedRecord` snapshots directly as a tuple. Their canonical stored content is exposed
-as `modules`; it is not the template-shaped `RecordImportItem.data` accepted by record import.
-`records.search()` maps each requested field name to a stored record path. A match exposes only Provider-returned
-entries in `values`, so key membership distinguishes an absent result from an explicit JSON `null`.
-Extraction aliases cannot use `id`, `uid`, `eln_id`, `title`, or `eln_name`, which would overwrite result metadata
-(PVD-043). Paths contain one to four segments: the first three accept non-empty, non-numeric names or non-negative
-integer indices; a fourth segment must be a non-numeric property name. Numeric strings are rejected before HTTP.
-The current Provider excludes encrypted records from search (PVD-041); an empty search result therefore does
-not prove that no matching encrypted record exists.
-
-The Provider calls its notebook directory tree `subtype`; that name remains wire-only. The SDK exposes
-`RecordFolder`, `RecordSummary.folder_id`, and the `folders` returned with record listings. A top-level folder has
-`parent_folder_id=None`, and SQL `NULL` counts are normalized to zero. Records at the notebook root have
-`folder_id=None`. For `records.page()`, omit `folder_id` to include all folders, pass `0` for root records, or pass a
-positive folder ID for one folder.
-
-`records.page` fixes the legacy request to `page_size=0&default=1`, preventing the known owner-preference writes
-described by PVD-028; its total is derived internally from the Provider's complete matching ID list. The result keeps
-semantic `NotebookPermissions` directly, without a shallow context model or duplicated notebook/owner/template
-display metadata. Effective request pagination, the UI selection list and Provider keyword-filter echo are not exposed.
-Its `search` argument, shared with `records.list()`, maps the Provider's wire-level `content` filter without exposing
-that ambiguous name.
-It remains distinct from the unpaged integration `records.list()` operation: only the legacy page response supplies
-effective permissions, folders and total matching identities, so merging the two would introduce nullable fields.
-Active and deleted records use the same `RecordRef`; recycle-bin state is expressed by `DeletedRecordSummary`, not a
-second identity type. Public catalog records use a distinct identity because their catalog and source IDs differ.
-Public summaries keep source notebook attribution but omit the Provider's unused publication-lock residue and owner
-email; their `notebook_title` follows the same naming used by export and search results. Relation refs retain only the
-stored relation row and declared target IDs; nullable JOIN previews and resolved target identity stay wire-only.
-Search and relation order remain unspecified, and no continuation token is invented. Export and search return tuples
-directly. Remote data-server forwarding code `10` is rejected because only local data-server results are covered.
-`DeletedRecordPage` does not repeat its input notebook.
-
-Record creation keeps blank creation and structured import as separate capabilities:
-
-```python
-from matelab import RecordImportItem
-
-await client.records.create_blank(
-    notebook=notebook, title="Blank Record", record_uid="caller-generated-uid", folder_path=("Measurements",)
-)
-imported = await client.records.import_dataset(
-    notebook=notebook,
-    template_title="Example Template",
-    items=[
-        RecordImportItem(
-            record_uid="import-uid", title="Imported", data={"Notes": "value"}, folder_path=("Measurements",)
-        )
-    ],
-)
-```
-
-Blank-record creation returns `None` because the Provider returns no record identity, even when the caller supplies a
-UID. Import validates the complete batch with generated wire models but cannot map returned database IDs to
-individual inputs or promise atomicity (PCG-009); it therefore returns only the tuple of database IDs actually
-reported by the Provider. `RecordImportItem.keywords` is a tuple; the adapter owns the Provider's
-legacy semicolon encoding. Folder paths are ordered existing folder titles from the notebook root; they do not create
-missing folders. The current Provider rejects explicit-null table-file imports (PVD-031). Because the SDK accepts
-arbitrary template-shaped data and cannot identify file columns without the template definition, integrations must omit
-an unset file-valued key instead of sending it as `None`. Delete means moving records into the recycle bin, not permanent
-deletion. Delete and restore return `None`; record mutations are not automatically retried.
-
-`records.copy()` accepts an optional `new_record_uid`; when omitted, the SDK generates one locally. The Provider
-returns only the copied row's database ID, so retaining that UID lets the SDK return a complete `RecordLocator`
-without a readback request. Omitting `target_notebook` copies within the source notebook.
-
-Record patching exposes a deliberately narrower capability than the raw Provider operation. Scalar/module changes
-cannot smuggle Provider-native attachment strings; staged attachments use separate form-removal, table-replacement,
-files append/replace/remove, and rich-text types. Unsafe form replacement and table-file removal are absent, while a
-files/images removal is rejected when the observed module contains the same hash more than once (PVD-010, PVD-018,
-and PVD-019). The SDK reads current content only when a change needs attachment type, occurrence, row, or index state;
-ordinary module creation and deletion rely on the Provider's own canonical update validation. `records.update()`
-returns the acknowledgement classification
-`"persisted"`, `"pending"`, or `"unknown"`; it does not
-issue a post-write read. Database, active-browser, and unclassified acknowledgements remain distinct, and mutation
-retries stay disabled. Business code `0` alone does not distinguish persisted data from a browser collaboration
-broadcast; the classification uses the observed Provider acknowledgement and supplies no revision or atomicity
-guarantee. Current collaboration peers must be browsers viewing the same notebook and record.
-Encrypted reads return `Record.encrypted_modules` as an `EncryptedRecordModules` containing the ciphertext,
-algorithm and additive fields; `modules` and `attachments` are empty because no plaintext is available. Plaintext
-reads have `encrypted_modules=None`. State-dependent updates reject encrypted content before mutation, while
-ordinary module changes rely on the Provider's password validation before any write. The password and decryption
-lifecycle remain unexposed. The list-level `RecordSummary.encrypted` flag remains available for discovery.
-Unresolved author lookup descriptors remain wire-only and map to `author_name=None` on records and comments (PVD-044).
-A staged attachment is indeterminate once the write has started.
-
-Relation addition reads both endpoints and checks their resolved data server before writing; this reduces PVD-009
-risk but is not an atomic Provider authorization guarantee. It does not list relations merely to inspect the
-caller-relative `editable` display flag: the mutation endpoint performs the source permission check. Relation
-deletion lists current relations only to refuse an observed cross-notebook target-ID collision because the Provider
-ignores target notebook identity (PVD-020); its mutation likewise performs authorization. Both mutations return
-`None` after acknowledgement. `records.relations()` returns the relation tuple directly. The endpoint's duplicated
-`more` comments, `editable` value and target preview/JOIN fields stay wire-only; comments come from
-`records.comments()`. Each returned `RecordRelationRef` carries only the relation row and declared target IDs.
-Deletion accepts the source `RecordLocator` and one of those observed refs.
-
-Comment upload follows the current Provider's literal one-request `file` field. Comment mutations return `None`
-after acknowledgement. Edit first verifies that the selected
-comment is currently observed and caller-owned because the Provider otherwise reports a false success for a missing or
-other-user ID (PVD-004). Delete sends the typed ref directly because the Provider mutation itself enforces record and
-caller ownership. Neither operation performs a post-write read. Staged comment attachments have no Contract abort
-operation, and binding remains affected by PVD-003. Comment create/update use the same `body` vocabulary as the
-returned `RecordComment.body`; the SDK does not perform rich-text display normalization, while the Provider's
-documented surrounding-whitespace trim still applies when saving.
-`RecordCommentRef` carries its `RecordLocator`, so update and delete accept the ref rather than an entire comment or a
-public `owned_by_caller` UI flag.
-
-Attachment bytes are streamed and must be consumed or closed explicitly:
-
-```python
-from matelab import ByteRange
-
-comments = await client.records.comments(source)
-comment = comments[0]
-attachment = comment.attachments[0]
-async with await client.records.download_comment_attachment(
-    comment.ref, attachment, byte_range=ByteRange.from_start(0)
-) as download:
-    async for chunk in download:
-        consume(chunk)
-```
-
-`DownloadStream` exposes status, content type, length, range, and disposition metadata without buffering the
-complete file. Streams are not automatically replayed. `ByteRange` deliberately rejects `bytes=0-0` (PVD-015).
-For local files, `ByteRange.from_start(0)` returns at most the first 4097 bytes. Inspect `content_range` and request
-the next range starting at its end plus one, use a positive explicit end, or omit `byte_range` for the full file.
-Zero-byte comment attachments can be discovered and downloaded without a range.
-Comment attachment refs contain only file identity. Pass the parent comment ref returned by the same read when
-downloading; current Providers do not verify that association (PVD-006).
-
-Cross-domain staging keeps resumable state and completed-file identity separate:
-
-```python
-from matelab import StagedFile
-
-pdf_bytes = b"sanitized PDF bytes"
-staged = await client.uploads.stage(pdf_bytes, filename="example.pdf")
-assert isinstance(staged, StagedFile)
-```
-
-The SDK derives `fragment_size` and computes the complete SHA-256 for a single `bytes` fragment. File-like content
-must declare its fragment size. For multiple fragments, pass the returned `StagedUploadSession` into the next call and
-supply `complete_sha256` on the final call. `next_offset` is explicitly a caller-side total on an active upload session,
-derived from declared fragment sizes; the Provider does not confirm an offset. The SDK verifies the Provider's returned filename and size against the submitted filename and
-client-tracked total, but does not repeat those caller-known values on the final result. A final result contains the
-Provider hash, temporary row identity and direct `binding`; it no longer embeds resumable session state. The temporary
-Provider URL and upload-session identity needed by internal binding and cleanup remain hidden. Callers do not need to
-splice either into content. The result does not claim that a later literature/cloud operation checks the uploader or
-consumes the file exactly once. `uploads.abort()` accepts either an active `StagedUploadSession` or a completed
-`StagedFile` and exposes the Provider's legacy code-2 cancellation signal as a `None`-returning compensating cleanup
-that is not independently verified (PVD-024).
-Staging mutations are never automatically retried.
-
-Literature identities distinguish the personal library from shared libraries:
-
-```python
-from matelab import LiteratureMetadataInput
-
-libraries = await client.literature.libraries()
-page = await client.literature.list()
-detail = await client.literature.read(page.items[0].ref)
-candidate = await client.literature.extract_metadata(doi="10.0000/example")
-
-await client.literature.create(
-    LiteratureMetadataInput(title="Example import", doi="10.0000/example"), staged_pdf=staged
-)
-```
-
-`literature.libraries()` directly returns usable `LiteratureLibrarySummary` values in Provider-unspecified order.
-`LiteratureLibraryRef()` identifies the synthetic personal library; a positive `library_id` identifies a real shared
-library, and the read-only `scope` property is derived from that identity. Each `LiteratureItemRef` carries the library
-where it was observed. Raw permission masks are normalized as `LiteratureLibraryPermissions`. Dangling memberships
-without a usable library identity and pending-share projections remain wire-only; the pinned Contract does not provide
-the complete accept/reject workflow needed to expose pending shares safely.
-
-The Provider's static literature form definition and extraction deployment flag remain wire-only; Consumers call
-`extract_metadata()` directly and handle an unavailable or failing optional backend as a Provider error. Extraction
-returns a `PublicationMetadataCandidate`: unstored, rich publication evidence rather than metadata already attached to
-a literature item. Its structured authors are `PublicationAuthorCandidate` values. Extraction accepts a DOI, a
-completed staged PDF, or both; a supplied DOI takes precedence over the staged PDF. A non-empty DOI must match
-`^10\.[0-9]+/\S+$`; the generated request model rejects other values before sending them to the Provider (PVD-040).
-The Provider can wrap an error inside an outer successful extraction response. The SDK maps that nested error to
-its usual safe Provider/authentication error. Empty or opaque backend lists raise `MatelabProtocolError` because they
-provide no structured `PublicationMetadataCandidate`; an outer success code does not promise extracted metadata
-(PVD-045).
-Literature list
-results likewise exclude Provider-generated citation HTML and author-highlight fragments; Consumers receive the
-underlying citation fields instead of presentation markup. `LiteratureDetail.metadata` is `None` when invalid legacy
-JSON produces the Provider's empty-array fallback; otherwise it contains decoded stored metadata without arbitrary
-extension values.
-List and detail results normalize the Provider's zero rating to `None`. Missing list author, abstract, journal, and PDF
-values are likewise `None`. A `LiteraturePdf` is exposed only when the Provider supplies the SHA-256 required for
-download; its optional filename and size metadata may still be `None`. The list response's
-`dtime` is not exposed as a publication date because it is a mutable library-entry timestamp with no stable Contract
-meaning. `LiteratureItemSummary.tags` and `LiteratureDetail.tags` contain the current item's library classification
-tags; bibliographic keywords remain under `LiteratureDetail.metadata.keywords` when stored metadata is available.
-`LiteratureLibrarySummary.tags` and `LiteraturePage.tags` contain the library-wide tag set used for filtering. Library
-names and tag sets belong to library/list results rather than being repeated on an item detail.
-`StoredLiteratureMetadata.author` is the single public author representation: canonical author text takes precedence,
-while a legacy author list is joined with semicolons when no canonical value exists. The legacy array remains wire-only.
-
-`LiteratureMetadataInput` is the complete canonical input for create and replacement. `StoredLiteratureMetadata` is a
-decoded snapshot returned by `read()` and can contain readable legacy/source fields that the canonical write schema
-does not accept. Neither is interchangeable with an extraction candidate.
-
-Create returns `None` and never guesses the new item from list position because the Provider returns no ID. By default,
-canonical update preflights the raw item response and refuses to drop top-level or nested source/hidden fields. Passing
-`allow_source_metadata_loss=True` explicitly skips that preflight and sends the canonical replacement directly. The
-default read/check/write protection is best effort rather than atomic because the Provider offers no revision or
-compare-and-swap condition; this Provider-specific behavior remains internal to the update operation (PVD-012).
-PDF replace/delete are separate acknowledged mutations and are not presented as atomic with metadata.
-Permanent personal deletion is named `permanently_delete`, returns `None`, and is non-recoverable. Sharing requires
-list-observed item summaries, user-search summaries and a
-valid caller identity, then returns `None` because the Provider supplies no per-recipient IDs (PVD-008, PVD-027).
-
-Literature comments use explicit `create_comment()` and `update_comment()` intents. Creation first reads the current
-detail and rejects when the caller already owns a comment; callers then use that comment's `LiteratureCommentRef` with
-`update_comment()`. The ref contains only the Provider comment-row identity. Update and delete send that identity
-directly because the Provider mutation verifies current ownership and library permission. The creation preflight
-maintains the Integration Contract's one-caller-comment invariant for ordinary SDK use, but is not atomic because the
-Provider has no matching uniqueness constraint (PVD-026). When sharing with `copy_owner_comment=True`, multiple
-caller-owned comments remain an explicit ambiguity because the Provider would otherwise choose one implicitly. A
-staged attachment can replace one `matelab-staged-file` marker; raw temporary URLs are rejected. These checks prevent
-common misuse but do not repair the Provider's cross-user UID lookup (PVD-003). Shared-library reads and writes remain
-experimental because the Provider permission JOIN is not scoped to the current user (PVD-007); successful SDK calls
-must not be treated as independent authorization proof. Literature PDF downloads reuse `DownloadStream` and the
-stable `ByteRange` subset.
-
-The personal cloud-drive surface keeps root, folder, final file and temporary staging identities separate:
-
-```python
-listing = await client.cloud_drive.list()
-folder = await client.cloud_drive.create_folder(name="Example data")
-await client.cloud_drive.bind_staged_file(staged, target=folder)
-```
-
-`CloudDriveListing` contains the selected files, `total_count` and SDK-derived `has_more` alongside a complete folder
-snapshot and quota usage; pagination applies only to `files`, while request page arguments are not echoed. Personal-root
-metadata and permissions are synthetic/fixed for this Contract line and remain wire-only. File rows omit the constant
-caller owner fields and do not invent a folder location that the Provider fails to return for root-wide searches.
-Listings likewise omit search/order/direction request echoes. Ordering has no stable ID tie-breaker (PCG-011, PVD-038).
-`CloudFile.modified_at` contains the stored modification timestamp as a non-null string. A stored null causes a
-Provider error before a successful file row can be returned (PVD-047). Display-formatted date and time remain wire-only.
-
-Folder create returns a `CloudFolderRef` built from the Provider ID. Other folder and file mutations return `None`
-after acknowledgement and do not automatically list the drive. Staged finalize accepts a completed `StagedFile`;
-the Provider binds by temporary row ID without checking its owner (PVD-002), and finalize atomicity/idempotency remain
-absent. Batch move and permanent delete do not claim Provider per-item results or atomicity. Permanent
-deletion is named `permanently_delete_files` and is non-recoverable. Cloud downloads
-resolve bytes from the final file identity and reuse `DownloadStream`, thumbnail/preview choices and the PVD-015-safe
-range subset. Cloud mutations are not automatically retried.
-
-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-blank `str` preserved exactly because private operations use it as a Provider selector.
-The pinned owned/shared wire field remains nullable because the database column allows null, but Provider writes
-require a non-empty title. A runtime database audit found no null or blank titles and did find legacy private titles
-with surrounding whitespace; the SDK therefore treats null/blank as a protocol violation without normalizing the exact
-selector. Public record listing uses that non-blank title as an additional Provider selector and accepts only public
-scope. Private
-operations reject public scope, while owned-only notebook mutations continue to reject shared/public refs. Static
-typing exposes exactly those three scope values, so a redundant runtime membership check is not repeated. Scope policy
-is checked at each SDK operation boundary; reading `title` itself does not imply or perform a private-scope check.
-`RecordRef` and `RecordVersionRef` keep their Provider identifiers distinct; a version ref carries its typed
-`RecordLocator` instead of repeating notebook ID, record database ID and record UID fields. `records.read()` accepts
-either a `RecordLocator` for current content or a `RecordVersionRef` for historical content, so callers never repeat
-the record identity alongside its version. 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.
-
-All three notebook collections contain the same `NotebookSummary` model. Public catalog entries do not expose owner
-names or groups, so those fields are `None`. Public summary and creation time remain non-null at runtime under the wire
-Contract, while the unified model uses the wider owned/shared nullable types.
-
-Provider `types`, `display`, and `requests` fields configure its notebook-list UI rather than notebook domain data.
-`types` normally holds classification tags used by the Provider frontend for client-side filtering; legacy stored JSON
-can have another non-null shape. These fields are absent from `NotebookSummary` and from create/update inputs;
-the SDK handles their update-time
-preservation only as an internal Provider compatibility detail.
-
-Template render metadata is also excluded from template summaries and record reads. A `Record` has one
-`source: RecordLocator`; it does not duplicate the notebook and record refs, caller-relative owner/editable UI state,
-notebook title/keywords, Provider data-server routing, or the frontend PDF-capability flag. `Record.version` identifies
-historical content and is `None` for the current content. `Record.versions` contains refs usable for historical reads;
-Provider lock and signature projections remain wire-only. Relation creation still checks returned data servers
-internally to mitigate PVD-009.
-
-Provider record-finalization and additional-signature mutations are intentionally outside the pinned Contract and SDK
-interface. They require the account password to unlock a private key, combine version creation with signing, provide no
-reliable per-record result, and lack a compare-and-swap guard between hashing and snapshot creation. The SDK therefore
-does not expose a signing operation, signature projection or credentials for these operations; notebook permission
-results only report whether Provider policy allows signing.
-
-Errors are separated into semantic Provider errors, authentication errors, HTTP/transport errors,
-Integration Contract response errors, and client-side usage errors. Semantic Provider errors retain only the
-Contract-defined top-level code plus an SDK-owned safe summary; Provider-authored messages, response bodies, legacy
-aliases, and unrelated fields do not enter exceptions.
-
-## Development
-
-```bash
-uv sync
-uv run python scripts/generate_models.py
-uv run python scripts/generate_models.py --check
-uv run ruff check .
-uv run ruff format --check .
-uv run basedpyright
-uv run pytest
-uv build
-```
-
-The generator first verifies the contract lock, OpenAPI release metadata, and snapshot digest. It then
-creates a temporary OpenAPI 3.1 generation projection, resolves references without network access, and
-generates private component, operation-response, and parameter models. Generator emission uses its built-in formatter;
-the checked-in output is then normalized using the repository `pyproject.toml` as the sole Ruff configuration. The
-projection flattens pure
-object inheritance and preserves constraints the model generator cannot express as self-contained JSON Schema
-2020-12 metadata; the checked-in release snapshot remains unchanged. `--check` performs the same validation and
-deterministic generation without writing the checked-in models. `WireModel` applies that metadata with the standard
-`jsonschema` Draft 2020-12 validator; the SDK does not maintain a second hand-written schema interpreter. The current
-lock resolves
-`datamodel-code-generator 0.71.0` and
-`hatchling 1.31.0`. Published metadata requires `httpx2>=2.9.1,<3`, `jsonschema>=4.26,<5`,
-`pydantic>=2.13.4,<3`, and `typing-extensions>=4.14.1,<5`; the build backend requires
-`hatchling>=1.27,<2`. These lower bounds are verified
-against the complete test suite on the supported Python boundary versions rather than inferred from
-`uv.lock`. The exact toolchain remains locked for development and release builds. Basedpyright and its
-Node wheel retain the compatible exact pair `basedpyright==1.39.9` and
-`nodejs-wheel-binaries==22.20.0`.
-
-## Opt-in Provider consumer smoke
-
-`tests/provider/test_provider_smoke.py` exercises the consumer flow through only the public SDK interface. Its base
-scenario covers credential authentication, persistence of the complete returned Session, restoration through a new
-`AsyncMatelab` instance, refresh with identity preservation, and notebook discovery. It is not Provider Verification
-and is skipped by default.
-
-Raw Provider conformance remains the responsibility of `matelab-spec`, which sends direct HTTP requests and validates
-the unmodified responses. The SDK does not repeat its route-by-route, cross-account, sharing, or attachment-isolation
-verification. Representative SDK adapter tests instead feed the pinned OpenAPI's sanitized response examples through
-`MockTransport` and assert the resulting public values; synthetic fixtures remain where SDK-specific encoding,
-error, retry, and compatibility boundaries require evidence beyond those examples.
-
-Provider smoke is restricted to the confirmed isolated test service. Authentication and refresh persist Provider
-token state. This side effect is inherent to the tested Provider operations; it cannot be disabled by a test setting.
-Explicitly loading `.env.test` and selecting the `provider` marker is the opt-in for this flow.
-
-Copy `.env.example` to the git-ignored local `.env.test`, then fill in the shared Provider connection settings:
-
-- `MATELAB_PROVIDER_BASE_URL`
-- `MATELAB_PROVIDER_USERNAME`
-- `MATELAB_PROVIDER_PASSWORD`
-
-These names intentionally match `matelab-spec` Provider Verification. The isolated target may copy them from the spec
-`.env` into this repository's `.env.test`. Refreshing the restored Session must preserve its authenticated identity.
-With the environment prepared:
-
-```bash
-uv run --env-file .env.test pytest -m provider tests/provider/test_provider_smoke.py
-```
-
-This command runs only the SDK public-interface smoke; it is not the 71-operation Provider Verification. To reuse the
-same `.env.test` for the complete Contract suite, also populate the optional share user, secondary account, record
-staging opt-in, and Chat SSO settings documented in `.env.example`, then run from sibling checkouts:
-
-```bash
-cd ../matelab-spec
-uv run --env-file ../matelab-python-sdk/.env.test pytest
-```
-
-The files are never loaded implicitly, so normal test runs remain safely skipped. Do not use either flow against
-production, and never commit Provider credentials.
-
-## Reproducible release build
-
-Build from a clean release commit (or its tag) and set the archive timestamp to that commit's
-committer timestamp. `pyproject.toml` declares the supported Hatchling range, while `uv.lock` supplies the
-exact version used by the frozen, no-build-isolation release environment:
-
-```bash
-export SOURCE_DATE_EPOCH="$(git show -s --format=%ct HEAD)"
-uv sync --frozen
-uv run python scripts/generate_models.py --check
-uv build --no-build-isolation --out-dir dist/release
-uv run python scripts/check_release.py dist/release/*.whl dist/release/*.tar.gz
-(cd dist/release && sha256sum *.whl *.tar.gz > SHA256SUMS)
-```
-
-Rebuilding the same commit with the same locked environment and `SOURCE_DATE_EPOCH` must produce
-byte-identical wheel and source distribution hashes. The SDK Contract pin is immutable `matelab-spec v2026.10.1`, commit
-`9941e2d623a1c2633adb459b823d78d4e62d3802`, and OpenAPI SHA-256
-`a07997128c1df17a03724c5af8e11b45a34166f9d6e15558e66e0a301f2e0813`.