matelab-python-sdk 0.1.0a2__tar.gz → 0.1.0a3__tar.gz

matelab_python_sdk-0.1.0a3/.env.example

@@ -0,0 +1,6 @@
+# Provider consumer tests must target the confirmed isolated test service.
+# Authentication and external-token refresh persist Provider token state.
+# Keep these names aligned with matelab-spec Provider Verification.
+MATELAB_PROVIDER_BASE_URL=
+MATELAB_PROVIDER_USERNAME=
+MATELAB_PROVIDER_PASSWORD=

{matelab_python_sdk-0.1.0a2 → matelab_python_sdk-0.1.0a3}/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.1.0a3 - 2026-07-28
+
+- Replaces HTTPX with HTTPX2 2.9.1 and raises the Pydantic compatibility floor to 2.13.4. Injected clients must now
+  be `httpx2.AsyncClient` instances; HTTPX and HTTPX2 objects are not interchangeable. Default TLS verification now
+  uses the operating system trust store.
+- Shrinks the alpha public surface from 184 to 150 symbols by returning existing domain values, tuples, booleans, or
+  `None` from simple mutations instead of defining endpoint-shaped result dataclasses. Contract invariants remain
+  documented operation semantics rather than repeated constant fields.
+- Reorganizes the record and literature implementations into domain packages and keeps generated wire imports behind
+  one private namespace without changing the generated-model boundary.
+- Aligns the opt-in SDK Provider smoke with the isolated test service's shared `MATELAB_PROVIDER_*` environment
+  variables and adds a safe `.env.example`.
+
 ## 0.1.0a2 - 2026-07-27
 
 - Adopts the immutable `matelab-spec v0.1.1` release.

{matelab_python_sdk-0.1.0a2 → matelab_python_sdk-0.1.0a3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matelab-python-sdk
-Version: 0.1.0a2
+Version: 0.1.0a3
 Summary: Reusable async Python client for the Matelab Integration Contract
 Author-email: 朱天念 <zhutiannian@gmail.com>
 License-Expression: Apache-2.0
@@ -20,15 +20,15 @@ Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
-Requires-Dist: httpx<1,>=0.27.2
-Requires-Dist: pydantic<3,>=2.12.5
+Requires-Dist: httpx2<3,>=2.9.1
+Requires-Dist: pydantic<3,>=2.13.4
 Description-Content-Type: text/markdown
 
 # matelab-python-sdk
 
 Reusable async Python client for the Matelab Integration Contract.
 
-The current alpha is `0.1.0a2`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a3`. `[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.1.1` Contract Release. The sole release pin is
@@ -57,7 +57,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.0a2-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a3-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -155,6 +155,9 @@ alice_client = AsyncMatelab(session=alice_session, http_client=shared_http_clien
 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.
@@ -284,8 +287,8 @@ groups = await client.groups.list()
 targets = await client.users.search("Example Researcher", scope=UserSearchScope.SAME_INSTITUTE)
 ```
 
-Both results explicitly report `provider_unspecified` ordering. Group members belong only to
-`groups.members_for`, not to every returned group. These two discovery interfaces are experimental because the
+Ordering remains Provider-unspecified and is documented rather than repeated as a constant result field. Group
+members belong only to `groups.members_for`, not to every returned group. These two discovery interfaces are experimental because the
 Provider returns members for an unstable first group and user search is unpaged, unordered, and not field-minimized
 (PVD-006, PVD-029, PCG-011).
 
@@ -294,17 +297,16 @@ Notebook create/update and direct sharing keep write acknowledgement separate fr
 ```python
 from matelab import NotebookMetadata, NotebookSharePermissionGrant
 
-created = await client.notebooks.create(NotebookMetadata(title="Example Notebook"))
+await client.notebooks.create(NotebookMetadata(title="Example Notebook"))
 shares = await client.notebooks.share(notebook, [target.ref])
-updated = await client.notebooks.update_share(
-    shares.visible_after_write[0].ref, NotebookSharePermissionGrant(write=True, create=True)
-)
+updated = await client.notebooks.update_share(shares[0].ref, NotebookSharePermissionGrant(write=True, create=True))
 ```
 
-Create cannot return a notebook ref because the Provider returns no identity. Owned updates are read back by database
-ID and report matching, mismatched, or missing observations, containing PVD-003 false success without claiming an
-atomic guarantee. Share results similarly report post-write visibility rather than invented affected rows. A stored
-share mask of zero still has effective read access (PVD-010), and share-list order remains unspecified.
+Create returns `None` because the Provider returns no identity. Owned updates return the notebook row observed by
+database ID, or `None` when it is missing, containing PVD-003 false success without claiming an atomic guarantee.
+Share returns only requested relations visible during readback, and permission updates return the observed relation
+or `None`. A stored share mask of zero still has effective read access (PVD-010), and share-list order remains
+unspecified.
 
 Template discovery keeps a template database identity separate from direct-share, market-acquisition, and group
 relation identities:
@@ -316,18 +318,18 @@ content = await client.templates.read(templates.owned[0].ref)
 ```
 
 The market result reports the Provider `total_count`, the requested and effective page sizes, and a `has_more`
-value explicitly marked as `derived_from_total`; it does not claim a stable order or continuation token. Canonical
+value derived from the total; it does not claim a stable order or continuation token. Canonical
 modules are mapped to public `TemplateModule` values and retain additive module attributes. Template reads remain
 experimental because Provider discovery ordering/pagination and historical `images` compatibility are not fully
 stable (PCG-003, PCG-009, PVD-013, PVD-022).
 
 Template writes remain separate operations: metadata, canonical modules, and usage HTML are not presented as one
-transaction. Metadata create returns the Provider template ID; copy explicitly returns no new identity because the
-Provider supplies none. Direct-share, market-acquisition, and group relation refs are distinct and are required by
-their matching removal methods. Mutation results report readback observations without inventing affected rows.
-Metadata and intro results explicitly report that they do not advance the marketplace revision (PVD-021).
-`UploadBindingRef.new()` creates the fresh hidden correlation value required by intro attachment binding, while the
-result still records that the Provider does not verify the uploader (PVD-026).
+transaction. Metadata create returns the Provider template ID plus an optional observed summary; copy and share
+return `None` because the Provider supplies no new identity or per-recipient rows. Group addition and market
+acquisition return the observed relation or `None`, while removal returns readback-confirmed absence as `bool`.
+Direct-share, market-acquisition, and group relation refs remain distinct. Marketplace revision and uploader-binding
+limitations are documented operation semantics rather than constant fields on every result (PVD-021, PVD-026).
+`UploadBindingRef.new()` creates the fresh hidden correlation value required by intro attachment binding.
 
 Extended record reads stay behind the same `records` interface:
 
@@ -362,8 +364,8 @@ imported = await client.records.import_dataset(
 )
 ```
 
-A caller-supplied blank-record UID is read back; when the Provider generates it, the result explicitly has no
-invented identity. Import validates the complete batch with generated wire models but cannot map returned database
+A caller-supplied blank-record UID returns its matching readback; when the Provider generates it, create returns
+`None` rather than inventing identity. Import validates the complete batch with generated wire models but cannot map returned database
 IDs to individual inputs or promise atomicity (PCG-008). Delete means moving records into the recycle bin, not
 permanent deletion. Delete and restore results classify only post-write observations; restore never treats an active
 row with the same UID but a different database ID as proof of success (PCG-005). Record mutations are not
@@ -373,19 +375,21 @@ Record patching exposes a deliberately narrower capability than the raw Provider
 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-014 through
-PVD-016). `Record.content_sha256` can be supplied as a client-side precondition, but results explicitly label it as
-advisory read-before-write rather than Provider CAS. Database, active-browser, and unclassified acknowledgements
+PVD-016). `Record.content_sha256` can be supplied as a client-side precondition, documented as advisory
+read-before-write rather than Provider CAS. `RecordUpdateResult` retains only the before/after evidence and whether
+the acknowledgement means persisted, pending browser save, or unclassified. Database, active-browser, and unclassified acknowledgements
 remain distinct, and mutation retries stay disabled.
 
 Relation addition reads both endpoints and checks their resolved data server before writing; this reduces PVD-019
-risk but is not an atomic Provider authorization guarantee. Relation deletion refuses an observed cross-notebook
-target-ID collision because the Provider ignores target notebook identity (PVD-020), then reports readback and any
-other relation that disappeared without inventing an affected-row count.
+risk but is not an atomic Provider authorization guarantee. Relation addition returns matching relations observed
+afterward. Relation deletion refuses an observed cross-notebook target-ID collision because the Provider ignores
+target notebook identity (PVD-020), then returns the complete post-write relation snapshot.
 
 Comment upload follows the Provider's literal one-request `upload` field, not the incompatible Front fragment
-protocol (PVD-037). Comment creation derives an ID only from a unique post-write observation. Edit and delete require
-a currently observed caller-owned comment and read it back, containing the Provider's edit false-success behavior
-(PVD-004). Staged comment attachments have no Contract abort operation, and binding remains affected by PVD-026.
+protocol (PVD-037). Comment create/update return matching post-write comment rows; delete returns whether the selected
+comment is absent. Edit and delete require a currently observed caller-owned comment and read it back, containing the
+Provider's edit false-success behavior (PVD-004). Staged comment attachments have no Contract abort operation, and
+binding remains affected by PVD-026.
 
 Attachment bytes are streamed and must be consumed or closed explicitly:
 
@@ -425,7 +429,8 @@ For multiple fragments, pass `StagedFileFragment.session` into the next call. `n
 caller-side total derived from declared fragment sizes; the Provider does not confirm an offset. A final result
 contains the Provider hash, size, temporary row identity and fresh hidden binding value, but does not claim that a
 later literature/cloud operation checks the uploader or consumes the file exactly once. `uploads.abort` exposes the
-Provider's legacy code-2 cancellation signal as compensating cleanup that is not independently verified (PVD-028).
+Provider's legacy code-2 cancellation signal as a `None`-returning compensating cleanup that is not independently
+verified (PVD-028).
 Staging mutations are never automatically retried.
 
 Literature identities distinguish the personal library, shared libraries and pending incoming copies:
@@ -441,18 +446,15 @@ schema = await client.literature.creation_schema()
 if schema.metadata_extraction_available:
     candidates = await client.literature.extract_metadata(DoiMetadataSource("10.0000/example"))
 
-created = await client.literature.create(
-    LiteratureMetadata(title="Example import", doi="10.0000/example"), staged_pdf=staged
-)
-assert created.created_item is None
+await client.literature.create(LiteratureMetadata(title="Example import", doi="10.0000/example"), staged_pdf=staged)
 ```
 
-Create never guesses the new item from list position because the Provider returns no ID. Canonical update reads the
+Create returns `None` and never guesses the new item from list position because the Provider returns no ID. Canonical update reads the
 item first and refuses to drop source/hidden fields unless `allow_source_metadata_loss=True` is explicit (PVD-027).
 PDF replace/delete are separate, read-back-verified mutations and are not presented as atomic with metadata
-(PCG-010). Permanent personal deletion is named `permanently_delete`, reports snapshot verification, and is marked
-non-recoverable. Sharing requires list-observed item summaries, user-search summaries and a resolved caller identity;
-its result deliberately contains no invented per-recipient IDs or batch atomicity (PVD-012, PVD-036).
+(PCG-010). Permanent personal deletion is named `permanently_delete` and returns snapshot-confirmed absence as a
+`bool`; the operation is non-recoverable. Sharing requires list-observed item summaries, user-search summaries and a
+resolved caller identity, then returns `None` because the Provider supplies no per-recipient IDs (PVD-012, PVD-036).
 
 Literature comments use one public save intent: detail is read first, an existing caller-owned comment is edited, and
 otherwise a comment is created. Multiple caller-owned comments are rejected as ambiguous (PVD-035). A staged
@@ -469,11 +471,11 @@ from matelab import CloudFolderMetadata
 
 listing = await client.cloud_drive.list()
 folder_result = await client.cloud_drive.create_folder(CloudFolderMetadata(name="Example data"))
-bound = await client.cloud_drive.bind_staged_file(staged, target=folder_result.folder)
+matches = await client.cloud_drive.bind_staged_file(staged, target=folder_result.folder)
 
-if bound.observed is not None:
+if len(matches) == 1:
     renamed = await client.cloud_drive.update_file(
-        bound.observed, filename="example-renamed.pdf", description="Sanitized description"
+        matches[0], filename="example-renamed.pdf", description="Sanitized description"
     )
 ```
 
@@ -482,12 +484,14 @@ than flattening them into one ambiguous collection. Folder browse results retain
 are explicitly root-wide and return `location=None` because the Provider omits each match's folder ID. Ordering has
 no stable ID tie-breaker (PCG-003, PVD-013).
 
-Folder create returns the Provider ID and all folder mutations read back the complete tree. Staged finalize accepts a
-completed `StagedFile`, then paginates the target folder and returns a final `CloudFileRef` only for one exact
-filename/hash/size observation. This is useful evidence, not an uploader-ownership guarantee: the Provider binds by
+Folder create returns the Provider ID plus an optional observed folder, and all folder mutations read back the
+complete tree. Staged finalize accepts a completed `StagedFile`, then paginates the target folder and returns all
+exact filename/hash/size matches; zero, one, or multiple results preserve missing and ambiguous observations without
+another result model. This is useful evidence, not an uploader-ownership guarantee: the Provider binds by
 temporary row ID without checking its owner (PVD-031), and finalize atomicity/idempotency remain absent (PCG-012).
-Batch move and permanent delete keep Provider item results as `None`, report only post-write observations and do not
-claim atomicity. Permanent deletion is named `permanently_delete_files` and marked non-recoverable. Cloud downloads
+Batch move returns identities observed in the target, while permanent delete returns identities confirmed absent;
+neither claims 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-002-safe
 range subset. Cloud mutations are not automatically retried.
 
@@ -526,8 +530,8 @@ generates private component, operation-response, and parameter models. The proje
 object inheritance that the generator cannot otherwise preserve correctly; the checked-in release
 snapshot remains unchanged. `--check` performs the same validation and deterministic generation without
 writing the checked-in models. The current lock resolves `datamodel-code-generator 0.71.0` and
-`hatchling 1.31.0`. Published metadata requires `httpx>=0.27.2,<1` and
-`pydantic>=2.12.5,<3`; the build backend requires `hatchling>=1.27,<2`. These lower bounds are verified
+`hatchling 1.31.0`. Published metadata requires `httpx2>=2.9.1,<3` and
+`pydantic>=2.13.4,<3`; 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
@@ -535,47 +539,37 @@ Node wheel retain the compatible exact pair `basedpyright==1.39.9` and
 
 ## Opt-in Provider consumer smoke
 
-`tests/provider/test_provider_smoke.py` exercises the consumer flow through only the public SDK interface:
-credential authentication, extraction of the returned token pair, exchange through a new
-`AsyncMatelab.bind_external_tokens` instance, userid consistency checks, owned/shared notebook discovery,
-record listing, and current-record reading. It is not Provider Verification and is skipped by default.
+`tests/provider/test_provider_smoke.py` exercises the consumer flow through only the public SDK interface. Its base
+scenario covers credential authentication, extraction of the returned token pair, exchange through a new
+`AsyncMatelab.bind_external_tokens` instance, userid consistency checks, and notebook discovery. It is not Provider
+Verification and is skipped by default.
 
-Prefer an explicitly isolated Provider. A production target requires explicit authorization for the current run
-and a dedicated test fixture. Authentication and external-token refresh persist Provider token state, and
-`GET /eln_items/item_view` writes a Provider audit entry even though it is a read operation. The smoke therefore
-requires explicit target and write acknowledgements:
+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.
 
-```dotenv
-MATELAB_PROVIDER_SMOKE=1
-MATELAB_PROVIDER_SMOKE_ISOLATED=1
-MATELAB_PROVIDER_SMOKE_ALLOW_WRITES=1
-```
-
-For an explicitly authorized production test fixture, leave `MATELAB_PROVIDER_SMOKE_ISOLATED` empty and use:
-
-```dotenv
-MATELAB_PROVIDER_SMOKE_PRODUCTION_ACKNOWLEDGED=1
-```
+Provider smoke is restricted to the confirmed isolated test service. Authentication and external-token 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.
 
-Fill the git-ignored local `.env.test` with exactly one target acknowledgement and the fixture:
+Copy `.env.example` to the git-ignored local `.env.test`, then fill in the shared Provider connection settings:
 
-- `MATELAB_PROVIDER_SMOKE_BASE_URL`
-- `MATELAB_PROVIDER_SMOKE_USERNAME`
-- `MATELAB_PROVIDER_SMOKE_PASSWORD`
-- `MATELAB_PROVIDER_SMOKE_EXPECTED_USERID`
-- `MATELAB_PROVIDER_SMOKE_NOTEBOOK_ID`
-- `MATELAB_PROVIDER_SMOKE_RECORD_DATABASE_ID`
-- `MATELAB_PROVIDER_SMOKE_RECORD_UID`
+- `MATELAB_PROVIDER_BASE_URL`
+- `MATELAB_PROVIDER_USERNAME`
+- `MATELAB_PROVIDER_PASSWORD`
 
-The userid and both record identifiers are checked before the record read so an ambiguous or incorrect
-fixture fails safely. With the environment prepared:
+These names intentionally match `matelab-spec` Provider Verification. The isolated target may copy them from the spec
+`.env` into this repository's `.env.test`. The identities returned by authentication and external token binding must
+agree. With the environment prepared:
 
 ```bash
 uv run --env-file .env.test pytest -m provider tests/provider/test_provider_smoke.py
 ```
 
-The file is never loaded implicitly, so the normal test suite remains safely skipped. Never use production without
-explicit authorization for that run, and never commit its credentials.
+The file is never loaded implicitly, so the normal test suite remains safely skipped. Do not use this flow against
+production, and never commit its credentials.
 
 ## Reproducible release build
 

{matelab_python_sdk-0.1.0a2 → matelab_python_sdk-0.1.0a3}/README.md

@@ -2,7 +2,7 @@
 
 Reusable async Python client for the Matelab Integration Contract.
 
-The current alpha is `0.1.0a2`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a3`. `[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.1.1` 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.0a2-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a3-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -129,6 +129,9 @@ alice_client = AsyncMatelab(session=alice_session, http_client=shared_http_clien
 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.
@@ -258,8 +261,8 @@ groups = await client.groups.list()
 targets = await client.users.search("Example Researcher", scope=UserSearchScope.SAME_INSTITUTE)
 ```
 
-Both results explicitly report `provider_unspecified` ordering. Group members belong only to
-`groups.members_for`, not to every returned group. These two discovery interfaces are experimental because the
+Ordering remains Provider-unspecified and is documented rather than repeated as a constant result field. Group
+members belong only to `groups.members_for`, not to every returned group. These two discovery interfaces are experimental because the
 Provider returns members for an unstable first group and user search is unpaged, unordered, and not field-minimized
 (PVD-006, PVD-029, PCG-011).
 
@@ -268,17 +271,16 @@ Notebook create/update and direct sharing keep write acknowledgement separate fr
 ```python
 from matelab import NotebookMetadata, NotebookSharePermissionGrant
 
-created = await client.notebooks.create(NotebookMetadata(title="Example Notebook"))
+await client.notebooks.create(NotebookMetadata(title="Example Notebook"))
 shares = await client.notebooks.share(notebook, [target.ref])
-updated = await client.notebooks.update_share(
-    shares.visible_after_write[0].ref, NotebookSharePermissionGrant(write=True, create=True)
-)
+updated = await client.notebooks.update_share(shares[0].ref, NotebookSharePermissionGrant(write=True, create=True))
 ```
 
-Create cannot return a notebook ref because the Provider returns no identity. Owned updates are read back by database
-ID and report matching, mismatched, or missing observations, containing PVD-003 false success without claiming an
-atomic guarantee. Share results similarly report post-write visibility rather than invented affected rows. A stored
-share mask of zero still has effective read access (PVD-010), and share-list order remains unspecified.
+Create returns `None` because the Provider returns no identity. Owned updates return the notebook row observed by
+database ID, or `None` when it is missing, containing PVD-003 false success without claiming an atomic guarantee.
+Share returns only requested relations visible during readback, and permission updates return the observed relation
+or `None`. A stored share mask of zero still has effective read access (PVD-010), and share-list order remains
+unspecified.
 
 Template discovery keeps a template database identity separate from direct-share, market-acquisition, and group
 relation identities:
@@ -290,18 +292,18 @@ content = await client.templates.read(templates.owned[0].ref)
 ```
 
 The market result reports the Provider `total_count`, the requested and effective page sizes, and a `has_more`
-value explicitly marked as `derived_from_total`; it does not claim a stable order or continuation token. Canonical
+value derived from the total; it does not claim a stable order or continuation token. Canonical
 modules are mapped to public `TemplateModule` values and retain additive module attributes. Template reads remain
 experimental because Provider discovery ordering/pagination and historical `images` compatibility are not fully
 stable (PCG-003, PCG-009, PVD-013, PVD-022).
 
 Template writes remain separate operations: metadata, canonical modules, and usage HTML are not presented as one
-transaction. Metadata create returns the Provider template ID; copy explicitly returns no new identity because the
-Provider supplies none. Direct-share, market-acquisition, and group relation refs are distinct and are required by
-their matching removal methods. Mutation results report readback observations without inventing affected rows.
-Metadata and intro results explicitly report that they do not advance the marketplace revision (PVD-021).
-`UploadBindingRef.new()` creates the fresh hidden correlation value required by intro attachment binding, while the
-result still records that the Provider does not verify the uploader (PVD-026).
+transaction. Metadata create returns the Provider template ID plus an optional observed summary; copy and share
+return `None` because the Provider supplies no new identity or per-recipient rows. Group addition and market
+acquisition return the observed relation or `None`, while removal returns readback-confirmed absence as `bool`.
+Direct-share, market-acquisition, and group relation refs remain distinct. Marketplace revision and uploader-binding
+limitations are documented operation semantics rather than constant fields on every result (PVD-021, PVD-026).
+`UploadBindingRef.new()` creates the fresh hidden correlation value required by intro attachment binding.
 
 Extended record reads stay behind the same `records` interface:
 
@@ -336,8 +338,8 @@ imported = await client.records.import_dataset(
 )
 ```
 
-A caller-supplied blank-record UID is read back; when the Provider generates it, the result explicitly has no
-invented identity. Import validates the complete batch with generated wire models but cannot map returned database
+A caller-supplied blank-record UID returns its matching readback; when the Provider generates it, create returns
+`None` rather than inventing identity. Import validates the complete batch with generated wire models but cannot map returned database
 IDs to individual inputs or promise atomicity (PCG-008). Delete means moving records into the recycle bin, not
 permanent deletion. Delete and restore results classify only post-write observations; restore never treats an active
 row with the same UID but a different database ID as proof of success (PCG-005). Record mutations are not
@@ -347,19 +349,21 @@ Record patching exposes a deliberately narrower capability than the raw Provider
 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-014 through
-PVD-016). `Record.content_sha256` can be supplied as a client-side precondition, but results explicitly label it as
-advisory read-before-write rather than Provider CAS. Database, active-browser, and unclassified acknowledgements
+PVD-016). `Record.content_sha256` can be supplied as a client-side precondition, documented as advisory
+read-before-write rather than Provider CAS. `RecordUpdateResult` retains only the before/after evidence and whether
+the acknowledgement means persisted, pending browser save, or unclassified. Database, active-browser, and unclassified acknowledgements
 remain distinct, and mutation retries stay disabled.
 
 Relation addition reads both endpoints and checks their resolved data server before writing; this reduces PVD-019
-risk but is not an atomic Provider authorization guarantee. Relation deletion refuses an observed cross-notebook
-target-ID collision because the Provider ignores target notebook identity (PVD-020), then reports readback and any
-other relation that disappeared without inventing an affected-row count.
+risk but is not an atomic Provider authorization guarantee. Relation addition returns matching relations observed
+afterward. Relation deletion refuses an observed cross-notebook target-ID collision because the Provider ignores
+target notebook identity (PVD-020), then returns the complete post-write relation snapshot.
 
 Comment upload follows the Provider's literal one-request `upload` field, not the incompatible Front fragment
-protocol (PVD-037). Comment creation derives an ID only from a unique post-write observation. Edit and delete require
-a currently observed caller-owned comment and read it back, containing the Provider's edit false-success behavior
-(PVD-004). Staged comment attachments have no Contract abort operation, and binding remains affected by PVD-026.
+protocol (PVD-037). Comment create/update return matching post-write comment rows; delete returns whether the selected
+comment is absent. Edit and delete require a currently observed caller-owned comment and read it back, containing the
+Provider's edit false-success behavior (PVD-004). Staged comment attachments have no Contract abort operation, and
+binding remains affected by PVD-026.
 
 Attachment bytes are streamed and must be consumed or closed explicitly:
 
@@ -399,7 +403,8 @@ For multiple fragments, pass `StagedFileFragment.session` into the next call. `n
 caller-side total derived from declared fragment sizes; the Provider does not confirm an offset. A final result
 contains the Provider hash, size, temporary row identity and fresh hidden binding value, but does not claim that a
 later literature/cloud operation checks the uploader or consumes the file exactly once. `uploads.abort` exposes the
-Provider's legacy code-2 cancellation signal as compensating cleanup that is not independently verified (PVD-028).
+Provider's legacy code-2 cancellation signal as a `None`-returning compensating cleanup that is not independently
+verified (PVD-028).
 Staging mutations are never automatically retried.
 
 Literature identities distinguish the personal library, shared libraries and pending incoming copies:
@@ -415,18 +420,15 @@ schema = await client.literature.creation_schema()
 if schema.metadata_extraction_available:
     candidates = await client.literature.extract_metadata(DoiMetadataSource("10.0000/example"))
 
-created = await client.literature.create(
-    LiteratureMetadata(title="Example import", doi="10.0000/example"), staged_pdf=staged
-)
-assert created.created_item is None
+await client.literature.create(LiteratureMetadata(title="Example import", doi="10.0000/example"), staged_pdf=staged)
 ```
 
-Create never guesses the new item from list position because the Provider returns no ID. Canonical update reads the
+Create returns `None` and never guesses the new item from list position because the Provider returns no ID. Canonical update reads the
 item first and refuses to drop source/hidden fields unless `allow_source_metadata_loss=True` is explicit (PVD-027).
 PDF replace/delete are separate, read-back-verified mutations and are not presented as atomic with metadata
-(PCG-010). Permanent personal deletion is named `permanently_delete`, reports snapshot verification, and is marked
-non-recoverable. Sharing requires list-observed item summaries, user-search summaries and a resolved caller identity;
-its result deliberately contains no invented per-recipient IDs or batch atomicity (PVD-012, PVD-036).
+(PCG-010). Permanent personal deletion is named `permanently_delete` and returns snapshot-confirmed absence as a
+`bool`; the operation is non-recoverable. Sharing requires list-observed item summaries, user-search summaries and a
+resolved caller identity, then returns `None` because the Provider supplies no per-recipient IDs (PVD-012, PVD-036).
 
 Literature comments use one public save intent: detail is read first, an existing caller-owned comment is edited, and
 otherwise a comment is created. Multiple caller-owned comments are rejected as ambiguous (PVD-035). A staged
@@ -443,11 +445,11 @@ from matelab import CloudFolderMetadata
 
 listing = await client.cloud_drive.list()
 folder_result = await client.cloud_drive.create_folder(CloudFolderMetadata(name="Example data"))
-bound = await client.cloud_drive.bind_staged_file(staged, target=folder_result.folder)
+matches = await client.cloud_drive.bind_staged_file(staged, target=folder_result.folder)
 
-if bound.observed is not None:
+if len(matches) == 1:
     renamed = await client.cloud_drive.update_file(
-        bound.observed, filename="example-renamed.pdf", description="Sanitized description"
+        matches[0], filename="example-renamed.pdf", description="Sanitized description"
     )
 ```
 
@@ -456,12 +458,14 @@ than flattening them into one ambiguous collection. Folder browse results retain
 are explicitly root-wide and return `location=None` because the Provider omits each match's folder ID. Ordering has
 no stable ID tie-breaker (PCG-003, PVD-013).
 
-Folder create returns the Provider ID and all folder mutations read back the complete tree. Staged finalize accepts a
-completed `StagedFile`, then paginates the target folder and returns a final `CloudFileRef` only for one exact
-filename/hash/size observation. This is useful evidence, not an uploader-ownership guarantee: the Provider binds by
+Folder create returns the Provider ID plus an optional observed folder, and all folder mutations read back the
+complete tree. Staged finalize accepts a completed `StagedFile`, then paginates the target folder and returns all
+exact filename/hash/size matches; zero, one, or multiple results preserve missing and ambiguous observations without
+another result model. This is useful evidence, not an uploader-ownership guarantee: the Provider binds by
 temporary row ID without checking its owner (PVD-031), and finalize atomicity/idempotency remain absent (PCG-012).
-Batch move and permanent delete keep Provider item results as `None`, report only post-write observations and do not
-claim atomicity. Permanent deletion is named `permanently_delete_files` and marked non-recoverable. Cloud downloads
+Batch move returns identities observed in the target, while permanent delete returns identities confirmed absent;
+neither claims 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-002-safe
 range subset. Cloud mutations are not automatically retried.
 
@@ -500,8 +504,8 @@ generates private component, operation-response, and parameter models. The proje
 object inheritance that the generator cannot otherwise preserve correctly; the checked-in release
 snapshot remains unchanged. `--check` performs the same validation and deterministic generation without
 writing the checked-in models. The current lock resolves `datamodel-code-generator 0.71.0` and
-`hatchling 1.31.0`. Published metadata requires `httpx>=0.27.2,<1` and
-`pydantic>=2.12.5,<3`; the build backend requires `hatchling>=1.27,<2`. These lower bounds are verified
+`hatchling 1.31.0`. Published metadata requires `httpx2>=2.9.1,<3` and
+`pydantic>=2.13.4,<3`; 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
@@ -509,47 +513,37 @@ Node wheel retain the compatible exact pair `basedpyright==1.39.9` and
 
 ## Opt-in Provider consumer smoke
 
-`tests/provider/test_provider_smoke.py` exercises the consumer flow through only the public SDK interface:
-credential authentication, extraction of the returned token pair, exchange through a new
-`AsyncMatelab.bind_external_tokens` instance, userid consistency checks, owned/shared notebook discovery,
-record listing, and current-record reading. It is not Provider Verification and is skipped by default.
+`tests/provider/test_provider_smoke.py` exercises the consumer flow through only the public SDK interface. Its base
+scenario covers credential authentication, extraction of the returned token pair, exchange through a new
+`AsyncMatelab.bind_external_tokens` instance, userid consistency checks, and notebook discovery. It is not Provider
+Verification and is skipped by default.
 
-Prefer an explicitly isolated Provider. A production target requires explicit authorization for the current run
-and a dedicated test fixture. Authentication and external-token refresh persist Provider token state, and
-`GET /eln_items/item_view` writes a Provider audit entry even though it is a read operation. The smoke therefore
-requires explicit target and write acknowledgements:
+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.
 
-```dotenv
-MATELAB_PROVIDER_SMOKE=1
-MATELAB_PROVIDER_SMOKE_ISOLATED=1
-MATELAB_PROVIDER_SMOKE_ALLOW_WRITES=1
-```
-
-For an explicitly authorized production test fixture, leave `MATELAB_PROVIDER_SMOKE_ISOLATED` empty and use:
-
-```dotenv
-MATELAB_PROVIDER_SMOKE_PRODUCTION_ACKNOWLEDGED=1
-```
+Provider smoke is restricted to the confirmed isolated test service. Authentication and external-token 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.
 
-Fill the git-ignored local `.env.test` with exactly one target acknowledgement and the fixture:
+Copy `.env.example` to the git-ignored local `.env.test`, then fill in the shared Provider connection settings:
 
-- `MATELAB_PROVIDER_SMOKE_BASE_URL`
-- `MATELAB_PROVIDER_SMOKE_USERNAME`
-- `MATELAB_PROVIDER_SMOKE_PASSWORD`
-- `MATELAB_PROVIDER_SMOKE_EXPECTED_USERID`
-- `MATELAB_PROVIDER_SMOKE_NOTEBOOK_ID`
-- `MATELAB_PROVIDER_SMOKE_RECORD_DATABASE_ID`
-- `MATELAB_PROVIDER_SMOKE_RECORD_UID`
+- `MATELAB_PROVIDER_BASE_URL`
+- `MATELAB_PROVIDER_USERNAME`
+- `MATELAB_PROVIDER_PASSWORD`
 
-The userid and both record identifiers are checked before the record read so an ambiguous or incorrect
-fixture fails safely. With the environment prepared:
+These names intentionally match `matelab-spec` Provider Verification. The isolated target may copy them from the spec
+`.env` into this repository's `.env.test`. The identities returned by authentication and external token binding must
+agree. With the environment prepared:
 
 ```bash
 uv run --env-file .env.test pytest -m provider tests/provider/test_provider_smoke.py
 ```
 
-The file is never loaded implicitly, so the normal test suite remains safely skipped. Never use production without
-explicit authorization for that run, and never commit its credentials.
+The file is never loaded implicitly, so the normal test suite remains safely skipped. Do not use this flow against
+production, and never commit its credentials.
 
 ## Reproducible release build