matelab-python-sdk 0.1.0a6__tar.gz → 0.1.0a7__tar.gz

{matelab_python_sdk-0.1.0a6 → matelab_python_sdk-0.1.0a7}/AGENTS.md

@@ -1,8 +1,8 @@
 # AGENTS.md
 
 本文档只保留维护 `matelab-python-sdk` 必须长期遵守的项目约束。当前能力和使用方式见
-`README.md`，实现路线与进度见 `docs/roadmap.md`，operation 状态以
-`docs/operation-coverage.yaml` 为机器权威。不要在本文记录阶段性完成状态、一次性验收数字或迁移历史。
+`README.md`，版本历史见 `CHANGELOG.md`，operation 状态以 `docs/operation-coverage.yaml` 为机器权威。
+不要在本文记录阶段性完成状态、一次性验收数字或迁移历史。
 
 ## 权威与范围
 

{matelab_python_sdk-0.1.0a6 → matelab_python_sdk-0.1.0a7}/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.1.0a7 - 2026-08-04
+
+- Replaces the hand-maintained wire-validation rule tables with deterministic generated JSON Schema 2020-12 rules.
+- Simplifies transport, streaming, error mapping, and domain adapters while retaining the pinned `matelab-spec v0.3.0`
+  behavior and automatic Session refresh guarantees.
+- Breaking: tightens several public domain inputs and results, and exposes stable `MatelabProviderErrorKind` values
+  instead of raw Provider error codes.
+- Removes completed roadmap and work-package bookkeeping; refreshes release checks, documentation, and tests.
+
 ## 0.1.0a6 - 2026-08-01
 
 - Adopts the immutable `matelab-spec v0.3.0` Contract release and its form-encoding updates.

{matelab_python_sdk-0.1.0a6 → matelab_python_sdk-0.1.0a7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matelab-python-sdk
-Version: 0.1.0a6
+Version: 0.1.0a7
 Summary: Reusable async Python client for the Matelab Integration Contract
 Author-email: 朱天念 <zhutiannian@gmail.com>
 License-Expression: Apache-2.0
@@ -21,6 +21,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Requires-Dist: httpx2<3,>=2.9.1
+Requires-Dist: jsonschema<5,>=4.26
 Requires-Dist: pydantic<3,>=2.13.4
 Description-Content-Type: text/markdown
 
@@ -28,7 +29,7 @@ Description-Content-Type: text/markdown
 
 Reusable async Python client for the Matelab Integration Contract.
 
-The current alpha is `0.1.0a6`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a7`. `[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.3.0` Contract Release. The sole release pin is
@@ -57,7 +58,7 @@ To test the same artifact a downstream Consumer will install, build and install
 
 ```bash
 uv build --no-build-isolation --out-dir dist/release
-python -m pip install dist/release/matelab_python_sdk-0.1.0a6-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a7-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -90,12 +91,19 @@ Catch `MatelabError` for one application-level fallback, or a specific subclass
 |---|---|
 | `MatelabUsageError` | The call cannot be represented safely; correct its arguments. |
 | `MatelabAuthenticationError` | The Session is missing, expired, invalid, or rejected; refresh or authenticate again as appropriate. |
-| `MatelabProviderError` | The Provider rejected a valid request with a business error; inspect `code` and do not assume a mutation was applied. |
+| `MatelabProviderError` | The Provider returned a non-authentication error; inspect its stable `kind` and do not assume a mutation was applied. |
 | `MatelabTransportError` | The HTTP exchange failed; `status_code` is present for HTTP failures, and a mutation outcome may be unknown. |
 | `MatelabProtocolError` | The Provider response does not match the pinned Contract; treat it as Provider drift or an SDK defect. A mutation may already have been applied. |
 
-`code` and `status_code` are the stable scalar diagnostics. Provider response bodies and caller inputs are never
-attached to exceptions. Never automatically retry a mutation solely because it raised a transport or protocol error.
+`MatelabProviderError.kind` is a `MatelabProviderErrorKind`: `REJECTED` covers input, permission, and business
+rejections; `SERVER` identifies Provider server failures; `VALIDATION` identifies multi-error validation failures; and
+`UNKNOWN` safely represents all other non-success, non-authentication Provider codes. Authentication codes are hidden
+behind `MatelabAuthenticationError`; raw Provider codes are not part of the public error interface.
+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 kind.
+`MatelabTransportError.status_code` remains available for HTTP failures. Provider response bodies and caller inputs are
+never attached to exceptions. Never automatically retry a mutation solely because it raised a transport or protocol
+error.
 
 ### Session ownership
 
@@ -340,11 +348,7 @@ plain text and that a hash-based URI can fall back to an existing quote, so neit
 Existing `RecordRichTextUpdate` remains legal only with record-scoped `StagedRecordAttachment`. Attachment-bearing
 multi-record import is also forbidden; callers must split it into single-record finalizers.
 
-## Implementation roadmap
-
-`docs/roadmap.md` is the complete SDK-only execution plan. It assigns all 71
-`matelab-spec v0.3.0` operations to ordered work packages, defines the machine-readable coverage that
-must be added, records Provider-risk gates, and specifies the final completion checks.
+## Operation coverage
 
 The SDK tracks all 71 Contract operations and exposes 70 through public domain interfaces; one identity-bootstrap
 operation is intentionally unexposed. It deliberately excludes MCP migration, adjacent-repository changes, external
@@ -352,7 +356,7 @@ publishing, and automatic mutation against a real Provider.
 
 Machine-readable status lives in
 `docs/operation-coverage.yaml`. An exact-coverage test keeps its 71
-operation IDs, methods, paths, work packages, and Provider issue references aligned with the pinned
+operation IDs, methods, paths, states, public interfaces, and Provider issue references aligned with the pinned
 OpenAPI snapshot.
 
 | Domain | Implemented | Planned | Current public surface |
@@ -590,19 +594,11 @@ deletion is named `permanently_delete_files` and is non-recoverable. Cloud downl
 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.
 
-To run the implementation as a persistent Codex goal, start a task in this repository and use:
-
-> 完整阅读并严格遵循 `AGENTS.md`、`README.md` 和 `docs/roadmap.md`。创建并持续执行一个 goal：
-> 只修改当前仓库，按照 roadmap 从第一个未完成 work package 开始，完成 71-operation 精确覆盖和全部
-> SDK 领域 interface；每个 package 通过局部验证后自动继续，最终让 generation `--check`、Ruff、
-> Ruff format、Basedpyright、Pytest 和 package build 全部通过。不要修改相邻仓库，不执行生产 Provider
-> mutation，不 commit、push、tag 或发布。
-
 Owned/shared `NotebookRef`, public `PublicNotebookRef`, `RecordRef`, and `RecordVersionRef` keep
 Provider identifiers distinct. Historical reads first re-read the authorized current record and confirm
 that the requested version is still present in its `modify_log`; both reads write Provider audit entries.
 
-Errors are separated into Provider business errors, authentication errors, HTTP/transport errors,
+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.
 
@@ -621,11 +617,13 @@ uv build
 
 The generator first verifies the contract lock, OpenAPI release metadata, and snapshot digest. It then
 creates a temporary OpenAPI 3.1 generation projection, resolves references without network access, and
-generates private component, operation-response, and parameter models. The projection only flattens pure
-object inheritance that the generator cannot otherwise preserve correctly; the checked-in release
-snapshot remains unchanged. `--check` performs the same validation and deterministic generation without
-writing the checked-in models. The current lock resolves `datamodel-code-generator 0.71.0` and
-`hatchling 1.31.0`. Published metadata requires `httpx2>=2.9.1,<3` and
+generates private component, operation-response, and parameter models. The projection flattens pure
+object inheritance and preserves constraints the model generator cannot express as self-contained JSON Schema
+2020-12 metadata; the checked-in release snapshot remains unchanged. `--check` performs the same validation and deterministic generation without
+writing the checked-in models. `WireModel` applies that metadata with the standard
+`jsonschema` Draft 2020-12 validator; the SDK does not maintain a second hand-written schema interpreter. The current lock resolves
+`datamodel-code-generator 0.71.0` and
+`hatchling 1.31.0`. Published metadata requires `httpx2>=2.9.1,<3`, `jsonschema>=4.26,<5`, and
 `pydantic>=2.13.4,<3`; the build backend requires `hatchling>=1.27,<2`. These lower bounds are verified
 against the complete test suite on the supported Python boundary versions rather than inferred from
 `uv.lock`. The exact toolchain remains locked for development and release builds. Basedpyright and its

{matelab_python_sdk-0.1.0a6 → matelab_python_sdk-0.1.0a7}/README.md

@@ -2,7 +2,7 @@
 
 Reusable async Python client for the Matelab Integration Contract.
 
-The current alpha is `0.1.0a6`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a7`. `[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.3.0` Contract Release. The sole release pin is
@@ -31,7 +31,7 @@ To test the same artifact a downstream Consumer will install, build and install
 
 ```bash
 uv build --no-build-isolation --out-dir dist/release
-python -m pip install dist/release/matelab_python_sdk-0.1.0a6-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a7-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -64,12 +64,19 @@ Catch `MatelabError` for one application-level fallback, or a specific subclass
 |---|---|
 | `MatelabUsageError` | The call cannot be represented safely; correct its arguments. |
 | `MatelabAuthenticationError` | The Session is missing, expired, invalid, or rejected; refresh or authenticate again as appropriate. |
-| `MatelabProviderError` | The Provider rejected a valid request with a business error; inspect `code` and do not assume a mutation was applied. |
+| `MatelabProviderError` | The Provider returned a non-authentication error; inspect its stable `kind` and do not assume a mutation was applied. |
 | `MatelabTransportError` | The HTTP exchange failed; `status_code` is present for HTTP failures, and a mutation outcome may be unknown. |
 | `MatelabProtocolError` | The Provider response does not match the pinned Contract; treat it as Provider drift or an SDK defect. A mutation may already have been applied. |
 
-`code` and `status_code` are the stable scalar diagnostics. Provider response bodies and caller inputs are never
-attached to exceptions. Never automatically retry a mutation solely because it raised a transport or protocol error.
+`MatelabProviderError.kind` is a `MatelabProviderErrorKind`: `REJECTED` covers input, permission, and business
+rejections; `SERVER` identifies Provider server failures; `VALIDATION` identifies multi-error validation failures; and
+`UNKNOWN` safely represents all other non-success, non-authentication Provider codes. Authentication codes are hidden
+behind `MatelabAuthenticationError`; raw Provider codes are not part of the public error interface.
+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 kind.
+`MatelabTransportError.status_code` remains available for HTTP failures. Provider response bodies and caller inputs are
+never attached to exceptions. Never automatically retry a mutation solely because it raised a transport or protocol
+error.
 
 ### Session ownership
 
@@ -314,11 +321,7 @@ plain text and that a hash-based URI can fall back to an existing quote, so neit
 Existing `RecordRichTextUpdate` remains legal only with record-scoped `StagedRecordAttachment`. Attachment-bearing
 multi-record import is also forbidden; callers must split it into single-record finalizers.
 
-## Implementation roadmap
-
-`docs/roadmap.md` is the complete SDK-only execution plan. It assigns all 71
-`matelab-spec v0.3.0` operations to ordered work packages, defines the machine-readable coverage that
-must be added, records Provider-risk gates, and specifies the final completion checks.
+## Operation coverage
 
 The SDK tracks all 71 Contract operations and exposes 70 through public domain interfaces; one identity-bootstrap
 operation is intentionally unexposed. It deliberately excludes MCP migration, adjacent-repository changes, external
@@ -326,7 +329,7 @@ publishing, and automatic mutation against a real Provider.
 
 Machine-readable status lives in
 `docs/operation-coverage.yaml`. An exact-coverage test keeps its 71
-operation IDs, methods, paths, work packages, and Provider issue references aligned with the pinned
+operation IDs, methods, paths, states, public interfaces, and Provider issue references aligned with the pinned
 OpenAPI snapshot.
 
 | Domain | Implemented | Planned | Current public surface |
@@ -564,19 +567,11 @@ deletion is named `permanently_delete_files` and is non-recoverable. Cloud downl
 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.
 
-To run the implementation as a persistent Codex goal, start a task in this repository and use:
-
-> 完整阅读并严格遵循 `AGENTS.md`、`README.md` 和 `docs/roadmap.md`。创建并持续执行一个 goal：
-> 只修改当前仓库，按照 roadmap 从第一个未完成 work package 开始，完成 71-operation 精确覆盖和全部
-> SDK 领域 interface；每个 package 通过局部验证后自动继续，最终让 generation `--check`、Ruff、
-> Ruff format、Basedpyright、Pytest 和 package build 全部通过。不要修改相邻仓库，不执行生产 Provider
-> mutation，不 commit、push、tag 或发布。
-
 Owned/shared `NotebookRef`, public `PublicNotebookRef`, `RecordRef`, and `RecordVersionRef` keep
 Provider identifiers distinct. Historical reads first re-read the authorized current record and confirm
 that the requested version is still present in its `modify_log`; both reads write Provider audit entries.
 
-Errors are separated into Provider business errors, authentication errors, HTTP/transport errors,
+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.
 
@@ -595,11 +590,13 @@ uv build
 
 The generator first verifies the contract lock, OpenAPI release metadata, and snapshot digest. It then
 creates a temporary OpenAPI 3.1 generation projection, resolves references without network access, and
-generates private component, operation-response, and parameter models. The projection only flattens pure
-object inheritance that the generator cannot otherwise preserve correctly; the checked-in release
-snapshot remains unchanged. `--check` performs the same validation and deterministic generation without
-writing the checked-in models. The current lock resolves `datamodel-code-generator 0.71.0` and
-`hatchling 1.31.0`. Published metadata requires `httpx2>=2.9.1,<3` and
+generates private component, operation-response, and parameter models. The projection flattens pure
+object inheritance and preserves constraints the model generator cannot express as self-contained JSON Schema
+2020-12 metadata; the checked-in release snapshot remains unchanged. `--check` performs the same validation and deterministic generation without
+writing the checked-in models. `WireModel` applies that metadata with the standard
+`jsonschema` Draft 2020-12 validator; the SDK does not maintain a second hand-written schema interpreter. The current lock resolves
+`datamodel-code-generator 0.71.0` and
+`hatchling 1.31.0`. Published metadata requires `httpx2>=2.9.1,<3`, `jsonschema>=4.26,<5`, and
 `pydantic>=2.13.4,<3`; the build backend requires `hatchling>=1.27,<2`. These lower bounds are verified
 against the complete test suite on the supported Python boundary versions rather than inferred from
 `uv.lock`. The exact toolchain remains locked for development and release builds. Basedpyright and its