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

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

@@ -3,6 +3,20 @@
 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.0a19 - 2026-08-23
+
+- Re-adopts the force-rewritten `matelab-spec v0.4.2` at commit
+  `1a4b77721d782fccd2b1f26bcc16a7d876347686` and OpenAPI SHA-256
+  `1e737421aac636356487122ea89e20d54de07c8b9c0651cf6970a7123fe3b72b`. The published `0.1.0a18` entry below remains
+  historical evidence for the former `v0.4.2` target at `a51483f`; it is not rewritten.
+- Aligns with current Provider evidence: comment attachment multipart uses `file`; temporary-file and comment identifiers
+  allow 100 characters; code-4 `errs` accepts opaque array or object containers; and DOI extraction validates
+  `^10\.[0-9]+/\S+$` before transport.
+- Breaking: removes `RecordValueAddition.path` and `RecordFilesAttachmentAppend.folder_path` because the current
+  Provider's add-value shape no longer accepts `path`; files-module append now targets only the module root. Search
+  excludes encrypted records, and callers of arbitrary template-shaped imports must omit unset file-valued keys because
+  the Provider rejects their explicit `null`.
+
 ## 0.1.0a18 - 2026-08-23
 
 - Adopts immutable `matelab-spec v0.4.2` at commit `a51483f910440fbbbc3693cc32566482064bb3ab` and OpenAPI

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matelab-python-sdk
-Version: 0.1.0a18
+Version: 0.1.0a19
 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.0a18`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a19`. `[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.2` Contract Release. The sole release pin is
+The SDK is pinned to the rewritten `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,17 +64,15 @@ 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.0a18-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a19-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.
+The Contract and public SDK interface track the current reviewed Provider at
+`a3e6b961800f6b1ab666f0d3f6cd4c64c2a3ce27`. Provider limitations that remain relevant to integrations are documented
+alongside the affected interfaces below.
 
 ## Design
 
@@ -123,8 +121,8 @@ 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.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
+The pinned v0.4.2 Contract also declares optional code-4 `errs`, but PVD-041 and PCG-015 record opaque array/object
+containers 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
@@ -318,8 +316,8 @@ supports one file column. A locally rejected target does not spend the handle; o
 result cannot be retried through the same client.
 
 Files-module append and table/files replacement use the general record attachment intents and may be combined with
-other non-conflicting record changes. `RecordFilesAttachmentAppend` targets the module root by default; pass
-`folder_path=(...)` for an existing folder-title path:
+other non-conflicting record changes. `RecordFilesAttachmentAppend` targets the module root; the current Provider does
+not accept a files-folder path (PVD-044):
 
 ```python
 from matelab import RecordAttachmentReplacement, RecordFilesAttachmentAppend, RecordValueUpdate
@@ -544,7 +542,7 @@ 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
+The current 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
@@ -595,9 +593,10 @@ 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. 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.
+missing folders. The current Provider rejects explicit-null table-file imports (PVD-045). Because the SDK accepts
+arbitrary template-shaped data and cannot identify file columns without the template definition, integrations must omit
+an unset file-valued key instead of sending it as `None`. 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`
@@ -614,9 +613,8 @@ 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. 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.
+password lifecycle remain unexposed. Files-module attachment append is root-only because the current Provider rejects
+folder-path segments (PVD-044). A staged attachment is 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
@@ -628,8 +626,7 @@ 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 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`
+Comment upload follows the current Provider's literal one-request `file` field (PVD-037). 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
@@ -709,9 +706,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. 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
+completed staged PDF, or both; a supplied DOI takes precedence over the staged PDF. A non-empty DOI must match
+`^10\.[0-9]+/\S+$`; the generated request model rejects other values before sending them to the Provider (PVD-042).
+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
@@ -915,6 +912,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.2`,
-commit `a51483f910440fbbbc3693cc32566482064bb3ab`, and OpenAPI SHA-256
-`4c92b96ba3dfe7122b30b4db2e2c8054c06018291c8c52c15482112b51a32920`.
+byte-identical wheel and source distribution hashes. The release is bound to the rewritten `matelab-spec v0.4.2`,
+commit `1a4b77721d782fccd2b1f26bcc16a7d876347686`, and OpenAPI SHA-256
+`1e737421aac636356487122ea89e20d54de07c8b9c0651cf6970a7123fe3b72b`.

{matelab_python_sdk-0.1.0a18 → matelab_python_sdk-0.1.0a19}/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.0a18`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a19`. `[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.2` Contract Release. The sole release pin is
+The SDK is pinned to the rewritten `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,17 +36,15 @@ 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.0a18-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a19-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.
+The Contract and public SDK interface track the current reviewed Provider at
+`a3e6b961800f6b1ab666f0d3f6cd4c64c2a3ce27`. Provider limitations that remain relevant to integrations are documented
+alongside the affected interfaces below.
 
 ## Design
 
@@ -95,8 +93,8 @@ 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.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
+The pinned v0.4.2 Contract also declares optional code-4 `errs`, but PVD-041 and PCG-015 record opaque array/object
+containers 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
@@ -290,8 +288,8 @@ supports one file column. A locally rejected target does not spend the handle; o
 result cannot be retried through the same client.
 
 Files-module append and table/files replacement use the general record attachment intents and may be combined with
-other non-conflicting record changes. `RecordFilesAttachmentAppend` targets the module root by default; pass
-`folder_path=(...)` for an existing folder-title path:
+other non-conflicting record changes. `RecordFilesAttachmentAppend` targets the module root; the current Provider does
+not accept a files-folder path (PVD-044):
 
 ```python
 from matelab import RecordAttachmentReplacement, RecordFilesAttachmentAppend, RecordValueUpdate
@@ -516,7 +514,7 @@ 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
+The current 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
@@ -567,9 +565,10 @@ 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. 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.
+missing folders. The current Provider rejects explicit-null table-file imports (PVD-045). Because the SDK accepts
+arbitrary template-shaped data and cannot identify file columns without the template definition, integrations must omit
+an unset file-valued key instead of sending it as `None`. 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`
@@ -586,9 +585,8 @@ 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. 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.
+password lifecycle remain unexposed. Files-module attachment append is root-only because the current Provider rejects
+folder-path segments (PVD-044). A staged attachment is 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
@@ -600,8 +598,7 @@ 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 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`
+Comment upload follows the current Provider's literal one-request `file` field (PVD-037). 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
@@ -681,9 +678,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. 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
+completed staged PDF, or both; a supplied DOI takes precedence over the staged PDF. A non-empty DOI must match
+`^10\.[0-9]+/\S+$`; the generated request model rejects other values before sending them to the Provider (PVD-042).
+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
@@ -887,6 +884,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.2`,
-commit `a51483f910440fbbbc3693cc32566482064bb3ab`, and OpenAPI SHA-256
-`4c92b96ba3dfe7122b30b4db2e2c8054c06018291c8c52c15482112b51a32920`.
+byte-identical wheel and source distribution hashes. The release is bound to the rewritten `matelab-spec v0.4.2`,
+commit `1a4b77721d782fccd2b1f26bcc16a7d876347686`, and OpenAPI SHA-256
+`1e737421aac636356487122ea89e20d54de07c8b9c0651cf6970a7123fe3b72b`.

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

@@ -3,11 +3,11 @@
   "contract_line": "integration-v1",
   "release": {
     "tag": "v0.4.2",
-    "commit": "a51483f910440fbbbc3693cc32566482064bb3ab"
+    "commit": "1a4b77721d782fccd2b1f26bcc16a7d876347686"
   },
   "openapi": {
     "source_path": "openapi/matelab-integration-v1.openapi.yaml",
     "snapshot": "matelab-integration-v1.openapi.yaml",
-    "sha256": "4c92b96ba3dfe7122b30b4db2e2c8054c06018291c8c52c15482112b51a32920"
+    "sha256": "1e737421aac636356487122ea89e20d54de07c8b9c0651cf6970a7123fe3b72b"
   }
 }