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

matelab_python_sdk-0.1.0a6/.env.example

@@ -0,0 +1,14 @@
+# SDK Provider smoke 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=
+
+# The SDK smoke does not read the settings below. Populate them only when the
+# same .env.test will also run the complete matelab-spec Provider Verification.
+MATELAB_PROVIDER_SHARE_USER_ID=
+MATELAB_PROVIDER_SECONDARY_USERNAME=
+MATELAB_PROVIDER_SECONDARY_PASSWORD=
+MATELAB_PROVIDER_RECORD_STAGING_MUTATIONS=
+MATELAB_PROVIDER_CHAT_SSO_KEY=

{matelab_python_sdk-0.1.0a4 → matelab_python_sdk-0.1.0a6}/AGENTS.md

@@ -50,8 +50,11 @@
 - `base_url` 表示 Provider API 根。query、JSON、form-urlencoded、multipart 和 streaming 必须按各 operation
   定义分别实现。
 - bearer 只用于要求认证的 operation；成功码按 operation 配置，不能全局接受 `{0, 10}`。
-- 每个 `AsyncMatelab` 实例最多持有一个进程内 Session，包含 access/refresh token、毫秒 expiration 和可选
-  identity；不同用户的 token pair 必须拒绝绑定，失败时不得替换现有 Session。
+- 每个 `AsyncMatelab` 实例最多持有一个进程内 Session，包含 access/refresh token、毫秒 expiration 和已验证
+  identity。SDK 不提供裸 access/refresh token 绑定接口；构造传入完整 Session 的真实性和身份归属验证属于
+  集成方。
+- `Token`、`Identity` 和 `Session` 是冻结、拒绝额外字段的 Pydantic public model，组成稳定的规范化 Session
+  JSON 契约。token 在 repr 中隐藏，但显式序列化必须保留真实凭证；序列化结果不得进入日志或发送给不可信方。
 - `client.session` 暴露实例内最新 Session。持久化、加密、撤销、`userid/session_id` 关联和跨进程锁属于
   集成方；不同逻辑 Session 不得共享同一个 `AsyncMatelab`，但多个实例可以共享注入的 `httpx.AsyncClient`。
 - access 到期前按 skew 刷新；并发刷新使用单个异步锁；已认证且可安全重试的请求遇到 `code=5` 最多强制

{matelab_python_sdk-0.1.0a4 → matelab_python_sdk-0.1.0a6}/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.1.0a6 - 2026-08-01
+
+- Adopts the immutable `matelab-spec v0.3.0` Contract release and its form-encoding updates.
+- Tightens the public authentication/session contract around complete, serializable Pydantic `Session` models while
+  retaining automatic access-token refresh and Provider SSO exchange.
+- Simplifies transport and domain interfaces, removes external-token binding and identity-attachment seams, and
+  restores strict runtime validation for byte-range inputs.
+
+## 0.1.0a5 - 2026-07-29
+
+- Adopts immutable `matelab-spec v0.1.2` at commit `6dd674ac001ae61197495ace5eba489d585cb825` and OpenAPI
+  SHA-256 `7ccaf3116c8dcec7a6e49ff51fb1a5ecc83a140e013ec600516f5c2ffb3b5378`.
+- Adds notebook-scoped staged finalizers for a null table file cell, an attachment-bearing appended table row,
+  files-module root append, and table/files occurrence replacement, with exact provenance, one-shot transport, and
+  canonical readback checks.
+- Adds typed intents for an empty file table column and complete form file-field/table file-column deletion.
+- Allows `records.update(..., module_deletions=...)` to delete a canonical module even when the current record read
+  observes attachments in it, verifies absence on persisted readback, and does not claim attachment-quote or byte
+  cleanup beyond the pinned Contract.
+- Rejects cross-scope staged attachment handles before the record read, preserving the public static types while
+  avoiding the Provider's read-audit side effect for invalid runtime input.
+- Keeps notebook-staged rich-text binding and attachment-bearing multi-record import explicitly unsupported because
+  v0.1.2 Provider Verification does not provide safe one-shot semantics for either.
+
 ## 0.1.0a4 - 2026-07-28
 
 - Further reduces the alpha public surface from 150 to 126 symbols by accepting direct keyword arguments and existing

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matelab-python-sdk
-Version: 0.1.0a4
+Version: 0.1.0a6
 Summary: Reusable async Python client for the Matelab Integration Contract
 Author-email: 朱天念 <zhutiannian@gmail.com>
 License-Expression: Apache-2.0
@@ -28,10 +28,10 @@ Description-Content-Type: text/markdown
 
 Reusable async Python client for the Matelab Integration Contract.
 
-The current alpha is `0.1.0a4`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a6`. `[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
+The SDK is pinned to the immutable `matelab-spec v0.3.0` Contract Release. The sole release pin is
 `contracts/matelab-integration-v1.lock.json`, which records
 the source tag, commit, OpenAPI path, local snapshot path, and SHA-256.
 
@@ -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.0a4-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a6-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -92,13 +92,10 @@ Catch `MatelabError` for one application-level fallback, or a specific subclass
 | `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. |
+| `MatelabProtocolError` | The Provider response does not match the pinned Contract; treat it as Provider drift or an SDK defect. A mutation may already have been applied. |
 
-`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.
+`code` and `status_code` are the stable scalar diagnostics. Provider response bodies and caller inputs are never
+attached to exceptions. Never automatically retry a mutation solely because it raised a transport or protocol error.
 
 ### Session ownership
 
@@ -114,24 +111,28 @@ rotation through `client.session`. If refresh succeeds but the subsequent busine
 | 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 immutable value objects, and token values are excluded from their
-representations. The SDK does not read tokens from environment variables and does not provide a session store.
+`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`.
 
-Credential authentication installs the returned Session on the client:
+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
-async with AsyncMatelab() as client:
-    session = await client.authenticate(username, password)
-    assert client.session is session
+serialized = session.model_dump_json()
+restored = Session.model_validate_json(serialized)
+assert restored == session
 ```
 
-External token exchange validates the original access-token identity, refreshes the supplied refresh token,
-validates the refreshed access-token identity, and rejects a userid mismatch. The existing client Session is
-replaced only after all three steps succeed:
+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.bind_external_tokens(access_token, refresh_token)
+    session = await client.authenticate(username, password)
     assert client.session is session
 ```
 
@@ -144,6 +145,10 @@ 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:
 
@@ -194,7 +199,7 @@ notebook selector used for upload:
 ```python
 import hashlib
 
-from matelab import RecordImportItem, TemplateRef
+from matelab import RecordImportItem
 
 content = b"measurement data"
 staged = await client.records.stage_attachment(
@@ -206,20 +211,17 @@ staged = await client.records.stage_attachment(
 )
 result = await client.records.import_dataset(
     notebook=notebook,
-    template=TemplateRef(template_id=8),
     template_title="Example Template",
     items=(
         RecordImportItem(
-            record_uid="REC-IMPORT-001",
-            title="Imported measurement",
-            data={"Attachments": {"File": [staged]}},
+            record_uid="REC-IMPORT-001", title="Imported measurement", data={"Attachments": {"File": [staged]}}
         ),
     ),
 )
 ```
 
-The same staged handle may instead be consumed by one safe update that adds a new file field to an existing form
-module:
+The same staged handle may instead be consumed by one safe update finalizer. For example, add a new file field to an
+existing form module:
 
 ```python
 from matelab import RecordFormAttachmentFieldAddition
@@ -228,30 +230,124 @@ from matelab import RecordFormAttachmentFieldAddition
 result = await client.records.update(
     source,
     attachment_changes=(
-        RecordFormAttachmentFieldAddition(
-            module="Attachments",
-            name="Measurement",
-            attachment=staged,
+        RecordFormAttachmentFieldAddition(module="Attachments", name="Measurement", attachment=staged),
+    ),
+)
+```
+
+Choose exactly one finalizer. A staged name may occur once in either a single-record import or one update operation;
+do not reuse it after transport starts, even when the Provider outcome is unknown. A locally rejected target or
+argument does not spend the handle. The SDK rejects raw Provider attachment references, cross-user or cross-notebook
+handles, unsafe combinations, duplicate use in one request, and a second finalization attempt through the same
+client.
+
+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
+
+The v0.1.2 Contract adds dedicated, verified notebook-staged update shapes. They remain public intent objects; callers
+never construct Provider paths or attachment strings:
+
+```python
+from matelab import RecordFilesAttachmentRootAppend, RecordTableFileCellSet, RecordTableRowAttachmentAppend
+
+# Each example is a separate finalizer; never run several with the same handle.
+await client.records.update(
+    source,
+    attachment_changes=(RecordTableFileCellSet(table="Measurements", column="Evidence", row=0, attachment=staged),),
+)
+
+await client.records.update(
+    source,
+    attachment_changes=(
+        RecordTableRowAttachmentAppend(
+            table="Measurements", file_column="Evidence", values={"Label": "Sample C"}, attachment=another_staged
         ),
     ),
 )
+
+await client.records.update(
+    source,
+    attachment_changes=(RecordFilesAttachmentRootAppend(module="Files", caption="Evidence", attachment=third_staged),),
+)
+```
+
+`RecordTableFileCellSet` requires an existing file column and a cell whose immediate canonical value is exactly
+`null`. The row-append intent addresses the new row by the row count from the SDK's immediate read and supports one
+staged file column. Files append is root-only and requires a string caption.
+
+Replacement starts with an occurrence returned by `records.read()`; applications must not fabricate a
+`RecordAttachmentRef`:
+
+```python
+from matelab import RecordFilesAttachmentReplacement
+
+record = await client.records.read(notebook=source.notebook, record=source.record)
+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, attachment_changes=(RecordFilesAttachmentReplacement(existing=existing, replacement=staged, caption=None),)
+)
+```
+
+For a files occurrence, `caption=None` preserves the observed string caption (an observed null caption normalizes to
+the required empty string). The update preserves the Provider `uid` and folder in the submitted content. Table
+replacement requires exactly one current attachment in the selected cell and uses
+`RecordTableFileAttachmentReplacement`. Both replacement forms require the new hash to differ.
+
+Row/index-based finalizers 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. `expected_content_sha256` is only a client-side prewrite
+check, not Provider compare-and-swap.
+
+File-bearing structure changes do not consume staging:
+
+```python
+from matelab import RecordFormFileFieldDeletion, RecordTableFileColumnAddition, RecordTableFileColumnDeletion
+
+await client.records.update(
+    source,
+    file_structure_changes=(
+        RecordTableFileColumnAddition(table="Measurements", name="Additional evidence"),
+        RecordFormFileFieldDeletion(form="Attachments", name="Obsolete evidence"),
+        RecordTableFileColumnDeletion(table="Measurements", name="Old evidence"),
+    ),
+)
 ```
 
-Choose exactly one finalizer. A staged name may occur once in either a single-record import or one update
-operation; do not reuse it, even after an error whose Provider outcome is unknown. The SDK rejects raw Provider
-attachment references, cross-user or cross-notebook handles, unsafe update shapes, duplicate use in one request,
-and a second finalization attempt through the same client. A Session imported without identity must first call
-`await client.resolve_identity()`. The Provider supplies no staging status, abort, TTL, atomicity, or retry
-guarantee, so callers must discard the handle as soon as a finalization request starts.
+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
+result = await client.records.update(
+    source, module_deletions=("Raw files",), expected_content_sha256=record.content_sha256
+)
+```
+
+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_browser_save"`, not persisted.
+
+Notebook-staged rich-text binding remains unsupported. Provider Verification shows that `#file{name}` is stored as
+plain text and that a hash-based URI can fall back to an existing quote, so neither is a one-shot staged finalizer.
+Existing `RecordRichTextUpdate` remains legal only with record-scoped `StagedRecordAttachment`. Attachment-bearing
+multi-record import is also forbidden; callers must split it into single-record finalizers.
 
 ## Implementation roadmap
 
 `docs/roadmap.md` is the complete SDK-only execution plan. It assigns all 71
-`matelab-spec v0.1.1` operations to ordered work packages, defines the machine-readable coverage that
+`matelab-spec v0.3.0` operations to ordered work packages, defines the machine-readable coverage that
 must be added, records Provider-risk gates, and specifies the final completion checks.
 
-The SDK exposes all 71 Contract operations through public domain interfaces. It deliberately excludes MCP
-migration, adjacent-repository changes, external
+The SDK tracks all 71 Contract operations and exposes 70 through public domain interfaces; one identity-bootstrap
+operation is intentionally unexposed. It deliberately excludes MCP migration, adjacent-repository changes, external
 publishing, and automatic mutation against a real Provider.
 
 Machine-readable status lives in
@@ -261,7 +357,7 @@ OpenAPI snapshot.
 
 | Domain | Implemented | Planned | Current public surface |
 |---|---:|---:|---|
-| Authentication | 4 | 0 | `authenticate`, `bind_external_tokens`, `refresh`, `resolve_identity`, `exchange_chat_sso_code` |
+| 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 |
@@ -270,20 +366,21 @@ OpenAPI snapshot.
 | File staging | 1 | 0 | Resumable fragment staging and compensating abort request |
 | Literature | 13 | 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** | **71** | **0** | No operation is intentionally unexposed |
+| **Total** | **70** | **0** | One operation is intentionally unexposed |
 
 ### Stability and known capability limits
 
-Coverage currently contains 15 `stable` and 56 `experimental` operations. The stable operation IDs are
-`resolveCurrentIdentity`, `loginTokenSet`, `refreshTokenSet`, `exchangeChatSsoCode`,
+Coverage currently contains 14 `stable`, 56 `experimental`, and one `not_applicable` operation. The stable operation
+IDs are `loginTokenSet`, `refreshTokenSet`, `exchangeChatSsoCode`,
 `shareMultipleTemplatesWithUsers`, `removeTemplateFromGroup`, `deleteNotebookShare`, `listNotebooks`,
 `listNotebookRecords`, `exportRecords`, `deleteRecordsByUid`, `copyRecord`, `readRecord`,
 `deletePersonalLiteratureItem`, and `readLiteratureCreateTemplate`.
 
 Every other implemented operation is explicitly `experimental`; the exact per-operation list and its
 PVD/PCG references live in
-`docs/operation-coverage.yaml`. There are no `intentionally_unexposed`
-operations and no `planned` operations. Experimental support means the SDK validates and exposes the
+`docs/operation-coverage.yaml`. `resolveCurrentIdentity` is intentionally unexposed because the SDK accepts only
+complete, integration-validated Sessions and does not bind bare external token pairs. 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.
@@ -298,10 +395,8 @@ session = await client.exchange_chat_sso_code(code="chat-sanitizedcode123", key=
 Group and user discovery expose sharing identities without inventing Provider pagination:
 
 ```python
-from matelab import UserSearchScope
-
 groups = await client.groups.list()
-targets = await client.users.search("Example Researcher", scope=UserSearchScope.SAME_INSTITUTE)
+targets = await client.users.search("Example Researcher", global_scope=False)
 ```
 
 Ordering remains Provider-unspecified and is documented rather than repeated as a constant result field. Group
@@ -309,19 +404,18 @@ members belong only to `groups.members_for`, not to every returned group. These
 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:
+Notebook create/update and direct sharing use the Provider acknowledgement without an automatic follow-up read:
 
 ```python
 await client.notebooks.create(title="Example Notebook")
-shares = await client.notebooks.share(notebook, [target.ref])
-updated = await client.notebooks.update_share(shares[0].ref, write=True, create=True)
+shares = await client.notebooks.shares(notebook)
+await client.notebooks.share(notebook, [target.ref])
+await client.notebooks.update_share(shares.shares[0].ref, write=True, create=True)
 ```
 
-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.
+Create, update, share, permission update, and unshare return `None` because their Provider responses contain no new
+resource representation. Call `list()` or `shares()` explicitly when the application needs current state. 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:
@@ -339,9 +433,9 @@ experimental because Provider discovery ordering/pagination and historical `imag
 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 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`.
+transaction. Metadata create/update returns the `TemplateRef` built from the Provider template ID. Other mutations
+return `None` because the Provider supplies no new identity or resource representation; callers can explicitly list
+or read when they need current state.
 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.
@@ -367,43 +461,40 @@ remain unspecified, and no continuation token is invented.
 Record creation keeps blank creation and structured import as separate capabilities:
 
 ```python
-from matelab import RecordImportItem, TemplateRef
+from matelab import RecordImportItem
 
-blank = await client.records.create_blank(notebook=notebook, title="Blank Record", record_uid="caller-generated-uid")
+await client.records.create_blank(notebook=notebook, title="Blank Record", record_uid="caller-generated-uid")
 imported = await client.records.import_dataset(
     notebook=notebook,
-    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 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
-automatically retried.
+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-008). Delete means moving records into the recycle bin, not permanent
+deletion. Delete and restore return `None`; record mutations are not automatically retried.
 
 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-014 through
 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.
+read-before-write rather than Provider CAS. `records.update()` returns the acknowledgement classification
+`"provider_reported_persisted"`, `"pending_browser_save"`, or `"provider_acknowledged_unclassified"`; it does not
+issue a post-write read. 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 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.
+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). Both mutations return `None`
+after acknowledgement.
 
 Comment upload follows the Provider's literal one-request `upload` field, not the incompatible Front fragment
-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.
+protocol (PVD-037). Comment mutations return `None` after acknowledgement. Edit and delete first verify that the
+selected comment is currently observed and caller-owned, but do not perform a post-write read (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:
 
@@ -465,10 +556,10 @@ await client.literature.create(LiteratureMetadata(title="Example import", doi="1
 
 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` 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).
+PDF replace/delete are separate acknowledged mutations and are not presented as atomic with metadata (PCG-010).
+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-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
@@ -482,13 +573,8 @@ The personal cloud-drive surface keeps root, folder, final file and temporary st
 
 ```python
 listing = await client.cloud_drive.list()
-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 len(matches) == 1:
-    renamed = await client.cloud_drive.update_file(
-        matches[0], filename="example-renamed.pdf", description="Sanitized description"
-    )
+folder = await client.cloud_drive.create_folder(name="Example data")
+await client.cloud_drive.bind_staged_file(staged, target=folder)
 ```
 
 `CloudDriveListing` contains a typed file page, complete folder snapshot, quota usage and personal-root permissions rather
@@ -496,14 +582,11 @@ 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 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 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
+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-031), and finalize atomicity/idempotency remain
+absent (PCG-012). 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-002-safe
 range subset. Cloud mutations are not automatically retried.
 
@@ -520,8 +603,8 @@ Provider identifiers distinct. Historical reads first re-read the authorized cur
 that the requested version is still present in its `modify_log`; both reads write Provider audit entries.
 
 Errors are separated into Provider business errors, authentication errors, HTTP/transport errors,
-Integration Contract response errors, and client-side usage errors. Token values and sensitive response
-fields are redacted from error text and retained diagnostic payloads.
+Integration Contract response errors, and client-side usage errors. Provider response bodies and caller inputs do not
+enter exceptions.
 
 ## Development
 
@@ -552,9 +635,9 @@ 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. 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.
+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
@@ -562,9 +645,9 @@ verification. Representative SDK adapter tests instead feed the pinned OpenAPI's
 `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 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.
+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:
 
@@ -573,15 +656,24 @@ Copy `.env.example` to the git-ignored local `.env.test`, then fill in the share
 - `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`. The identities returned by authentication and external token binding must
-agree. With the environment prepared:
+`.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
 ```
 
-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.
+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
 
@@ -599,6 +691,6 @@ uv run python scripts/check_release.py dist/release/*.whl dist/release/*.tar.gz
 ```
 
 Rebuilding the same commit with the same locked environment and `SOURCE_DATE_EPOCH` must produce
-byte-identical wheel and source distribution hashes. The release is bound to `matelab-spec v0.1.1`,
-commit `047746ad37d827a85f93d947942f1e5fab80d54c`, and OpenAPI SHA-256
-`1d437b071968d2df165c712092fba4a283832e0ac19bc791e0d5af82294d1cca`.
+byte-identical wheel and source distribution hashes. The release is bound to `matelab-spec v0.3.0`,
+commit `0b5612588708b4639a42c7983ee2f08c350994bf`, and OpenAPI SHA-256
+`ebf5d446e3a5866d773cf8cfffe1db28f27015635fbb621bc091673e865ef70e`.