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

matelab_python_sdk-0.1.0a22/AGENTS.md

@@ -0,0 +1,52 @@
+# AGENTS.md
+
+本文件只承载每次维护都必须在上下文中的步骤、权威和授权边界。分支规则通过下列指针按需加载。
+
+## 维护顺序
+
+1. **定界**：先读 `git status` 和适用权威；完成标准是任务范围、用户现有改动和所需外部权限均已识别。
+2. **查证**：沿 public intent → wire operation → Provider evidence 核对；完成标准是每个受影响 operation 的
+   request、response、security、examples、成功码及 PVD/PCG 均有结论，Contract 缺口已明确报告。
+3. **收敛**：只修改任务必需的层；完成标准是 public、adapter、generated、tests、coverage 和 docs 的影响均已
+   记账，未加入 Provider 推测、Consumer 私有概念或无真实第二实现的 seam。
+4. **验证**：先跑聚焦测试，再跑适用的完整门槛；完成标准是必需命令全部退出为零，skip 单独说明。
+5. **交付**：复核最终 diff、状态和验证证据；完成标准是结果、限制和未执行项都可由用户独立核对。
+
+## 分支指针
+
+- **SDK architecture**：修改 public 类型、命名、身份空间或模块边界时读
+  [`docs/agent-architecture.md#public-interface`](docs/agent-architecture.md#public-interface)；修改 transport、认证、
+  Session、stream 或错误时读
+  [`docs/agent-architecture.md#transport-session-and-errors`](docs/agent-architecture.md#transport-session-and-errors)。
+- **Contract adoption**：同步 spec tag、snapshot、lock 或生成模型时执行
+  [`docs/agent-workflows.md#contract-adoption`](docs/agent-workflows.md#contract-adoption)。
+- **Delivery gate**：代码、Contract、依赖或构建元数据变化后执行
+  [`docs/agent-workflows.md#delivery-gate`](docs/agent-workflows.md#delivery-gate)。
+- **Provider validation**：任何实时 Provider smoke、读取或 mutation 前执行
+  [`docs/agent-workflows.md#provider-validation`](docs/agent-workflows.md#provider-validation)。
+- **Release**：版本、制品、commit、tag、push 或 publish 任务执行
+  [`docs/agent-workflows.md#release`](docs/agent-workflows.md#release)。
+
+## 权威
+
+| 权威 | 负责内容 |
+| --- | --- |
+| `README.md` | 当前 public interface、集成语义、示例及人类流程 |
+| `CONTEXT.md` | public 类型和命名采用的领域词汇 |
+| `CHANGELOG.md` | SDK 版本变化与迁移影响；不定义当前接口 |
+| `docs/operation-coverage.yaml` | operation 状态、公开入口、稳定性和已知问题 |
+| `pyproject.toml` | SDK 版本、依赖范围、构建与工具配置；`uv.lock` 只锁定本仓库环境 |
+| Contract lock 与 snapshot | Contract pin 与 wire schema |
+| `src/matelab/__init__.py::__all__` | 公开导入边界 |
+
+机器权威变化时，同一变更同步受影响的当前态文档；历史只追加到 `CHANGELOG.md`。测试提供行为证据，不替代
+接口、coverage 或 Contract 权威。
+
+## 范围与授权
+
+- 现有工作区改动属于用户；在其上做最小、可归因的修改。默认只写本仓库，邻接的 spec、Provider 和 Consumer
+  仓库只作只读证据来源。
+- `/home/tnzhu/projects/matelab-spec` 定义 Wire Contract、兼容策略及 Provider 问题；`matelab-server` 是 Provider
+  实现，`matelab-mcp` 只提供 Consumer evidence，均不能反向定义 SDK interface。
+- commit、push、tag、publish、生产访问和真实 Provider mutation 需要本轮明确授权；授权只覆盖用户指定的目标与
+  副作用。

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

@@ -3,6 +3,41 @@
 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.0a22 - 2026-09-03
+
+- Adopts immutable `matelab-spec v0.4.5` at commit `6afac7ff151680130e6e4bc6d95782589b97f4e7` and OpenAPI
+  SHA-256 `31a8d03b4366e2345dfccdbbaaaccf6754b2711428afa4295d778d121988460d`, aligned with Provider source evidence
+  `59eb05b233e5ddd023a60ccb5e5c5f2ae22a70f0` and its verified production-core equivalent.
+- Tightens the private `readRecord` wire model so required `datetime_locked` is a non-negative integer; the Provider
+  normalizes an unavailable lock timestamp to `0`. The public `Record` interface remains unchanged.
+- Retains the root-only `RecordFilesAttachmentAppend` boundary because `UpdateRecordRequest.add[]` still excludes the
+  folder `path` declared by the dedicated staged-name append schema; PVD-044 remains contract-contained.
+
+## 0.1.0a21 - 2026-08-28
+
+- Adopts immutable `matelab-spec v0.4.4` at commit `be070c5f931b2063327a3beaccc53a360204b64e` and OpenAPI
+  SHA-256 `2de38e46d3814b8b049af8afd18e85fb20be6ca29cc409390d25df663abc43f9`, aligned with Provider evidence
+  `7bd9704286057653632424fa82f413d99cd69ab6`.
+- Accepts the required nullable `readRecord.datetime_locked` wire field for current unlocked records and follows the
+  unexposed `/actions/app` rename to `readApplicationBootstrap`; SDK Session identity remains sourced from token issuance.
+- Keeps `RecordFilesAttachmentAppend` root-only. The release describes a safe optional folder path in its dedicated
+  staged-name append schema, but `UpdateRecordRequest.add[]` still references `AddValueOperation`, which forbids that
+  `path`;
+  exposing it would require bypassing whole-request Contract validation. PVD-044 also records that malformed path
+  containers can silently append at root.
+
+## 0.1.0a20 - 2026-08-24
+
+- Adopts immutable `matelab-spec v0.4.3` at commit `7965ac9803505ae35dc5ce36f52afc3c2c133c45` and OpenAPI
+  SHA-256 `6576812dd13f92ad58131f4edb8dc919d1b1fe0f19a695c2d25fbe6d13a8445b`, aligned with Provider evidence
+  `a3e6b961800f6b1ab666f0d3f6cd4c64c2a3ce27`.
+- Breaking: tightens record readback to one canonical attachment object or `null` per table file cell, removing the
+  obsolete attachment-array compatibility path. Template decoding now accepts nullable JSON-code data and preserves
+  empty-string number/boolean cells alongside their scalar and null forms.
+- Records PVD-046 while keeping `templates.save_content()` deliberately narrower than the Provider: the request remains
+  a canonical module list, and every table file cell remains one canonical attachment object or `null`, never an
+  arbitrary or multi-attachment array.
+
 ## 0.1.0a19 - 2026-08-23
 
 - Re-adopts the force-rewritten `matelab-spec v0.4.2` at commit

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matelab-python-sdk
-Version: 0.1.0a19
+Version: 0.1.0a22
 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.0a19`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a22`. `[project].version` in `pyproject.toml` is the sole SDK version source;
 `uv.lock` only mirrors that source.
 
-The SDK is pinned to the rewritten `matelab-spec v0.4.2` Contract Release. The sole release pin is
+The SDK is pinned to the immutable `matelab-spec v0.4.5` 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,14 +64,14 @@ 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.0a19-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a22-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 track the current reviewed Provider at
-`a3e6b961800f6b1ab666f0d3f6cd4c64c2a3ce27`. Provider limitations that remain relevant to integrations are documented
+`59eb05b233e5ddd023a60ccb5e5c5f2ae22a70f0`. Provider limitations that remain relevant to integrations are documented
 alongside the affected interfaces below.
 
 ## Design
@@ -121,7 +121,7 @@ success code it does not allow raises `MatelabProtocolError` rather than assigni
 `MatelabTransportError.status_code` remains available for HTTP failures. Provider response bodies, top-level `msg`,
 legacy `errmsg`, opaque `errs`, uncontracted debug fields, and request payloads are not attached to exceptions because
 Provider-authored diagnostics may contain stack traces, credentials, or submitted values.
-The pinned v0.4.2 Contract also declares optional code-4 `errs`, but PVD-041 and PCG-015 record opaque array/object
+The pinned v0.4.5 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`
@@ -316,8 +316,10 @@ 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; the current Provider does
-not accept a files-folder path (PVD-044):
+other non-conflicting record changes. `RecordFilesAttachmentAppend` currently targets the module root. Although
+v0.4.5 records Provider evidence for safe folder paths, its top-level `UpdateRecordRequest.add[]` schema still excludes
+the `path` property declared by the dedicated staged-name append shape; the SDK therefore does not expose folder paths
+until that wire-schema conflict is resolved (PVD-044):
 
 ```python
 from matelab import RecordAttachmentReplacement, RecordFilesAttachmentAppend, RecordValueUpdate
@@ -348,7 +350,9 @@ await client.records.update(
 
 For a files occurrence, `caption=None` preserves the observed string caption (an observed null caption normalizes to
 the required empty string). Table replacement requires exactly one current attachment in the selected cell and does
-not accept a caption. Both forms require the replacement hash to differ from the current occurrence.
+not accept a caption. Record reads likewise accept only one canonical attachment object or `null` in a table file cell;
+an attachment array violates the pinned response contract. Both replacement forms require the replacement hash to
+differ from the current occurrence.
 
 All record attachment intents reject handles from another notebook or authenticated uploader, duplicate use within one
 finalization request, and raw Provider attachment references. Row/index-based operations use an immediate SDK read and
@@ -425,8 +429,8 @@ and `deletePersonalLiteratureItem`.
 
 Every other implemented operation is explicitly `experimental`; the exact per-operation list and its
 PVD/PCG references live in
-`docs/operation-coverage.yaml`. `resolveCurrentIdentity` is intentionally unexposed because the SDK accepts only
-complete, integration-validated Sessions and does not bind bare external token pairs. `readLiteratureCreateTemplate`
+`docs/operation-coverage.yaml`. `readApplicationBootstrap` is intentionally unexposed because it returns the Provider
+application environment and menu model, while SDK identity is sourced from token issuance. `readLiteratureCreateTemplate`
 is intentionally unexposed because it returns a frontend form definition and an optional deployment flag rather than
 a resource needed by the SDK interface. There are no `planned` operations. Experimental support means the SDK
 validates and exposes the pinned Contract while preserving limitations such as unstable ordering/pagination,
@@ -500,9 +504,12 @@ await client.templates.save_content(template, modules)
 `TemplateModule.data_present` distinguishes a missing `data` property from an explicit null value, while
 `attributes` prevents additive canonical properties from being dropped during a read/save cycle. The SDK does not
 synthesize frontend editor UIDs, layout widths, rows, folders, option encoding, or a fixed set of display module
-types. The Provider supports only whole-content replacement and has no atomic patch or compare-and-swap operation
-(PCG-007), so
-a read-modify-save sequence can overwrite a concurrent change.
+types. A JSON-language code module with style metadata may return its JSON string or explicit `null`; number and boolean
+table cells preserve the Provider's empty string as distinct from scalar and `null` values. The Provider accepts some
+non-canonical module roots and arbitrary table file arrays, but the SDK does not expose that behavior: saved content
+must remain a canonical module list, and a table file cell must be one canonical attachment object or `null` (PVD-046).
+The Provider supports only whole-content replacement and has no atomic patch or compare-and-swap operation (PCG-007),
+so a read-modify-save sequence can overwrite a concurrent change.
 
 The market result retains the Provider's `total_count` and derives `has_more` without echoing the caller's page
 arguments; it does not claim a stable order or continuation token. Template reads remain experimental
@@ -613,8 +620,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. 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.
+password lifecycle remain unexposed. Files-module attachment append remains root-only because the pinned top-level
+update request schema does not admit the dedicated staged-name append shape's folder `path`; malformed path containers
+may also silently append at root according to 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
@@ -912,6 +920,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 the rewritten `matelab-spec v0.4.2`,
-commit `1a4b77721d782fccd2b1f26bcc16a7d876347686`, and OpenAPI SHA-256
-`1e737421aac636356487122ea89e20d54de07c8b9c0651cf6970a7123fe3b72b`.
+byte-identical wheel and source distribution hashes. The release is bound to immutable `matelab-spec v0.4.5`, commit
+`6afac7ff151680130e6e4bc6d95782589b97f4e7`, and OpenAPI SHA-256
+`31a8d03b4366e2345dfccdbbaaaccf6754b2711428afa4295d778d121988460d`.

{matelab_python_sdk-0.1.0a19 → matelab_python_sdk-0.1.0a22}/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.0a19`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a22`. `[project].version` in `pyproject.toml` is the sole SDK version source;
 `uv.lock` only mirrors that source.
 
-The SDK is pinned to the rewritten `matelab-spec v0.4.2` Contract Release. The sole release pin is
+The SDK is pinned to the immutable `matelab-spec v0.4.5` 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,14 +36,14 @@ 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.0a19-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a22-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 track the current reviewed Provider at
-`a3e6b961800f6b1ab666f0d3f6cd4c64c2a3ce27`. Provider limitations that remain relevant to integrations are documented
+`59eb05b233e5ddd023a60ccb5e5c5f2ae22a70f0`. Provider limitations that remain relevant to integrations are documented
 alongside the affected interfaces below.
 
 ## Design
@@ -93,7 +93,7 @@ success code it does not allow raises `MatelabProtocolError` rather than assigni
 `MatelabTransportError.status_code` remains available for HTTP failures. Provider response bodies, top-level `msg`,
 legacy `errmsg`, opaque `errs`, uncontracted debug fields, and request payloads are not attached to exceptions because
 Provider-authored diagnostics may contain stack traces, credentials, or submitted values.
-The pinned v0.4.2 Contract also declares optional code-4 `errs`, but PVD-041 and PCG-015 record opaque array/object
+The pinned v0.4.5 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`
@@ -288,8 +288,10 @@ 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; the current Provider does
-not accept a files-folder path (PVD-044):
+other non-conflicting record changes. `RecordFilesAttachmentAppend` currently targets the module root. Although
+v0.4.5 records Provider evidence for safe folder paths, its top-level `UpdateRecordRequest.add[]` schema still excludes
+the `path` property declared by the dedicated staged-name append shape; the SDK therefore does not expose folder paths
+until that wire-schema conflict is resolved (PVD-044):
 
 ```python
 from matelab import RecordAttachmentReplacement, RecordFilesAttachmentAppend, RecordValueUpdate
@@ -320,7 +322,9 @@ await client.records.update(
 
 For a files occurrence, `caption=None` preserves the observed string caption (an observed null caption normalizes to
 the required empty string). Table replacement requires exactly one current attachment in the selected cell and does
-not accept a caption. Both forms require the replacement hash to differ from the current occurrence.
+not accept a caption. Record reads likewise accept only one canonical attachment object or `null` in a table file cell;
+an attachment array violates the pinned response contract. Both replacement forms require the replacement hash to
+differ from the current occurrence.
 
 All record attachment intents reject handles from another notebook or authenticated uploader, duplicate use within one
 finalization request, and raw Provider attachment references. Row/index-based operations use an immediate SDK read and
@@ -397,8 +401,8 @@ and `deletePersonalLiteratureItem`.
 
 Every other implemented operation is explicitly `experimental`; the exact per-operation list and its
 PVD/PCG references live in
-`docs/operation-coverage.yaml`. `resolveCurrentIdentity` is intentionally unexposed because the SDK accepts only
-complete, integration-validated Sessions and does not bind bare external token pairs. `readLiteratureCreateTemplate`
+`docs/operation-coverage.yaml`. `readApplicationBootstrap` is intentionally unexposed because it returns the Provider
+application environment and menu model, while SDK identity is sourced from token issuance. `readLiteratureCreateTemplate`
 is intentionally unexposed because it returns a frontend form definition and an optional deployment flag rather than
 a resource needed by the SDK interface. There are no `planned` operations. Experimental support means the SDK
 validates and exposes the pinned Contract while preserving limitations such as unstable ordering/pagination,
@@ -472,9 +476,12 @@ await client.templates.save_content(template, modules)
 `TemplateModule.data_present` distinguishes a missing `data` property from an explicit null value, while
 `attributes` prevents additive canonical properties from being dropped during a read/save cycle. The SDK does not
 synthesize frontend editor UIDs, layout widths, rows, folders, option encoding, or a fixed set of display module
-types. The Provider supports only whole-content replacement and has no atomic patch or compare-and-swap operation
-(PCG-007), so
-a read-modify-save sequence can overwrite a concurrent change.
+types. A JSON-language code module with style metadata may return its JSON string or explicit `null`; number and boolean
+table cells preserve the Provider's empty string as distinct from scalar and `null` values. The Provider accepts some
+non-canonical module roots and arbitrary table file arrays, but the SDK does not expose that behavior: saved content
+must remain a canonical module list, and a table file cell must be one canonical attachment object or `null` (PVD-046).
+The Provider supports only whole-content replacement and has no atomic patch or compare-and-swap operation (PCG-007),
+so a read-modify-save sequence can overwrite a concurrent change.
 
 The market result retains the Provider's `total_count` and derives `has_more` without echoing the caller's page
 arguments; it does not claim a stable order or continuation token. Template reads remain experimental
@@ -585,8 +592,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. 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.
+password lifecycle remain unexposed. Files-module attachment append remains root-only because the pinned top-level
+update request schema does not admit the dedicated staged-name append shape's folder `path`; malformed path containers
+may also silently append at root according to 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
@@ -884,6 +892,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 the rewritten `matelab-spec v0.4.2`,
-commit `1a4b77721d782fccd2b1f26bcc16a7d876347686`, and OpenAPI SHA-256
-`1e737421aac636356487122ea89e20d54de07c8b9c0651cf6970a7123fe3b72b`.
+byte-identical wheel and source distribution hashes. The release is bound to immutable `matelab-spec v0.4.5`, commit
+`6afac7ff151680130e6e4bc6d95782589b97f4e7`, and OpenAPI SHA-256
+`31a8d03b4366e2345dfccdbbaaaccf6754b2711428afa4295d778d121988460d`.

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

@@ -2,12 +2,12 @@
   "schema_version": 1,
   "contract_line": "integration-v1",
   "release": {
-    "tag": "v0.4.2",
-    "commit": "1a4b77721d782fccd2b1f26bcc16a7d876347686"
+    "tag": "v0.4.5",
+    "commit": "6afac7ff151680130e6e4bc6d95782589b97f4e7"
   },
   "openapi": {
     "source_path": "openapi/matelab-integration-v1.openapi.yaml",
     "snapshot": "matelab-integration-v1.openapi.yaml",
-    "sha256": "1e737421aac636356487122ea89e20d54de07c8b9c0651cf6970a7123fe3b72b"
+    "sha256": "31a8d03b4366e2345dfccdbbaaaccf6754b2711428afa4295d778d121988460d"
   }
 }