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

{matelab_python_sdk-0.1.0a6 → matelab_python_sdk-0.1.0a8}/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` 为机器权威。
+不要在本文记录阶段性完成状态、一次性验收数字或迁移历史。
 
 ## 权威与范围
 
@@ -62,6 +62,8 @@
 - mutation 默认不自动重试。multipart 或 stream 只有在确认可重放时才能重试；download stream 不自动重放，
   必须支持显式关闭。
 - HTTP/transport、Provider business/authentication、Wire Contract/schema 和 client usage 错误必须稳定区分。
+- 每个公开 `MatelabError` 必须直接提供稳定的集成级 `category` 和保守的 `retryable`；Provider kind 和 HTTP
+  status 只用于诊断，下游不得重新解释 Provider 数字 code 才能决定恢复类别。
 - password、token、SSO code/key、临时附件凭证、原始文件内容和敏感 payload 不得进入日志、异常或提交内容。
 
 ## 测试与质量门槛

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

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.1.0a8 - 2026-08-04
+
+- Adds a unified `MatelabErrorCategory` and conservative `retryable` flag to every public SDK error, centralizing
+  Provider error semantics so integrations no longer reinterpret `MatelabProviderErrorKind`.
+
+## 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.0a8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matelab-python-sdk
-Version: 0.1.0a6
+Version: 0.1.0a8
 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.0a8`. `[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.0a8-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -84,18 +85,29 @@ explicitly when needed, for example `AsyncMatelab("https://custom.example/api")`
 
 ### Error handling
 
-Catch `MatelabError` for one application-level fallback, or a specific subclass when recovery differs:
-
-| Error | Meaning and normal response |
-|---|---|
-| `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. |
-| `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.
+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:
+
+| 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 by `category`, with `kind` available only for diagnosis. |
+| `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 `REJECTED` to `BUSINESS`, `VALIDATION` to `VALIDATION`, and `SERVER` or
+`UNKNOWN` to `UPSTREAM`. `MatelabProviderError.kind` remains a `MatelabProviderErrorKind` diagnostic, but integrations
+do not need it for recovery routing. 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. `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
 
@@ -340,11 +352,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 +360,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 +598,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 +621,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.0a8}/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.0a8`. `[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.0a8-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -58,18 +58,29 @@ explicitly when needed, for example `AsyncMatelab("https://custom.example/api")`
 
 ### Error handling
 
-Catch `MatelabError` for one application-level fallback, or a specific subclass when recovery differs:
-
-| Error | Meaning and normal response |
-|---|---|
-| `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. |
-| `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.
+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:
+
+| 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 by `category`, with `kind` available only for diagnosis. |
+| `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 `REJECTED` to `BUSINESS`, `VALIDATION` to `VALIDATION`, and `SERVER` or
+`UNKNOWN` to `UPSTREAM`. `MatelabProviderError.kind` remains a `MatelabProviderErrorKind` diagnostic, but integrations
+do not need it for recovery routing. 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. `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
 
@@ -314,11 +325,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 +333,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 +571,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 +594,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