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

matelab_python_sdk-0.1.0a4/.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.0a4/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+## 0.1.0a4 - 2026-07-28
+
+- Further reduces the alpha public surface from 150 to 126 symbols by accepting direct keyword arguments and existing
+  domain values instead of request-shaped wrapper dataclasses.
+- Centralizes safe request-model validation, strengthens generated Contract constraints, and preserves structured field
+  diagnostics without exposing credentials, tokens, or sensitive payload values.
+- Tightens Session replacement, refresh races, multipart retry safety, streaming cleanup, and exact HTTP success
+  handling while retaining stable transport, authentication, Provider, protocol, usage, and verification errors.
+- Collects all business capabilities under `matelab.domains`, keeps client/session/error/transport primitives at the
+  package root, and hardens generation and release-artifact audits.
+
+## 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.
+- Adds notebook-scoped, uploader-bound record attachment staging before a target record exists.
+- Finalizes staged attachments through a single-record import or one new form-file-field update without exposing
+  Provider-native attachment syntax or private transport details.
+- Enforces exact notebook/user provenance and one finalization attempt per staged handle in one SDK client.
+
+## 0.1.0a1 - 2026-07-27
+
+First public alpha candidate of the asynchronous Matelab Integration Contract SDK.
+
+- Binds the immutable `matelab-spec v0.1.0` release.
+- Exposes all 71 pinned Contract operations through public domain interfaces: 15 are stable and 56 remain
+  experimental.
+- Provides instance-owned immutable Sessions, bounded token refresh, typed public models, streaming downloads,
+  and generated private wire validation.
+- Ships as a typed package for Python 3.11 through 3.14.
+- Uses the Apache License 2.0 with PEP 639 package metadata.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matelab-python-sdk
-Version: 0.1.0a2
+Version: 0.1.0a4
 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.0a4`. `[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.0a4-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -82,6 +82,24 @@ async with AsyncMatelab() as client:
 `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` for one application-level fallback, or a specific subclass when recovery differs:
+
+| Error | Meaning and normal response |
+|---|---|
+| `MatelabUsageError` | The call cannot be represented safely; correct its arguments. |
+| `MatelabAuthenticationError` | The Session is missing, expired, invalid, or rejected; refresh or authenticate again as appropriate. |
+| `MatelabProviderError` | The Provider rejected a valid request with a business error; inspect `code` and do not assume a mutation was applied. |
+| `MatelabTransportError` | The HTTP exchange failed; `status_code` is present for HTTP failures, and a mutation outcome may be unknown. |
+| `MatelabProtocolError` | The Provider response does not match the pinned Contract; treat it as Provider drift or an SDK defect. |
+| `MatelabVerificationError` | A mutation was acknowledged but its readback failed; the mutation may already have persisted. |
+
+`code`, `status_code`, and the sanitized `payload` are diagnostics. The `payload` shape may contain private wire
+field names and is not a stable Consumer interface; application control flow should use the exception class and
+documented scalar attributes. Never automatically retry a mutation solely because it raised a transport or
+verification error.
+
 ### Session ownership
 
 Each `AsyncMatelab` instance owns at most one current, process-local `Session`. The SDK injects its bearer
@@ -155,6 +173,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.
@@ -173,7 +194,7 @@ notebook selector used for upload:
 ```python
 import hashlib
 
-from matelab import RecordImportItem, RecordImportTemplate, TemplateRef
+from matelab import RecordImportItem, TemplateRef
 
 content = b"measurement data"
 staged = await client.records.stage_attachment(
@@ -185,7 +206,8 @@ staged = await client.records.stage_attachment(
 )
 result = await client.records.import_dataset(
     notebook=notebook,
-    template=RecordImportTemplate(template=TemplateRef(template_id=8), title="Example Template"),
+    template=TemplateRef(template_id=8),
+    template_title="Example Template",
     items=(
         RecordImportItem(
             record_uid="REC-IMPORT-001",
@@ -200,19 +222,17 @@ The same staged handle may instead be consumed by one safe update that adds a ne
 module:
 
 ```python
-from matelab import RecordFormAttachmentFieldAddition, RecordPatch
+from matelab import RecordFormAttachmentFieldAddition
 
 # Alternative to the import above; do not run both with the same staged handle.
 result = await client.records.update(
     source,
-    RecordPatch(
-        attachment_changes=(
-            RecordFormAttachmentFieldAddition(
-                module="Attachments",
-                name="Measurement",
-                attachment=staged,
-            ),
-        )
+    attachment_changes=(
+        RecordFormAttachmentFieldAddition(
+            module="Attachments",
+            name="Measurement",
+            attachment=staged,
+        ),
     ),
 )
 ```
@@ -284,27 +304,24 @@ 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).
 
 Notebook create/update and direct sharing keep write acknowledgement separate from what a readback can prove:
 
 ```python
-from matelab import NotebookMetadata, NotebookSharePermissionGrant
-
-created = await client.notebooks.create(NotebookMetadata(title="Example Notebook"))
+await client.notebooks.create(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, 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:
@@ -312,32 +329,30 @@ relation identities:
 ```python
 templates = await client.templates.list()
 market = await client.templates.search_market("calibration", page=1, page_size=20)
-content = await client.templates.read(templates.owned[0].ref)
+modules = 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:
 
 ```python
-from matelab import RecordFieldExtraction, RecordLocator
+from matelab import RecordLocator
 
 exported = await client.records.export([RecordLocator(notebook=notebook, record=record)])
-matches = await client.records.search(
-    notebooks=[notebook], extractions=[RecordFieldExtraction(alias="notes", path=("Notes",))]
-)
+matches = await client.records.search(notebooks=[notebook], extractions={"notes": ("Notes",)})
 page = await client.records.page(notebook)
 deleted = await client.records.recycle_bin(notebook)
 relations = await client.records.relations(notebook=notebook, record=record)
@@ -352,18 +367,19 @@ remain unspecified, and no continuation token is invented.
 Record creation keeps blank creation and structured import as separate capabilities:
 
 ```python
-from matelab import RecordImportItem, RecordImportTemplate, TemplateRef
+from matelab import RecordImportItem, TemplateRef
 
 blank = await client.records.create_blank(notebook=notebook, title="Blank Record", record_uid="caller-generated-uid")
 imported = await client.records.import_dataset(
     notebook=notebook,
-    template=RecordImportTemplate(template=TemplateRef(template_id=8), title="Example Template"),
+    template=TemplateRef(template_id=8),
+    template_title="Example Template",
     items=[RecordImportItem(record_uid="import-uid", title="Imported", data={"Notes": "value"})],
 )
 ```
 
-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 +389,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:
 
@@ -393,7 +411,7 @@ Attachment bytes are streamed and must be consumed or closed explicitly:
 from matelab import ByteRange
 
 comments = await client.records.comments(notebook=notebook, record=record)
-attachment = comments.comments[0].attachments[0]
+attachment = comments[0].attachments[0]
 async with await client.records.download_comment_attachment(attachment, byte_range=ByteRange.from_start(0)) as download:
     async for chunk in download:
         consume(chunk)
@@ -425,13 +443,14 @@ 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:
 
 ```python
-from matelab import DoiMetadataSource, LiteratureMetadata
+from matelab import LiteratureMetadata
 
 libraries = await client.literature.libraries()
 page = await client.literature.list(libraries.personal.ref)
@@ -439,20 +458,17 @@ detail = await client.literature.read(page.items[0].ref)
 schema = await client.literature.creation_schema()
 
 if schema.metadata_extraction_available:
-    candidates = await client.literature.extract_metadata(DoiMetadataSource("10.0000/example"))
+    candidates = await client.literature.extract_metadata(doi="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
@@ -465,29 +481,29 @@ stable `ByteRange` subset.
 The personal cloud-drive surface keeps root, folder, final file and temporary staging identities separate:
 
 ```python
-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)
+folder_result = await client.cloud_drive.create_folder(name="Example data")
+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"
     )
 ```
 
-`CloudDriveListing` contains a typed file page, complete folder tree, quota usage and personal-root permissions rather
+`CloudDriveListing` contains a typed file page, complete folder snapshot, quota usage and personal-root permissions rather
 than flattening them into one ambiguous collection. Folder browse results retain their location; filename searches
 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 folder snapshot. 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 +542,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 +551,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