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

{matelab_python_sdk-0.2.0a8 → 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.0a8 → matelab_python_sdk-0.2.0a9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matelab-python-sdk
-Version: 0.2.0a8
+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

{matelab_python_sdk-0.2.0a8 → 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.4",
-    "commit": "c422f4f7425ade81eb5a65d9448ca4ea8bcacc79"
+    "tag": "v2026.11.1",
+    "commit": "402a158052995850e0b7fad5ed5399c8a2eed294"
   },
   "openapi": {
     "source_path": "openapi/matelab-integration-v1.openapi.yaml",
     "snapshot": "matelab-integration-v1.openapi.yaml",
-    "sha256": "1bc28a61647b7b8f38b86c8ea0085415616857f967c997031794a88deb2e377c"
+    "sha256": "f9d3bd0baa4e5e70fe13870c21d9be70e40e2686831a0ffcc4632b39f83a3257"
   }
 }

{matelab_python_sdk-0.2.0a8 → 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.4"
+  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: 161c4560ae1cb6267d46841d6fe8adc8270ee1bc
+    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: 161c4560ae1cb6267d46841d6fe8adc8270ee1bc
-    previousReleaseEvidenceCommit: b70f590571b860f043365c9f2d6f95818d595862
-    lastProviderVerifiedCommit: 161c4560ae1cb6267d46841d6fe8adc8270ee1bc
+    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,8 +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: filename-extension-selects-continuation-bytes-and-abort-cleans-incomplete-extension-variants}
-      - {operationId: uploadRecordAttachment, change: temporary-bytes-retain-sanitized-source-extension}
+      - {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
@@ -88,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: 89332767c2f20de210baed1e1e42df56e7071ad6
+      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
@@ -107,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:
@@ -1627,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.
@@ -1645,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:
@@ -1678,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
@@ -1772,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
@@ -1827,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
@@ -1930,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

{matelab_python_sdk-0.2.0a8 → 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.4` 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
-`c422f4f7425ade81eb5a65d9448ca4ea8bcacc79`, source `openapi/matelab-integration-v1.openapi.yaml`, the local snapshot path,
-and SHA-256 `1bc28a61647b7b8f38b86c8ea0085415616857f967c997031794a88deb2e377c`. The annotated tag object is
-`72c52e2267598f9bde820f629bc62d5982f7081c`.
+`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 `161c4560ae1cb6267d46841d6fe8adc8270ee1bc`; v2026.10.4 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
-`89332767c2f20de210baed1e1e42df56e7071ad6` 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,7 +193,7 @@ 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,
@@ -219,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
@@ -254,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
@@ -318,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:
@@ -354,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
 

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

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

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "matelab-python-sdk"
-version = "0.2.0a8"
+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"]

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

@@ -11,7 +11,7 @@ from pydantic import ConfigDict, Field, RootModel, SecretStr, StrictBool, Strict
 
 from matelab._wire_validation import WireModel
 
-OPENAPI_INFO_VERSION = "2026.10.4"
+OPENAPI_INFO_VERSION = "2026.11.1"
 
 
 class ResponseEnvelope(WireModel):

{matelab_python_sdk-0.2.0a8 → matelab_python_sdk-0.2.0a9}/src/matelab/domains/records.py

@@ -16,6 +16,7 @@ from matelab._hashes import LOWERCASE_SHA256_PATTERN
 from matelab._transport import Encoding, Operation, SessionTransport, StreamOperation
 from matelab._wire_validation import WireValue, encode_json_field, validate_multipart_request, validate_request
 from matelab.domains._attachment_content import prepare_attachment_content
+from matelab.domains.cloud_drive import CloudFile
 from matelab.domains.notebooks import NotebookPermissions, NotebookRef, validate_notebook_scope
 from matelab.domains.uploads import UploadBindingRef
 from matelab.domains.users import UserRef
@@ -432,6 +433,7 @@ RecordImportValue: TypeAlias = (
     | bool
     | None
     | StagedAttachment
+    | CloudFile
     | Mapping[str, "RecordImportValue"]
     | list["RecordImportValue"]
     | tuple["RecordImportValue", ...]
@@ -488,11 +490,11 @@ class RecordValueAddition:
 
 @dataclass(frozen=True, slots=True)
 class RecordFormAttachmentFieldAddition:
-    """Add one new file field and finalize one staged attachment."""
+    """Add one file field from a staged upload or an existing cloud file."""
 
     module: str
     name: str
-    attachment: StagedAttachment
+    attachment: StagedAttachment | CloudFile
 
 
 @dataclass(frozen=True, slots=True)
@@ -929,8 +931,8 @@ def _current_attachment(source: RecordLocator, current: Record, requested: Recor
     return attachment
 
 
-def _iter_import_attachments(value: RecordImportValue) -> Iterator[StagedAttachment]:
-    if isinstance(value, StagedAttachment):
+def _iter_import_attachments(value: RecordImportValue) -> Iterator[StagedAttachment | CloudFile]:
+    if isinstance(value, StagedAttachment | CloudFile):
         yield value
     elif isinstance(value, Mapping):
         for item in value.values():
@@ -940,13 +942,13 @@ def _iter_import_attachments(value: RecordImportValue) -> Iterator[StagedAttachm
             yield from _iter_import_attachments(item)
 
 
-def _iter_dataset_attachments(items: Sequence[RecordImportItem]) -> Iterator[StagedAttachment]:
+def _iter_dataset_attachments(items: Sequence[RecordImportItem]) -> Iterator[StagedAttachment | CloudFile]:
     for item in items:
         for value in item.data.values():
             yield from _iter_import_attachments(value)
 
 
-def _iter_update_attachments(changes: tuple[RecordChange, ...]) -> Iterator[StagedAttachment]:
+def _iter_update_attachments(changes: tuple[RecordChange, ...]) -> Iterator[StagedAttachment | CloudFile]:
     for change in changes:
         if isinstance(
             change,
@@ -965,6 +967,7 @@ def _iter_update_attachments(changes: tuple[RecordChange, ...]) -> Iterator[Stag
 def _validate_staged_name_update_shape(changes: tuple[RecordChange, ...]) -> None:
     has_finalizer = any(
         isinstance(change, RecordFormAttachmentFieldAddition | RecordTableFileCellSet | RecordTableRowAttachmentAppend)
+        and isinstance(change.attachment, StagedAttachment)
         or isinstance(change, RecordFilesAttachmentAppend)
         and bool(change.folder_path)
         for change in changes
@@ -994,7 +997,7 @@ def _record_update_requires_current_state(changes: tuple[RecordChange, ...]) ->
     )
 
 
-def _encode_record_attachment_reference(attachment: StagedAttachment) -> str:
+def _encode_record_attachment_reference(attachment: StagedAttachment | CloudFile) -> str:
     return f"#hash{{{attachment.filename}, {attachment.sha256}}}"
 
 
@@ -1925,7 +1928,7 @@ class Records:
                 | RecordTableRowAttachmentAppend
                 | RecordFilesAttachmentAppend,
             ):
-                self._compile_staged_record_attachment_change(change, patch)
+                self._compile_record_attachment_addition(change, patch)
             else:
                 self._compile_observed_record_attachment_change(
                     source, current, change, removals, value_deletions, patch
@@ -1939,7 +1942,7 @@ class Records:
             patch.claim(path)
             patch.modify.append({"path": list(path), "data": _encode_record_rich_text(change)})
 
-    def _compile_staged_record_attachment_change(
+    def _compile_record_attachment_addition(
         self,
         change: (
             RecordFormAttachmentFieldAddition
@@ -1953,19 +1956,31 @@ class Records:
             patch.reject_deleted_module(change.module)
             module = patch.modules.get(change.module)
             if module is None or module.get("type") != "form":
-                raise MatelabUsageError("A record attachment can be finalized only into an existing form module.")
-            if not change.name or _module_field(module, change.name) is not None:
-                raise MatelabUsageError("A record attachment requires a new non-empty form field name.")
+                raise MatelabUsageError("A record attachment requires an existing form module.")
+            if (
+                not change.name
+                or _module_field(module, change.name) is not None
+                or any(
+                    isinstance(addition, dict)
+                    and addition.get("module") == change.module
+                    and addition.get("name") == change.name
+                    for addition in patch.add_values
+                )
+            ):
+                raise MatelabUsageError("A record attachment requires a new, unique non-empty form field name.")
+            patch.claim((change.module, change.name))
+            attachment = change.attachment
+            if isinstance(attachment, CloudFile):
+                model = wire_models.AddValueOperation
+                reference = _encode_record_attachment_reference(attachment)
+            else:
+                model = wire_models.AddNewFormFileFieldWithStagedAttachmentOperation
+                reference = f"#file{{{attachment.binding.uid}}}"
             patch.add_values.append(
                 _operation_payload(
-                    wire_models.AddNewFormFileFieldWithStagedAttachmentOperation,
-                    {
-                        "module": change.module,
-                        "name": change.name,
-                        "type": "file",
-                        "data": [f"#file{{{change.attachment.binding.uid}}}"],
-                    },
-                    "New form-file attachment finalizer does not satisfy the contract.",
+                    model,
+                    {"module": change.module, "name": change.name, "type": "file", "data": [reference]},
+                    "New form-file attachment does not satisfy the contract.",
                 )
             )
             return
@@ -2235,11 +2250,21 @@ class Records:
             )
 
     def _staged_attachment_keys(
-        self, notebook: NotebookRef, attachments: Iterable[StagedAttachment]
+        self, notebook: NotebookRef, attachments: Iterable[StagedAttachment | CloudFile]
     ) -> set[_StagedAttachmentKey]:
         uploader = UserRef(userid=self._transport.require_session().identity.userid)
         keys: set[_StagedAttachmentKey] = set()
         for attachment in attachments:
+            if isinstance(attachment, CloudFile):
+                if (
+                    not attachment.filename
+                    or len(attachment.filename) > 255
+                    or "\r" in attachment.filename
+                    or "\n" in attachment.filename
+                    or LOWERCASE_SHA256_PATTERN.fullmatch(attachment.sha256) is None
+                ):
+                    raise MatelabUsageError("Cloud-file metadata does not satisfy the Integration Contract.")
+                continue
             if attachment.notebook != notebook:
                 raise MatelabUsageError("Staged attachment belongs to a different notebook.")
             if attachment.uploader != uploader:
@@ -2262,9 +2287,11 @@ class Records:
         """Encode one domain import value."""
         if isinstance(value, StagedAttachment):
             return f"#file{{{value.binding.uid}}}"
+        if isinstance(value, CloudFile):
+            return _encode_record_attachment_reference(value)
         if isinstance(value, str):
             if _contains_native_attachment_reference(value):
-                raise MatelabUsageError("Provider-native attachment references require a staged attachment object.")
+                raise MatelabUsageError("Provider-native attachment references require a typed attachment object.")
             return value
         if isinstance(value, Mapping):
             return {name: self._encode_import_value(item) for name, item in value.items()}

{matelab_python_sdk-0.2.0a8 → matelab_python_sdk-0.2.0a9}/tests/conftest.py

@@ -8,7 +8,7 @@ from typing import Any, cast
 import pytest
 import yaml
 
-from matelab import Identity, Session, Token
+from matelab import CloudFile, CloudFileRef, Identity, Session, Token
 
 ROOT = Path(__file__).resolve().parents[1]
 SPEC = ROOT / "contracts" / "matelab-integration-v1.openapi.yaml"
@@ -24,6 +24,18 @@ def provider_session() -> Session:
     )
 
 
+@pytest.fixture
+def cloud_file() -> CloudFile:
+    return CloudFile(
+        ref=CloudFileRef(cloud_file_id=81),
+        filename="evidence.zip",
+        sha256="0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+        size=5,
+        modified_at="2026-01-02 08:00:00",
+        description="",
+    )
+
+
 @pytest.fixture
 def provider_envelope() -> Callable[..., dict[str, object]]:
     def build(*, code: int = 0, message: str = "", **payload: object) -> dict[str, object]:

{matelab_python_sdk-0.2.0a8 → matelab_python_sdk-0.2.0a9}/tests/test_record_lifecycle.py

@@ -1,5 +1,6 @@
 import json
 from collections.abc import Callable
+from dataclasses import replace
 from typing import cast
 
 import pytest
@@ -7,10 +8,12 @@ from httpx2 import AsyncClient, MockTransport, Request, Response
 
 from matelab import (
     AsyncMatelab,
+    CloudFile,
     Identity,
     MatelabAuthenticationError,
     MatelabUsageError,
     NotebookRef,
+    RecordFormAttachmentFieldAddition,
     RecordImportItem,
     RecordLocator,
     RecordRef,
@@ -152,8 +155,93 @@ async def test_import_dataset_validates_wire_shape_without_interpreting_notebook
 
 
 @pytest.mark.asyncio
-async def test_import_dataset_consumes_one_staged_import_attachment_once(
-    provider_session: Session, provider_envelope: Callable[..., dict[str, object]]
+async def test_import_dataset_reuses_cloud_file_across_records_and_requests(
+    cloud_file: CloudFile, provider_session: Session, provider_envelope: Callable[..., dict[str, object]]
+) -> None:
+    notebook = NotebookRef(notebook_id=23, title="Shared Notebook", owner_userid=202, scope="shared")
+    request_count = 0
+
+    async def handler(request: Request) -> Response:
+        nonlocal request_count
+        request_count += 1
+        assert request.method == "POST"
+        assert request.url.path == "/api/eln_api/import"
+        assert request.headers["Authorization"] == "Bearer access"
+        assert request.headers["Content-Type"] == "application/json"
+        expected_records = (1, 2) if request_count == 1 else (3,)
+        assert json.loads(request.content) == {
+            "eln": "Shared Notebook",
+            "user": 202,
+            "template": "Example Template",
+            "dataset": [
+                {
+                    "uid": f"IMPORT-CLOUD-{number}",
+                    "title": "Existing cloud attachment",
+                    "data": {
+                        "Attachments": {
+                            "File": [
+                                "#hash{evidence.zip, 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef}"
+                            ]
+                        }
+                    },
+                }
+                for number in expected_records
+            ],
+        }
+        return Response(200, json=provider_envelope(id=[9100 + number for number in expected_records], eln_id=23))
+
+    async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
+        client = AsyncMatelab("https://ignored.example", session=provider_session, http_client=http_client)
+        results: list[tuple[int, ...]] = []
+        for numbers in ((1, 2), (3,)):
+            items = tuple(
+                RecordImportItem(
+                    record_uid=f"IMPORT-CLOUD-{number}",
+                    title="Existing cloud attachment",
+                    data={"Attachments": {"File": (cloud_file,)}},
+                )
+                for number in numbers
+            )
+            results.append(
+                await client.records.import_dataset(notebook=notebook, template_title="Example Template", items=items)
+            )
+
+    assert results == [(9101, 9102), (9103,)]
+    assert request_count == 2
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "metadata", ({"filename": ""}, {"filename": "x" * 256}, {"filename": "file\n.zip"}, {"sha256": "A" * 64})
+)
+async def test_invalid_cloud_file_metadata_is_rejected_before_import_or_update_http(
+    metadata: dict[str, str], cloud_file: CloudFile, provider_session: Session
+) -> None:
+    invalid_file = replace(cloud_file, **metadata)
+    notebook = NotebookRef(notebook_id=12, title="Owned Notebook", owner_userid=101, scope="owned")
+    source = RecordLocator(notebook=notebook, record=RecordRef(record_id=9001, record_uid="REC-001"))
+
+    async def handler(_: Request) -> Response:
+        raise AssertionError("Invalid cloud-file metadata must be rejected before HTTP")
+
+    async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
+        client = AsyncMatelab("https://ignored.example", session=provider_session, http_client=http_client)
+        with pytest.raises(MatelabUsageError, match="Cloud-file metadata"):
+            _ = await client.records.import_dataset(
+                notebook=notebook,
+                template_title="Example Template",
+                items=(RecordImportItem(record_uid="IMPORT-001", title="Cloud file", data={"File": [invalid_file]}),),
+            )
+        with pytest.raises(MatelabUsageError, match="Cloud-file metadata"):
+            _ = await client.records.update(
+                source,
+                (RecordFormAttachmentFieldAddition(module="Attachments", name="Cloud file", attachment=invalid_file),),
+            )
+
+
+@pytest.mark.asyncio
+async def test_import_dataset_consumes_only_the_staged_attachment_in_a_mixed_import(
+    cloud_file: CloudFile, provider_session: Session, provider_envelope: Callable[..., dict[str, object]]
 ) -> None:
     notebook = NotebookRef(notebook_id=12, title="Owned Notebook", owner_userid=101, scope="owned")
     staged = StagedAttachment(
@@ -164,7 +252,9 @@ async def test_import_dataset_consumes_one_staged_import_attachment_once(
         sha256="a" * 64,
     )
     item = RecordImportItem(
-        record_uid="IMPORT-STAGED-001", title="Imported attachment", data={"Attachments": {"File": [staged]}}
+        record_uid="IMPORT-STAGED-001",
+        title="Imported attachment",
+        data={"Attachments": {"File": [staged, cloud_file]}},
     )
     request_count = 0
 
@@ -179,7 +269,14 @@ async def test_import_dataset_consumes_one_staged_import_attachment_once(
                 {
                     "uid": "IMPORT-STAGED-001",
                     "title": "Imported attachment",
-                    "data": {"Attachments": {"File": ["#file{staged-import}"]}},
+                    "data": {
+                        "Attachments": {
+                            "File": [
+                                "#file{staged-import}",
+                                "#hash{evidence.zip, 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef}",
+                            ]
+                        }
+                    },
                 }
             ],
         }

{matelab_python_sdk-0.2.0a8 → matelab_python_sdk-0.2.0a9}/tests/test_record_mutations.py

@@ -10,8 +10,10 @@ from pydantic import JsonValue
 
 from matelab import (
     AsyncMatelab,
+    CloudFile,
     Identity,
     MatelabAuthenticationError,
+    MatelabProviderError,
     MatelabTransportError,
     MatelabUsageError,
     NotebookRef,
@@ -630,6 +632,132 @@ async def test_upload_attachment_uses_one_generated_staging_identity_and_scopes_
     assert digest not in repr(staged)
 
 
+@pytest.mark.asyncio
+async def test_update_reuses_cloud_file_for_form_fields_with_other_changes(
+    cloud_file: CloudFile, provider_session: Session, provider_envelope: Callable[..., dict[str, object]]
+) -> None:
+    source = RecordLocator(
+        notebook=NotebookRef(notebook_id=23, title="Shared Notebook", owner_userid=202, scope="shared"),
+        record=RecordRef(record_id=9001, record_uid="REC-001"),
+    )
+    modules: list[dict[str, object]] = [
+        {"name": "Attachments", "type": "form", "data": [{"name": "Reviewed", "type": "bool", "data": False}]}
+    ]
+    paths: list[str] = []
+
+    async def handler(request: Request) -> Response:
+        paths.append(request.url.path)
+        if request.url.path == "/api/eln_items/item_view":
+            assert request.method == "GET"
+            return Response(200, json=_item_view(provider_envelope, source, modules))
+        assert request.method == "POST"
+        assert request.url.path == "/api/eln_api/update"
+        assert request.headers["Authorization"] == "Bearer access"
+        assert request.headers["Content-Type"] == "application/json"
+        assert json.loads(request.content) == {
+            "eln": "Shared Notebook",
+            "user": 202,
+            "uid": "REC-001",
+            "modify": [{"path": ["Attachments", "Reviewed"], "data": True}],
+            "add": [
+                {
+                    "module": "Attachments",
+                    "name": name,
+                    "type": "file",
+                    "data": ["#hash{evidence.zip, 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef}"],
+                }
+                for name in ("Cloud file", "Copy")
+            ],
+        }
+        return Response(200, json=provider_envelope(message="Database data update successful"))
+
+    async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
+        client = AsyncMatelab("https://ignored.example", session=provider_session, http_client=http_client)
+        result = await client.records.update(
+            source,
+            (
+                RecordValueUpdate(path=("Attachments", "Reviewed"), value=True),
+                RecordFormAttachmentFieldAddition(module="Attachments", name="Cloud file", attachment=cloud_file),
+                RecordFormAttachmentFieldAddition(module="Attachments", name="Copy", attachment=cloud_file),
+            ),
+        )
+
+    assert result == "persisted"
+    assert paths == ["/api/eln_items/item_view", "/api/eln_api/update"]
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("field_name", ("Existing", "Duplicate", "Scalar addition"))
+async def test_update_cloud_file_rejects_existing_or_duplicate_form_field_names(
+    field_name: str,
+    cloud_file: CloudFile,
+    provider_session: Session,
+    provider_envelope: Callable[..., dict[str, object]],
+) -> None:
+    source = _source()
+    read_count = 0
+
+    async def handler(request: Request) -> Response:
+        nonlocal read_count
+        assert request.url.path == "/api/eln_items/item_view"
+        read_count += 1
+        modules = [
+            {"name": "Attachments", "type": "form", "data": [{"name": "Existing", "type": "text", "data": "value"}]}
+        ]
+        return Response(200, json=_item_view(provider_envelope, source, modules))
+
+    change = RecordFormAttachmentFieldAddition(module="Attachments", name=field_name, attachment=cloud_file)
+    if field_name == "Existing":
+        changes = (change,)
+    elif field_name == "Duplicate":
+        changes = (change, change)
+    else:
+        changes = (RecordValueAddition(module="Attachments", name=field_name, value_type="text", value="value"), change)
+    async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
+        client = AsyncMatelab("https://ignored.example", session=provider_session, http_client=http_client)
+        with pytest.raises(MatelabUsageError):
+            _ = await client.records.update(source, changes)
+
+    assert read_count == 1
+
+
+@pytest.mark.asyncio
+async def test_cloud_file_can_be_used_again_after_provider_rejects_the_record_update(
+    cloud_file: CloudFile,
+    provider_session: Session,
+    provider_envelope: Callable[..., dict[str, object]],
+    contract_response_example: Callable[[str, str], dict[str, object]],
+) -> None:
+    source = _source()
+    mutation_count = 0
+
+    async def handler(request: Request) -> Response:
+        nonlocal mutation_count
+        if request.url.path == "/api/eln_items/item_view":
+            return Response(
+                200, json=_item_view(provider_envelope, source, [{"name": "Attachments", "type": "form", "data": []}])
+            )
+        assert request.url.path == "/api/eln_api/update"
+        mutation_count += 1
+        if mutation_count == 1:
+            return Response(200, json=contract_response_example("updateRecordData", "inaccessible_hash"))
+        return Response(200, json=provider_envelope(message="Database data update successful"))
+
+    change = RecordFormAttachmentFieldAddition(module="Attachments", name="Cloud file", attachment=cloud_file)
+    async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
+        client = AsyncMatelab("https://ignored.example", session=provider_session, http_client=http_client)
+        with pytest.raises(MatelabProviderError) as caught:
+            _ = await client.records.update(source, (change,))
+        assert caught.value.provider_code == 2
+        assert not caught.value.retryable
+        assert cloud_file.sha256 not in str(caught.value)
+        assert mutation_count == 1
+        result = await client.records.update(source, (change,))
+
+    assert mutation_count == 2
+    assert result == "persisted"
+
+
 @pytest.mark.asyncio
 async def test_update_finalizes_record_attachment_as_one_new_form_field(
     provider_session: Session, provider_envelope: Callable[..., dict[str, object]]
@@ -1180,7 +1308,9 @@ async def test_table_file_cell_prewrite_rejection_preserves_stage_for_a_later_va
 
 
 @pytest.mark.asyncio
-async def test_one_shot_finalizer_rejects_mixed_or_multiple_intents_before_read(provider_session: Session) -> None:
+async def test_one_shot_finalizer_rejects_mixed_or_multiple_intents_before_read(
+    cloud_file: CloudFile, provider_session: Session
+) -> None:
     source = _source()
     paths: list[str] = []
 
@@ -1222,6 +1352,18 @@ async def test_one_shot_finalizer_rejects_mixed_or_multiple_intents_before_read(
                     ),
                 ),
             )
+        with pytest.raises(MatelabUsageError, match="only mutation"):
+            _ = await client.records.update(
+                source,
+                (
+                    RecordFormAttachmentFieldAddition(
+                        module="Attachments",
+                        name="Staged file",
+                        attachment=_staged(source, 38, "staged.txt", _HASH_A, userid=101),
+                    ),
+                    RecordFormAttachmentFieldAddition(module="Attachments", name="Cloud file", attachment=cloud_file),
+                ),
+            )
 
     assert paths == []
 

{matelab_python_sdk-0.2.0a8 → matelab_python_sdk-0.2.0a9}/tests/typing/consumer.py

@@ -2,6 +2,7 @@ from collections.abc import AsyncIterator
 
 from matelab import (
     AsyncMatelab,
+    CloudFile,
     GroupSummary,
     LiteratureLibrarySummary,
     LiteratureMetadataInput,
@@ -96,6 +97,21 @@ async def consume_record(client: AsyncMatelab, source: RecordLocator) -> Record:
     return record
 
 
+async def reuse_cloud_file(
+    client: AsyncMatelab, source: RecordLocator, cloud_file: CloudFile
+) -> tuple[tuple[int, ...], str]:
+    data: dict[str, RecordImportValue] = {"Attachments": {"File": [cloud_file]}}
+    record_ids = await client.records.import_dataset(
+        notebook=source.notebook,
+        template_title="Example",
+        items=(RecordImportItem(record_uid="REC-CLOUD-001", title="Cloud file", data=data),),
+    )
+    result = await client.records.update(
+        source, (RecordFormAttachmentFieldAddition(module="Attachments", name="Cloud file", attachment=cloud_file),)
+    )
+    return record_ids, result
+
+
 async def consume_public_record(client: AsyncMatelab, notebook: NotebookRef) -> PublicRecord | None:
     entries: tuple[PublicRecordSummary, ...] = await client.records.list_public(notebook)
     record: PublicRecord | None = await client.records.read_public(entries[0].ref) if entries else None

{matelab_python_sdk-0.2.0a8 → matelab_python_sdk-0.2.0a9}/uv.lock

@@ -433,7 +433,7 @@ wheels = [
 
 [[package]]
 name = "matelab-python-sdk"
-version = "0.2.0a8"
+version = "0.2.0a9"
 source = { editable = "." }
 dependencies = [
     { name = "httpx2" },