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

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

@@ -3,6 +3,30 @@
 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
+  SHA-256 `73d899c9e60b59f9521062ffcfaaae5f073eea36f24f3e535fcb53f12242581c`. The standard wire structure is
+  unchanged from v0.4.0. PVD-041 and PCG-015 confirm that optional code-4 `errs` remains opaque, potentially sensitive
+  and unsafe to expose as a stable typed SDK interface without stronger Provider evidence and a future Contract release.
+- Breaking: `MatelabProviderError` construction now requires `provider_code`, `provider_message`, and `category`.
+  Transport and download errors preserve the Provider envelope's numeric `code` and expose an SDK-owned safe summary
+  instead of copying Provider-authored diagnostics into exceptions. The stable recovery interface remains `category`
+  plus conservative `retryable=False`; raw Provider codes are diagnostic rather than stable routing identifiers.
+  Exceptions exclude the response body, top-level `msg`, legacy `errmsg`, opaque `errs`, uncontracted debug fields, and
+  request payloads because Provider text may contain stack traces, credentials, or submitted values.
+
 ## 0.1.0a16 - 2026-08-14
 
 - Breaking: `UserSummary.display_name` is renamed to `name`; the SDK exposes the Provider's raw nullable real name

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matelab-python-sdk
-Version: 0.1.0a16
+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.0a16`. `[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.0` 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.0a16-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:
@@ -93,29 +99,37 @@ explicitly when needed, for example `AsyncMatelab("https://custom.example/api")`
 ### Error handling
 
 Catch `MatelabError` once at an integration seam. Every instance exposes a stable `category: MatelabErrorCategory` and
-`retryable: bool`, so an integration can copy the message, category, and retry flag without inspecting subclasses or
-Provider details:
+`retryable: bool`. `MatelabProviderError` additionally exposes `provider_code: int` and `provider_message: str`, so a
+gateway can retain a stable diagnostic code and safe summary while routing recovery through the integration-level
+category:
 
 | Error | Category | Retryable | Meaning and normal response |
 |---|---|---:|---|
 | `MatelabAuthenticationError` | `AUTHENTICATION` | No | The Session or credentials cannot authenticate; obtain valid authentication before making a new call. |
 | `MatelabUsageError` | `VALIDATION` | No | The call cannot be represented safely; correct its arguments. |
-| `MatelabProviderError` | `BUSINESS`, `VALIDATION`, or `UPSTREAM` | No | The Provider rejected the request; route directly by `category`. |
+| `MatelabProviderError` | `BUSINESS`, `VALIDATION`, or `UPSTREAM` | No | The Provider rejected the request; record `provider_code` and route recovery by `category`; `provider_message` is an SDK-owned safe summary. |
 | `MatelabTransportError` | `UPSTREAM` | No | The HTTP exchange failed; `status_code` is present for HTTP failures, and a mutation outcome may be unknown. |
 | `MatelabProtocolError` | `UPSTREAM` | No | The response violates the pinned Contract; treat it as Provider drift or an SDK defect. |
 
 For `MatelabProviderError`, the SDK maps Provider wire code `2` to `BUSINESS`, `4` to `VALIDATION`, and `3` or an
-unknown code to `UPSTREAM`. Authentication codes are hidden behind `MatelabAuthenticationError`; raw Provider codes
-are not part of the public error interface. Code `5` triggers at most one refresh and replay only for authenticated
-operations that explicitly enable `retry_on_access_expired`; otherwise codes `1` and `5` raise
-`MatelabAuthenticationError` directly.
+unknown code to `UPSTREAM`. `provider_code` is diagnostic metadata, not a stable routing identifier, and integrations
+must not reinterpret it instead of `category`. `provider_message` and the exception string are SDK-owned safe summaries
+selected from the code mapping; they do not reproduce Provider-authored text. Authentication codes remain hidden behind
+`MatelabAuthenticationError`; code `5`
+triggers at most one refresh and replay only for authenticated operations that explicitly enable
+`retry_on_access_expired`, otherwise codes `1` and `5` raise `MatelabAuthenticationError` directly.
 Codes `0` and `10` remain operation-specific successes selected by the pinned Contract; an operation that receives a
 success code it does not allow raises `MatelabProtocolError` rather than assigning an error category.
-`MatelabTransportError.status_code` remains available for HTTP failures. Provider response bodies and caller inputs are
-never attached to exceptions. `retryable` means the identical SDK call is safe to replay without further
-interpretation. It is conservatively `False` for every current SDK error because the Contract does not guarantee
-mutation idempotency or outcome; an integration may add a narrower operation-specific retry policy only when it owns
-that evidence.
+`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.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`
+means the identical SDK call is safe to replay without further interpretation. It is conservatively `False` for every
+current SDK error because the Contract does not guarantee mutation idempotency or outcome; an integration may add a
+narrower operation-specific retry policy only when it owns that evidence.
 
 ### Session ownership
 
@@ -438,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.
 
@@ -530,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
@@ -579,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`
@@ -597,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
@@ -609,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
@@ -689,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
@@ -714,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).
@@ -751,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.
@@ -798,8 +820,9 @@ does not expose a signing operation, signature projection or credentials for the
 results only report whether Provider policy allows signing.
 
 Errors are separated into semantic Provider errors, authentication errors, HTTP/transport errors,
-Integration Contract response errors, and client-side usage errors. Provider response bodies and caller inputs do not
-enter exceptions.
+Integration Contract response errors, and client-side usage errors. Semantic Provider errors retain only the
+Contract-defined top-level code plus an SDK-owned safe summary; Provider-authored messages, response bodies, legacy
+aliases, and unrelated fields do not enter exceptions.
 
 ## Development
 
@@ -892,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.0`,
-commit `7993a7bccc213f626b9cc8124423e2b2c9e48dd7`, and OpenAPI SHA-256
-`e725c9649700d5b4d1c7d75fb9422d64b04a68e0308ddec29ba274d774104c8e`.
+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.0a16 → 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.0a16`. `[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.0` 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.0a16-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:
@@ -65,29 +71,37 @@ explicitly when needed, for example `AsyncMatelab("https://custom.example/api")`
 ### Error handling
 
 Catch `MatelabError` once at an integration seam. Every instance exposes a stable `category: MatelabErrorCategory` and
-`retryable: bool`, so an integration can copy the message, category, and retry flag without inspecting subclasses or
-Provider details:
+`retryable: bool`. `MatelabProviderError` additionally exposes `provider_code: int` and `provider_message: str`, so a
+gateway can retain a stable diagnostic code and safe summary while routing recovery through the integration-level
+category:
 
 | Error | Category | Retryable | Meaning and normal response |
 |---|---|---:|---|
 | `MatelabAuthenticationError` | `AUTHENTICATION` | No | The Session or credentials cannot authenticate; obtain valid authentication before making a new call. |
 | `MatelabUsageError` | `VALIDATION` | No | The call cannot be represented safely; correct its arguments. |
-| `MatelabProviderError` | `BUSINESS`, `VALIDATION`, or `UPSTREAM` | No | The Provider rejected the request; route directly by `category`. |
+| `MatelabProviderError` | `BUSINESS`, `VALIDATION`, or `UPSTREAM` | No | The Provider rejected the request; record `provider_code` and route recovery by `category`; `provider_message` is an SDK-owned safe summary. |
 | `MatelabTransportError` | `UPSTREAM` | No | The HTTP exchange failed; `status_code` is present for HTTP failures, and a mutation outcome may be unknown. |
 | `MatelabProtocolError` | `UPSTREAM` | No | The response violates the pinned Contract; treat it as Provider drift or an SDK defect. |
 
 For `MatelabProviderError`, the SDK maps Provider wire code `2` to `BUSINESS`, `4` to `VALIDATION`, and `3` or an
-unknown code to `UPSTREAM`. Authentication codes are hidden behind `MatelabAuthenticationError`; raw Provider codes
-are not part of the public error interface. Code `5` triggers at most one refresh and replay only for authenticated
-operations that explicitly enable `retry_on_access_expired`; otherwise codes `1` and `5` raise
-`MatelabAuthenticationError` directly.
+unknown code to `UPSTREAM`. `provider_code` is diagnostic metadata, not a stable routing identifier, and integrations
+must not reinterpret it instead of `category`. `provider_message` and the exception string are SDK-owned safe summaries
+selected from the code mapping; they do not reproduce Provider-authored text. Authentication codes remain hidden behind
+`MatelabAuthenticationError`; code `5`
+triggers at most one refresh and replay only for authenticated operations that explicitly enable
+`retry_on_access_expired`, otherwise codes `1` and `5` raise `MatelabAuthenticationError` directly.
 Codes `0` and `10` remain operation-specific successes selected by the pinned Contract; an operation that receives a
 success code it does not allow raises `MatelabProtocolError` rather than assigning an error category.
-`MatelabTransportError.status_code` remains available for HTTP failures. Provider response bodies and caller inputs are
-never attached to exceptions. `retryable` means the identical SDK call is safe to replay without further
-interpretation. It is conservatively `False` for every current SDK error because the Contract does not guarantee
-mutation idempotency or outcome; an integration may add a narrower operation-specific retry policy only when it owns
-that evidence.
+`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.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`
+means the identical SDK call is safe to replay without further interpretation. It is conservatively `False` for every
+current SDK error because the Contract does not guarantee mutation idempotency or outcome; an integration may add a
+narrower operation-specific retry policy only when it owns that evidence.
 
 ### Session ownership
 
@@ -410,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.
 
@@ -502,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
@@ -551,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`
@@ -569,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
@@ -581,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
@@ -661,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
@@ -686,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).
@@ -723,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.
@@ -770,8 +792,9 @@ does not expose a signing operation, signature projection or credentials for the
 results only report whether Provider policy allows signing.
 
 Errors are separated into semantic Provider errors, authentication errors, HTTP/transport errors,
-Integration Contract response errors, and client-side usage errors. Provider response bodies and caller inputs do not
-enter exceptions.
+Integration Contract response errors, and client-side usage errors. Semantic Provider errors retain only the
+Contract-defined top-level code plus an SDK-owned safe summary; Provider-authored messages, response bodies, legacy
+aliases, and unrelated fields do not enter exceptions.
 
 ## Development
 
@@ -864,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.0`,
-commit `7993a7bccc213f626b9cc8124423e2b2c9e48dd7`, and OpenAPI SHA-256
-`e725c9649700d5b4d1c7d75fb9422d64b04a68e0308ddec29ba274d774104c8e`.
+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.0a16 → 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.0",
-    "commit": "7993a7bccc213f626b9cc8124423e2b2c9e48dd7"
+    "tag": "v0.4.2",
+    "commit": "a51483f910440fbbbc3693cc32566482064bb3ab"
   },
   "openapi": {
     "source_path": "openapi/matelab-integration-v1.openapi.yaml",
     "snapshot": "matelab-integration-v1.openapi.yaml",
-    "sha256": "e725c9649700d5b4d1c7d75fb9422d64b04a68e0308ddec29ba274d774104c8e"
+    "sha256": "4c92b96ba3dfe7122b30b4db2e2c8054c06018291c8c52c15482112b51a32920"
   }
 }

{matelab_python_sdk-0.1.0a16 → 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.0
+  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.
@@ -32,10 +32,21 @@ info:
       - lib/Base.php
       - lib/Route.php
       - lib/HttpServer.php
+      - lib/MultiException.php
       - config/Channel.php
       - 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
@@ -172,6 +183,25 @@ info:
         pathSegments: 2
         readback: column-absent-and-table-rows-preserved
         cellLikeThreeSegmentPath: deletes-whole-column-not-cell
+  x-provider-error-diagnostics:
+    status: evidence-gap
+    tracking: [PVD-041, PCG-015]
+    typedPublicInterface: unsafe
+    code4:
+      errsRequired: unverified
+      errsMinItems: unverified
+      errsOnOtherCodes: not-observed-but-not-contracted
+      releasedContainerShape: array
+      sourceConfirmedArrayItemShapes: [string, object, nested-object]
+      sourceConfirmedContractViolations: [object-container-from-file-validator-envelope-merge]
+    responsibilities:
+      codeAndErrcode: machine-readable-envelope-status
+      msgAndErrmsg: human-oriented-summary-not-a-stable-identifier
+      errs: opaque-provider-diagnostics
+    securityBoundary:
+      trust: untrusted-potentially-sensitive
+      observedContent: [localized-validation-text, request-derived-values, stored-field-names]
+      stackTraceExclusion: not-contractually-guaranteed
 servers:
   - url: https://matelab.example.invalid
     description: Placeholder; consumers supply their Provider base URL.
@@ -943,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: []}]
@@ -1487,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]
+      x-known-provider-issues: [PVD-023, PVD-024, PVD-040, PVD-041, PVD-045]
       security: [{bearerAuth: []}]
       requestBody:
         required: true
@@ -1577,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
@@ -1627,6 +1663,15 @@ paths:
         caller-owned staging or authorized existing file quotes, and binds the
         resulting attachments while saving the record.
 
+        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. 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
         dedicated component schemas. They cover a new form file field, setting
@@ -1649,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]
+      x-known-provider-issues: [PVD-014, PVD-015, PVD-016, PVD-017, PVD-040, PVD-041, PVD-044]
       security: [{bearerAuth: []}]
       requestBody:
         required: true
@@ -3373,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
@@ -3456,7 +3502,7 @@ paths:
         both branches must verify the stored result through
         `readLiteratureDetail`. Create-time file binding is affected by PVD-026.
       x-consumer-use-case: Create canonical personal literature with an optional staged PDF, or replace the canonical metadata of a writable item.
-      x-known-provider-issues: [PVD-011, PVD-026, PVD-027]
+      x-known-provider-issues: [PVD-011, PVD-026, PVD-027, PVD-041]
       security: [{bearerAuth: []}]
       requestBody:
         required: true
@@ -4062,12 +4108,19 @@ components:
           type: integer
         msg:
           type: string
+          description: |
+            Human-oriented envelope summary. Consumers must use `code` for
+            branching and must not parse this text as a stable identifier,
+            field location, or retry signal.
         errcode:
           type: integer
           description: Legacy alias of `code`; always present in these operations.
         errmsg:
           type: string
-          description: Legacy alias of `msg`; always present in these operations.
+          description: |
+            Legacy alias of `msg`; always present in these operations. It has
+            the same human-summary responsibility and is not a structured
+            diagnostic field.
     BasicSuccessResponse:
       allOf:
         - $ref: "#/components/schemas/ResponseEnvelope"
@@ -4083,7 +4136,14 @@ components:
             code: {enum: [0, 10]}
             errcode: {enum: [0, 10]}
     ErrorDetail:
-      description: A stable per-field or per-location error value returned when code is 4.
+      description: |
+        Intentionally unconstrained Provider diagnostic array item. Source
+        evidence includes strings, structured objects, sparse objects, and
+        nested error groups. Integration-v1 therefore does not promise a stable
+        item shape. The separate source-confirmed object-container branch
+        violates ErrorResponse and is tracked by PVD-041 and PCG-015.
+      x-contract-status: evidence-gap
+      x-tracking: [PVD-041, PCG-015]
     ErrorResponse:
       allOf:
         - $ref: "#/components/schemas/ResponseEnvelope"
@@ -4106,11 +4166,23 @@ components:
               type: array
               items:
                 $ref: "#/components/schemas/ErrorDetail"
-              description: Present for multi-error code 4; absent from ordinary errors.
+              description: |
+                Optional array of opaque, untrusted Provider diagnostics
+                observed on code 4. Integration-v1 does not constrain its
+                requiredness, cardinality, item shape, order, or absence on
+                other codes. Values can contain localized validation text,
+                request-derived values, or stored field names and must not be
+                broadly logged or displayed without sanitization. No
+                stack-trace exclusion is contractually guaranteed. The
+                Provider's source-confirmed object-container branch violates
+                this released array contract; see PVD-041 and PCG-015.
+          x-known-provider-issues: [PVD-041]
       description: |
         Stable HTTP 200 error envelope. Codes observed in the common router are:
         1 authentication, 2 input/permission/business failure, 3 server failure,
-        4 multiple errors (`errs` present), and 5 expired access token.
+        4 multiple errors (normally with `errs`), and 5 expired access token.
+        `msg`/`errmsg` summarize the envelope for people; `errs`, when present,
+        carries opaque diagnostics and is not a stable public detail interface.
     Sha256:
       type: string
       pattern: "^[0-9a-f]{64}$"