matelab-python-sdk 0.1.0a17__tar.gz → 0.1.0a18__tar.gz

{matelab_python_sdk-0.1.0a17 → matelab_python_sdk-0.1.0a18}/CHANGELOG.md

@@ -3,6 +3,17 @@
 This file records release-to-release changes and migration impact. It is not the authority for the current interface;
 see [README.md](README.md) for current behavior and [AGENTS.md](AGENTS.md) for maintenance policy.
 
+## 0.1.0a18 - 2026-08-23
+
+- Adopts immutable `matelab-spec v0.4.2` at commit `a51483f910440fbbbc3693cc32566482064bb3ab` and OpenAPI
+  SHA-256 `4c92b96ba3dfe7122b30b4db2e2c8054c06018291c8c52c15482112b51a32920`. The wire schema, methods,
+  paths, encodings, operation count, and public interface are unchanged.
+- Records that compatibility evidence remains the stable Provider revision
+  `59101f006e9fd6d6ce0b951dfd34695a7949b54f`; the latest reviewed revision
+  `a3e6b961800f6b1ab666f0d3f6cd4c64c2a3ce27` is incompatible. The SDK retains the stable multipart comment-upload
+  field, while integrations must account for that Provider's DOI rejection, encrypted-search omission, valid
+  files-folder-path rejection, and explicit-null table-file-import failure.
+
 ## 0.1.0a17 - 2026-08-20
 
 - Adopts immutable `matelab-spec v0.4.1` at commit `6f8ab3d14797385d0075d0aba38bf3bf529e674d` and OpenAPI

{matelab_python_sdk-0.1.0a17 → matelab_python_sdk-0.1.0a18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matelab-python-sdk
-Version: 0.1.0a17
+Version: 0.1.0a18
 Summary: Reusable async Python client for the Matelab Integration Contract
 Author-email: 朱天念 <zhutiannian@gmail.com>
 License-Expression: Apache-2.0
@@ -35,10 +35,10 @@ This README describes the current SDK interface, integration semantics, examples
 [AGENTS.md](AGENTS.md) for durable maintenance rules, and `docs/operation-coverage.yaml` for the machine-readable
 operation inventory.
 
-The current alpha is `0.1.0a17`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a18`. `[project].version` in `pyproject.toml` is the sole SDK version source;
 `uv.lock` only mirrors that source.
 
-The SDK is pinned to the immutable `matelab-spec v0.4.1` Contract Release. The sole release pin is
+The SDK is pinned to the immutable `matelab-spec v0.4.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.
 
@@ -64,12 +64,18 @@ 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.0a17-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a18-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
 tag, commit, and checksum recorded below.
 
+The Contract and public SDK interface remain compatible with the stable Provider evidence at
+`59101f006e9fd6d6ce0b951dfd34695a7949b54f`. The latest reviewed Provider,
+`a3e6b961800f6b1ab666f0d3f6cd4c64c2a3ce27`, is incompatible with that evidence. Its operation-specific
+differences are documented alongside the affected interfaces below; do not treat a successful Contract adoption as
+proof that this newer Provider revision is interchangeable.
+
 ## Design
 
 The public module is intentionally small:
@@ -117,7 +123,7 @@ success code it does not allow raises `MatelabProtocolError` rather than assigni
 `MatelabTransportError.status_code` remains available for HTTP failures. Provider response bodies, top-level `msg`,
 legacy `errmsg`, opaque `errs`, uncontracted debug fields, and request payloads are not attached to exceptions because
 Provider-authored diagnostics may contain stack traces, credentials, or submitted values.
-The pinned v0.4.1 Contract also declares optional code-4 `errs`, but PVD-041 and PCG-015 record incompatible observed
+The pinned v0.4.2 Contract also declares optional code-4 `errs`, but PVD-041 and PCG-015 record incompatible observed
 item/container shapes and insufficient evidence for requiredness, cardinality, or exclusion from other codes. The SDK
 therefore keeps those diagnostics wire-only and does not expose `errs` as stable public metadata. A typed detail
 interface remains blocked until a future Contract release can define one from stronger Provider evidence. `retryable`
@@ -446,7 +452,7 @@ targets = await client.users.search("Example Researcher", global_scope=False)
 `groups.list()` returns the `GroupSummary` tuple directly. Ordering remains Provider-unspecified and is documented
 rather than repeated as a constant result field. The Provider's members for an unstable first group remain wire-only;
 `users.search()` is the public recipient-discovery interface. These two discovery interfaces are experimental because
-group order is unstable and user search is unpaged, unordered and not field-minimized (PVD-006, PVD-029, PCG-011).
+group order is unstable and user search is unpaged, unordered and not field-minimized (PVD-006, PVD-029).
 `GroupSummary.notebook_creation_available` expresses whether the group can currently host notebook creation without
 exposing the Provider's data-server routing value.
 
@@ -538,6 +544,8 @@ relations = await client.records.relations(source)
 as `modules`; it is not the template-shaped `RecordImportItem.data` accepted by record import.
 `records.search()` maps each requested field name to a stored record path. A match exposes only Provider-returned
 entries in `values`, so key membership distinguishes an absent result from an explicit JSON `null`.
+The latest reviewed Provider excludes encrypted records from search (PVD-043); an empty search result therefore does
+not prove that no matching encrypted record exists.
 
 The Provider calls its notebook directory tree `subtype`; that name remains wire-only. The SDK exposes
 `RecordFolder`, `RecordSummary.folder_id`, and the `folders` returned with record listings. A top-level folder has
@@ -587,8 +595,9 @@ UID. Import validates the complete batch with generated wire models but cannot m
 individual inputs or promise atomicity (PCG-008); it therefore returns only the tuple of database IDs actually
 reported by the Provider. `RecordImportItem.keywords` is a tuple; the adapter owns the Provider's
 legacy semicolon encoding. Folder paths are ordered existing folder titles from the notebook root; they do not create
-missing folders. Delete means moving records into the recycle bin, not permanent
-deletion. Delete and restore return `None`; record mutations are not automatically retried.
+missing folders. The latest reviewed Provider rejects explicit-null table-file imports (PVD-045), so integrations
+targeting it must not interpret that rejection as an invalid SDK input. Delete means moving records into the recycle bin,
+not permanent deletion. Delete and restore return `None`; record mutations are not automatically retried.
 
 `records.copy()` accepts an optional `new_record_uid`; when omitted, the SDK generates one locally. The Provider
 returns only the copied row's database ID, so retaining that UID lets the SDK return a complete `RecordLocator`
@@ -605,7 +614,9 @@ returns the acknowledgement classification
 issue a post-write read. Database, active-browser, and unclassified acknowledgements remain distinct, and mutation
 retries stay disabled. Encrypted record content is outside the SDK's public read/update interface: the list-level
 `RecordSummary.encrypted` flag lets callers identify and skip it, while the Provider password field and frontend-only
-password lifecycle remain unexposed.
+password lifecycle remain unexposed. The latest reviewed Provider rejects a valid files-folder append path
+(PVD-044); integrations targeting it must not reinterpret that rejection as invalid SDK input, and should treat a
+staged attachment as indeterminate once the write has started.
 
 Relation addition reads both endpoints and checks their resolved data server before writing; this reduces PVD-019
 risk but is not an atomic Provider authorization guarantee. It does not list relations merely to inspect the
@@ -617,8 +628,9 @@ ignores target notebook identity (PVD-020); its mutation likewise performs autho
 `records.comments()`. Each returned `RecordRelationRef` carries only the relation row and declared target IDs.
 Deletion accepts the source `RecordLocator` and one of those observed refs.
 
-Comment upload follows the Provider's literal one-request `upload` field, not the incompatible Front fragment
-protocol (PVD-037). Comment mutations return `None` after acknowledgement. Edit first verifies that the selected
+Comment upload follows the stable Provider's literal one-request `upload` field. The latest reviewed Provider renames
+that field (PVD-037), but the SDK retains the Contract-compatible `upload` encoding. Comment mutations return `None`
+after acknowledgement. Edit first verifies that the selected
 comment is currently observed and caller-owned because the Provider otherwise reports a false success for a missing or
 other-user ID (PVD-004). Delete sends the typed ref directly because the Provider mutation itself enforces record and
 caller ownership. Neither operation performs a post-write read. Staged comment attachments have no Contract abort
@@ -697,7 +709,9 @@ The Provider's static literature form definition and extraction deployment flag
 `extract_metadata()` directly and handle an unavailable or failing optional backend as a Provider error. Extraction
 returns a `PublicationMetadataCandidate`: unstored, rich publication evidence rather than metadata already attached to
 a literature item. Its structured authors are `PublicationAuthorCandidate` values. Extraction accepts a DOI, a
-completed staged PDF, or both; a supplied DOI takes precedence over the staged PDF. Literature list
+completed staged PDF, or both; a supplied DOI takes precedence over the staged PDF. The latest reviewed Provider
+rejects DOI formats accepted by the stable evidence (PVD-042), so a rejection from that revision does not by itself
+make a DOI invalid for this SDK interface. Literature list
 results likewise exclude Provider-generated citation HTML and author-highlight fragments; Consumers receive the
 underlying citation fields instead of presentation markup. `LiteratureDetail.metadata` is `None` when invalid legacy
 JSON produces the Provider's empty-array fallback; otherwise it contains decoded stored metadata without arbitrary
@@ -722,7 +736,7 @@ canonical update preflights the raw item response and refuses to drop top-level
 `allow_source_metadata_loss=True` explicitly skips that preflight and sends the canonical replacement directly. The
 default read/check/write protection is best effort rather than atomic because the Provider offers no revision or
 compare-and-swap condition; this Provider-specific behavior remains internal to the update operation (PVD-027).
-PDF replace/delete are separate acknowledged mutations and are not presented as atomic with metadata (PCG-010).
+PDF replace/delete are separate acknowledged mutations and are not presented as atomic with metadata.
 Permanent personal deletion is named `permanently_delete`, returns `None`, and is non-recoverable. Sharing requires
 list-observed item summaries, user-search summaries and a
 valid caller identity, then returns `None` because the Provider supplies no per-recipient IDs (PVD-012, PVD-036).
@@ -759,7 +773,7 @@ time strings.
 Folder create returns a `CloudFolderRef` built from the Provider ID. Other folder and file mutations return `None`
 after acknowledgement and do not automatically list the drive. Staged finalize accepts a completed `StagedFile`;
 the Provider binds by temporary row ID without checking its owner (PVD-031), and finalize atomicity/idempotency remain
-absent (PCG-012). Batch move and permanent delete do not claim Provider per-item results or atomicity. Permanent
+absent. Batch move and permanent delete do not claim Provider per-item results or atomicity. Permanent
 deletion is named `permanently_delete_files` and is non-recoverable. Cloud downloads
 resolve bytes from the final file identity and reuse `DownloadStream`, thumbnail/preview choices and the PVD-002-safe
 range subset. Cloud mutations are not automatically retried.
@@ -901,6 +915,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.4.1`,
-commit `6f8ab3d14797385d0075d0aba38bf3bf529e674d`, and OpenAPI SHA-256
-`73d899c9e60b59f9521062ffcfaaae5f073eea36f24f3e535fcb53f12242581c`.
+byte-identical wheel and source distribution hashes. The release is bound to `matelab-spec v0.4.2`,
+commit `a51483f910440fbbbc3693cc32566482064bb3ab`, and OpenAPI SHA-256
+`4c92b96ba3dfe7122b30b4db2e2c8054c06018291c8c52c15482112b51a32920`.

{matelab_python_sdk-0.1.0a17 → matelab_python_sdk-0.1.0a18}/README.md

@@ -7,10 +7,10 @@ This README describes the current SDK interface, integration semantics, examples
 [AGENTS.md](AGENTS.md) for durable maintenance rules, and `docs/operation-coverage.yaml` for the machine-readable
 operation inventory.
 
-The current alpha is `0.1.0a17`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a18`. `[project].version` in `pyproject.toml` is the sole SDK version source;
 `uv.lock` only mirrors that source.
 
-The SDK is pinned to the immutable `matelab-spec v0.4.1` Contract Release. The sole release pin is
+The SDK is pinned to the immutable `matelab-spec v0.4.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.
 
@@ -36,12 +36,18 @@ 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.0a17-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a18-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
 tag, commit, and checksum recorded below.
 
+The Contract and public SDK interface remain compatible with the stable Provider evidence at
+`59101f006e9fd6d6ce0b951dfd34695a7949b54f`. The latest reviewed Provider,
+`a3e6b961800f6b1ab666f0d3f6cd4c64c2a3ce27`, is incompatible with that evidence. Its operation-specific
+differences are documented alongside the affected interfaces below; do not treat a successful Contract adoption as
+proof that this newer Provider revision is interchangeable.
+
 ## Design
 
 The public module is intentionally small:
@@ -89,7 +95,7 @@ success code it does not allow raises `MatelabProtocolError` rather than assigni
 `MatelabTransportError.status_code` remains available for HTTP failures. Provider response bodies, top-level `msg`,
 legacy `errmsg`, opaque `errs`, uncontracted debug fields, and request payloads are not attached to exceptions because
 Provider-authored diagnostics may contain stack traces, credentials, or submitted values.
-The pinned v0.4.1 Contract also declares optional code-4 `errs`, but PVD-041 and PCG-015 record incompatible observed
+The pinned v0.4.2 Contract also declares optional code-4 `errs`, but PVD-041 and PCG-015 record incompatible observed
 item/container shapes and insufficient evidence for requiredness, cardinality, or exclusion from other codes. The SDK
 therefore keeps those diagnostics wire-only and does not expose `errs` as stable public metadata. A typed detail
 interface remains blocked until a future Contract release can define one from stronger Provider evidence. `retryable`
@@ -418,7 +424,7 @@ targets = await client.users.search("Example Researcher", global_scope=False)
 `groups.list()` returns the `GroupSummary` tuple directly. Ordering remains Provider-unspecified and is documented
 rather than repeated as a constant result field. The Provider's members for an unstable first group remain wire-only;
 `users.search()` is the public recipient-discovery interface. These two discovery interfaces are experimental because
-group order is unstable and user search is unpaged, unordered and not field-minimized (PVD-006, PVD-029, PCG-011).
+group order is unstable and user search is unpaged, unordered and not field-minimized (PVD-006, PVD-029).
 `GroupSummary.notebook_creation_available` expresses whether the group can currently host notebook creation without
 exposing the Provider's data-server routing value.
 
@@ -510,6 +516,8 @@ relations = await client.records.relations(source)
 as `modules`; it is not the template-shaped `RecordImportItem.data` accepted by record import.
 `records.search()` maps each requested field name to a stored record path. A match exposes only Provider-returned
 entries in `values`, so key membership distinguishes an absent result from an explicit JSON `null`.
+The latest reviewed Provider excludes encrypted records from search (PVD-043); an empty search result therefore does
+not prove that no matching encrypted record exists.
 
 The Provider calls its notebook directory tree `subtype`; that name remains wire-only. The SDK exposes
 `RecordFolder`, `RecordSummary.folder_id`, and the `folders` returned with record listings. A top-level folder has
@@ -559,8 +567,9 @@ UID. Import validates the complete batch with generated wire models but cannot m
 individual inputs or promise atomicity (PCG-008); it therefore returns only the tuple of database IDs actually
 reported by the Provider. `RecordImportItem.keywords` is a tuple; the adapter owns the Provider's
 legacy semicolon encoding. Folder paths are ordered existing folder titles from the notebook root; they do not create
-missing folders. Delete means moving records into the recycle bin, not permanent
-deletion. Delete and restore return `None`; record mutations are not automatically retried.
+missing folders. The latest reviewed Provider rejects explicit-null table-file imports (PVD-045), so integrations
+targeting it must not interpret that rejection as an invalid SDK input. Delete means moving records into the recycle bin,
+not permanent deletion. Delete and restore return `None`; record mutations are not automatically retried.
 
 `records.copy()` accepts an optional `new_record_uid`; when omitted, the SDK generates one locally. The Provider
 returns only the copied row's database ID, so retaining that UID lets the SDK return a complete `RecordLocator`
@@ -577,7 +586,9 @@ returns the acknowledgement classification
 issue a post-write read. Database, active-browser, and unclassified acknowledgements remain distinct, and mutation
 retries stay disabled. Encrypted record content is outside the SDK's public read/update interface: the list-level
 `RecordSummary.encrypted` flag lets callers identify and skip it, while the Provider password field and frontend-only
-password lifecycle remain unexposed.
+password lifecycle remain unexposed. The latest reviewed Provider rejects a valid files-folder append path
+(PVD-044); integrations targeting it must not reinterpret that rejection as invalid SDK input, and should treat a
+staged attachment as indeterminate once the write has started.
 
 Relation addition reads both endpoints and checks their resolved data server before writing; this reduces PVD-019
 risk but is not an atomic Provider authorization guarantee. It does not list relations merely to inspect the
@@ -589,8 +600,9 @@ ignores target notebook identity (PVD-020); its mutation likewise performs autho
 `records.comments()`. Each returned `RecordRelationRef` carries only the relation row and declared target IDs.
 Deletion accepts the source `RecordLocator` and one of those observed refs.
 
-Comment upload follows the Provider's literal one-request `upload` field, not the incompatible Front fragment
-protocol (PVD-037). Comment mutations return `None` after acknowledgement. Edit first verifies that the selected
+Comment upload follows the stable Provider's literal one-request `upload` field. The latest reviewed Provider renames
+that field (PVD-037), but the SDK retains the Contract-compatible `upload` encoding. Comment mutations return `None`
+after acknowledgement. Edit first verifies that the selected
 comment is currently observed and caller-owned because the Provider otherwise reports a false success for a missing or
 other-user ID (PVD-004). Delete sends the typed ref directly because the Provider mutation itself enforces record and
 caller ownership. Neither operation performs a post-write read. Staged comment attachments have no Contract abort
@@ -669,7 +681,9 @@ The Provider's static literature form definition and extraction deployment flag
 `extract_metadata()` directly and handle an unavailable or failing optional backend as a Provider error. Extraction
 returns a `PublicationMetadataCandidate`: unstored, rich publication evidence rather than metadata already attached to
 a literature item. Its structured authors are `PublicationAuthorCandidate` values. Extraction accepts a DOI, a
-completed staged PDF, or both; a supplied DOI takes precedence over the staged PDF. Literature list
+completed staged PDF, or both; a supplied DOI takes precedence over the staged PDF. The latest reviewed Provider
+rejects DOI formats accepted by the stable evidence (PVD-042), so a rejection from that revision does not by itself
+make a DOI invalid for this SDK interface. Literature list
 results likewise exclude Provider-generated citation HTML and author-highlight fragments; Consumers receive the
 underlying citation fields instead of presentation markup. `LiteratureDetail.metadata` is `None` when invalid legacy
 JSON produces the Provider's empty-array fallback; otherwise it contains decoded stored metadata without arbitrary
@@ -694,7 +708,7 @@ canonical update preflights the raw item response and refuses to drop top-level
 `allow_source_metadata_loss=True` explicitly skips that preflight and sends the canonical replacement directly. The
 default read/check/write protection is best effort rather than atomic because the Provider offers no revision or
 compare-and-swap condition; this Provider-specific behavior remains internal to the update operation (PVD-027).
-PDF replace/delete are separate acknowledged mutations and are not presented as atomic with metadata (PCG-010).
+PDF replace/delete are separate acknowledged mutations and are not presented as atomic with metadata.
 Permanent personal deletion is named `permanently_delete`, returns `None`, and is non-recoverable. Sharing requires
 list-observed item summaries, user-search summaries and a
 valid caller identity, then returns `None` because the Provider supplies no per-recipient IDs (PVD-012, PVD-036).
@@ -731,7 +745,7 @@ time strings.
 Folder create returns a `CloudFolderRef` built from the Provider ID. Other folder and file mutations return `None`
 after acknowledgement and do not automatically list the drive. Staged finalize accepts a completed `StagedFile`;
 the Provider binds by temporary row ID without checking its owner (PVD-031), and finalize atomicity/idempotency remain
-absent (PCG-012). Batch move and permanent delete do not claim Provider per-item results or atomicity. Permanent
+absent. Batch move and permanent delete do not claim Provider per-item results or atomicity. Permanent
 deletion is named `permanently_delete_files` and is non-recoverable. Cloud downloads
 resolve bytes from the final file identity and reuse `DownloadStream`, thumbnail/preview choices and the PVD-002-safe
 range subset. Cloud mutations are not automatically retried.
@@ -873,6 +887,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.4.1`,
-commit `6f8ab3d14797385d0075d0aba38bf3bf529e674d`, and OpenAPI SHA-256
-`73d899c9e60b59f9521062ffcfaaae5f073eea36f24f3e535fcb53f12242581c`.
+byte-identical wheel and source distribution hashes. The release is bound to `matelab-spec v0.4.2`,
+commit `a51483f910440fbbbc3693cc32566482064bb3ab`, and OpenAPI SHA-256
+`4c92b96ba3dfe7122b30b4db2e2c8054c06018291c8c52c15482112b51a32920`.

{matelab_python_sdk-0.1.0a17 → matelab_python_sdk-0.1.0a18}/contracts/matelab-integration-v1.lock.json

@@ -2,12 +2,12 @@
   "schema_version": 1,
   "contract_line": "integration-v1",
   "release": {
-    "tag": "v0.4.1",
-    "commit": "6f8ab3d14797385d0075d0aba38bf3bf529e674d"
+    "tag": "v0.4.2",
+    "commit": "a51483f910440fbbbc3693cc32566482064bb3ab"
   },
   "openapi": {
     "source_path": "openapi/matelab-integration-v1.openapi.yaml",
     "snapshot": "matelab-integration-v1.openapi.yaml",
-    "sha256": "73d899c9e60b59f9521062ffcfaaae5f073eea36f24f3e535fcb53f12242581c"
+    "sha256": "4c92b96ba3dfe7122b30b4db2e2c8054c06018291c8c52c15482112b51a32920"
   }
 }

{matelab_python_sdk-0.1.0a17 → matelab_python_sdk-0.1.0a18}/contracts/matelab-integration-v1.openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: Matelab Integration Contract
-  version: 0.4.1
+  version: 0.4.2
   description: |
     Stable PHP wire contract for the `integration-v1` contract line.
     Business failures are returned as JSON envelopes over HTTP 200.
@@ -37,6 +37,16 @@ info:
       - sql/eln.sql
       - sql/matelab.sql
       - sql/recommend.sql
+  x-provider-audit:
+    latestReviewedCommit: a3e6b961800f6b1ab666f0d3f6cd4c64c2a3ce27
+    stableEvidenceCommit: 59101f006e9fd6d6ce0b951dfd34695a7949b54f
+    compatibility: incompatible
+    regressions:
+      - {issue: PVD-037, operationId: uploadRecordCommentAttachment}
+      - {issue: PVD-042, operationId: extractLiteratureMetadata}
+      - {issue: PVD-043, operationId: searchRecordData}
+      - {issue: PVD-044, operationId: updateRecordData}
+      - {issue: PVD-045, operationId: importRecordDataset}
   x-consumer-evidence:
     - repository: /home/tnzhu/projects/matelab-mcp
       commit: 94a129b2df0ef0fbcf179c10550fb7c9a5dd2e6f
@@ -963,7 +973,7 @@ paths:
         product capability and the notebook/template share routes do not require
         common group membership. The contract still narrows the keyword to a
         bounded, non-blank 2–100-character string and records the unpaged global
-        directory as PVD-029/PCG-011.
+        directory as PVD-029.
       x-consumer-use-case: Resolve same-institute or global target user ids before notebook, template, or literature sharing.
       x-known-provider-issues: [PVD-013, PVD-029]
       security: [{bearerAuth: []}]
@@ -1507,7 +1517,7 @@ paths:
         Consumers must split attachment-bearing imports into single-record
         requests with a distinct staged name for each request, and must not
         retry a failed finalize with the same name.
-      x-known-provider-issues: [PVD-023, PVD-024, PVD-040, PVD-041]
+      x-known-provider-issues: [PVD-023, PVD-024, PVD-040, PVD-041, PVD-045]
       security: [{bearerAuth: []}]
       requestBody:
         required: true
@@ -1597,6 +1607,12 @@ paths:
       operationId: searchRecordData
       tags: [Records]
       summary: Search notebooks and extract requested dynamic fields
+      description: |
+        The released contract is backed by Provider commit `59101f0`. The latest
+        reviewed Provider commit excludes encrypted records before applying the
+        requested filters, which is a response-subtractive behavior change still
+        awaiting policy confirmation and Provider Verification under PVD-043.
+      x-known-provider-issues: [PVD-043]
       security: [{bearerAuth: []}]
       requestBody:
         required: true
@@ -1650,7 +1666,11 @@ paths:
         This operation does not modify record title or other record metadata.
         `UpdateRecordRequest` rejects a top-level `title`; the Front uses the
         separate, currently unsupported `/eln_items/edit` route for that use
-        case. A stable Integration metadata update remains PCG-016.
+        case. That candidate route remains outside Supported Routes and has not
+        completed the request-boundary, permission, side-effect, response, and
+        Provider Verification audit required for Integration use. MCP therefore
+        deliberately omits title from `update_record`; the shared capability gap
+        remains tracked as PCG-016.
 
         Verified staged-name update shapes are enumerated by
         `info.x-record-attachment-staging.safeFinalizerShapes.update` and their
@@ -1674,7 +1694,7 @@ paths:
         consumption are not atomic. Once a finalizer begins, any write error,
         collaboration-pending response, response loss or failed readback leaves
         staging indeterminate and must not be retried.
-      x-known-provider-issues: [PVD-014, PVD-015, PVD-016, PVD-017, PVD-040, PVD-041]
+      x-known-provider-issues: [PVD-014, PVD-015, PVD-016, PVD-017, PVD-040, PVD-041, PVD-044]
       security: [{bearerAuth: []}]
       requestBody:
         required: true
@@ -3398,6 +3418,7 @@ paths:
         external to the PHP Provider and can omit fields or return additional
         fields, so only the documented candidate fields are promised.
       x-consumer-use-case: Prefill canonical literature metadata before import from a DOI or staged PDF.
+      x-known-provider-issues: [PVD-042]
       security: [{bearerAuth: []}]
       requestBody:
         required: true

{matelab_python_sdk-0.1.0a17 → matelab_python_sdk-0.1.0a18}/docs/operation-coverage.yaml

@@ -3,7 +3,7 @@
 schema_version: 1
 contract:
   line: integration-v1
-  release: v0.4.1
+  release: v0.4.2
   operation_count: 71
 
 operations:
@@ -169,7 +169,7 @@ operations:
     state: implemented
     stability: experimental
     public_interface: AsyncMatelab.groups.list
-    known_issues: [PCG-003, PCG-011, PVD-006, PVD-013]
+    known_issues: [PCG-003, PVD-006, PVD-013]
 
   - operation_id: searchUsers
     method: GET
@@ -178,7 +178,7 @@ operations:
     state: implemented
     stability: experimental
     public_interface: AsyncMatelab.users.search
-    known_issues: [PCG-003, PCG-011, PVD-013, PVD-029]
+    known_issues: [PCG-003, PVD-013, PVD-029]
 
   - operation_id: saveNotebookMetadata
     method: POST
@@ -259,7 +259,7 @@ operations:
     state: implemented
     stability: experimental
     public_interface: AsyncMatelab.records.import_dataset
-    known_issues: [PCG-008, PCG-014, PVD-023, PVD-024, PVD-040, PVD-041]
+    known_issues: [PCG-008, PCG-014, PVD-023, PVD-024, PVD-040, PVD-041, PVD-045]
 
   - operation_id: exportRecords
     method: POST
@@ -277,7 +277,7 @@ operations:
     state: implemented
     stability: experimental
     public_interface: AsyncMatelab.records.search
-    known_issues: [PCG-003, PVD-013]
+    known_issues: [PCG-003, PVD-013, PVD-043]
 
   - operation_id: updateRecordData
     method: POST
@@ -286,7 +286,7 @@ operations:
     state: implemented
     stability: experimental
     public_interface: AsyncMatelab.records.update
-    known_issues: [PCG-001, PCG-002, PCG-014, PVD-014, PVD-015, PVD-016, PVD-017, PVD-040, PVD-041]
+    known_issues: [PCG-001, PCG-002, PCG-014, PVD-014, PVD-015, PVD-016, PVD-017, PVD-040, PVD-041, PVD-044]
 
   - operation_id: deleteRecordsByUid
     method: POST
@@ -385,7 +385,7 @@ operations:
     state: implemented
     stability: experimental
     public_interface: AsyncMatelab.records.comments
-    known_issues: [PCG-013, PVD-013]
+    known_issues: [PVD-013]
 
   - operation_id: saveRecordComment
     method: POST
@@ -394,7 +394,7 @@ operations:
     state: implemented
     stability: experimental
     public_interface: AsyncMatelab.records.create_comment / AsyncMatelab.records.update_comment
-    known_issues: [PCG-013, PVD-004, PVD-026]
+    known_issues: [PVD-004, PVD-026]
 
   - operation_id: uploadRecordCommentAttachment
     method: POST
@@ -403,7 +403,7 @@ operations:
     state: implemented
     stability: experimental
     public_interface: AsyncMatelab.records.upload_comment_attachment
-    known_issues: [PCG-013, PVD-037]
+    known_issues: [PVD-037]
 
   - operation_id: deleteRecordComment
     method: POST
@@ -412,7 +412,7 @@ operations:
     state: implemented
     stability: experimental
     public_interface: AsyncMatelab.records.delete_comment
-    known_issues: [PCG-013]
+    known_issues: []
 
   - operation_id: downloadRecordCommentAttachment
     method: GET
@@ -421,7 +421,7 @@ operations:
     state: implemented
     stability: experimental
     public_interface: AsyncMatelab.records.download_comment_attachment
-    known_issues: [PCG-013, PVD-002, PVD-038]
+    known_issues: [PVD-002, PVD-038]
 
   - operation_id: readRecord
     method: GET
@@ -531,7 +531,7 @@ operations:
     state: implemented
     stability: experimental
     public_interface: AsyncMatelab.literature.extract_metadata
-    known_issues: [PCG-010]
+    known_issues: [PVD-042]
 
   - operation_id: saveLiteratureItem
     method: POST
@@ -540,7 +540,7 @@ operations:
     state: implemented
     stability: experimental
     public_interface: AsyncMatelab.literature.create / AsyncMatelab.literature.update
-    known_issues: [PCG-010, PVD-011, PVD-026, PVD-027, PVD-041]
+    known_issues: [PVD-011, PVD-026, PVD-027, PVD-041]
 
   - operation_id: replaceLiteraturePdf
     method: POST
@@ -549,7 +549,7 @@ operations:
     state: implemented
     stability: experimental
     public_interface: AsyncMatelab.literature.replace_pdf
-    known_issues: [PCG-010, PVD-011, PVD-026]
+    known_issues: [PVD-011, PVD-026]
 
   - operation_id: deleteLiteraturePdf
     method: POST
@@ -558,7 +558,7 @@ operations:
     state: implemented
     stability: experimental
     public_interface: AsyncMatelab.literature.delete_pdf
-    known_issues: [PCG-010, PVD-011]
+    known_issues: [PVD-011]
 
   - operation_id: downloadLiteraturePdf
     method: GET
@@ -576,7 +576,7 @@ operations:
     state: implemented
     stability: experimental
     public_interface: AsyncMatelab.cloud_drive.list
-    known_issues: [PCG-003, PCG-012, PVD-013]
+    known_issues: [PCG-003, PVD-013]
 
   - operation_id: saveCloudDriveFolder
     method: POST
@@ -585,7 +585,7 @@ operations:
     state: implemented
     stability: experimental
     public_interface: AsyncMatelab.cloud_drive.create_folder / AsyncMatelab.cloud_drive.update_folder
-    known_issues: [PCG-012]
+    known_issues: []
 
   - operation_id: deleteEmptyCloudDriveFolder
     method: POST
@@ -594,7 +594,7 @@ operations:
     state: implemented
     stability: experimental
     public_interface: AsyncMatelab.cloud_drive.delete_folder
-    known_issues: [PCG-012]
+    known_issues: []
 
   - operation_id: moveCloudDriveFolder
     method: POST
@@ -603,7 +603,7 @@ operations:
     state: implemented
     stability: experimental
     public_interface: AsyncMatelab.cloud_drive.move_folder
-    known_issues: [PCG-012]
+    known_issues: []
 
   - operation_id: bindStagedCloudDriveFile
     method: POST
@@ -612,7 +612,7 @@ operations:
     state: implemented
     stability: experimental
     public_interface: AsyncMatelab.cloud_drive.bind_staged_file
-    known_issues: [PCG-012, PVD-031]
+    known_issues: [PVD-031]
 
   - operation_id: editCloudDriveFile
     method: POST
@@ -621,7 +621,7 @@ operations:
     state: implemented
     stability: experimental
     public_interface: AsyncMatelab.cloud_drive.update_file
-    known_issues: [PCG-012]
+    known_issues: []
 
   - operation_id: deleteCloudDriveFiles
     method: POST
@@ -630,7 +630,7 @@ operations:
     state: implemented
     stability: experimental
     public_interface: AsyncMatelab.cloud_drive.permanently_delete_files
-    known_issues: [PCG-012]
+    known_issues: []
 
   - operation_id: moveCloudDriveFiles
     method: POST
@@ -639,7 +639,7 @@ operations:
     state: implemented
     stability: experimental
     public_interface: AsyncMatelab.cloud_drive.move_files
-    known_issues: [PCG-012]
+    known_issues: []
 
   - operation_id: downloadCloudDriveFile
     method: GET
@@ -648,4 +648,4 @@ operations:
     state: implemented
     stability: experimental
     public_interface: AsyncMatelab.cloud_drive.download
-    known_issues: [PCG-012, PVD-002]
+    known_issues: [PVD-002]

{matelab_python_sdk-0.1.0a17 → matelab_python_sdk-0.1.0a18}/pyproject.toml

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

{matelab_python_sdk-0.1.0a17 → matelab_python_sdk-0.1.0a18}/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 = "0.4.1"
+OPENAPI_INFO_VERSION = "0.4.2"
 
 
 class ResponseEnvelope(WireModel):

{matelab_python_sdk-0.1.0a17 → matelab_python_sdk-0.1.0a18}/tests/test_generation.py

@@ -333,7 +333,7 @@ def test_generated_models_cover_every_component_schema_and_non_streaming_operati
     }
     assert expected_response_models <= class_names
     assert len(operation_ids) == 71
-    assert wire_models.OPENAPI_INFO_VERSION == "0.4.1"
+    assert wire_models.OPENAPI_INFO_VERSION == "0.4.2"
 
 
 def test_generation_is_deterministic(tmp_path: Path) -> None:
@@ -445,8 +445,8 @@ def test_contract_lock_is_the_single_release_pin() -> None:
     openapi = cast(dict[str, Any], lock["openapi"])
     assert set(release) == {"tag", "commit"}
     assert set(openapi) == {"source_path", "snapshot", "sha256"}
-    assert release == {"tag": "v0.4.1", "commit": "6f8ab3d14797385d0075d0aba38bf3bf529e674d"}
-    assert openapi["sha256"] == "73d899c9e60b59f9521062ffcfaaae5f073eea36f24f3e535fcb53f12242581c"
+    assert release == {"tag": "v0.4.2", "commit": "a51483f910440fbbbc3693cc32566482064bb3ab"}
+    assert openapi["sha256"] == "4c92b96ba3dfe7122b30b4db2e2c8054c06018291c8c52c15482112b51a32920"
     assert re.fullmatch(r"[0-9a-f]{40}", cast(str, release["commit"]))
     assert re.fullmatch(r"[0-9a-f]{64}", cast(str, openapi["sha256"]))
     assert not (ROOT / "contracts" / "matelab-integration-v1.sha256").exists()

{matelab_python_sdk-0.1.0a17 → matelab_python_sdk-0.1.0a18}/uv.lock

@@ -352,7 +352,7 @@ wheels = [
 
 [[package]]
 name = "matelab-python-sdk"
-version = "0.1.0a17"
+version = "0.1.0a18"
 source = { editable = "." }
 dependencies = [
     { name = "httpx2" },