matelab-python-sdk 0.1.0a1__tar.gz → 0.1.0a2__tar.gz

{matelab_python_sdk-0.1.0a1 → matelab_python_sdk-0.1.0a2}/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.0a2 - 2026-07-27
+
+- Adopts the immutable `matelab-spec v0.1.1` release.
+- Adds notebook-scoped, uploader-bound record attachment staging before a target record exists.
+- Finalizes staged attachments through a single-record import or one new form-file-field update without exposing
+  Provider-native attachment syntax or private transport details.
+- Enforces exact notebook/user provenance and one finalization attempt per staged handle in one SDK client.
+
 ## 0.1.0a1 - 2026-07-27
 
 First public alpha candidate of the asynchronous Matelab Integration Contract SDK.

{matelab_python_sdk-0.1.0a1 → matelab_python_sdk-0.1.0a2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matelab-python-sdk
-Version: 0.1.0a1
+Version: 0.1.0a2
 Summary: Reusable async Python client for the Matelab Integration Contract
 Author-email: 朱天念 <zhutiannian@gmail.com>
 License-Expression: Apache-2.0
@@ -28,10 +28,10 @@ Description-Content-Type: text/markdown
 
 Reusable async Python client for the Matelab Integration Contract.
 
-The current alpha is `0.1.0a1`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a2`. `[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.1.0` Contract Release. The sole release pin is
+The SDK is pinned to the immutable `matelab-spec v0.1.1` 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.
 
@@ -57,7 +57,7 @@ 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.0a1-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a2-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -164,10 +164,70 @@ lifecycle operations, record discovery/lifecycle operations, comment reads, and
 comment attachment downloads, resumable file staging, literature discovery/lifecycle workflows, and
 personal cloud-drive management.
 
+### Staging a record attachment before record creation
+
+`records.stage_attachment` supports the Contract's pre-upload workflow without inventing a target record UID.
+The returned `StagedNotebookAttachment` is scoped by the SDK to the resolved authenticated user and the exact
+notebook selector used for upload:
+
+```python
+import hashlib
+
+from matelab import RecordImportItem, RecordImportTemplate, TemplateRef
+
+content = b"measurement data"
+staged = await client.records.stage_attachment(
+    notebook=notebook,
+    filename="measurement.csv",
+    content=content,
+    size=len(content),
+    sha256=hashlib.sha256(content).hexdigest(),
+)
+result = await client.records.import_dataset(
+    notebook=notebook,
+    template=RecordImportTemplate(template=TemplateRef(template_id=8), title="Example Template"),
+    items=(
+        RecordImportItem(
+            record_uid="REC-IMPORT-001",
+            title="Imported measurement",
+            data={"Attachments": {"File": [staged]}},
+        ),
+    ),
+)
+```
+
+The same staged handle may instead be consumed by one safe update that adds a new file field to an existing form
+module:
+
+```python
+from matelab import RecordFormAttachmentFieldAddition, RecordPatch
+
+# Alternative to the import above; do not run both with the same staged handle.
+result = await client.records.update(
+    source,
+    RecordPatch(
+        attachment_changes=(
+            RecordFormAttachmentFieldAddition(
+                module="Attachments",
+                name="Measurement",
+                attachment=staged,
+            ),
+        )
+    ),
+)
+```
+
+Choose exactly one finalizer. A staged name may occur once in either a single-record import or one update
+operation; do not reuse it, even after an error whose Provider outcome is unknown. The SDK rejects raw Provider
+attachment references, cross-user or cross-notebook handles, unsafe update shapes, duplicate use in one request,
+and a second finalization attempt through the same client. A Session imported without identity must first call
+`await client.resolve_identity()`. The Provider supplies no staging status, abort, TTL, atomicity, or retry
+guarantee, so callers must discard the handle as soon as a finalization request starts.
+
 ## Implementation roadmap
 
 `docs/roadmap.md` is the complete SDK-only execution plan. It assigns all 71
-`matelab-spec v0.1.0` operations to ordered work packages, defines the machine-readable coverage that
+`matelab-spec v0.1.1` operations to ordered work packages, defines the machine-readable coverage that
 must be added, records Provider-risk gates, and specifies the final completion checks.
 
 The SDK exposes all 71 Contract operations through public domain interfaces. It deliberately excludes MCP
@@ -533,6 +593,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 `matelab-spec v0.1.0`,
-commit `236795db1aa7a784ad9df936e9547e8d529be53f`, and OpenAPI SHA-256
-`62ca07dcd7a0b3f80eb381a0d1447316f69faa751bafb8ab7c6a751e619d8164`.
+byte-identical wheel and source distribution hashes. The release is bound to `matelab-spec v0.1.1`,
+commit `047746ad37d827a85f93d947942f1e5fab80d54c`, and OpenAPI SHA-256
+`1d437b071968d2df165c712092fba4a283832e0ac19bc791e0d5af82294d1cca`.

{matelab_python_sdk-0.1.0a1 → matelab_python_sdk-0.1.0a2}/README.md

@@ -2,10 +2,10 @@
 
 Reusable async Python client for the Matelab Integration Contract.
 
-The current alpha is `0.1.0a1`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a2`. `[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.1.0` Contract Release. The sole release pin is
+The SDK is pinned to the immutable `matelab-spec v0.1.1` 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.
 
@@ -31,7 +31,7 @@ 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.0a1-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a2-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -138,10 +138,70 @@ lifecycle operations, record discovery/lifecycle operations, comment reads, and
 comment attachment downloads, resumable file staging, literature discovery/lifecycle workflows, and
 personal cloud-drive management.
 
+### Staging a record attachment before record creation
+
+`records.stage_attachment` supports the Contract's pre-upload workflow without inventing a target record UID.
+The returned `StagedNotebookAttachment` is scoped by the SDK to the resolved authenticated user and the exact
+notebook selector used for upload:
+
+```python
+import hashlib
+
+from matelab import RecordImportItem, RecordImportTemplate, TemplateRef
+
+content = b"measurement data"
+staged = await client.records.stage_attachment(
+    notebook=notebook,
+    filename="measurement.csv",
+    content=content,
+    size=len(content),
+    sha256=hashlib.sha256(content).hexdigest(),
+)
+result = await client.records.import_dataset(
+    notebook=notebook,
+    template=RecordImportTemplate(template=TemplateRef(template_id=8), title="Example Template"),
+    items=(
+        RecordImportItem(
+            record_uid="REC-IMPORT-001",
+            title="Imported measurement",
+            data={"Attachments": {"File": [staged]}},
+        ),
+    ),
+)
+```
+
+The same staged handle may instead be consumed by one safe update that adds a new file field to an existing form
+module:
+
+```python
+from matelab import RecordFormAttachmentFieldAddition, RecordPatch
+
+# Alternative to the import above; do not run both with the same staged handle.
+result = await client.records.update(
+    source,
+    RecordPatch(
+        attachment_changes=(
+            RecordFormAttachmentFieldAddition(
+                module="Attachments",
+                name="Measurement",
+                attachment=staged,
+            ),
+        )
+    ),
+)
+```
+
+Choose exactly one finalizer. A staged name may occur once in either a single-record import or one update
+operation; do not reuse it, even after an error whose Provider outcome is unknown. The SDK rejects raw Provider
+attachment references, cross-user or cross-notebook handles, unsafe update shapes, duplicate use in one request,
+and a second finalization attempt through the same client. A Session imported without identity must first call
+`await client.resolve_identity()`. The Provider supplies no staging status, abort, TTL, atomicity, or retry
+guarantee, so callers must discard the handle as soon as a finalization request starts.
+
 ## Implementation roadmap
 
 `docs/roadmap.md` is the complete SDK-only execution plan. It assigns all 71
-`matelab-spec v0.1.0` operations to ordered work packages, defines the machine-readable coverage that
+`matelab-spec v0.1.1` operations to ordered work packages, defines the machine-readable coverage that
 must be added, records Provider-risk gates, and specifies the final completion checks.
 
 The SDK exposes all 71 Contract operations through public domain interfaces. It deliberately excludes MCP
@@ -507,6 +567,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 `matelab-spec v0.1.0`,
-commit `236795db1aa7a784ad9df936e9547e8d529be53f`, and OpenAPI SHA-256
-`62ca07dcd7a0b3f80eb381a0d1447316f69faa751bafb8ab7c6a751e619d8164`.
+byte-identical wheel and source distribution hashes. The release is bound to `matelab-spec v0.1.1`,
+commit `047746ad37d827a85f93d947942f1e5fab80d54c`, and OpenAPI SHA-256
+`1d437b071968d2df165c712092fba4a283832e0ac19bc791e0d5af82294d1cca`.

{matelab_python_sdk-0.1.0a1 → matelab_python_sdk-0.1.0a2}/contracts/matelab-integration-v1.lock.json

@@ -2,12 +2,12 @@
   "schema_version": 1,
   "contract_line": "integration-v1",
   "release": {
-    "tag": "v0.1.0",
-    "commit": "236795db1aa7a784ad9df936e9547e8d529be53f"
+    "tag": "v0.1.1",
+    "commit": "047746ad37d827a85f93d947942f1e5fab80d54c"
   },
   "openapi": {
     "source_path": "openapi/matelab-integration-v1.openapi.yaml",
     "snapshot": "matelab-integration-v1.openapi.yaml",
-    "sha256": "62ca07dcd7a0b3f80eb381a0d1447316f69faa751bafb8ab7c6a751e619d8164"
+    "sha256": "1d437b071968d2df165c712092fba4a283832e0ac19bc791e0d5af82294d1cca"
   }
 }

{matelab_python_sdk-0.1.0a1 → matelab_python_sdk-0.1.0a2}/contracts/matelab-integration-v1.openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: Matelab Integration Contract
-  version: 0.1.0
+  version: 0.1.1
   description: |
     Stable PHP wire contract for the `integration-v1` contract line.
     Business failures are returned as JSON envelopes over HTTP 200.
@@ -21,9 +21,13 @@ info:
       - controller/Recommend_fav.php
       - controller/Url.php
       - controller/Unlogin.php
+      - model/ElnItemsModel.php
+      - model/FileQuoteModel.php
       - model/FilesModel.php
       - traits/ElnTrait.php
       - traits/RecommendTrait.php
+      - service/ElnApiImport.php
+      - service/ElnApiUpdate.php
       - service/ElnServer.php
       - lib/Base.php
       - lib/Route.php
@@ -36,9 +40,16 @@ info:
     - repository: /home/tnzhu/projects/matelab-mcp
       commit: 94a129b2df0ef0fbcf179c10550fb7c9a5dd2e6f
       files:
+        - app/attachments/uploads.py
+        - app/resources/catalog.py
         - app/upstream/client.py
         - app/auth/pages.py
       note: |
+        The MCP prepare_upload flow generates an `mcp-upload-*` upload uid
+        before either create_records or update_record has selected a target
+        record and currently resolves its private staging state through a
+        native `#hash` reference.
+
         The MCP identity, ELN-group list, and notebook-list calls currently use
         non-contract POST and must migrate to GET.
     - repository: /home/tnzhu/projects/matelab-front
@@ -56,6 +67,42 @@ info:
         - src/views/recommend/fav.vue
         - src/views/recommend/favDetail.vue
         - src/views/recommend/favItems.vue
+  x-record-attachment-staging:
+    status: contract-contained
+    producerOperationId: uploadRecordAttachment
+    finalizerOperationIds: [importRecordDataset, updateRecordData]
+    reference:
+      syntax: "#file{name}"
+      sourceField: UploadAttachmentResponse.name
+      uploadEventUidIndependentOfRecordUid: true
+    providerScope:
+      uploader: authenticated-user
+      dataServer: selected-by-upload-notebook
+      notebook: not-bound
+      record: not-bound
+    safeConsumerScope:
+      uploader: same-authenticated-user
+      notebookSelector: same-eln-and-user-as-upload
+      dataServer: same
+    safeFinalizerShapes:
+      import:
+        datasetItems: 1
+      update:
+        operationArray: add
+        target: new-form-file-field
+        dataItems: 1
+    lifecycle:
+      finalizerChoice: exactly-one-of-import-or-update
+      targetRecords: 1
+      importDatasetItemsWhenFinalizing: 1
+      referencesPerStagedName: 1
+      secondConsumption: forbidden
+      uploadRetry: non-idempotent
+      finalizerRetryAfterError: forbidden
+      finalizerAtomicity: not-guaranteed
+      abortOperation: unsupported
+      statusOperation: unsupported
+      expiration: unspecified
 servers:
   - url: https://matelab.example.invalid
     description: Placeholder; consumers supply their Provider base URL.
@@ -1349,6 +1396,21 @@ paths:
       operationId: importRecordDataset
       tags: [Records]
       summary: Import one or more template-shaped records
+      description: |
+        Template-shaped file positions may contain `#file{name}`, where `name`
+        is the completed `uploadRecordAttachment` response name. For the safe
+        pre-upload workflow, the upload and import use the same authenticated
+        user and the same `eln`/`user` notebook selector, `dataset` contains
+        exactly one record, and the staged name occurs exactly once. The upload
+        request `uid` is an upload-event key and need not equal `dataset[].uid`.
+
+        The Provider resolves staging by uploader and data server, not by
+        notebook or future record identity. It consumes staging only after
+        record writing begins, without an atomic transaction covering record
+        creation, file quote creation, byte movement, and staging deletion.
+        Consumers must not batch one staged name into multiple records or retry
+        a failed finalize with the same name.
+      x-known-provider-issues: [PVD-023, PVD-024, PVD-040]
       security: [{bearerAuth: []}]
       requestBody:
         required: true
@@ -1362,6 +1424,17 @@ paths:
                   template: Example Template
                   dataset:
                     - {uid: GENERATED-WIRE-UID, title: Imported Example, data: {Notes: Sanitized}, keyword: calibration}
+              preuploaded_attachment:
+                summary: Upload-event UID and future record UID are deliberately different
+                value:
+                  eln: Example Notebook
+                  template: Example Template
+                  dataset:
+                    - uid: REC-IMPORT-EXAMPLE-001
+                      title: Imported attachment example
+                      data:
+                        Attachments:
+                          File: ["#file{staged-attachment-example}"]
               nullable_optionals:
                 value:
                   eln: Example Notebook
@@ -1476,7 +1549,21 @@ paths:
         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.
-      x-known-provider-issues: [PVD-014, PVD-015, PVD-016, PVD-017]
+
+        The verified safe pre-upload shape adds one new field to an existing
+        form module: the `add` item names a field that does not already exist,
+        sets `type: file`, and supplies a one-element `data` array containing
+        the `#file{name}` returned by `uploadRecordAttachment`. Appending to an
+        existing form file field and replacing an existing file occurrence are
+        outside this staging contract.
+
+        Upload and update use the same authenticated user and exact `eln`/`user`
+        notebook selector, reference the staged name once, and target one
+        existing record. The upload-event `uid` is independent of this
+        operation's record `uid`. Record persistence and staging consumption
+        are not atomic; after any finalize error the staged name is
+        indeterminate and must not be retried.
+      x-known-provider-issues: [PVD-014, PVD-015, PVD-016, PVD-017, PVD-040]
       security: [{bearerAuth: []}]
       requestBody:
         required: true
@@ -1486,6 +1573,16 @@ paths:
             examples:
               update:
                 value: {eln: Example Notebook, uid: REC-EXAMPLE-001, modify: [{path: [Notes], data: Sanitized update}]}
+              add_preuploaded_attachment_field:
+                value:
+                  eln: Example Notebook
+                  uid: REC-EXAMPLE-001
+                  add:
+                    - module: Attachments
+                      name: Staged file
+                      type: file
+                      data:
+                        - "#file{staged-update-example}"
               no_op:
                 summary: PHP accepts an update with no mutation arrays and rewrites the unchanged record
                 value: {eln: Example Notebook, uid: REC-EXAMPLE-001}
@@ -1533,6 +1630,23 @@ paths:
         This integration operation deliberately contracts the one-fragment flow used
         by the consumer (`last=1`). The PHP provider also has an internal fragmented
         upload mode, but that mode is outside `integration-v1`.
+
+        The caller may upload before the target record exists. `uid` is an
+        upload-event key stored with the temporary row; it is not a record UID
+        and need not match a later import or update record UID. The resolved
+        response `name` is the one-shot staging name consumed as `#file{name}`
+        by exactly one later `importRecordDataset` or `updateRecordData` request.
+
+        The Provider checks write access to `eln` and uses it to choose a data
+        server, but the resulting row is actually scoped only to the
+        authenticated uploader and that data server. It is not bound to the
+        notebook, a target record, or a finalizer operation. The safe Consumer
+        workflow therefore preserves the exact upload `eln`/`user` selector and
+        permits one occurrence in one target record. The operation has no
+        contracted abort, status, expiration, or idempotent retry. A hash
+        mismatch or ambiguous finalize error can leave staging behind, and
+        retention after failures is not guaranteed.
+      x-known-provider-issues: [PVD-040]
       security: [{bearerAuth: []}]
       requestBody:
         required: true
@@ -1547,8 +1661,8 @@ paths:
               upload:
                 value:
                   eln: Example Notebook
-                  uid: REC-EXAMPLE-001
-                  name: attachment-example
+                  uid: UPLOAD-EVENT-EXAMPLE
+                  name: staged-attachment-example
                   hash: 74034daeef860e12596c34f7e83703e668d578f4a85e72ec1645117223d4e6a7
                   last: 1
                   file: Sanitized attachment bytes
@@ -1556,7 +1670,7 @@ paths:
                 summary: Omitted name falls back to uid and omitted last selects the final fragment
                 value:
                   eln: Example Notebook
-                  uid: REC-EXAMPLE-001
+                  uid: UPLOAD-EVENT-DEFAULT-NAME
                   hash: 74034daeef860e12596c34f7e83703e668d578f4a85e72ec1645117223d4e6a7
                   file: Sanitized attachment bytes
       responses:
@@ -1578,7 +1692,7 @@ paths:
                     id: 7301
                     path: url_eln/temp
                     query: h=74034daeef860e12596c34f7e83703e668d578f4a85e72ec1645117223d4e6a7&id=7301&s=26&f=example.txt
-                    name: attachment-example
+                    name: staged-attachment-example
                     filename: example.txt
                     size: 26
                     hash: 74034daeef860e12596c34f7e83703e668d578f4a85e72ec1645117223d4e6a7
@@ -3436,7 +3550,7 @@ paths:
                       - id: 501
                         filename: measurement.csv
                         hash: 8b9f9f89f4d7a86d1ea98d6ee312194f7a6ad47356c4c71e2b9421a4ec02f66b
-                        size: "2048"
+                        size: 2048
                         userid: 101
                         date_time: "2026-01-10 09:00:00"
                         comm: ""
@@ -3498,7 +3612,7 @@ paths:
                       - id: 502
                         filename: legacy.dat
                         hash: 7fbc96d99fdaa807b29bdc2a0c6c1068e667b9bd294fb6d9e7c18d1044129dae
-                        size: "0"
+                        size: 0
                         userid: 101
                         date_time: null
                         comm: ""
@@ -3902,9 +4016,11 @@ components:
         filename: {type: string, minLength: 1, maxLength: 255}
         hash: {$ref: "#/components/schemas/Sha256"}
         size:
-          type: string
-          pattern: "^[0-9]+$"
-          description: Unsigned BIGINT serialized as a decimal string by this query.
+          type: integer
+          minimum: 0
+          description: |
+            File size in bytes. The Provider fetches the unsigned BIGINT with
+            PDO::ATTR_STRINGIFY_FETCHES disabled and returns a JSON integer.
         userid: {type: integer, minimum: 1}
         date_time:
           type: [string, "null"]
@@ -4049,21 +4165,33 @@ components:
         eln:
           type: string
           minLength: 1
-          description: Notebook title used to select its data server.
+          description: |
+            Notebook title used to check write permission and select its data
+            server. The value is not persisted on the staging row.
         user:
           type: integer
           minimum: 1
-          description: Optional notebook owner identifier for a non-owned notebook.
+          description: |
+            Optional notebook owner identifier for a non-owned notebook. It
+            selects the notebook but never replaces the authenticated uploader
+            as the staging owner.
         uid:
           type: string
           minLength: 1
           maxLength: 45
-          description: Record wire UID and upload-event identifier.
+          description: |
+            Caller-generated upload-event key stored in `upload_temp.data`.
+            It is independent of, and need not equal, the UID of a record later
+            created or updated with this staged file.
         name:
           type: string
           maxLength: 45
           default: ""
-          description: Missing or empty falls back to uid as the unique temporary upload name.
+          description: |
+            Caller-generated staging name stored in `upload_temp.unique_str`.
+            Missing or empty falls back to `uid`. On success, use the response
+            `name` once as `#file{name}` in the same user's same-notebook
+            import or update workflow.
         hash:
           $ref: "#/components/schemas/Sha256"
         last:
@@ -4088,7 +4216,10 @@ components:
             query:
               type: string
               description: Provider-built legacy query string for the temporary file.
-            name: {type: string, minLength: 1}
+            name:
+              type: string
+              minLength: 1
+              description: Resolved one-shot staging name used by `#file{name}`.
             filename: {type: string, minLength: 1}
             size: {type: integer, minimum: 0}
             hash: {$ref: "#/components/schemas/Sha256"}

{matelab_python_sdk-0.1.0a1 → matelab_python_sdk-0.1.0a2}/docs/operation-coverage.yaml

@@ -1,7 +1,7 @@
 schema_version: 1
 contract:
   line: integration-v1
-  release: v0.1.0
+  release: v0.1.1
   operation_count: 71
 
 operations:
@@ -282,7 +282,7 @@ operations:
     state: implemented
     stability: experimental
     public_interface: AsyncMatelab.records.import_dataset
-    known_issues: [PCG-008, PVD-023, PVD-024]
+    known_issues: [PCG-008, PCG-014, PVD-023, PVD-024, PVD-040]
     work_package: WP7
 
   - operation_id: exportRecords
@@ -312,7 +312,7 @@ operations:
     state: implemented
     stability: experimental
     public_interface: AsyncMatelab.records.update
-    known_issues: [PCG-001, PCG-002, PVD-014, PVD-015, PVD-016, PVD-017]
+    known_issues: [PCG-001, PCG-002, PCG-014, PVD-014, PVD-015, PVD-016, PVD-017, PVD-040]
     work_package: WP8
 
   - operation_id: deleteRecordsByUid
@@ -331,8 +331,8 @@ operations:
     domain: records
     state: implemented
     stability: experimental
-    public_interface: AsyncMatelab.records.upload_attachment
-    known_issues: [PCG-002]
+    public_interface: AsyncMatelab.records.upload_attachment / AsyncMatelab.records.stage_attachment
+    known_issues: [PCG-002, PCG-014, PVD-040]
     work_package: WP8
 
   - operation_id: listPublicNotebookRecords

{matelab_python_sdk-0.1.0a1 → matelab_python_sdk-0.1.0a2}/docs/roadmap.md

@@ -16,7 +16,7 @@
 目标是在当前仓库内完成一个可复用、异步、类型安全的 Matelab Python SDK：
 
 ```text
-matelab-spec v0.1.0
+matelab-spec v0.1.1
         │
         ▼
 private generated wire models
@@ -45,11 +45,11 @@ small domain-oriented public interface
 ## 2. 固定基线
 
 - Contract line：`integration-v1`
-- Contract release：`matelab-spec v0.1.0`
-- Contract commit：`236795db1aa7a784ad9df936e9547e8d529be53f`
-- OpenAPI SHA-256：`62ca07dcd7a0b3f80eb381a0d1447316f69faa751bafb8ab7c6a751e619d8164`
+- Contract release：`matelab-spec v0.1.1`
+- Contract commit：`047746ad37d827a85f93d947942f1e5fab80d54c`
+- OpenAPI SHA-256：`1d437b071968d2df165c712092fba4a283832e0ac19bc791e0d5af82294d1cca`
 - Contract operation：71
-- SDK 当前版本：`0.1.0a1`
+- SDK 当前版本：`0.1.0a2`
 - Python：3.11+
 - 生成器：`datamodel-code-generator 0.71.0`
 
@@ -73,7 +73,7 @@ goal 期间不得跟踪 `matelab-spec/main`，也不得自动升级 Contract Rel
   领域 interface；
 - 71 条 Contract operation 的 public-interface、wire adapter、测试与 coverage；
 - opt-in 的隔离 Provider smoke；
-- reproducible `0.1.0a1` build。
+- reproducible `0.1.0a2` build。
 
 当前 operation coverage：71 implemented / 0 planned。每条 operation 的领域入口、稳定性和已知问题以
 [`operation-coverage.yaml`](operation-coverage.yaml) 为准。
@@ -83,7 +83,7 @@ goal 期间不得跟踪 `matelab-spec/main`，也不得自动升级 Contract Rel
 在 `/home/tnzhu/projects/matelab-python-sdk` 启动新任务后，使用以下目标：
 
 > 完整阅读并严格遵循 `AGENTS.md`、`README.md` 和 `docs/roadmap.md`。创建并持续执行一个 goal：
-> 只修改当前 `matelab-python-sdk` 仓库，以 pinned `matelab-spec v0.1.0` 为唯一 Wire Contract，按照
+> 只修改当前 `matelab-python-sdk` 仓库，以 pinned `matelab-spec v0.1.1` 为唯一 Wire Contract，按照
 > roadmap 从第一个未完成 work package 开始，建立 71-operation 精确覆盖，完成全部安全可表达的领域
 > interface，并对无法安全公开的 operation 给出有证据的 intentionally_unexposed 分类。每个 work
 > package 完成后立即运行其测试并继续下一项，不停在规划、部分实现或单个领域；最终必须让 generation
@@ -882,3 +882,18 @@ License 和公开 author metadata 已确认；内部 Gitee repository 不作为
 documentation/issues URL。author 同时负责维护，因此不重复声明 maintainer。release 通过私有 GitHub mirror
 的 tag workflow 构建，并使用 PyPI Trusted Publishing；Gitee `origin` 仍是内部主仓库。剩余人工步骤仅为在
 PyPI 登记 Pending Publisher，之后创建并推送 release tag。
+
+## 26. `0.1.0a2` Contract adoption 与 record attachment staging
+
+本阶段采用 immutable `matelab-spec v0.1.1`，保持 71-operation 覆盖不变，并落实 PCG-014 / PVD-040
+明确的创建前附件暂存语义：
+
+- `/eln_api/upload` 的 `uid` 是独立 upload-event key，不再要求伪装成已有 record UID；
+- `records.stage_attachment` 返回由 SDK 绑定 authenticated uploader 与精确 notebook selector 的公开句柄；
+- import 只允许单记录、单次引用，update 只允许向已有 form module 新增一个 file field；
+- Consumer 不接触 `#file{name}`、`#hash{...}`、PHP path 或 private transport；
+- 同一 client 在 finalization 请求开始前记录一次性尝试；成功、业务错误、HTTP 错误或不确定结果后均禁止重试；
+- Provider 未提供 status、abort、TTL、原子性和跨请求幂等保证，结果类型与文档不推测这些能力。
+
+发布准备将 SDK 版本推进到 `0.1.0a2`，更新生成模型、coverage、公开类型消费测试、release artifact 审计与
+reproducible build 基线。

{matelab_python_sdk-0.1.0a1 → matelab_python_sdk-0.1.0a2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "matelab-python-sdk"
-version = "0.1.0a1"
+version = "0.1.0a2"
 description = "Reusable async Python client for the Matelab Integration Contract"
 readme = "README.md"
 requires-python = ">=3.11"

{matelab_python_sdk-0.1.0a1 → matelab_python_sdk-0.1.0a2}/scripts/check_installed_package.py

@@ -5,7 +5,7 @@ from typing import cast
 
 import matelab
 
-_EXPECTED_PUBLIC_SYMBOLS = 182
+_EXPECTED_PUBLIC_SYMBOLS = 184
 
 
 def main() -> None:

{matelab_python_sdk-0.1.0a1 → matelab_python_sdk-0.1.0a2}/scripts/check_release.py

@@ -9,7 +9,7 @@ from pathlib import Path, PurePosixPath
 from typing import cast
 from zipfile import ZipFile
 
-_VERSION = "0.1.0a1"
+_VERSION = "0.1.0a2"
 _DIST_INFO = f"matelab_python_sdk-{_VERSION}.dist-info"
 _EXPECTED_REQUIRES_DIST = {"httpx<1,>=0.27.2", "pydantic<3,>=2.12.5"}
 _EXPECTED_LICENSE_FILES = {"LICENSE", "NOTICE"}