matelab-python-sdk 0.1.0a4__tar.gz → 0.1.0a5__tar.gz

{matelab_python_sdk-0.1.0a4 → matelab_python_sdk-0.1.0a5}/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.1.0a5 - 2026-07-29
+
+- Adopts immutable `matelab-spec v0.1.2` at commit `6dd674ac001ae61197495ace5eba489d585cb825` and OpenAPI
+  SHA-256 `7ccaf3116c8dcec7a6e49ff51fb1a5ecc83a140e013ec600516f5c2ffb3b5378`.
+- Adds notebook-scoped staged finalizers for a null table file cell, an attachment-bearing appended table row,
+  files-module root append, and table/files occurrence replacement, with exact provenance, one-shot transport, and
+  canonical readback checks.
+- Adds typed intents for an empty file table column and complete form file-field/table file-column deletion.
+- Allows `records.update(..., module_deletions=...)` to delete a canonical module even when the current record read
+  observes attachments in it, verifies absence on persisted readback, and does not claim attachment-quote or byte
+  cleanup beyond the pinned Contract.
+- Rejects cross-scope staged attachment handles before the record read, preserving the public static types while
+  avoiding the Provider's read-audit side effect for invalid runtime input.
+- Keeps notebook-staged rich-text binding and attachment-bearing multi-record import explicitly unsupported because
+  v0.1.2 Provider Verification does not provide safe one-shot semantics for either.
+
 ## 0.1.0a4 - 2026-07-28
 
 - Further reduces the alpha public surface from 150 to 126 symbols by accepting direct keyword arguments and existing

{matelab_python_sdk-0.1.0a4 → matelab_python_sdk-0.1.0a5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matelab-python-sdk
-Version: 0.1.0a4
+Version: 0.1.0a5
 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.0a4`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a5`. `[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.1` Contract Release. The sole release pin is
+The SDK is pinned to the immutable `matelab-spec v0.1.2` 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.0a4-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a5-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -218,8 +218,8 @@ result = await client.records.import_dataset(
 )
 ```
 
-The same staged handle may instead be consumed by one safe update that adds a new file field to an existing form
-module:
+The same staged handle may instead be consumed by one safe update finalizer. For example, add a new file field to an
+existing form module:
 
 ```python
 from matelab import RecordFormAttachmentFieldAddition
@@ -237,17 +237,144 @@ result = await client.records.update(
 )
 ```
 
-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.
+Choose exactly one finalizer. A staged name may occur once in either a single-record import or one update operation;
+do not reuse it after transport starts, even when the Provider outcome is unknown. A locally rejected target or
+argument does not spend the handle. The SDK rejects raw Provider attachment references, cross-user or cross-notebook
+handles, unsafe combinations, 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, idempotency, or retry guarantee. Integrations that
+persist handles must durably claim their own `uploaded -> finalizing/indeterminate` transition before calling a
+finalizer.
+
+### Attachment-bearing record update boundary
+
+The v0.1.2 Contract adds dedicated, verified notebook-staged update shapes. They remain public intent objects; callers
+never construct Provider paths or attachment strings:
+
+```python
+from matelab import (
+    RecordFilesAttachmentRootAppend,
+    RecordTableFileCellSet,
+    RecordTableRowAttachmentAppend,
+)
+
+# Each example is a separate finalizer; never run several with the same handle.
+await client.records.update(
+    source,
+    attachment_changes=(
+        RecordTableFileCellSet(
+            table="Measurements",
+            column="Evidence",
+            row=0,
+            attachment=staged,
+        ),
+    ),
+)
+
+await client.records.update(
+    source,
+    attachment_changes=(
+        RecordTableRowAttachmentAppend(
+            table="Measurements",
+            file_column="Evidence",
+            values={"Label": "Sample C"},
+            attachment=another_staged,
+        ),
+    ),
+)
+
+await client.records.update(
+    source,
+    attachment_changes=(
+        RecordFilesAttachmentRootAppend(
+            module="Files",
+            caption="Evidence",
+            attachment=third_staged,
+        ),
+    ),
+)
+```
+
+`RecordTableFileCellSet` requires an existing file column and a cell whose immediate canonical value is exactly
+`null`. The row-append intent addresses the new row by the row count from the SDK's immediate read and supports one
+staged file column. Files append is root-only and requires a string caption.
+
+Replacement starts with an occurrence returned by `records.read()`; applications must not fabricate a
+`RecordAttachmentRef`:
+
+```python
+from matelab import RecordFilesAttachmentReplacement
+
+record = await client.records.read(notebook=source.notebook, record=source.record)
+existing = next(
+    attachment
+    for attachment in record.attachments
+    if attachment.location is not None and attachment.location.kind == "files_module"
+)
+await client.records.update(
+    source,
+    attachment_changes=(RecordFilesAttachmentReplacement(existing=existing, replacement=staged, caption=None),),
+)
+```
+
+For a files occurrence, `caption=None` preserves the observed string caption (an observed null caption normalizes to
+the required empty string). Canonical readback must preserve the Provider `uid` and folder. Table replacement requires
+exactly one current attachment in the selected cell and uses `RecordTableFileAttachmentReplacement`. Both replacement
+forms require the new hash to differ.
+
+Row/index-based finalizers 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. `expected_content_sha256` is only a client-side prewrite
+check, not Provider compare-and-swap.
+
+File-bearing structure changes do not consume staging:
+
+```python
+from matelab import (
+    RecordFormFileFieldDeletion,
+    RecordTableFileColumnAddition,
+    RecordTableFileColumnDeletion,
+)
+
+await client.records.update(
+    source,
+    file_structure_changes=(
+        RecordTableFileColumnAddition(table="Measurements", name="Additional evidence"),
+        RecordFormFileFieldDeletion(form="Attachments", name="Obsolete evidence"),
+        RecordTableFileColumnDeletion(table="Measurements", name="Old evidence"),
+    ),
+)
+```
+
+The SDK emits the v0.1.2 dedicated operations: a new file column omits wire `data` and must read back as `null` for
+every existing row; whole form-field/table-column deletion uses a strict two-segment target. It does not expose a
+three-segment delete as table-cell clearing.
+
+Deleting a complete canonical module is also supported even when the current read observes attachments in it:
+
+```python
+result = await client.records.update(
+    source,
+    module_deletions=("Raw files",),
+    expected_content_sha256=record.content_sha256,
+)
+```
+
+This requests only a canonical record-content mutation. Readback proves the module is absent; it does not prove
+attachment-quote cleanup or byte deletion. Collaboration-pending has no readback and is not reported as persisted.
+
+Notebook-staged rich-text binding remains unsupported. Provider Verification shows that `#file{name}` is stored as
+plain text and that a hash-based URI can fall back to an existing quote, so neither is a one-shot staged finalizer.
+Existing `RecordRichTextUpdate` remains legal only with record-scoped `StagedRecordAttachment`. Attachment-bearing
+multi-record import is also forbidden; callers must split it into single-record finalizers.
+
+See `docs/attachment-write-contract-gaps.md` in the source repository for the exact support matrix, integration
+lifecycle requirements, and minimum Contract changes needed to expose the remaining operations.
 
 ## Implementation roadmap
 
 `docs/roadmap.md` is the complete SDK-only execution plan. It assigns all 71
-`matelab-spec v0.1.1` operations to ordered work packages, defines the machine-readable coverage that
+`matelab-spec v0.1.2` 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
@@ -580,8 +707,17 @@ agree. With the environment prepared:
 uv run --env-file .env.test pytest -m provider tests/provider/test_provider_smoke.py
 ```
 
-The file is never loaded implicitly, so the normal test suite remains safely skipped. Do not use this flow against
-production, and never commit its credentials.
+This command runs only the SDK public-interface smoke; it is not the 71-operation Provider Verification. To reuse the
+same `.env.test` for the complete Contract suite, also populate the optional share user, secondary account, record
+staging opt-in, and Chat SSO settings documented in `.env.example`, then run from sibling checkouts:
+
+```bash
+cd ../matelab-spec
+uv run --env-file ../matelab-python-sdk/.env.test pytest
+```
+
+The files are never loaded implicitly, so normal test runs remain safely skipped. Do not use either flow against
+production, and never commit Provider credentials.
 
 ## Reproducible release build
 
@@ -599,6 +735,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.1`,
-commit `047746ad37d827a85f93d947942f1e5fab80d54c`, and OpenAPI SHA-256
-`1d437b071968d2df165c712092fba4a283832e0ac19bc791e0d5af82294d1cca`.
+byte-identical wheel and source distribution hashes. The release is bound to `matelab-spec v0.1.2`,
+commit `6dd674ac001ae61197495ace5eba489d585cb825`, and OpenAPI SHA-256
+`7ccaf3116c8dcec7a6e49ff51fb1a5ecc83a140e013ec600516f5c2ffb3b5378`.

{matelab_python_sdk-0.1.0a4 → matelab_python_sdk-0.1.0a5}/README.md

@@ -2,10 +2,10 @@
 
 Reusable async Python client for the Matelab Integration Contract.
 
-The current alpha is `0.1.0a4`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a5`. `[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.1` Contract Release. The sole release pin is
+The SDK is pinned to the immutable `matelab-spec v0.1.2` 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.0a4-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a5-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -192,8 +192,8 @@ result = await client.records.import_dataset(
 )
 ```
 
-The same staged handle may instead be consumed by one safe update that adds a new file field to an existing form
-module:
+The same staged handle may instead be consumed by one safe update finalizer. For example, add a new file field to an
+existing form module:
 
 ```python
 from matelab import RecordFormAttachmentFieldAddition
@@ -211,17 +211,144 @@ result = await client.records.update(
 )
 ```
 
-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.
+Choose exactly one finalizer. A staged name may occur once in either a single-record import or one update operation;
+do not reuse it after transport starts, even when the Provider outcome is unknown. A locally rejected target or
+argument does not spend the handle. The SDK rejects raw Provider attachment references, cross-user or cross-notebook
+handles, unsafe combinations, 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, idempotency, or retry guarantee. Integrations that
+persist handles must durably claim their own `uploaded -> finalizing/indeterminate` transition before calling a
+finalizer.
+
+### Attachment-bearing record update boundary
+
+The v0.1.2 Contract adds dedicated, verified notebook-staged update shapes. They remain public intent objects; callers
+never construct Provider paths or attachment strings:
+
+```python
+from matelab import (
+    RecordFilesAttachmentRootAppend,
+    RecordTableFileCellSet,
+    RecordTableRowAttachmentAppend,
+)
+
+# Each example is a separate finalizer; never run several with the same handle.
+await client.records.update(
+    source,
+    attachment_changes=(
+        RecordTableFileCellSet(
+            table="Measurements",
+            column="Evidence",
+            row=0,
+            attachment=staged,
+        ),
+    ),
+)
+
+await client.records.update(
+    source,
+    attachment_changes=(
+        RecordTableRowAttachmentAppend(
+            table="Measurements",
+            file_column="Evidence",
+            values={"Label": "Sample C"},
+            attachment=another_staged,
+        ),
+    ),
+)
+
+await client.records.update(
+    source,
+    attachment_changes=(
+        RecordFilesAttachmentRootAppend(
+            module="Files",
+            caption="Evidence",
+            attachment=third_staged,
+        ),
+    ),
+)
+```
+
+`RecordTableFileCellSet` requires an existing file column and a cell whose immediate canonical value is exactly
+`null`. The row-append intent addresses the new row by the row count from the SDK's immediate read and supports one
+staged file column. Files append is root-only and requires a string caption.
+
+Replacement starts with an occurrence returned by `records.read()`; applications must not fabricate a
+`RecordAttachmentRef`:
+
+```python
+from matelab import RecordFilesAttachmentReplacement
+
+record = await client.records.read(notebook=source.notebook, record=source.record)
+existing = next(
+    attachment
+    for attachment in record.attachments
+    if attachment.location is not None and attachment.location.kind == "files_module"
+)
+await client.records.update(
+    source,
+    attachment_changes=(RecordFilesAttachmentReplacement(existing=existing, replacement=staged, caption=None),),
+)
+```
+
+For a files occurrence, `caption=None` preserves the observed string caption (an observed null caption normalizes to
+the required empty string). Canonical readback must preserve the Provider `uid` and folder. Table replacement requires
+exactly one current attachment in the selected cell and uses `RecordTableFileAttachmentReplacement`. Both replacement
+forms require the new hash to differ.
+
+Row/index-based finalizers 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. `expected_content_sha256` is only a client-side prewrite
+check, not Provider compare-and-swap.
+
+File-bearing structure changes do not consume staging:
+
+```python
+from matelab import (
+    RecordFormFileFieldDeletion,
+    RecordTableFileColumnAddition,
+    RecordTableFileColumnDeletion,
+)
+
+await client.records.update(
+    source,
+    file_structure_changes=(
+        RecordTableFileColumnAddition(table="Measurements", name="Additional evidence"),
+        RecordFormFileFieldDeletion(form="Attachments", name="Obsolete evidence"),
+        RecordTableFileColumnDeletion(table="Measurements", name="Old evidence"),
+    ),
+)
+```
+
+The SDK emits the v0.1.2 dedicated operations: a new file column omits wire `data` and must read back as `null` for
+every existing row; whole form-field/table-column deletion uses a strict two-segment target. It does not expose a
+three-segment delete as table-cell clearing.
+
+Deleting a complete canonical module is also supported even when the current read observes attachments in it:
+
+```python
+result = await client.records.update(
+    source,
+    module_deletions=("Raw files",),
+    expected_content_sha256=record.content_sha256,
+)
+```
+
+This requests only a canonical record-content mutation. Readback proves the module is absent; it does not prove
+attachment-quote cleanup or byte deletion. Collaboration-pending has no readback and is not reported as persisted.
+
+Notebook-staged rich-text binding remains unsupported. Provider Verification shows that `#file{name}` is stored as
+plain text and that a hash-based URI can fall back to an existing quote, so neither is a one-shot staged finalizer.
+Existing `RecordRichTextUpdate` remains legal only with record-scoped `StagedRecordAttachment`. Attachment-bearing
+multi-record import is also forbidden; callers must split it into single-record finalizers.
+
+See `docs/attachment-write-contract-gaps.md` in the source repository for the exact support matrix, integration
+lifecycle requirements, and minimum Contract changes needed to expose the remaining operations.
 
 ## Implementation roadmap
 
 `docs/roadmap.md` is the complete SDK-only execution plan. It assigns all 71
-`matelab-spec v0.1.1` operations to ordered work packages, defines the machine-readable coverage that
+`matelab-spec v0.1.2` 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
@@ -554,8 +681,17 @@ agree. With the environment prepared:
 uv run --env-file .env.test pytest -m provider tests/provider/test_provider_smoke.py
 ```
 
-The file is never loaded implicitly, so the normal test suite remains safely skipped. Do not use this flow against
-production, and never commit its credentials.
+This command runs only the SDK public-interface smoke; it is not the 71-operation Provider Verification. To reuse the
+same `.env.test` for the complete Contract suite, also populate the optional share user, secondary account, record
+staging opt-in, and Chat SSO settings documented in `.env.example`, then run from sibling checkouts:
+
+```bash
+cd ../matelab-spec
+uv run --env-file ../matelab-python-sdk/.env.test pytest
+```
+
+The files are never loaded implicitly, so normal test runs remain safely skipped. Do not use either flow against
+production, and never commit Provider credentials.
 
 ## Reproducible release build
 
@@ -573,6 +709,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.1`,
-commit `047746ad37d827a85f93d947942f1e5fab80d54c`, and OpenAPI SHA-256
-`1d437b071968d2df165c712092fba4a283832e0ac19bc791e0d5af82294d1cca`.
+byte-identical wheel and source distribution hashes. The release is bound to `matelab-spec v0.1.2`,
+commit `6dd674ac001ae61197495ace5eba489d585cb825`, and OpenAPI SHA-256
+`7ccaf3116c8dcec7a6e49ff51fb1a5ecc83a140e013ec600516f5c2ffb3b5378`.

{matelab_python_sdk-0.1.0a4 → matelab_python_sdk-0.1.0a5}/contracts/matelab-integration-v1.lock.json

@@ -2,12 +2,12 @@
   "schema_version": 1,
   "contract_line": "integration-v1",
   "release": {
-    "tag": "v0.1.1",
-    "commit": "047746ad37d827a85f93d947942f1e5fab80d54c"
+    "tag": "v0.1.2",
+    "commit": "6dd674ac001ae61197495ace5eba489d585cb825"
   },
   "openapi": {
     "source_path": "openapi/matelab-integration-v1.openapi.yaml",
     "snapshot": "matelab-integration-v1.openapi.yaml",
-    "sha256": "1d437b071968d2df165c712092fba4a283832e0ac19bc791e0d5af82294d1cca"
+    "sha256": "7ccaf3116c8dcec7a6e49ff51fb1a5ecc83a140e013ec600516f5c2ffb3b5378"
   }
 }