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

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

@@ -3,6 +3,57 @@
 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`
+  (annotated tag object `cc362a9a36601f5d07d6e90c2c6994e33c202d88`) and OpenAPI SHA-256
+  `dee14f76e24b2d7c3d97a6f30a9369ac093d615d132db85836ab86671eadcf18`, aligned with Provider source evidence
+  `acb0e12f2d62a8959ab9e9bddf38e34a67c19b48`. The release evidence covers an isolated Provider, not production.
+- Breaking: `templates.save_content()` rejects invalid JSON in JSON code modules with non-null `style` before HTTP.
+  Generated write models and whole-request validation now enforce nested JSON content schemas. Readback continues to
+  preserve raw code strings (including empty or non-JSON text) and null; reading a module does not guarantee it can
+  be saved unchanged. JSON code without a style, or with null style, retains its existing write boundary.
+- Regenerates the private application bootstrap fields and credential-login restriction to an omitted or empty
+  WeChat code. Public credential login already omits that input. Record module creation preserves explicit code
+  strings and leaves omitted/null initialization to the Provider, which now uses an empty string without synthesizing
+  an ECharts series object.
+- Documents Chat SSO expiry against the user's mutable activity timestamp, single-attempt exchange, and lack of
+  concurrent one-time guarantees. Synchronizes the release's PVD/PCG renumbering and retired comment-upload issue.
+- Keeps staged files-module append root-only because its dedicated schema and `UpdateRecordRequest.add[]` still
+  disagree about folder paths (now PVD-030). Retains the read-only missing table-attachment timestamp compatibility.
+
 ## 0.1.0a23 - 2026-09-04
 
 - Temporarily accepts `readRecord` table file attachments that contain valid `filename`, `hash`, and `size` fields but

{matelab_python_sdk-0.1.0a23 → 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.0a23 → matelab_python_sdk-0.2.0a1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matelab-python-sdk
-Version: 0.1.0a23
+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,12 +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.0a23`. `[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.4.5` 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.
+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
+`a07997128c1df17a03724c5af8e11b45a34166f9d6e15558e66e0a301f2e0813`. The annotated tag object is
+`ae8098e1b5178b69706bddd8b70c1b4cfe3e09ba`.
 
 ## Installation
 
@@ -64,15 +66,32 @@ 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.0a23-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 and public SDK interface track the current reviewed Provider at
-`59eb05b233e5ddd023a60ccb5e5c5f2ae22a70f0`. Provider limitations that remain relevant to integrations are documented
-alongside the affected interfaces below.
+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
 
@@ -107,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
@@ -116,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.4.5 Contract also declares optional code-4 `errs`, but PVD-041 and PCG-015 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`
@@ -315,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.4.5 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-044):
+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
@@ -333,6 +351,20 @@ 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
+content as `[]`.
+
 A replacement starts with an occurrence returned by `records.read()`; applications must not fabricate a
 `RecordAttachmentRef`. The same `RecordAttachmentReplacement` covers both table-file and files-module occurrences:
 
@@ -436,7 +468,8 @@ and `deletePersonalLiteratureItem`.
 Every other implemented operation is explicitly `experimental`; the exact per-operation list and its
 PVD/PCG references live in
 `docs/operation-coverage.yaml`. `readApplicationBootstrap` is intentionally unexposed because it returns the Provider
-application environment and menu model, while SDK identity is sourced from token issuance. `readLiteratureCreateTemplate`
+application environment and menu model, including required `data_express_enable` and `data_express_text` fields, while
+SDK identity is sourced from token issuance. `readLiteratureCreateTemplate`
 is intentionally unexposed because it returns a frontend form definition and an optional deployment flag rather than
 a resource needed by the SDK interface. There are no `planned` operations. Experimental support means the SDK
 validates and exposes the pinned Contract while preserving limitations such as unstable ordering/pagination,
@@ -450,6 +483,13 @@ automatically retried, and the returned token set is stored in the same in-memor
 session = await client.exchange_chat_sso_code(code="chat-sanitizedcode123", key="sanitized-shared-key")
 ```
 
+The code suffix must be non-empty and the shared key must be non-blank. The Provider rejects a code after the current
+user's `active_datetime` plus 300 seconds; that timestamp can change through other user activity, so Consumers must not
+derive a deadline from the code or automatically retry an uncertain exchange. A sequential replay is rejected, but the
+Provider's read-then-clear implementation does not guarantee that concurrent exchanges have only one winner.
+Ordinary credential login does not expose the non-empty WeChat binding code branch, which can reassign another account's
+OpenID (PVD-032).
+
 Group and user discovery expose sharing identities without inventing Provider pagination:
 
 ```python
@@ -460,9 +500,11 @@ targets = await client.users.search("Example Researcher", global_scope=False)
 `groups.list()` returns the `GroupSummary` tuple directly. Ordering remains Provider-unspecified and is documented
 rather than repeated as a constant result field. The Provider's members for an unstable first group remain wire-only;
 `users.search()` is the public recipient-discovery interface. These two discovery interfaces are experimental because
-group order is unstable and user search is unpaged, unordered and not field-minimized (PVD-006, PVD-029).
+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:
 
@@ -485,9 +527,12 @@ Consequently, update performs one list pre-read followed by the write. This pres
 Provider offers no compare-and-swap or atomic read-modify-write operation. Call `list()` or `shares()` explicitly when
 the application needs current state. `NotebookPermissions` normalizes the Provider's stored and effective masks and
 is reused by record pages instead of maintaining a second nearly identical permission model. Direct shares always
-have implicit read access even when every optional permission is false (PVD-010).
+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:
@@ -510,17 +555,19 @@ await client.templates.save_content(template, modules)
 `TemplateModule.data_present` distinguishes a missing `data` property from an explicit null value, while
 `attributes` prevents additive canonical properties from being dropped during a read/save cycle. The SDK does not
 synthesize frontend editor UIDs, layout widths, rows, folders, option encoding, or a fixed set of display module
-types. A JSON-language code module with style metadata may return its JSON string or explicit `null`; number and boolean
-table cells preserve the Provider's empty string as distinct from scalar and `null` values. The Provider accepts some
+types. A JSON-language code module's `data` remains code text and may be empty, null, or invalid JSON;
+`language=json` does not imply that Consumers can parse it. When template content contains a code module with
+`language=json` and non-null `style`, its code text must be valid JSON to save. Number and boolean table cells preserve
+the Provider's empty string as distinct from scalar and `null` values. The Provider accepts some
 non-canonical module roots and arbitrary table file arrays, but the SDK does not expose that behavior: saved content
-must remain a canonical module list, and a table file cell must be one canonical attachment object or `null` (PVD-046).
-The Provider supports only whole-content replacement and has no atomic patch or compare-and-swap operation (PCG-007),
+must remain a canonical module list, and a table file cell must be one canonical attachment object or `null` (PVD-013).
+The Provider supports only whole-content replacement and has no atomic patch or compare-and-swap operation (PCG-008),
 so a read-modify-save sequence can overwrite a concurrent change.
 
 The market result retains the Provider's `total_count` and derives `has_more` without echoing the caller's page
 arguments; it does not claim a stable order or continuation token. Template reads remain experimental
 because Provider discovery ordering/pagination and historical `images` compatibility are not fully stable
-(PCG-003, PCG-009, PVD-013, PVD-022).
+(PCG-011, PCG-012, PVD-038, PVD-022).
 
 `templates.list()` returns one tuple. `TemplateSummary.scope` is limited to `owned`, `shared`, `group`, and `public`;
 Provider marketplace acquisitions and system defaults are both public templates. An acquired public template carries
@@ -535,7 +582,7 @@ transaction. Creation returns the new `TemplateRef`; metadata replacement and ot
 the Provider supplies no new resource representation. `update()` therefore requires the complete title, summary, and
 keyword set rather than implying a partial patch. `update_usage()` generates the Provider's required fresh hidden
 correlation value internally. Usage attachments remain unsupported until their staging and binding lifecycle is
-contracted safely (PVD-026). Marketplace revision limitations remain explicit through `content_version`,
+contracted safely (PVD-003). Marketplace revision limitations remain explicit through `content_version`,
 `published_content_version`, and `market_review_reason` (PVD-021).
 
 Extended record reads stay behind the same `records` interface:
@@ -555,7 +602,10 @@ 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`.
-The current Provider excludes encrypted records from search (PVD-043); an empty search result therefore does
+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.
 
 The Provider calls its notebook directory tree `subtype`; that name remains wire-only. The SDK exposes
@@ -565,7 +615,7 @@ The Provider calls its notebook directory tree `subtype`; that name remains wire
 positive folder ID for one folder.
 
 `records.page` fixes the legacy request to `page_size=0&default=1`, preventing the known owner-preference writes
-described by PVD-039; its total is derived internally from the Provider's complete matching ID list. The result keeps
+described by PVD-028; its total is derived internally from the Provider's complete matching ID list. The result keeps
 semantic `NotebookPermissions` directly, without a shallow context model or duplicated notebook/owner/template
 display metadata. Effective request pagination, the UI selection list and Provider keyword-filter echo are not exposed.
 Its `search` argument, shared with `records.list()`, maps the Provider's wire-level `content` filter without exposing
@@ -578,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:
@@ -603,10 +652,10 @@ imported = await client.records.import_dataset(
 
 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); it therefore returns only the tuple of database IDs actually
+individual inputs or promise atomicity (PCG-009); it therefore returns only the tuple of database IDs actually
 reported by the Provider. `RecordImportItem.keywords` is a tuple; the adapter owns the Provider's
 legacy semicolon encoding. Folder paths are ordered existing folder titles from the notebook root; they do not create
-missing folders. The current Provider rejects explicit-null table-file imports (PVD-045). Because the SDK accepts
+missing folders. The current Provider rejects explicit-null table-file imports (PVD-031). Because the SDK accepts
 arbitrary template-shaped data and cannot identify file columns without the template definition, integrations must omit
 an unset file-valued key instead of sending it as `None`. Delete means moving records into the recycle bin, not permanent
 deletion. Delete and restore return `None`; record mutations are not automatically retried.
@@ -618,19 +667,24 @@ without a readback request. Omitting `target_notebook` copies within the source
 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). The SDK reads current content only when a change needs attachment type, occurrence, row, or index state;
+files/images removal is rejected when the observed module contains the same hash more than once (PVD-010, PVD-018,
+and PVD-019). The SDK reads current content only when a change needs attachment type, occurrence, row, or index state;
 ordinary module creation and deletion rely on the Provider's own canonical update validation. `records.update()`
 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-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-019
+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
 caller-relative `editable` display flag: the mutation endpoint performs the source permission check. Relation
 deletion lists current relations only to refuse an observed cross-notebook target-ID collision because the Provider
@@ -640,12 +694,12 @@ ignores target notebook identity (PVD-020); its mutation likewise performs autho
 `records.comments()`. Each returned `RecordRelationRef` carries only the relation row and declared target IDs.
 Deletion accepts the source `RecordLocator` and one of those observed refs.
 
-Comment upload follows the current Provider's literal one-request `file` field (PVD-037). Comment mutations return `None`
+Comment upload follows the current Provider's literal one-request `file` field. Comment mutations return `None`
 after acknowledgement. Edit first verifies that the selected
 comment is currently observed and caller-owned because the Provider otherwise reports a false success for a missing or
 other-user ID (PVD-004). Delete sends the typed ref directly because the Provider mutation itself enforces record and
 caller ownership. Neither operation performs a post-write read. Staged comment attachments have no Contract abort
-operation, and binding remains affected by PVD-026. Comment create/update use the same `body` vocabulary as the
+operation, and binding remains affected by PVD-003. Comment create/update use the same `body` vocabulary as the
 returned `RecordComment.body`; the SDK does not perform rich-text display normalization, while the Provider's
 documented surrounding-whitespace trim still applies when saving.
 `RecordCommentRef` carries its `RecordLocator`, so update and delete accept the ref rather than an entire comment or a
@@ -667,9 +721,12 @@ 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-002).
+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-038).
+downloading; current Providers do not verify that association (PVD-006).
 
 Cross-domain staging keeps resumable state and completed-file identity separate:
 
@@ -691,7 +748,7 @@ Provider URL and upload-session identity needed by internal binding and cleanup
 splice either into content. The result does not claim that a later literature/cloud operation checks the uploader or
 consumes the file exactly once. `uploads.abort()` accepts either an active `StagedUploadSession` or a completed
 `StagedFile` and exposes the Provider's legacy code-2 cancellation signal as a `None`-returning compensating cleanup
-that is not independently verified (PVD-028).
+that is not independently verified (PVD-024).
 Staging mutations are never automatically retried.
 
 Literature identities distinguish the personal library from shared libraries:
@@ -721,7 +778,11 @@ The Provider's static literature form definition and extraction deployment flag
 returns a `PublicationMetadataCandidate`: unstored, rich publication evidence rather than metadata already attached to
 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-042).
+`^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
@@ -746,22 +807,22 @@ Create returns `None` and never guesses the new item from list position because
 canonical update preflights the raw item response and refuses to drop top-level or nested source/hidden fields. Passing
 `allow_source_metadata_loss=True` explicitly skips that preflight and sends the canonical replacement directly. The
 default read/check/write protection is best effort rather than atomic because the Provider offers no revision or
-compare-and-swap condition; this Provider-specific behavior remains internal to the update operation (PVD-027).
+compare-and-swap condition; this Provider-specific behavior remains internal to the update operation (PVD-012).
 PDF replace/delete are separate acknowledged mutations and are not presented as atomic with metadata.
 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).
+valid caller identity, then returns `None` because the Provider supplies no per-recipient IDs (PVD-008, PVD-027).
 
 Literature comments use explicit `create_comment()` and `update_comment()` intents. Creation first reads the current
 detail and rejects when the caller already owns a comment; callers then use that comment's `LiteratureCommentRef` with
 `update_comment()`. The ref contains only the Provider comment-row identity. Update and delete send that identity
 directly because the Provider mutation verifies current ownership and library permission. The creation preflight
 maintains the Integration Contract's one-caller-comment invariant for ordinary SDK use, but is not atomic because the
-Provider has no matching uniqueness constraint (PVD-035). When sharing with `copy_owner_comment=True`, multiple
+Provider has no matching uniqueness constraint (PVD-026). When sharing with `copy_owner_comment=True`, multiple
 caller-owned comments remain an explicit ambiguity because the Provider would otherwise choose one implicitly. A
 staged attachment can replace one `matelab-staged-file` marker; raw temporary URLs are rejected. These checks prevent
-common misuse but do not repair the Provider's cross-user UID lookup (PVD-026). Shared-library reads and writes remain
-experimental because the Provider permission JOIN is not scoped to the current user (PVD-011); successful SDK calls
+common misuse but do not repair the Provider's cross-user UID lookup (PVD-003). Shared-library reads and writes remain
+experimental because the Provider permission JOIN is not scoped to the current user (PVD-007); successful SDK calls
 must not be treated as independent authorization proof. Literature PDF downloads reuse `DownloadStream` and the
 stable `ByteRange` subset.
 
@@ -777,16 +838,16 @@ await client.cloud_drive.bind_staged_file(staged, target=folder)
 snapshot and quota usage; pagination applies only to `files`, while request page arguments are not echoed. Personal-root
 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-003, PVD-013).
-Cloud files expose the nullable stored modification timestamp, not the Provider's duplicate display-formatted date and
-time strings.
+Listings likewise omit search/order/direction request echoes. Ordering has no stable ID tie-breaker (PCG-011, PVD-038).
+`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`;
-the Provider binds by temporary row ID without checking its owner (PVD-031), and finalize atomicity/idempotency remain
+the Provider binds by temporary row ID without checking its owner (PVD-002), and finalize atomicity/idempotency remain
 absent. 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
+resolve bytes from the final file identity and reuse `DownloadStream`, thumbnail/preview choices and the PVD-015-safe
 range subset. Cloud mutations are not automatically retried.
 
 Owned, shared, and public catalog notebooks use one `NotebookRef`, distinguished by its
@@ -813,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
@@ -822,7 +884,7 @@ Template render metadata is also excluded from template summaries and record rea
 notebook title/keywords, Provider data-server routing, or the frontend PDF-capability flag. `Record.version` identifies
 historical content and is `None` for the current content. `Record.versions` contains refs usable for historical reads;
 Provider lock and signature projections remain wire-only. Relation creation still checks returned data servers
-internally to mitigate PVD-019.
+internally to mitigate PVD-009.
 
 Provider record-finalization and additional-signature mutations are intentionally outside the pinned Contract and SDK
 interface. They require the account password to unlock a private key, combine version creation with signing, provide no
@@ -926,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 release is bound to immutable `matelab-spec v0.4.5`, commit
-`6afac7ff151680130e6e4bc6d95782589b97f4e7`, and OpenAPI SHA-256
-`31a8d03b4366e2345dfccdbbaaaccf6754b2711428afa4295d778d121988460d`.
+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`.