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

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

@@ -3,6 +3,38 @@
 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.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.0a1}/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.1.0a24 → matelab_python_sdk-0.2.0a1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matelab-python-sdk
-Version: 0.1.0a24
+Version: 0.2.0a1
 Summary: Reusable async Python client for the Matelab Integration Contract
 Author-email: 朱天念 <zhutiannian@gmail.com>
 License-Expression: Apache-2.0
@@ -35,14 +35,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.0a1`. `[project].version` in `pyproject.toml` is the sole SDK version source;
 `uv.lock` only mirrors that source.
 
-The SDK is pinned to the immutable `matelab-spec 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 +66,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.0a1-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
 tag, commit, and checksum recorded below.
 
-The Contract uses Provider source evidence from `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.0a1` is the first alpha candidate for `0.2.0`. During `0.x` development, incompatible changes advance
+the minor version. From `1.0.0`, compatible fixes advance patch, compatible additions advance minor, and incompatible
+changes advance major. Successive candidates for the same target version use `aN`, `bN`, or `rcN`.
+
+Contract calendar versions identify Provider wire snapshots independently. Each SDK release records its exact
+Contract tag, commit and checksum in the lock; multiple SDK fixes can use the same Contract release. Adopting a new
+Contract changes the SDK version according to its public impact. See [CHANGELOG.md](CHANGELOG.md) for migration details.
+
 ## Design
 
 The public module is intentionally small:
@@ -111,7 +126,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 +135,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 +334,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 +351,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 +503,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 +530,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 +602,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 +628,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 +673,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 +722,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 +779,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 +839,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 +874,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
@@ -945,6 +988,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.0a1}/README.md

@@ -7,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.0a1`. `[project].version` in `pyproject.toml` is the sole SDK version source;
 `uv.lock` only mirrors that source.
 
-The SDK is pinned to the immutable `matelab-spec 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
 
@@ -38,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.0a1-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
 tag, commit, and checksum recorded below.
 
-The Contract uses Provider source evidence from `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.0a1` is the first alpha candidate for `0.2.0`. During `0.x` development, incompatible changes advance
+the minor version. From `1.0.0`, compatible fixes advance patch, compatible additions advance minor, and incompatible
+changes advance major. Successive candidates for the same target version use `aN`, `bN`, or `rcN`.
+
+Contract calendar versions identify Provider wire snapshots independently. Each SDK release records its exact
+Contract tag, commit and checksum in the lock; multiple SDK fixes can use the same Contract release. Adopting a new
+Contract changes the SDK version according to its public impact. See [CHANGELOG.md](CHANGELOG.md) for migration details.
+
 ## Design
 
 The public module is intentionally small:
@@ -83,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
@@ -92,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`
@@ -291,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
@@ -309,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
@@ -452,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:
 
@@ -477,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:
@@ -546,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.
 
@@ -569,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:
@@ -615,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
@@ -659,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).
 
@@ -713,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
@@ -769,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`;
@@ -804,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
@@ -917,6 +960,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.0a1}/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"
   }
 }