matelab-python-sdk 0.1.0a24__tar.gz → 0.2.0a3__tar.gz

matelab_python_sdk-0.2.0a3/.env.example

@@ -0,0 +1,7 @@
+# SDK Provider smoke targets the confirmed isolated test service.
+# Configure this repository's .env.test independently of matelab-spec.
+# 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.0a24 → matelab_python_sdk-0.2.0a3}/.github/workflows/release.yml

@@ -84,7 +84,7 @@ jobs:
           uv pip install \
             --python "${RUNNER_TEMP}/matelab-consumer/bin/python" \
             dist/release/*.whl \
-            "basedpyright==1.39.9" \
+            "basedpyright<2,>=1.40.1" \
             "nodejs-wheel-binaries==22.20.0"
           "${RUNNER_TEMP}/matelab-consumer/bin/python" scripts/check_installed_package.py
           "${RUNNER_TEMP}/matelab-consumer/bin/basedpyright" \
@@ -116,4 +116,4 @@ jobs:
           name: python-package-distributions
           path: dist
       - name: Publish distributions
-        uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # v1.14.1
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

{matelab_python_sdk-0.1.0a24 → matelab_python_sdk-0.2.0a3}/AGENTS.md

@@ -5,11 +5,12 @@
 ## 维护顺序
 
 1. **定界**：先读 `git status` 和适用权威；完成标准是任务范围、用户现有改动和所需外部权限均已识别。
-2. **查证**：沿 public intent → wire operation → Provider evidence 核对；完成标准是每个受影响 operation 的
-   request、response、security、examples、成功码及 PVD/PCG 均有结论，Contract 缺口已明确报告。
-3. **收敛**：只修改任务必需的层；完成标准是 public、adapter、generated、tests、coverage 和 docs 的影响均已
-   记账，未加入 Provider 推测、Consumer 私有概念或无真实第二实现的 seam。
-4. **验证**：先跑聚焦测试，再跑适用的完整门槛；完成标准是必需命令全部退出为零，skip 单独说明。
+2. **查证**：涉及 SDK 行为或 Contract 时，沿 public intent → wire operation → Provider evidence 核对受影响
+   operation 的 request、response、security、examples、成功码及 PVD/PCG，明确报告 Contract 缺口。文档、排版和
+   工具配置修改只核对相关权威。
+3. **收敛**：只修改任务必需的层，检查 public、adapter、generated、tests、coverage 和 docs 中受影响的内容。
+4. **验证**：按变更类型选择 [delivery gate](docs/agent-workflows.md#delivery-gate)，先运行相关检查；代码变更先跑
+   聚焦测试，再跑完整门槛。完成标准是必需命令全部退出为零，skip 和 deselected 分别说明。
 5. **交付**：复核最终 diff、状态和验证证据；完成标准是结果、限制和未执行项都可由用户独立核对。
 
 ## 分支指针
@@ -20,11 +21,13 @@
   [`docs/agent-architecture.md#transport-session-and-errors`](docs/agent-architecture.md#transport-session-and-errors)。
 - **Contract adoption**：同步 spec tag、snapshot、lock 或生成模型时执行
   [`docs/agent-workflows.md#contract-adoption`](docs/agent-workflows.md#contract-adoption)。
-- **Delivery gate**：代码、Contract、依赖或构建元数据变化后执行
+- **Configuration and dependencies**：修改 `pyproject.toml`、依赖范围、lock 或对应 CI 配置时读
+  [`docs/agent-workflows.md#configuration-and-dependencies`](docs/agent-workflows.md#configuration-and-dependencies)。
+- **Delivery gate**：交付前按变更类型执行
   [`docs/agent-workflows.md#delivery-gate`](docs/agent-workflows.md#delivery-gate)。
 - **Provider validation**：任何实时 Provider smoke、读取或 mutation 前执行
   [`docs/agent-workflows.md#provider-validation`](docs/agent-workflows.md#provider-validation)。
-- **Release**：版本、制品、commit、tag、push 或 publish 任务执行
+- **Release**：准备版本或发布制品时执行；普通 commit/push 只应用其中的授权与 diff 审查要求
   [`docs/agent-workflows.md#release`](docs/agent-workflows.md#release)。
 
 ## 权威
@@ -48,5 +51,7 @@
   仓库只作只读证据来源。
 - `/home/tnzhu/projects/matelab-spec` 定义 Wire Contract、兼容策略及 Provider 问题；`matelab-server` 是 Provider
   实现，`matelab-mcp` 只提供 Consumer evidence，均不能反向定义 SDK interface。
-- commit、push、tag、publish、生产访问和真实 Provider mutation 需要本轮明确授权；授权只覆盖用户指定的目标与
-  副作用。
+- SDK 与 spec 可以使用同一个 Docker 测试服务，各自维护环境配置和测试职责；修改 SDK 不授权修改邻接仓库或
+  运行 spec 测试。
+- commit、push、tag、publish、生产访问和真实 Provider mutation 需要用户对目标及副作用的明确授权。沿用会话中
+  已有的有效授权；只在目标、副作用超出授权或必要信息缺失时再询问。

{matelab_python_sdk-0.1.0a24 → matelab_python_sdk-0.2.0a3}/CHANGELOG.md

@@ -3,6 +3,61 @@
 This file records release-to-release changes and migration impact. It is not the authority for the current interface;
 see [README.md](README.md) for current behavior and [AGENTS.md](AGENTS.md) for maintenance policy.
 
+## 0.2.0a3 - 2026-10-02
+
+- Updates the pinned PyPI publishing action to v1.14.2, whose Twine 7 supports the Core Metadata 2.5 emitted by
+  Hatchling 1.32.4. Publishes the changes recorded under `0.2.0a2`; that candidate passed SDK and artifact checks but
+  was not uploaded to PyPI because the previous publisher rejected its metadata version.
+
+## 0.2.0a2 - 2026-10-02
+
+- Raises runtime and build dependency lower bounds to validated stable releases and uses compatible
+  development tool ranges, retaining `nodejs-wheel-binaries==22.20.0` as the sole system-specific exact pin. Refreshes
+  the lock against PyPI and aligns the installed-wheel CI checker with the declared Basedpyright range.
+- Release artifact auditing compares dependency metadata with `pyproject.toml`, and release tests verify version
+  constraints and CI consistency without freezing dependency update values.
+- Sets the distribution author to CMPDC, Institute of Physics, Chinese Academy of Sciences.
+- Documents that SDK smoke can use the same isolated test service as spec while each repository keeps its own test
+  configuration; limits the SDK environment template to its smoke connection settings. Clarifies maintenance
+  validation by change type, keeps the default gate offline, and records the project and Basedpyright field order.
+- Fixes rich-text and comment attachment markers whose names share a prefix, preserving exact attachment bindings
+  regardless of mapping order.
+- Keeps download rejection errors within the public SDK error boundary when response cleanup fails.
+- Consolidates duplicate attachment tests and removes documentation, formatting, and current operation-count
+  assertions. Strengthens SDK stream lifecycle and upload metadata validation coverage with controlled offline fixtures.
+
+## 0.2.0a1 - 2026-10-02
+
+- Establishes the `0.x` versioning rule: incompatible public changes advance the SDK minor version; alpha/beta/RC
+  counters identify successive candidates for the same target version. SDK and Contract versions remain independent.
+- Adopts immutable `matelab-spec v2026.10.1` at commit `9941e2d623a1c2633adb459b823d78d4e62d3802`
+  (annotated tag object `ae8098e1b5178b69706bddd8b70c1b4cfe3e09ba`) and OpenAPI SHA-256
+  `a07997128c1df17a03724c5af8e11b45a34166f9d6e15558e66e0a301f2e0813`, aligned with Provider evidence
+  `3f39d47b7ad43bed618b029a7d9cc51fab852eb6`. The Contract's calendar version identifies a Provider-specific
+  snapshot verified on an isolated Workerman instance with local data servers.
+- Breaking: record JSON operations accept business code `0` only; Provider-internal forwarding code `10` is outside
+  the verified callable scope and raises `MatelabProtocolError` (PVD-049). Search aliases additionally reserve
+  `eln_id`, `title`, and `eln_name`; extraction paths reject numeric strings, negative indices and a numeric fourth
+  segment before HTTP. Generation retains these referenced scalar and positional JSON Schema constraints.
+- Adds `Record.encrypted_modules` and public `EncryptedRecordModules`, preserving ciphertext and additive fields
+  without decryption. Encrypted reads have no plaintext modules or attachment refs. State-dependent updates reject
+  encrypted content locally; stateless module changes retain the Provider's pre-write password check. Unresolved
+  author descriptors map to `author_name=None` while remaining validated in the private wire layer (PVD-044).
+- Restores `RecordFilesAttachmentAppend.folder_path` after the dedicated shape became valid within the top-level
+  update request. A non-empty path uses the staged-name finalizer, validates safe segments and requires an exclusive
+  mutation; reuse and ambiguous-finalization protections remain in effect (PVD-030). Inline base64 file input remains
+  outside the public write boundary (PVD-042).
+- Breaking: `GroupSummary.ref` can be `None` for a dangling membership (PVD-048), and `CloudFile.modified_at` is now
+  a required string because stored null timestamps fail before a successful Provider row is returned (PVD-047).
+  Notebook reads accept non-null JSON type settings, but metadata updates reject settings or extraction requests that
+  cannot be preserved within the write Contract before mutation (PVD-046).
+- Literature metadata extraction maps nested Provider errors to the usual safe SDK errors. Empty or opaque lists
+  raise `MatelabProtocolError` instead of being presented as publication candidates (PVD-045).
+- Allows zero-byte comment attachment discovery/downloads and documents the 4097-byte cap on local open ranges
+  beginning at zero. Download metadata remains available for explicit continuation; no automatic replay is added.
+- Retains the existing read-only missing table-attachment timestamp containment and the unexposed password,
+  signing, record-title-update and structured-error-detail capabilities.
+
 ## 0.1.0a24 - 2026-09-26
 
 - Adopts immutable `matelab-spec v0.5.0` at commit `4f2959472933da47d1ea3e275552884d51d4fdd9`

{matelab_python_sdk-0.1.0a24 → matelab_python_sdk-0.2.0a3}/CONTEXT.md

@@ -85,6 +85,11 @@ A template-shaped value composed of JSON-compatible scalars and containers, with
 allowed wherever the template expects a file.
 _Avoid_: Arbitrary object, stored record module, Provider attachment reference
 
+**Encrypted record modules**:
+Stored ciphertext returned without decryption, separate from a record's available plaintext modules and attachments.
+The encrypted descriptor is read evidence; it does not provide a decryption or password management interface.
+_Avoid_: Empty record content, decrypted modules
+
 **Staged attachment**:
 An upload prepared in a selected notebook for one later record import or update; uploading does not choose the target
 record.

matelab_python_sdk-0.2.0a3/PKG-INFO

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

matelab_python_sdk-0.1.0a24/PKG-INFO → matelab_python_sdk-0.2.0a3/README.md

@@ -1,31 +1,3 @@
-Metadata-Version: 2.4
-Name: matelab-python-sdk
-Version: 0.1.0a24
-Summary: Reusable async Python client for the Matelab Integration Contract
-Author-email: 朱天念 <zhutiannian@gmail.com>
-License-Expression: Apache-2.0
-License-File: LICENSE
-License-File: NOTICE
-Keywords: asyncio,electronic-lab-notebook,eln,matelab,sdk
-Classifier: Development Status :: 3 - Alpha
-Classifier: Framework :: AsyncIO
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: Scientific/Engineering
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Typing :: Typed
-Requires-Python: >=3.11
-Requires-Dist: httpx2<3,>=2.9.1
-Requires-Dist: jsonschema<5,>=4.26
-Requires-Dist: pydantic<3,>=2.13.4
-Requires-Dist: typing-extensions<5,>=4.14.1
-Description-Content-Type: text/markdown
-
 # matelab-python-sdk
 
 Reusable async Python client for the Matelab Integration Contract.
@@ -35,14 +7,14 @@ This README describes the current SDK interface, integration semantics, examples
 [AGENTS.md](AGENTS.md) for durable maintenance rules, and `docs/operation-coverage.yaml` for the machine-readable
 operation inventory.
 
-The current alpha is `0.1.0a24`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.2.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.5.0` Contract Release. The sole pin,
-`contracts/matelab-integration-v1.lock.json`, records peeled commit `4f2959472933da47d1ea3e275552884d51d4fdd9`,
+The SDK is pinned to the immutable `matelab-spec v2026.10.1` Contract Release. The sole pin,
+`contracts/matelab-integration-v1.lock.json`, records peeled commit `9941e2d623a1c2633adb459b823d78d4e62d3802`,
 source `openapi/matelab-integration-v1.openapi.yaml`, the local snapshot path, and SHA-256
-`dee14f76e24b2d7c3d97a6f30a9369ac093d615d132db85836ab86671eadcf18`. The annotated tag object is
-`cc362a9a36601f5d07d6e90c2c6994e33c202d88`.
+`a07997128c1df17a03724c5af8e11b45a34166f9d6e15558e66e0a301f2e0813`. The annotated tag object is
+`ae8098e1b5178b69706bddd8b70c1b4cfe3e09ba`.
 
 ## Installation
 
@@ -66,18 +38,33 @@ 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.0a24-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.2.0a3-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
 tag, commit, and checksum recorded below.
 
-The Contract uses Provider source evidence from `acb0e12f2d62a8959ab9e9bddf38e34a67c19b48`; v0.5.0 validation ran
+The Contract uses Provider source evidence from `3f39d47b7ad43bed618b029a7d9cc51fab852eb6`; v2026.10.1 validation ran
 against an isolated test instance and does not establish production behavior. The corresponding Front Consumer evidence
 is `0c985f5b6da8e8ef4627ca7065cea85e408ae981`; it informs cross-Consumer capability review but does not define the SDK
 interface. Provider limitations that remain relevant to integrations are documented alongside the affected interfaces
 below.
 
+Contract releases now use calendar versions to identify Provider-specific snapshots. This snapshot covers the
+Workerman runtime with the `localhost` data-server branch for ELN records and attachments; remote data-server
+forwarding is outside its verified callable scope (PVD-049).
+
+## Versioning
+
+SDK versions express compatibility of the public Python interface and behavior. Python prerelease spelling follows
+PEP 440: `0.2.0a3` is the third alpha candidate for `0.2.0`. During `0.x` development, incompatible changes advance
+the minor version. From `1.0.0`, compatible fixes advance patch, compatible additions advance minor, and incompatible
+changes advance major. Successive candidates for the same target version use `aN`, `bN`, or `rcN`.
+
+Contract calendar versions identify Provider wire snapshots independently. Each SDK release records its exact
+Contract tag, commit and checksum in the lock; multiple SDK fixes can use the same Contract release. Adopting a new
+Contract changes the SDK version according to its public impact. See [CHANGELOG.md](CHANGELOG.md) for migration details.
+
 ## Design
 
 The public module is intentionally small:
@@ -111,7 +98,7 @@ category:
 | `MatelabUsageError` | `VALIDATION` | No | The call cannot be represented safely; correct its arguments. |
 | `MatelabProviderError` | `BUSINESS`, `VALIDATION`, or `UPSTREAM` | No | The Provider rejected the request; record `provider_code` and route recovery by `category`; `provider_message` is an SDK-owned safe summary. |
 | `MatelabTransportError` | `UPSTREAM` | No | The HTTP exchange failed; `status_code` is present for HTTP failures, and a mutation outcome may be unknown. |
-| `MatelabProtocolError` | `UPSTREAM` | No | The response violates the pinned Contract; treat it as Provider drift or an SDK defect. |
+| `MatelabProtocolError` | `UPSTREAM` | No | The response violates the pinned Contract or cannot supply the structured result required by the SDK operation; inspect the Provider result or SDK boundary. |
 
 For `MatelabProviderError`, the SDK maps Provider wire code `2` to `BUSINESS`, `4` to `VALIDATION`, and `3` or an
 unknown code to `UPSTREAM`. `provider_code` is diagnostic metadata, not a stable routing identifier, and integrations
@@ -120,12 +107,12 @@ selected from the code mapping; they do not reproduce Provider-authored text. Au
 `MatelabAuthenticationError`; code `5`
 triggers at most one refresh and replay only for authenticated operations that explicitly enable
 `retry_on_access_expired`, otherwise codes `1` and `5` raise `MatelabAuthenticationError` directly.
-Codes `0` and `10` remain operation-specific successes selected by the pinned Contract; an operation that receives a
-success code it does not allow raises `MatelabProtocolError` rather than assigning an error category.
+Record operations accept business code `0`. Provider-internal forwarding code `10` is outside the pinned
+callable Contract and raises `MatelabProtocolError` rather than assigning an error category.
 `MatelabTransportError.status_code` remains available for HTTP failures. Provider response bodies, top-level `msg`,
 legacy `errmsg`, opaque `errs`, uncontracted debug fields, and request payloads are not attached to exceptions because
 Provider-authored diagnostics may contain stack traces, credentials, or submitted values.
-The pinned v0.5.0 Contract also declares optional code-4 `errs`, but PVD-029 and PCG-010 record opaque array/object
+The pinned v2026.10.1 Contract also declares optional code-4 `errs`, but PVD-029 and PCG-010 record opaque array/object
 containers and insufficient evidence for requiredness, cardinality, or exclusion from other codes. The SDK
 therefore keeps those diagnostics wire-only and does not expose `errs` as stable public metadata. A typed detail
 interface remains blocked until a future Contract release can define one from stronger Provider evidence. `retryable`
@@ -319,11 +306,10 @@ These three operations use the Provider's staged-name finalizer and must be the
 supports one file column. A locally rejected target does not spend the handle; once transport starts, an ambiguous
 result cannot be retried through the same client.
 
-Files-module append and table/files replacement use the general record attachment intents and may be combined with
-other non-conflicting record changes. `RecordFilesAttachmentAppend` currently targets the module root. Although
-v0.5.0 records Provider evidence for safe folder paths, its top-level `UpdateRecordRequest.add[]` schema still excludes
-the `path` property declared by the dedicated staged-name append shape; the SDK therefore does not expose folder paths
-until that wire-schema conflict is resolved (PVD-030):
+Files-module append at the module root and table/files replacement may be combined with other non-conflicting record
+changes. `RecordFilesAttachmentAppend.folder_path` optionally selects folders within the files module. A non-empty
+path uses the staged-name finalizer and must be the only mutation in its update request; the SDK validates every
+segment before writing to avoid the Provider's malformed-path fallback to the module root (PVD-030):
 
 ```python
 from matelab import RecordAttachmentReplacement, RecordFilesAttachmentAppend, RecordValueUpdate
@@ -337,6 +323,15 @@ await client.records.update(
 )
 ```
 
+To append within a folder, use a fresh upload in a separate update:
+
+```python
+await client.records.update(
+    source,
+    (RecordFilesAttachmentAppend(module="Files", attachment=folder_uploaded, folder_path=("Evidence", "Raw Data")),),
+)
+```
+
 For `RecordModuleCreation(module_type="code", language="json", style="echarts")`, omitted, null, and empty `data` all
 produce an empty string; explicit `"0"` stays `"0"`. Send the desired initial chart configuration as a JSON code string.
 Richtext/code module creation defaults missing `data` to `""`; form/table/files creation ignores it and initializes
@@ -480,6 +475,8 @@ rather than repeated as a constant result field. The Provider's members for an u
 group order is unstable and user search is unpaged, unordered and not field-minimized (PVD-017, PVD-025).
 `GroupSummary.notebook_creation_available` expresses whether the group can currently host notebook creation without
 exposing the Provider's data-server routing value.
+An observed dangling group membership has `GroupSummary.ref=None` and no usable group identity. If such a membership
+is selected as the Provider's first group, the whole request can fail with a Provider error (PVD-048).
 
 Notebook create and direct sharing use the Provider acknowledgement without an automatic follow-up read:
 
@@ -505,6 +502,9 @@ is reused by record pages instead of maintaining a second nearly identical permi
 have implicit read access even when every optional permission is false (PVD-037).
 `provider_signing_allowed` only represents Provider policy, not an SDK signing operation. Share-list order remains
 unspecified.
+Stored notebook type configuration may decode to any non-null JSON value, but metadata writes accept arrays only.
+If the stored configuration or display extraction requests cannot be preserved within the write Contract, update
+raises `MatelabProtocolError` before sending a mutation instead of silently replacing them (PVD-046).
 
 Template discovery keeps a template database identity separate from direct-share, market-acquisition, and group
 relation identities:
@@ -574,6 +574,9 @@ relations = await client.records.relations(source)
 as `modules`; it is not the template-shaped `RecordImportItem.data` accepted by record import.
 `records.search()` maps each requested field name to a stored record path. A match exposes only Provider-returned
 entries in `values`, so key membership distinguishes an absent result from an explicit JSON `null`.
+Extraction aliases cannot use `id`, `uid`, `eln_id`, `title`, or `eln_name`, which would overwrite result metadata
+(PVD-043). Paths contain one to four segments: the first three accept non-empty, non-numeric names or non-negative
+integer indices; a fourth segment must be a non-numeric property name. Numeric strings are rejected before HTTP.
 The current Provider excludes encrypted records from search (PVD-041); an empty search result therefore does
 not prove that no matching encrypted record exists.
 
@@ -597,8 +600,7 @@ Public summaries keep source notebook attribution but omit the Provider's unused
 email; their `notebook_title` follows the same naming used by export and search results. Relation refs retain only the
 stored relation row and declared target IDs; nullable JOIN previews and resolved target identity stay wire-only.
 Search and relation order remain unspecified, and no continuation token is invented. Export and search return tuples
-directly; Provider code `10` only reports transparent data-server forwarding and does not create a second public result
-shape.
+directly. Remote data-server forwarding code `10` is rejected because only local data-server results are covered.
 `DeletedRecordPage` does not repeat its input notebook.
 
 Record creation keeps blank creation and structured import as separate capabilities:
@@ -643,11 +645,16 @@ ordinary module creation and deletion rely on the Provider's own canonical updat
 returns the acknowledgement classification
 `"persisted"`, `"pending"`, or `"unknown"`; it does not
 issue a post-write read. Database, active-browser, and unclassified acknowledgements remain distinct, and mutation
-retries stay disabled. Encrypted record content is outside the SDK's public read/update interface: the list-level
-`RecordSummary.encrypted` flag lets callers identify and skip it, while the Provider password field and frontend-only
-password lifecycle remain unexposed. Files-module attachment append remains root-only because the pinned top-level
-update request schema does not admit the dedicated staged-name append shape's folder `path`; malformed path containers
-may also silently append at root according to PVD-030. A staged attachment is indeterminate once the write has started.
+retries stay disabled. Business code `0` alone does not distinguish persisted data from a browser collaboration
+broadcast; the classification uses the observed Provider acknowledgement and supplies no revision or atomicity
+guarantee. Current collaboration peers must be browsers viewing the same notebook and record.
+Encrypted reads return `Record.encrypted_modules` as an `EncryptedRecordModules` containing the ciphertext,
+algorithm and additive fields; `modules` and `attachments` are empty because no plaintext is available. Plaintext
+reads have `encrypted_modules=None`. State-dependent updates reject encrypted content before mutation, while
+ordinary module changes rely on the Provider's password validation before any write. The password and decryption
+lifecycle remain unexposed. The list-level `RecordSummary.encrypted` flag remains available for discovery.
+Unresolved author lookup descriptors remain wire-only and map to `author_name=None` on records and comments (PVD-044).
+A staged attachment is indeterminate once the write has started.
 
 Relation addition reads both endpoints and checks their resolved data server before writing; this reduces PVD-009
 risk but is not an atomic Provider authorization guarantee. It does not list relations merely to inspect the
@@ -687,6 +694,9 @@ async with await client.records.download_comment_attachment(
 
 `DownloadStream` exposes status, content type, length, range, and disposition metadata without buffering the
 complete file. Streams are not automatically replayed. `ByteRange` deliberately rejects `bytes=0-0` (PVD-015).
+For local files, `ByteRange.from_start(0)` returns at most the first 4097 bytes. Inspect `content_range` and request
+the next range starting at its end plus one, use a positive explicit end, or omit `byte_range` for the full file.
+Zero-byte comment attachments can be discovered and downloaded without a range.
 Comment attachment refs contain only file identity. Pass the parent comment ref returned by the same read when
 downloading; current Providers do not verify that association (PVD-006).
 
@@ -741,6 +751,10 @@ returns a `PublicationMetadataCandidate`: unstored, rich publication evidence ra
 a literature item. Its structured authors are `PublicationAuthorCandidate` values. Extraction accepts a DOI, a
 completed staged PDF, or both; a supplied DOI takes precedence over the staged PDF. A non-empty DOI must match
 `^10\.[0-9]+/\S+$`; the generated request model rejects other values before sending them to the Provider (PVD-040).
+The Provider can wrap an error inside an outer successful extraction response. The SDK maps that nested error to
+its usual safe Provider/authentication error. Empty or opaque backend lists raise `MatelabProtocolError` because they
+provide no structured `PublicationMetadataCandidate`; an outer success code does not promise extracted metadata
+(PVD-045).
 Literature list
 results likewise exclude Provider-generated citation HTML and author-highlight fragments; Consumers receive the
 underlying citation fields instead of presentation markup. `LiteratureDetail.metadata` is `None` when invalid legacy
@@ -797,8 +811,8 @@ snapshot and quota usage; pagination applies only to `files`, while request page
 metadata and permissions are synthetic/fixed for this Contract line and remain wire-only. File rows omit the constant
 caller owner fields and do not invent a folder location that the Provider fails to return for root-wide searches.
 Listings likewise omit search/order/direction request echoes. Ordering has no stable ID tie-breaker (PCG-011, PVD-038).
-Cloud files expose the nullable stored modification timestamp, not the Provider's duplicate display-formatted date and
-time strings.
+`CloudFile.modified_at` contains the stored modification timestamp as a non-null string. A stored null causes a
+Provider error before a successful file row can be returned (PVD-047). Display-formatted date and time remain wire-only.
 
 Folder create returns a `CloudFolderRef` built from the Provider ID. Other folder and file mutations return `None`
 after acknowledgement and do not automatically list the drive. Staged finalize accepts a completed `StagedFile`;
@@ -832,8 +846,9 @@ names or groups, so those fields are `None`. Public summary and creation time re
 Contract, while the unified model uses the wider owned/shared nullable types.
 
 Provider `types`, `display`, and `requests` fields configure its notebook-list UI rather than notebook domain data.
-`types` is a list of user-defined classification tags used by the Provider frontend for client-side filtering. These
-fields are therefore absent from `NotebookSummary` and from create/update inputs; the SDK handles their update-time
+`types` normally holds classification tags used by the Provider frontend for client-side filtering; legacy stored JSON
+can have another non-null shape. These fields are absent from `NotebookSummary` and from create/update inputs;
+the SDK handles their update-time
 preservation only as an internal Provider compatibility detail.
 
 Template render metadata is also excluded from template summaries and record reads. A `Record` has one
@@ -857,16 +872,20 @@ aliases, and unrelated fields do not enter exceptions.
 ## Development
 
 ```bash
-uv sync
-uv run python scripts/generate_models.py
+uv sync --frozen
 uv run python scripts/generate_models.py --check
 uv run ruff check .
 uv run ruff format --check .
 uv run basedpyright
-uv run pytest
-uv build
+uv run pytest -m 'not provider'
+uv build --no-build-isolation
 ```
 
+This gate checks the SDK with offline fixtures and excludes the real Provider smoke. Run focused tests first when
+changing code; documentation and configuration-only edits use the relevant checks described in
+[the maintenance workflows](docs/agent-workflows.md#delivery-gate). Contract or generator changes regenerate the
+private models with `uv run python scripts/generate_models.py` before running the gate.
+
 The generator first verifies the contract lock, OpenAPI release metadata, and snapshot digest. It then
 creates a temporary OpenAPI 3.1 generation projection, resolves references without network access, and
 generates private component, operation-response, and parameter models. Generator emission uses its built-in formatter;
@@ -875,23 +894,19 @@ projection flattens pure
 object inheritance and preserves constraints the model generator cannot express as self-contained JSON Schema
 2020-12 metadata; the checked-in release snapshot remains unchanged. `--check` performs the same validation and
 deterministic generation without writing the checked-in models. `WireModel` applies that metadata with the standard
-`jsonschema` Draft 2020-12 validator; the SDK does not maintain a second hand-written schema interpreter. The current
-lock resolves
-`datamodel-code-generator 0.71.0` and
-`hatchling 1.31.0`. Published metadata requires `httpx2>=2.9.1,<3`, `jsonschema>=4.26,<5`,
-`pydantic>=2.13.4,<3`, and `typing-extensions>=4.14.1,<5`; the build backend requires
-`hatchling>=1.27,<2`. These lower bounds are verified
-against the complete test suite on the supported Python boundary versions rather than inferred from
-`uv.lock`. The exact toolchain remains locked for development and release builds. Basedpyright and its
-Node wheel retain the compatible exact pair `basedpyright==1.39.9` and
-`nodejs-wheel-binaries==22.20.0`.
+`jsonschema` Draft 2020-12 validator; the SDK does not maintain a second hand-written schema interpreter.
+
+`pyproject.toml` declares runtime, build, and development compatibility ranges; `uv.lock` fixes the exact environment
+for development and release builds. Runtime and build lower bounds are verified against the complete test suite on
+the supported Python boundary versions. The sole exact development requirement is `nodejs-wheel-binaries`, retained
+for system compatibility. The `0.x` generator and Ruff ranges allow patch updates within their current minor versions.
 
 ## Opt-in Provider consumer smoke
 
 `tests/provider/test_provider_smoke.py` exercises the consumer flow through only the public SDK interface. Its base
 scenario covers credential authentication, persistence of the complete returned Session, restoration through a new
-`AsyncMatelab` instance, refresh with identity preservation, and notebook discovery. It is not Provider Verification
-and is skipped by default.
+`AsyncMatelab` instance, refresh with identity preservation, and notebook discovery. The development gate excludes it;
+a direct pytest run skips it if any of its three connection variables are missing.
 
 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
@@ -903,31 +918,27 @@ Provider smoke is restricted to the confirmed isolated test service. Authenticat
 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:
+SDK smoke can use the same isolated `matelab-test` service as `matelab-spec`. Each repository keeps its own test
+configuration: the SDK uses `.env.test`, and spec keeps its existing `.env`.
+
+Copy this repository's `.env.example` to the git-ignored local `.env.test`, then fill in the SDK connection settings:
 
 - `MATELAB_PROVIDER_BASE_URL`
 - `MATELAB_PROVIDER_USERNAME`
 - `MATELAB_PROVIDER_PASSWORD`
 
-These names intentionally match `matelab-spec` Provider Verification. The isolated target may copy them from the spec
-`.env` into this repository's `.env.test`. Refreshing the restored Session must preserve its authenticated identity.
-With the environment prepared:
+These names intentionally match `matelab-spec` Provider Verification. Refreshing the restored Session must preserve
+its authenticated identity. With the SDK environment prepared, run the public-interface smoke:
 
 ```bash
 uv run --env-file .env.test pytest -m provider tests/provider/test_provider_smoke.py
 ```
 
-This command runs only the SDK public-interface smoke; it is not the 71-operation Provider Verification. To reuse the
-same `.env.test` for the complete Contract suite, also populate the optional share user, secondary account, record
-staging opt-in, and Chat SSO settings documented in `.env.example`, then run from sibling checkouts:
-
-```bash
-cd ../matelab-spec
-uv run --env-file ../matelab-python-sdk/.env.test pytest
-```
-
-The files are never loaded implicitly, so normal test runs remain safely skipped. Do not use either flow against
-production, and never commit Provider credentials.
+This command runs only the SDK public-interface smoke; Provider Verification is maintained in
+`matelab-spec` with its own configuration and run instructions.
+SDK tests do not load `.env.test` implicitly; without Provider environment variables, the real smoke remains skipped.
+Offline SDK tests continue to use `MockTransport`. Do not use the smoke flow against production, and never commit
+Provider credentials.
 
 ## Reproducible release build
 
@@ -945,6 +956,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 SDK Contract pin is immutable `matelab-spec v0.5.0`, commit
-`4f2959472933da47d1ea3e275552884d51d4fdd9`, and OpenAPI SHA-256
-`dee14f76e24b2d7c3d97a6f30a9369ac093d615d132db85836ab86671eadcf18`.
+byte-identical wheel and source distribution hashes. The SDK Contract pin is immutable `matelab-spec v2026.10.1`, commit
+`9941e2d623a1c2633adb459b823d78d4e62d3802`, and OpenAPI SHA-256
+`a07997128c1df17a03724c5af8e11b45a34166f9d6e15558e66e0a301f2e0813`.

{matelab_python_sdk-0.1.0a24 → matelab_python_sdk-0.2.0a3}/contracts/matelab-integration-v1.lock.json

@@ -2,12 +2,12 @@
   "schema_version": 1,
   "contract_line": "integration-v1",
   "release": {
-    "tag": "v0.5.0",
-    "commit": "4f2959472933da47d1ea3e275552884d51d4fdd9"
+    "tag": "v2026.10.1",
+    "commit": "9941e2d623a1c2633adb459b823d78d4e62d3802"
   },
   "openapi": {
     "source_path": "openapi/matelab-integration-v1.openapi.yaml",
     "snapshot": "matelab-integration-v1.openapi.yaml",
-    "sha256": "dee14f76e24b2d7c3d97a6f30a9369ac093d615d132db85836ab86671eadcf18"
+    "sha256": "a07997128c1df17a03724c5af8e11b45a34166f9d6e15558e66e0a301f2e0813"
   }
 }