matelab-python-sdk 0.2.0a7__tar.gz → 0.2.0a9__tar.gz

{matelab_python_sdk-0.2.0a7 → matelab_python_sdk-0.2.0a9}/CONTEXT.md

@@ -86,8 +86,8 @@ A notebook-scoped hierarchical container used to organize records. Records at th
 _Avoid_: Subtype, record type, template
 
 **Record import value**:
-A template-shaped value composed of JSON-compatible scalars and containers, with a staged attachment
-allowed wherever the template expects a file.
+A template-shaped value composed of JSON-compatible scalars and containers, with a staged attachment or existing
+cloud file allowed wherever the template expects a file.
 _Avoid_: Arbitrary object, stored record module, Provider attachment reference
 
 **Encrypted record modules**:

{matelab_python_sdk-0.2.0a7 → matelab_python_sdk-0.2.0a9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matelab-python-sdk
-Version: 0.2.0a7
+Version: 0.2.0a9
 Summary: Reusable async Python client for the Matelab Integration Contract
 Author: CMPDC, Institute of Physics, Chinese Academy of Sciences
 License-Expression: Apache-2.0
@@ -20,7 +20,7 @@ Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
-Requires-Dist: httpx2>=2.15.1
+Requires-Dist: httpx2>=2.16.0
 Requires-Dist: jsonschema>=4.26.0
 Requires-Dist: pydantic>=2.14.1
 Requires-Dist: typing-extensions>=4.16.0

{matelab_python_sdk-0.2.0a7 → matelab_python_sdk-0.2.0a9}/contracts/matelab-integration-v1.lock.json

@@ -2,12 +2,12 @@
   "schema_version": 1,
   "contract_line": "integration-v1",
   "release": {
-    "tag": "v2026.10.3",
-    "commit": "c668cff75b7fcedbee048a8f1c8792162bf4eb77"
+    "tag": "v2026.11.1",
+    "commit": "402a158052995850e0b7fad5ed5399c8a2eed294"
   },
   "openapi": {
     "source_path": "openapi/matelab-integration-v1.openapi.yaml",
     "snapshot": "matelab-integration-v1.openapi.yaml",
-    "sha256": "757017be241f1014f3b5966c2a0f89a4ef578a700ebd626c51d02a8ff92a6b2a"
+    "sha256": "f9d3bd0baa4e5e70fe13870c21d9be70e40e2686831a0ffcc4632b39f83a3257"
   }
 }

{matelab_python_sdk-0.2.0a7 → matelab_python_sdk-0.2.0a9}/contracts/matelab-integration-v1.openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: Matelab Integration Contract
-  version: "2026.10.3"
+  version: "2026.11.1"
   description: |
     Current PHP wire contract for generating SDKs against the selected
     `matelab-server` Provider version.
@@ -10,15 +10,20 @@ info:
     and attachment operations that resolve a data server support the
     `localhost` branch; remote forwarding is excluded pending downstream
     wire evidence and end-to-end verification (PVD-049).
+    Integration requests omit the optional browser `Version` header. If it is
+    supplied, PHP applies `intval` and compares it with the current minimum
+    20261029; a lower value returns HTTP 200 with string `code` and `errcode`
+    equal to `reload`. That browser refresh branch is outside the integer
+    response envelopes selected by this integration contract.
   x-contract-line: integration-v1
   x-provider-evidence:
     repository: /home/tnzhu/projects/matelab-server
-    commit: b70f590571b860f043365c9f2d6f95818d595862
+    commit: 00f17b6ce0906bb78b0a3e9bb8c50abee90ca3d0
     verificationRuntime:
-      baseUrl: http://127.0.0.1:18080/api
+      baseUrl: https://matelab.iphy.ac.cn/eln-test/api
       container: matelab-test-server-1
       coreSourceComparison: sha256-exact
-      coreSourceFileCount: 157
+      coreSourceFileCount: 152
       dataServerScope: localhost
     files:
       - controller/Actions.php
@@ -56,9 +61,9 @@ info:
       - sql/matelab.sql
       - sql/recommend.sql
   x-provider-audit:
-    currentCommit: b70f590571b860f043365c9f2d6f95818d595862
-    previousReleaseEvidenceCommit: 3f39d47b7ad43bed618b029a7d9cc51fab852eb6
-    lastProviderVerifiedCommit: b70f590571b860f043365c9f2d6f95818d595862
+    currentCommit: 00f17b6ce0906bb78b0a3e9bb8c50abee90ca3d0
+    previousReleaseEvidenceCommit: 161c4560ae1cb6267d46841d6fe8adc8270ee1bc
+    lastProviderVerifiedCommit: 00f17b6ce0906bb78b0a3e9bb8c50abee90ca3d0
     contractStatus: current-provider-aligned
     # Summary of changes adopted by current Supported Routes since the last
     # released contract, including contract corrections. The Provider diff is
@@ -66,29 +71,8 @@ info:
     # updates against that fixed release baseline; use [] if no relevant changes.
     # Entries are not per-change verification results or a cumulative history.
     incorporatedChanges:
-      - {operationId: stageTemporaryFile, change: byte-offset-continuation-and-45-character-session-limit}
-      - {operationId: stageTemporaryFile, change: abort-only-cleans-incomplete-bytes-and-workerman-errors-have-no-resume-anchor}
-      - {operationId: uploadRecordAttachment, change: single-fragment-hash-failure-rollback}
-      - {operationId: searchUsers, change: utf8-byte-minimum-without-a-keyword-length-cap-or-whitespace-filter}
-      - {operationId: listNotebookRecords, change: owner-id-or-email-selector-and-caller-defaults}
-      - {operationId: createBlankRecord, change: owner-id-or-email-selector-and-php-zero-title-rejection}
-      - {operationId: importRecordDataset, change: owner-and-template-owner-selectors-json-list-data-and-php-zero-string-rejection}
-      - {operationId: updateRecordData, change: owner-selector-numeric-extraction-selectors-and-module-specific-field-validation}
-      - {operationId: deleteRecordsByUid, change: owner-id-or-email-selector-and-caller-defaults}
-      - {operationId: saveNotebookMetadata, change: numeric-string-and-number-extraction-selectors}
-      - {operationId: searchRecordData, change: numeric-string-and-number-extraction-selectors}
-      - {operationId: addNotebookShare, change: provider-deduplicated-recipient-lists}
-      - {operationId: shareMultipleTemplatesWithUsers, change: list-limits-apply-after-provider-deduplication}
-      - {operationId: listLiteratureItems, change: duplicate-source-rating-and-keyword-filters-are-accepted}
-      - {operationId: shareLiteratureItems, change: provider-deduplicated-ids-and-optional-empty-recipient-list}
-      - {operationId: moveCloudDriveFiles, change: provider-deduplicated-file-ids}
-      - {operationId: deleteCloudDriveFiles, change: provider-deduplicated-file-ids}
-      - {operationId: listDeletedRecordPage, change: unpaged-zero-page-size-omits-count-and-page}
-      - {operationId: extractLiteratureMetadata, change: nonempty-doi-takes-precedence-over-staged-file-id}
-      - {operationId: saveTemplateContent, change: php-name-validation-and-json-body-checks-apply-only-on-write}
-      - {operationId: listTemplates, change: stored-keywords-accept-nonnull-json-values}
-      - {operationId: readTemplateContent, change: stored-module-names-and-language-are-returned-without-template-write-validation}
-      - {operationId: readRecord, change: record-update-names-and-stored-module-language-use-raw-response-types}
+      - {operationId: importRecordDataset, change: authorized-cloud-drive-hash-references-pass-permission-query}
+      - {operationId: updateRecordData, change: authorized-cloud-drive-hash-references-pass-permission-query}
   x-consumer-evidence:
     - repository: /home/tnzhu/projects/matelab-mcp
       commit: 94a129b2df0ef0fbcf179c10550fb7c9a5dd2e6f
@@ -109,10 +93,11 @@ info:
         identity must come from token issuance. ELN-group and notebook-list
         calls still provide Consumer evidence for their canonical GET forms.
     - repository: /home/tnzhu/projects/matelab-front
-      commit: c6a2fef86ef215256556d340b964f56dded7d3ce
+      commit: 55bc8d95d9d4ef02841621f0b793d273cea66137
       files:
         - src/App.vue
         - src/fn/index.js
+        - src/store/index.js
         - src/components/fullview.vue
         - src/components/userSelect.vue
         - src/components/users.vue
@@ -128,7 +113,8 @@ info:
         The current Front dev commit reads environment/menu from GET
         `/actions/app` and obtains session identity from token issuance.
         The shared upload client sends byte offsets to `/actions/bigupload`
-        and uses the acknowledged offset for the next fragment.
+        and uses the acknowledged offset for the next fragment. GET requests
+        also carry the browser version stored in `src/store/index.js`.
         Existing record, comment, template, literature and cloud-drive calls
         retain their Consumer use cases; no new routes are added by this audit.
   x-record-attachment-staging:
@@ -1648,7 +1634,13 @@ paths:
         Template-shaped file values supplied by the request must be strings in
         the `#file{name}` or `#hash{filename.ext, hash}` form. The current
         validator rejects even valid `#base64` input (PVD-042); inline base64
-        is outside the callable contract. In particular,
+        is outside the callable contract. Existing cloud-drive files can be
+        referenced by `#hash{filename.ext, hash}` when the selected notebook
+        owner's userid owns the personal-root file (`root_id=0`), or has a
+        `files_permissions` row for its shared root. An existing cloud quote
+        alone does not grant access. The reference creates a record attachment
+        quote without consuming the cloud-drive file.
+        In particular,
         table/form file arrays cannot contain explicit JSON null values on the
         current Provider. To create empty table file cells, omit the file column
         and let the Provider complete it with canonical null cells.
@@ -1666,6 +1658,17 @@ paths:
                   template: Example Template
                   dataset:
                     - {uid: GENERATED-WIRE-UID, title: Imported Example, data: {Notes: Sanitized}, keyword: calibration}
+              existing_cloud_attachment:
+                summary: Reuse an authorized cloud-drive file without consuming it
+                value:
+                  eln: Example Notebook
+                  template: Example Template
+                  dataset:
+                    - uid: REC-CLOUD-EXAMPLE-001
+                      title: Existing cloud attachment
+                      data:
+                        Attachments:
+                          File: ["#hash{evidence.zip, 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef}"]
               preuploaded_attachment:
                 summary: Upload-event UID and future record UID are deliberately different
                 value:
@@ -1699,6 +1702,12 @@ paths:
                   value: {code: 0, msg: Data imported, errcode: 0, errmsg: Data imported, id: [9004], eln_id: 12}
                 error:
                   value: {code: 4, msg: Multiple errors, errcode: 4, errmsg: Multiple errors, errs: [Invalid imported field]}
+                inaccessible_hash:
+                  value:
+                    code: 2
+                    msg: The referenced hash 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef does not exist
+                    errcode: 2
+                    errmsg: The referenced hash 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef does not exist
   /eln_api/export:
     post:
       operationId: exportRecords
@@ -1793,7 +1802,12 @@ paths:
         strings containing canonical `elnurl://h=...&s=...&f=...` references.
         The Provider scans the incoming richtext value, resolves hashes against
         caller-owned staging or authorized existing file quotes, and binds the
-        resulting attachments while saving the record.
+        resulting attachments while saving the record. Template-shaped
+        `#hash{filename.ext, hash}` values also accept existing cloud-drive
+        files: permission is checked against the selected notebook owner's
+        userid, using personal-root ownership or a `files_permissions` row for
+        the shared root. The cloud file is retained; an inaccessible hash is
+        rejected before record content is written.
 
         This operation does not modify record title or other record metadata.
         `UpdateRecordRequest` rejects a top-level `title`; the Front uses the
@@ -1848,6 +1862,15 @@ paths:
             examples:
               update:
                 value: {eln: Example Notebook, uid: REC-EXAMPLE-001, modify: [{path: [Notes], data: Sanitized update}]}
+              add_existing_cloud_attachment_field:
+                value:
+                  eln: Example Notebook
+                  uid: REC-EXAMPLE-001
+                  add:
+                    - module: Attachments
+                      name: Cloud file
+                      type: file
+                      data: ["#hash{evidence.zip, 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef}"]
               add_preuploaded_attachment_field:
                 value:
                   eln: Example Notebook
@@ -1951,6 +1974,12 @@ paths:
                   value: {code: 0, msg: Collaboration data update completed, errcode: 0, errmsg: Collaboration data update completed}
                 error:
                   value: {code: 4, msg: Multiple errors, errcode: 4, errmsg: Multiple errors, errs: [Invalid update path]}
+                inaccessible_hash:
+                  value:
+                    code: 2
+                    msg: The referenced hash 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef does not exist
+                    errcode: 2
+                    errmsg: The referenced hash 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef does not exist
   /eln_api/delete:
     post:
       operationId: deleteRecordsByUid
@@ -1993,7 +2022,10 @@ paths:
         contracted abort, status, expiration, or idempotent retry. A hash
         mismatch in this one-fragment flow rolls back the temporary row and
         new bytes. Errors after import/update writing starts still do not prove
-        whether the stage was consumed. Raw identifiers identify the staging row;
+        whether the stage was consumed. Temporary bytes retain the multipart
+        filename's extension after removing non-ASCII-alphanumeric characters;
+        the response still reports the original source filename.
+        Raw identifiers identify the staging row;
         their filesystem components are sanitized and can alias (PVD-051).
       x-known-provider-issues: [PVD-014, PVD-051]
       security: [{bearerAuth: []}]
@@ -3703,11 +3735,18 @@ paths:
         successful response's `offset`. Omitting it defaults to zero and
         restarts incomplete bytes rather than appending. The final fragment
         returns the combined SHA-256, size, source filename, temporary row id,
-        and legacy preview query.
+        and legacy preview query. The multipart filename's final extension,
+        stripped of characters outside `[A-Za-z0-9]` with case preserved,
+        also selects the temporary bytes. Repeat that extension on every
+        fragment; changing it cannot continue the previous bytes and returns
+        code 2 when the requested offset has no matching file. A different
+        filename stem with the same sanitized extension can continue them.
 
         `abort=1` is the compensating cleanup operation. It requires the same
-        `uid` and `tempid`, omits `file`, and removes incomplete bytes only.
-        It preserves an already completed staging row and its bytes. Both
+        `uid` and `tempid` and omits `file`. If no completed row exists for
+        those identifiers, it removes incomplete bytes for all extension
+        variants, including the extensionless file. If a completed row exists,
+        it preserves the row and bytes without cleaning any variants. Both
         states return the standard HTTP 200 code-2 error envelope ("upload
         cancelled"); that response does not prove completed staging was deleted.
         Complete uploads must be consumed by their intended finalizer; this
@@ -7450,7 +7489,10 @@ components:
         file:
           type: string
           format: binary
-          description: Required for upload branches and omitted for abort.
+          description: |
+            Required for upload branches and omitted for abort. The multipart
+            filename's sanitized final extension selects the temporary bytes;
+            keep that extension unchanged throughout continuation.
       allOf:
         - if:
             required: [abort]

{matelab_python_sdk-0.2.0a7 → matelab_python_sdk-0.2.0a9}/docs/api.md

@@ -5,18 +5,20 @@ See the [README](../README.md) for installation and quick start and [CONTEXT.md]
 
 ## Contract
 
-The SDK is pinned to the immutable `matelab-spec v2026.10.3` Contract Release. The sole pin,
+The SDK is pinned to the immutable `matelab-spec v2026.11.1` Contract Release. The sole pin,
 [contracts/matelab-integration-v1.lock.json](../contracts/matelab-integration-v1.lock.json), records peeled commit
-`c668cff75b7fcedbee048a8f1c8792162bf4eb77`, source `openapi/matelab-integration-v1.openapi.yaml`, the local snapshot path,
-and SHA-256 `757017be241f1014f3b5966c2a0f89a4ef578a700ebd626c51d02a8ff92a6b2a`. The annotated tag object is
-`b1d3ff039c576032f69ec7116347af1ba441ba5f`.
+`402a158052995850e0b7fad5ed5399c8a2eed294`, source `openapi/matelab-integration-v1.openapi.yaml`, the local snapshot path,
+and SHA-256 `f9d3bd0baa4e5e70fe13870c21d9be70e40e2686831a0ffcc4632b39f83a3257`. The annotated tag object is
+`18dbfd99f36ee7fc8cd620a251c7973d86e8dedd`.
 
-The Contract uses Provider source evidence from `b70f590571b860f043365c9f2d6f95818d595862`; v2026.10.3 validation ran
+The Contract uses Provider source evidence from `00f17b6ce0906bb78b0a3e9bb8c50abee90ca3d0`; v2026.11.1 validation ran
 against an isolated test instance and does not establish production behavior. The Front Consumer evidence
-`c6a2fef86ef215256556d340b964f56dded7d3ce` informs cross-Consumer capability review but does not define the SDK interface.
+`55bc8d95d9d4ef02841621f0b793d273cea66137` informs cross-Consumer capability review but does not define the SDK interface.
 
 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).
+The SDK does not add the optional browser `Version` header. Integrators should also omit it from injected HTTP clients:
+an outdated value triggers a string `reload` envelope outside the integration response schemas.
 
 ## Design
 
@@ -191,14 +193,15 @@ record_ids = await client.records.import_dataset(
 ```
 
 `RecordImportItem.data` uses the recursive `RecordImportValue` type: JSON-compatible scalars and nested mappings,
-lists, or tuples may contain a `StagedAttachment` wherever the template expects a file. Arbitrary Python
+lists, or tuples may contain a `StagedAttachment` or `CloudFile` wherever the template expects a file. Arbitrary Python
 objects are outside the interface and are also rejected at runtime before a Provider request.
 
 `content` accepts `bytes`, a synchronous `IO[bytes]`, or an `AsyncIterable[bytes]`. Callers do not supply a size,
 checksum, or multipart content type. The SDK calculates the SHA-256 itself; streams are fully consumed into a
 `SpooledTemporaryFile`, rewound, and only then sent to the Provider. Temporary-file write, seek, read, and close
 operations run outside the event-loop thread, including after the spool rolls to disk. The Contract fixes attachment
-parts to `application/octet-stream`.
+parts to `application/octet-stream`. Temporary record-attachment bytes retain the source filename's final extension,
+stripped to ASCII letters and digits with case preserved; the response retains the original source filename.
 
 An exception raised by an async source is propagated unchanged after the SDK closes its temporary file. The SDK reads
 streams through end-of-file and imposes no upload-size policy; callers remain responsible for limits such as an HTTP
@@ -218,6 +221,33 @@ The Provider supplies no staging status, abort, TTL, atomicity, idempotency, or
 persist handles must durably claim their own `uploaded -> finalizing/indeterminate` transition before calling a
 finalizer.
 
+### Existing cloud-drive attachments
+
+Use a `CloudFile` returned by `cloud_drive.list()` directly in template-shaped import data or in a new form file field:
+
+```python
+from matelab import RecordFormAttachmentFieldAddition, RecordImportItem
+
+cloud_file = (await client.cloud_drive.list()).files[0]
+item = RecordImportItem(
+    record_uid="REC-CLOUD-001", title="Cloud attachment", data={"Attachments": {"File": [cloud_file]}}
+)
+await client.records.import_dataset(notebook=notebook, template_title="Example Template", items=(item,))
+await client.records.update(
+    source, (RecordFormAttachmentFieldAddition(module="Attachments", name="Cloud file", attachment=cloud_file),)
+)
+```
+
+The SDK encodes the reference; the Provider retains the source cloud file. The same `CloudFile` may appear in
+multiple records or requests; it does not enter the SDK's one-shot staging claims. Imports containing any
+`StagedAttachment` retain the single-record and single-use restrictions. Cloud-file form additions may be combined
+with other non-conflicting changes; other attachment update intents still require `StagedAttachment`.
+
+The Provider checks access for the selected notebook owner's userid: personal-root ownership or permission on the
+file's shared root is required; an existing file quote alone grants no access. Inaccessible hashes are rejected
+before record content is written. Avoid overlapping reuse with a pending upload of the same bytes: Provider hash
+lookup can select and consume that upload and use its filename, while retaining the source cloud file.
+
 ### Attachment-bearing record update boundary
 
 `records.update(source, changes, ...)` accepts one non-empty sequence of `RecordChange` intents. Value updates and
@@ -253,7 +283,8 @@ await client.records.update(
 )
 ```
 
-These three operations use the Provider's staged-name finalizer and must be the only mutation in their update request.
+With `StagedAttachment`, these three operations use the Provider's staged-name finalizer and must be the only mutation
+in their update request.
 `RecordTableFileCellSet` requires an existing file column and a cell whose immediate canonical value is exactly
 `null`. `RecordTableRowAttachmentAppend` addresses the new row by the row count from the SDK's immediate read and
 supports one file column. A locally rejected target does not spend the handle; once transport starts, an ambiguous
@@ -317,9 +348,10 @@ preserves that omission in `Record.modules` and does not invent a timestamp; nul
 attachment shapes remain response errors. This exception can be removed after the Provider canonicalizes current and
 historical record content.
 
-All record attachment intents reject handles from another notebook or authenticated uploader, duplicate use within one
-finalization request, and raw Provider attachment references. Row/index-based operations use an immediate SDK read and
-must not be called while a concurrent editor is known to be active. The Provider offers no expected hash or revision,
+Staged attachment inputs reject handles from another notebook or authenticated uploader and duplicate use within one
+finalization request. Raw Provider attachment strings remain outside the public interface. Row/index-based operations
+use an immediate SDK read and must not be called while a concurrent editor is known to be active. The Provider offers
+no expected hash or revision,
 so the SDK does not present its read-before-write checks as concurrency control.
 
 File-bearing structure changes do not consume staging:
@@ -353,10 +385,9 @@ This requests only a canonical record-content mutation. A successful response ac
 it does not prove attachment-quote cleanup or byte deletion. Collaboration-pending is reported as
 `"pending"`, not persisted.
 
-`RecordRichTextUpdate` accepts the same `StagedAttachment` as import and other update intents. Attachment-bearing
-multi-record import is forbidden, so callers must split it into single-record imports with a fresh staged attachment
-for each request. Once an import or update request using a staged attachment starts, that handle cannot be retried or
-used for the other finalizer through the same client.
+`RecordRichTextUpdate` accepts `StagedAttachment`. Imports containing a staged attachment are limited to one record;
+callers must use a fresh staged attachment for each request. Once an import or update request using a staged attachment
+starts, that handle cannot be retried or used for the other finalizer through the same client.
 
 ## Operation coverage
 
@@ -692,19 +723,25 @@ assert isinstance(staged, StagedFile)
 The SDK derives `fragment_size` and computes the complete SHA-256 for a single `bytes` fragment. File-like content
 must declare its fragment size. For multiple fragments, pass the returned `StagedUploadSession` into the next call and
 supply `complete_sha256` on the final call. `next_offset` is the Provider-acknowledged byte offset, checked against the
-declared fragment size and sent with the next fragment. The SDK verifies the returned filename and total size, and
-compares hashes when a local expected hash is available. A final result contains the Provider hash, temporary row
+declared fragment size and sent with the next fragment. Repeat the filename's final extension across fragments:
+the Provider removes characters outside `[A-Za-z0-9]` and preserves case, so `paper.P-d_f` and `renamed.Pdf` select
+the same bytes. Changing that sanitized extension cannot resume the upload and returns code 2 when no matching
+file exists at the requested offset. The SDK sends each filename unchanged, checks the returned filename and total
+size, and compares hashes when a local expected hash is available. A final result contains the Provider hash, temporary row
 identity and direct `binding`; it no longer embeds resumable session state. The temporary Provider URL and upload-session
 identity needed by internal binding and cleanup remain hidden. Callers do not need to
 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 returns `None` for the Provider's code-2 cancellation signal. It removes incomplete bytes only;
-completed staging rows and bytes remain and must be consumed by their intended finalizer (PVD-052).
+`StagedFile` and returns `None` for the Provider's code-2 cancellation signal. Without a completed staging row, it
+removes all incomplete extension variants, including extensionless bytes. A completed row prevents any cleanup for
+that identity; completed staging must be consumed by its intended finalizer (PVD-052).
 Binding UIDs allow up to 100 characters; upload-session IDs allow up to 45 (PVD-024). Use fresh identities: different
 raw identifiers can alias after Provider filename sanitization (PVD-051). Workerman upload errors supply no usable
 resume offset (PVD-050). After a failed non-final fragment, cancel incomplete bytes and restart with fresh identities.
 An ambiguous final response can leave completed staging that `abort()` cannot delete.
 Staging mutations are never automatically retried.
+After upgrading from the previous Provider's extensionless storage, restart old incomplete uploads from offset zero
+or cancel them and use fresh session identities.
 
 Literature identities distinguish the personal library from shared libraries:
 

{matelab_python_sdk-0.2.0a7 → matelab_python_sdk-0.2.0a9}/docs/operation-coverage.yaml

@@ -3,7 +3,7 @@
 schema_version: 1
 contract:
   line: integration-v1
-  release: v2026.10.3
+  release: v2026.11.1
   operation_count: 71
 
 operations:

{matelab_python_sdk-0.2.0a7 → matelab_python_sdk-0.2.0a9}/pyproject.toml

@@ -1,10 +1,10 @@
 [build-system]
-requires = ["hatchling>=1.32.4"]
+requires = ["hatchling>=1.33.0"]
 build-backend = "hatchling.build"
 
 [project]
 name = "matelab-python-sdk"
-version = "0.2.0a7"
+version = "0.2.0a9"
 description = "Reusable async Python client for the Matelab Integration Contract"
 requires-python = ">=3.11"
 keywords = ["matelab", "electronic-lab-notebook", "eln", "asyncio", "sdk"]
@@ -12,7 +12,7 @@ authors = [
     { name = "CMPDC, Institute of Physics, Chinese Academy of Sciences" },
 ]
 dependencies = [
-    "httpx2>=2.15.1",
+    "httpx2>=2.16.0",
     "jsonschema>=4.26.0",
     "pydantic>=2.14.1",
     "typing-extensions>=4.16.0",
@@ -39,12 +39,12 @@ classifiers = [
 dev = [
     "basedpyright>=1.40.2",
     "nodejs-wheel-binaries==22.20.0",
-    "datamodel-code-generator>=0.86.0",
-    "hatchling>=1.32.4",
-    "pytest>=9.1.1",
-    "pytest-asyncio>=1.4.0",
+    "datamodel-code-generator>=0.87.0",
+    "hatchling>=1.33.0",
+    "pytest>=9.2.0",
+    "pytest-asyncio>=1.4.1",
     "pyyaml>=6.0.3",
-    "ruff>=0.17.1",
+    "ruff>=0.17.3",
 ]
 
 [tool.ruff]
@@ -65,6 +65,7 @@ reportIncompatibleUnannotatedOverride = "error"
 markers = [
     "provider: opt-in smoke tests against an explicitly acknowledged real Provider target",
 ]
+asyncio_default_fixture_loop_scope = "function"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/matelab"]

{matelab_python_sdk-0.2.0a7 → matelab_python_sdk-0.2.0a9}/src/matelab/_generated/models.py

@@ -2,7 +2,7 @@
 #
 # @generated by datamodel-codegen:
 #   filename:  openapi.yaml
-#   version:   0.86.0
+#   version:   0.87.0
 
 from enum import StrEnum
 from typing import Annotated, Any, Literal
@@ -11,7 +11,7 @@ from pydantic import ConfigDict, Field, RootModel, SecretStr, StrictBool, Strict
 
 from matelab._wire_validation import WireModel
 
-OPENAPI_INFO_VERSION = "2026.10.3"
+OPENAPI_INFO_VERSION = "2026.11.1"
 
 
 class ResponseEnvelope(WireModel):
@@ -2759,7 +2759,10 @@ class StageTemporaryFileRequest(WireModel):
     """
     file: bytes | None = None
     """
-    Required for upload branches and omitted for abort.
+    Required for upload branches and omitted for abort. The multipart
+    filename's sanitized final extension selects the temporary bytes;
+    keep that extension unchanged throughout continuation.
+
     """