matelab-python-sdk 0.1.0a21__tar.gz → 0.1.0a23__tar.gz

matelab_python_sdk-0.1.0a23/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.0a21 → matelab_python_sdk-0.1.0a23}/CHANGELOG.md

@@ -3,6 +3,22 @@
 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.0a23 - 2026-09-04
+
+- Temporarily accepts `readRecord` table file attachments that contain valid `filename`, `hash`, and `size` fields but
+  omit the Contract-required `timestamp`. The SDK preserves the omission instead of synthesizing a timestamp; explicit
+  null timestamps and other malformed attachment values remain rejected.
+
+## 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

{matelab_python_sdk-0.1.0a21 → matelab_python_sdk-0.1.0a23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matelab-python-sdk
-Version: 0.1.0a21
+Version: 0.1.0a23
 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.0a21`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a23`. `[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.4` 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.0a21-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a23-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
-`7bd9704286057653632424fa82f413d99cd69ab6`. 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.4 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`
@@ -317,7 +317,7 @@ 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` currently targets the module root. Although
-v0.4.4 records Provider evidence for safe folder paths, its top-level `UpdateRecordRequest.add[]` schema still excludes
+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):
 
@@ -354,6 +354,12 @@ not accept a caption. Record reads likewise accept only one canonical attachment
 an attachment array violates the pinned response contract. Both replacement forms require the replacement hash to
 differ from the current occurrence.
 
+As a temporary Provider-compatibility exception, `records.read()` also accepts a table file attachment object whose
+otherwise valid `filename`, `hash`, and `size` are present but whose Contract-required `timestamp` is omitted. The SDK
+preserves that omission in `Record.modules` and does not invent a timestamp; null timestamps and all other malformed
+attachment shapes remain response errors. This exception can be removed after the Provider canonicalizes current and
+historical record content.
+
 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
 must not be called while a concurrent editor is known to be active. The Provider offers no expected hash or revision,
@@ -920,6 +926,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 immutable `matelab-spec v0.4.4`, commit
-`be070c5f931b2063327a3beaccc53a360204b64e`, and OpenAPI SHA-256
-`2de38e46d3814b8b049af8afd18e85fb20be6ca29cc409390d25df663abc43f9`.
+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.0a21 → matelab_python_sdk-0.1.0a23}/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.0a21`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a23`. `[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.4` 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.0a21-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a23-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
-`7bd9704286057653632424fa82f413d99cd69ab6`. 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.4 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`
@@ -289,7 +289,7 @@ 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` currently targets the module root. Although
-v0.4.4 records Provider evidence for safe folder paths, its top-level `UpdateRecordRequest.add[]` schema still excludes
+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):
 
@@ -326,6 +326,12 @@ not accept a caption. Record reads likewise accept only one canonical attachment
 an attachment array violates the pinned response contract. Both replacement forms require the replacement hash to
 differ from the current occurrence.
 
+As a temporary Provider-compatibility exception, `records.read()` also accepts a table file attachment object whose
+otherwise valid `filename`, `hash`, and `size` are present but whose Contract-required `timestamp` is omitted. The SDK
+preserves that omission in `Record.modules` and does not invent a timestamp; null timestamps and all other malformed
+attachment shapes remain response errors. This exception can be removed after the Provider canonicalizes current and
+historical record content.
+
 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
 must not be called while a concurrent editor is known to be active. The Provider offers no expected hash or revision,
@@ -892,6 +898,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 immutable `matelab-spec v0.4.4`, commit
-`be070c5f931b2063327a3beaccc53a360204b64e`, and OpenAPI SHA-256
-`2de38e46d3814b8b049af8afd18e85fb20be6ca29cc409390d25df663abc43f9`.
+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.0a21 → matelab_python_sdk-0.1.0a23}/contracts/matelab-integration-v1.lock.json

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

{matelab_python_sdk-0.1.0a21 → matelab_python_sdk-0.1.0a23}/contracts/matelab-integration-v1.openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: Matelab Integration Contract
-  version: 0.4.4
+  version: 0.4.5
   description: |
     Current PHP wire contract for generating SDKs against the selected
     `matelab-server` Provider version.
@@ -9,7 +9,12 @@ info:
   x-contract-line: integration-v1
   x-provider-evidence:
     repository: /home/tnzhu/projects/matelab-server
-    commit: 7bd9704286057653632424fa82f413d99cd69ab6
+    commit: 59eb05b233e5ddd023a60ccb5e5c5f2ae22a70f0
+    productionRuntime:
+      source: /home/elnhr/matelab
+      workerStartedAt: "2026-09-02T08:11:00+08:00"
+      coreEquivalentCommit: 86c57f60aa66bf794d6227c77d1d483b3ea8c271
+      comparison: crlf-insensitive-core-tree
     files:
       - controller/Actions.php
       - controller/Tokens.php
@@ -34,13 +39,16 @@ info:
       - lib/Route.php
       - lib/HttpServer.php
       - lib/MultiException.php
+      - config/Db.php
       - config/Channel.php
       - sql/eln.sql
       - sql/matelab.sql
       - sql/recommend.sql
   x-provider-audit:
-    currentCommit: 7bd9704286057653632424fa82f413d99cd69ab6
-    previousReleaseEvidenceCommit: a3e6b961800f6b1ab666f0d3f6cd4c64c2a3ce27
+    currentCommit: 59eb05b233e5ddd023a60ccb5e5c5f2ae22a70f0
+    productionRuntimeCoreEquivalentCommit: 86c57f60aa66bf794d6227c77d1d483b3ea8c271
+    previousReleaseEvidenceCommit: 7bd9704286057653632424fa82f413d99cd69ab6
+    lastProviderVerifiedCommit: 59eb05b233e5ddd023a60ccb5e5c5f2ae22a70f0
     contractStatus: current-provider-aligned
     incorporatedChanges:
       - {operationId: stageTemporaryFile, change: staging-identifiers-expanded-to-100}
@@ -52,7 +60,7 @@ info:
       - {operationId: updateRecordData, change: safe-files-folder-path-restored-to-callable-shape}
       - {operationId: readApplicationBootstrap, change: identity-and-notifications-moved-out-of-app-response}
       - {operationId: readRecord, change: table-file-cell-readback-modeled-as-attachment-object-or-null}
-      - {operationId: readRecord, change: current-unlocked-datetime-locked-may-be-null}
+      - {operationId: readRecord, change: missing-datetime-locked-normalized-to-zero}
       - {operationId: readTemplateContent, change: json-code-null-readback-accepted}
       - {operationId: saveTemplateContent, change: empty-number-and-boolean-cells-preserved}
       - {operationId: saveTemplateContent, change: noncanonical-module-structures-contract-contained}
@@ -2568,7 +2576,7 @@ paths:
                     uid: REC-EXAMPLE-001
                     current_version: 70001
                     item_id: 9001
-                    datetime_locked: null
+                    datetime_locked: 0
                     locked: false
                     signs: []
                     signed: false
@@ -6527,12 +6535,9 @@ components:
               type: integer
               minimum: 1
             datetime_locked:
-              type: [integer, "null"]
+              type: integer
               minimum: 0
-              description: |
-                Unix timestamp in milliseconds; null for the current unlocked
-                record. Provider paths that normalize the absent timestamp may
-                return zero.
+              description: Unix timestamp in milliseconds; zero when no lock timestamp is available.
             locked:
               type: boolean
             signs:

matelab_python_sdk-0.1.0a23/docs/agent-architecture.md

@@ -0,0 +1,28 @@
+# SDK Architecture Invariants
+
+本文件按 `AGENTS.md` 的 architecture 指针加载；只记录环境和配置无法直接表达的设计边界。
+
+## Public interface
+
+- 本项目是 Matelab Integration Contract 的通用异步 Python Consumer，负责隐藏 HTTP 编码、认证刷新、业务错误、
+  wire model 和 Provider 兼容细节。
+- `AsyncMatelab` 是稳定入口。public interface 表达用户意图，并隐藏 controller、path、opcode、wire 字段、
+  generated model 和认证刷新细节。
+- 公共类型区分 userid、database id、UID、relation id、staging id 等身份空间。只表达 Provider 实际返回的
+  identity、affected rows、排序、分页、原子性、CAS、幂等性和持久化结果。
+- MCP typed refs、capabilities、fingerprints、FastMCP/Redis context 与 Agent 展示模型留在 Consumer。只有真实
+  第二种实现才能引入 seam。
+- 支持 Python 3.11+；源码不使用 `from __future__ import annotations`，前向引用优先靠定义顺序解决。
+
+## Transport, Session, and errors
+
+- `base_url` 是 Provider API 根；query、JSON、form、multipart、streaming、bearer 和成功码逐 operation 配置。
+- `Token`、`Identity`、`Session` 是冻结且拒绝额外字段的 public model，组成规范化 Session JSON。每个
+  `AsyncMatelab` 最多持有一个最新 Session；SDK 不绑定裸 token。不同逻辑 Session 使用不同 client，可共享注入的
+  `httpx2.AsyncClient`。
+- SDK 负责 bearer 注入、到期前刷新、单锁并发刷新和明确允许的单次 code-5 replay。集成方负责 Session
+  持久化、加密、撤销、身份归属和跨进程锁；mutation 默认不重试，multipart/stream 仅在可重放时重试。
+- token 在 repr 中隐藏；显式 Session JSON 保留凭证。日志、异常和提交内容排除凭证、SSO 参数、附件内容及
+  敏感 payload。download stream 必须可显式关闭。
+- transport、Provider business/authentication、Contract/schema 与 usage 错误保持稳定区分；公开错误提供集成级
+  `category` 和保守的 `retryable`，下游不重新解释 Provider 数字 code。

matelab_python_sdk-0.1.0a23/docs/agent-workflows.md

@@ -0,0 +1,76 @@
+# Agent Maintenance Workflows
+
+本文件只在对应分支触发时加载。机器值始终从仓库读取；这里记录顺序、授权边界和完成标准。
+
+## Contract adoption
+
+1. 读取当前工作区、Contract lock 和远端 release refs。只选择新的 annotated tag；移动分支和改写后的旧
+   snapshot 不能成为 SDK pin。记录 tag object、peeled commit、OpenAPI path 与 SHA-256。完成标准：四者固定且
+   互相一致。
+2. 比较当前 snapshot 与 release commit。逐项核对 operation request、response、security、examples、成功码、
+   Provider evidence 及 PVD/PCG。完成标准：每个 schema/operation 差异都分类为 generated-only、adapter、public
+   interface、test、coverage 或 docs 影响。
+3. request/response 均由生成 wire model 校验，adapter 只映射 public Python 名称与 wire 字段。required nullable
+   使用无默认值的 `T | None`；request 拒绝未知字段，response 接受新增字段。若专用 schema、顶层 request 或
+   Provider evidence 相互矛盾，保留当前安全边界并报告缺口。
+4. 从 release commit 复制 OpenAPI snapshot；同一变更更新 lock 的 tag、commit、snapshot path 和 SHA-256，运行
+   生成脚本并审查完整 generated diff。`_generated` 只由生成脚本修改；projection 只补偿生成器表达能力并保留
+   inherited required、`if/then`、`oneOf`、`anyOf` 和 `not`。完成标准：snapshot hash 与 lock 相等，生成差异
+   全部可由 OpenAPI 差异解释，`--check` 确定、非写入且能发现 stale output。
+5. 同步 runtime、测试、operation coverage、README、CHANGELOG、`pyproject.toml` 与 `uv.lock` 中受影响的当前态。
+   完成标准：每个 Contract 差异都有实现或明确 containment，历史 changelog 未被改写。
+6. 执行 [delivery gate](#delivery-gate)。
+
+## Delivery gate
+
+先运行改动对应的聚焦测试。新增或修改 operation 覆盖 method/path/encoding、认证、成功映射及适用的空结果、
+required nullable 和 additive response fields；operation coverage 与 pinned OpenAPI exact match，implemented
+operation 同时具备 public interface、wire adapter 和测试。删除或收紧 public interface 时同步移除过时测试，
+不保留无承诺的墓碑 alias。生成测试覆盖 metadata/checksum、schema、required/nullable、extra policy、确定性和
+stale detection。
+
+Ruff/Basedpyright 诊断通过修复代码或精确 ignore 解决，不缩小检查范围；Basedpyright 目标为 0 errors / 0 warnings。
+依赖变化声明已验证下限并排除未经验证的下一 major，构建后端范围与 wheel package 显式配置。
+
+交付代码、Contract、依赖或构建元数据前，依次完成：
+
+```bash
+uv sync --frozen
+uv run python scripts/generate_models.py --check
+uv run ruff check .
+uv run ruff format --check .
+uv run basedpyright
+uv run pytest
+uv build --no-build-isolation
+```
+
+若沙箱导致缓存、Node wheel 或解释器发现失败，在沙箱外复核同一锁定命令。完成标准：所有命令退出为零；skip
+按测试名称和原因报告，不能计为通过；最终 `git diff --check` 无错误，最终 diff 只包含任务范围内文件。
+
+## Provider validation
+
+1. 默认使用 pinned examples、`MockTransport` 和 SDK adapter tests。Provider smoke 默认 skip 且不自动读取
+   `.env`；实时 Provider 只在当前任务确实需要且本轮已明确授权时启用。
+2. 执行前确认目标是隔离服务、`.env.test` 处于 Git ignore、命令显式加载该文件，并列出 authentication、refresh、
+   mutation 或带写痕迹读取的副作用。生产目标或 mutation 需要本轮单独明确授权。
+3. SDK public smoke 使用 README 的 `Opt-in Provider consumer smoke` 命令；route-by-route conformance 由
+   `matelab-spec` Provider Verification 负责。两者的结果分开报告。
+4. mutation 场景在写前记录 fixture，在写后回读，并尽力清理。完成标准：目标、Provider commit、命令、通过数、
+   skip/failure 和清理结果均可追溯；凭证及敏感 payload 未进入输出或提交。
+
+## Release
+
+1. 只有用户明确要求 commit、push、tag 或 publish 时进入发布流程。读取 `[project].version`，确认版本未发布、
+   changelog 已追加且 Contract pin 完整。SDK 遵循 SemVer；公开接口删除、重命名、类型收紧或行为变化按 breaking
+   change 处理，Contract Line 不充当 SDK 版本。完成标准：版本、文档和 tag 名 `v{version}` 一致。
+2. 在完整 delivery gate 通过后创建单一 release commit。完成标准：tracked worktree 干净，commit 仅包含已审查
+   diff。
+3. 以 release commit 的 committer timestamp 设置 `SOURCE_DATE_EPOCH`，从锁定环境构建两次并逐字节比较 wheel
+   与 sdist；运行 `scripts/check_release.py`，再从 wheel 验证公开导入和类型消费。完成标准：制品可复现，
+   Apache-2.0 `LICENSE`/`NOTICE`、PEP 639 METADATA、`py.typed` 与公开边界审计通过，`_generated` 未公开，
+   checksum 已记录。
+4. 创建指向 release commit 的 annotated `v{version}` tag。先推送 `origin` 的 main/tag，再推送 GitHub mirror 的
+   main/tag；只有与项目版本完全匹配的 tag 触发 Trusted Publishing workflow，第三方 Action 固定 immutable
+   commit SHA。
+5. 跟踪 CI 的 Python 边界测试、生成检查、可复现构建、安装后消费和 PyPI publish。完成标准：两个远端 main/tag
+   都指向 release commit，workflow success，PyPI 对应版本可读取，本地 tracked worktree 干净。

{matelab_python_sdk-0.1.0a21 → matelab_python_sdk-0.1.0a23}/docs/operation-coverage.yaml

@@ -3,7 +3,7 @@
 schema_version: 1
 contract:
   line: integration-v1
-  release: v0.4.4
+  release: v0.4.5
   operation_count: 71
 
 operations:

{matelab_python_sdk-0.1.0a21 → matelab_python_sdk-0.1.0a23}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "matelab-python-sdk"
-version = "0.1.0a21"
+version = "0.1.0a23"
 description = "Reusable async Python client for the Matelab Integration Contract"
 readme = "README.md"
 requires-python = ">=3.11"

{matelab_python_sdk-0.1.0a21 → matelab_python_sdk-0.1.0a23}/src/matelab/_generated/models.py

@@ -11,7 +11,7 @@ from pydantic import ConfigDict, Field, RootModel, SecretStr, StrictBool, Strict
 
 from matelab._wire_validation import WireModel
 
-OPENAPI_INFO_VERSION = "0.4.4"
+OPENAPI_INFO_VERSION = "0.4.5"
 
 
 class ResponseEnvelope(WireModel):
@@ -3741,12 +3741,9 @@ class ItemViewResponse(WireModel):
     """
     current_version: Annotated[StrictInt, Field(ge=0)]
     item_id: Annotated[StrictInt, Field(ge=1)]
-    datetime_locked: Annotated[StrictInt | None, Field(ge=0)]
+    datetime_locked: Annotated[StrictInt, Field(ge=0)]
     """
-    Unix timestamp in milliseconds; null for the current unlocked
-    record. Provider paths that normalize the absent timestamp may
-    return zero.
-
+    Unix timestamp in milliseconds; zero when no lock timestamp is available.
     """
     locked: StrictBool
     signs: list[RecordSignature]

{matelab_python_sdk-0.1.0a21 → matelab_python_sdk-0.1.0a23}/src/matelab/domains/records.py

@@ -1,13 +1,14 @@
 import re
 import secrets
 from collections.abc import AsyncIterable, Iterable, Iterator, Mapping, Sequence
+from copy import deepcopy
 from dataclasses import dataclass, field
 from html.parser import HTMLParser
 from types import MappingProxyType
-from typing import IO, Literal, TypeAlias, cast
+from typing import IO, Literal, Self, TypeAlias, cast
 from urllib.parse import unquote
 
-from pydantic import BaseModel, JsonValue
+from pydantic import BaseModel, JsonValue, model_validator
 from typing_extensions import override
 
 from matelab._generated import models as wire_models
@@ -21,6 +22,56 @@ from matelab.domains.users import UserRef
 from matelab.errors import MatelabProtocolError, MatelabUsageError
 from matelab.streaming import ByteRange, DownloadStream
 
+_MISSING_TIMESTAMP_MARKER = "__matelab_missing_record_attachment_timestamp__"
+
+
+def _table_file_attachments(modules: JsonValue) -> Iterator[dict[str, JsonValue]]:
+    if not isinstance(modules, list):
+        return
+    for module in modules:
+        if not isinstance(module, dict) or module.get("type") != "table":
+            continue
+        columns = module.get("data")
+        if not isinstance(columns, list):
+            continue
+        for column in columns:
+            if not isinstance(column, dict) or column.get("type") != "file":
+                continue
+            values = column.get("data")
+            if not isinstance(values, list):
+                continue
+            for value in values:
+                if isinstance(value, dict):
+                    yield value
+
+
+class _ReadRecordResponse(wire_models.ItemViewResponse):
+    """Contain the Provider's temporary omission of stored attachment timestamps."""
+
+    @model_validator(mode="before")
+    @classmethod
+    def _allow_missing_attachment_timestamp(cls, value: object) -> object:
+        if not isinstance(value, dict):
+            return value
+        payload = deepcopy(cast(dict[str, JsonValue], value))
+        modules = payload.get("modules")
+        if modules is None:
+            return payload
+        for attachment in _table_file_attachments(modules):
+            if "timestamp" not in attachment and _MISSING_TIMESTAMP_MARKER not in attachment:
+                attachment["timestamp"] = 1
+                attachment[_MISSING_TIMESTAMP_MARKER] = True
+        return payload
+
+    @model_validator(mode="after")
+    def _restore_missing_attachment_timestamp(self) -> Self:
+        modules: JsonValue = [{"type": module.type, "data": cast(JsonValue, module.data)} for module in self.modules]
+        for attachment in _table_file_attachments(modules):
+            if attachment.pop(_MISSING_TIMESTAMP_MARKER, None) is True:
+                del attachment["timestamp"]
+        return self
+
+
 _LIST_RECORDS = Operation(
     method="POST",
     path="/eln_api/items",
@@ -68,7 +119,7 @@ _READ_RECORD = Operation(
     method="GET",
     path="/eln_items/item_view",
     encoding=Encoding.QUERY,
-    response_model=wire_models.ItemViewResponse,
+    response_model=_ReadRecordResponse,
     success_codes=frozenset({0}),
     retry_on_access_expired=True,
 )

{matelab_python_sdk-0.1.0a21 → matelab_python_sdk-0.1.0a23}/tests/test_generation.py

@@ -88,7 +88,7 @@ def test_generated_response_preserves_required_nullable_fields() -> None:
             "uid": None,
             "current_version": 0,
             "item_id": 1,
-            "datetime_locked": None,
+            "datetime_locked": 0,
             "locked": False,
             "signs": [],
             "signed": False,
@@ -107,7 +107,12 @@ def test_generated_response_preserves_required_nullable_fields() -> None:
     assert ItemViewResponse.model_fields["keywords"].is_required()
     assert response.keywords is None
     assert ItemViewResponse.model_fields["datetime_locked"].is_required()
-    assert response.datetime_locked is None
+    assert response.datetime_locked == 0
+
+    invalid = response.model_dump(mode="json")
+    invalid["datetime_locked"] = None
+    with pytest.raises(ValidationError):
+        _ = ItemViewResponse.model_validate(invalid)
 
 
 def _item_view_payload(modules: list[object]) -> dict[str, object]:
@@ -523,7 +528,7 @@ def test_generated_models_cover_every_component_schema_and_non_streaming_operati
     }
     assert expected_response_models <= class_names
     assert len(operation_ids) == 71
-    assert wire_models.OPENAPI_INFO_VERSION == "0.4.4"
+    assert wire_models.OPENAPI_INFO_VERSION == "0.4.5"
 
 
 def test_generation_is_deterministic(tmp_path: Path) -> None:
@@ -635,8 +640,8 @@ def test_contract_lock_is_the_single_release_pin() -> None:
     openapi = cast(dict[str, Any], lock["openapi"])
     assert set(release) == {"tag", "commit"}
     assert set(openapi) == {"source_path", "snapshot", "sha256"}
-    assert release == {"tag": "v0.4.4", "commit": "be070c5f931b2063327a3beaccc53a360204b64e"}
-    assert openapi["sha256"] == "2de38e46d3814b8b049af8afd18e85fb20be6ca29cc409390d25df663abc43f9"
+    assert release == {"tag": "v0.4.5", "commit": "6afac7ff151680130e6e4bc6d95782589b97f4e7"}
+    assert openapi["sha256"] == "31a8d03b4366e2345dfccdbbaaaccf6754b2711428afa4295d778d121988460d"
     assert re.fullmatch(r"[0-9a-f]{40}", cast(str, release["commit"]))
     assert re.fullmatch(r"[0-9a-f]{64}", cast(str, openapi["sha256"]))
     assert not (ROOT / "contracts" / "matelab-integration-v1.sha256").exists()

{matelab_python_sdk-0.1.0a21 → matelab_python_sdk-0.1.0a23}/tests/test_records.py

@@ -243,7 +243,7 @@ async def test_read_current_record_maps_required_nullable_and_open_modules() ->
                 uid="REC-EXAMPLE-001",
                 current_version=70001,
                 item_id=9001,
-                datetime_locked=None,
+                datetime_locked=0,
                 locked=False,
                 signs=[
                     {
@@ -303,6 +303,77 @@ async def test_read_current_record_maps_required_nullable_and_open_modules() ->
     assert "74034dae" not in repr(record.attachments[0])
 
 
+@pytest.mark.asyncio
+async def test_read_tolerates_provider_table_attachment_without_timestamp() -> None:
+    payload = _item_view_payload(uid="REC-EXAMPLE-001")
+    attachment = {
+        "hash": "d6a8f491a743ee3c10b42b4519d7545d7f1d79a7e98ed2ef9c03c0c1d75a1a91",
+        "filename": "evidence.pdf",
+        "size": 34,
+    }
+    payload["modules"] = [
+        {
+            "type": "table",
+            "name": "Data sheet",
+            "rows": ["row-1"],
+            "data": [{"name": "File", "type": "file", "data": [attachment]}],
+        }
+    ]
+
+    async def handler(_: Request) -> Response:
+        return Response(200, json=payload)
+
+    notebook = NotebookRef(notebook_id=23, title="Shared Example", owner_userid=202, scope="shared")
+    source = RecordLocator(notebook=notebook, record=RecordRef(record_id=9001, record_uid="REC-EXAMPLE-001"))
+    async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
+        client = AsyncMatelab("https://ignored.example", session=_session(), http_client=http_client)
+        record = await client.records.read(source)
+
+    assert record.modules[0] == {
+        "name": "Data sheet",
+        "type": "table",
+        "data": [{"name": "File", "type": "file", "data": [attachment]}],
+        "language": None,
+        "style": None,
+        "rows": ["row-1"],
+    }
+    assert [(item.filename, item.size) for item in record.attachments] == [("evidence.pdf", 34)]
+
+
+@pytest.mark.parametrize("invalid_change", ["filename", "hash", "size", "null_timestamp"])
+@pytest.mark.asyncio
+async def test_read_timestamp_compatibility_does_not_relax_other_attachment_requirements(invalid_change: str) -> None:
+    payload = _item_view_payload(uid="REC-EXAMPLE-001")
+    attachment: dict[str, object] = {
+        "hash": "d6a8f491a743ee3c10b42b4519d7545d7f1d79a7e98ed2ef9c03c0c1d75a1a91",
+        "filename": "evidence.pdf",
+        "size": 34,
+        "timestamp": 1_767_946_200_000,
+    }
+    if invalid_change == "null_timestamp":
+        attachment["timestamp"] = None
+    else:
+        del attachment[invalid_change]
+    payload["modules"] = [
+        {
+            "type": "table",
+            "name": "Data sheet",
+            "rows": ["row-1"],
+            "data": [{"name": "File", "type": "file", "data": [attachment]}],
+        }
+    ]
+
+    async def handler(_: Request) -> Response:
+        return Response(200, json=payload)
+
+    notebook = NotebookRef(notebook_id=23, title="Shared Example", owner_userid=202, scope="shared")
+    source = RecordLocator(notebook=notebook, record=RecordRef(record_id=9001, record_uid="REC-EXAMPLE-001"))
+    async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
+        client = AsyncMatelab("https://ignored.example", session=_session(), http_client=http_client)
+        with pytest.raises(MatelabProtocolError, match="does not match the Integration Contract"):
+            _ = await client.records.read(source)
+
+
 @pytest.mark.asyncio
 async def test_read_rejects_historical_table_attachment_array_at_public_boundary() -> None:
     payload = _item_view_payload(uid="REC-EXAMPLE-001")

{matelab_python_sdk-0.1.0a21 → matelab_python_sdk-0.1.0a23}/uv.lock

@@ -352,7 +352,7 @@ wheels = [
 
 [[package]]
 name = "matelab-python-sdk"
-version = "0.1.0a21"
+version = "0.1.0a23"
 source = { editable = "." }
 dependencies = [
     { name = "httpx2" },

matelab_python_sdk-0.1.0a21/AGENTS.md

@@ -1,94 +0,0 @@
-# AGENTS.md
-
-本文档只保留维护 `matelab-python-sdk` 必须长期遵守的约束，不记录当前功能清单、迁移历史、阶段性状态或
-一次性验收数字。
-
-## 文档与权威边界
-
-- `README.md`：当前 public interface、集成语义、示例及可执行的开发/发布流程；不承担版本迁移历史。
-- `CONTEXT.md`：公共领域术语及易混概念的统一词汇；不记录实现或协议细节。
-- `CHANGELOG.md`：按 SDK 版本记录变化和迁移影响；不作为当前接口说明。
-- `docs/operation-coverage.yaml`：operation 状态、公开入口、稳定性和已知问题的机器权威；不写叙述性用法。
-- `pyproject.toml`：SDK 版本、依赖范围、构建和工具配置的机器权威；`uv.lock` 只锁定本仓库环境。
-- `contracts/matelab-integration-v1.lock.json` 及其 snapshot：Contract pin 和 wire schema 的唯一机器权威。
-- `src/matelab/__init__.py::__all__`：公开导入边界；测试是行为证据，不替代上述文档。
-- 本文件只规定维护原则和质量门槛。机器权威变化时，同一变更必须同步受影响的叙述文档，避免复制无归属的
-  版本号、配置值或 operation 清单。
-
-## 工作范围与 public interface
-
-- 本项目是 Matelab Integration Contract 的通用异步 Python Consumer，负责隐藏 HTTP 编码、认证刷新、业务
-  错误、wire model 和 Provider 兼容细节。
-- `/home/tnzhu/projects/matelab-spec` 负责 Wire Contract、兼容策略及 Provider 问题；`matelab-server` 是 Provider
-  实现，`matelab-mcp` 只是 Consumer 证据，均不能反向定义 SDK interface。
-- 修改前执行 `git status`，现有改动视为用户工作。默认只修改本仓库；未经明确授权，不修改相邻仓库、不迁移
-  MCP、不 commit/push/tag/publish，也不对真实 Provider 执行 mutation。
-- `AsyncMatelab` 是稳定入口，能力按领域组织。public interface 只表达用户意图，不泄漏 controller、path、
-  opcode、wire 字段、generated model 或认证刷新细节。
-- 公共类型必须区分 userid、database id、UID、relation id、staging id 等身份空间。Provider 未返回的 identity、
-  affected rows、排序、分页、原子性、CAS、幂等性或持久化结果不得推测；legacy 限制应诚实表达。
-- MCP typed refs、capabilities、fingerprints、FastMCP/Redis context 和 Agent 展示模型不得进入 SDK。仅在存在真实
-  第二种实现时增加 seam，不为测试预设抽象。
-- 支持 Python 3.11+；源码不使用 `from __future__ import annotations`，前向引用优先通过定义顺序解决。
-
-## Contract、生成与 transport
-
-- 每个 operation 必须核对 pinned OpenAPI 的 request、response、security、examples 和成功码，并查看相关
-  PVD/PCG。Contract 不足时可只读参考 Provider/Consumer；仍无法安全表达就报告缺口，不猜测或静默适配漂移。
-- Contract Adoption 只能来自不可变 release tag，并在同一变更中更新唯一 lock 的 tag、commit、snapshot path
-  和 SHA-256，重新生成并复核差异；不得跟踪移动分支或改写正式 snapshot。
-- request/response 均由生成 wire model 校验，adapter 只负责 public Python 名称与 wire 字段映射。required
-  nullable 使用无默认值的 `T | None`；request 拒绝未知字段，response 兼容新增字段。
-- 不手工编辑 `_generated`。generation projection 只能补偿生成器表达能力，并保留 inherited required 及
-  `if/then`、`oneOf`、`anyOf`、`not`；生成变化必须可追溯，`--check` 必须确定、非写入且能发现 stale output。
-- `base_url` 是 Provider API 根；query、JSON、form、multipart、streaming、bearer 和成功码均按 operation 配置，
-  不能用全局默认掩盖差异。
-- `Token`、`Identity` 和 `Session` 是冻结、拒绝额外字段的 public model，组成规范化 Session JSON。每个
-  `AsyncMatelab` 最多持有一个最新 Session；SDK 不绑定裸 token，持久化、加密、撤销、身份归属和跨进程锁
-  属于集成方。不同逻辑 Session 不共享 client，但可共享注入的 `httpx.AsyncClient`。
-- token 在 repr 中隐藏，显式 Session JSON 保留凭证；凭证、SSO 参数、附件内容及敏感 payload 不得进入日志、
-  异常或提交内容。
-- access 到期前刷新；并发刷新使用单锁；安全请求遇到 `code=5` 最多刷新重试一次。mutation 默认不重试，
-  multipart/stream 仅在可重放时重试，download stream 必须可显式关闭。
-- transport、Provider business/authentication、Contract/schema 和 usage 错误必须稳定区分；公开错误直接提供
-  集成级 `category` 和保守的 `retryable`，下游不应重新解释 Provider 数字 code。
-
-## 测试与质量门槛
-
-- 测试以 public interface 为主。新增或修改 operation 至少覆盖 method/path/encoding、认证、成功映射及适用的
-  空结果、required nullable、additive response fields；通用 transport/auth/error 语义在集中测试中覆盖。
-- 删除或收紧 public interface 时同步删除过时测试；无明确兼容承诺时不保留墓碑 alias 或测试。
-- operation coverage 必须与 pinned OpenAPI exact match；implemented operation 必须同时具备 public interface、
-  wire adapter 和测试。生成测试必须覆盖 metadata/checksum、schema、required/nullable、extra policy、确定性和
-  stale detection。
-- Provider smoke 默认 skip 且不自动读取 `.env`；本地 `.env.test` 必须保持 Git ignore。只能通过显式
-  `uv run --env-file .env.test` 对已确认的隔离目标 opt in；生产目标、mutation 或带写痕迹的读取必须获得本轮
-  明确授权，并回读、尽力清理。
-- Ruff/Basedpyright 的具体配置以 `pyproject.toml` 为准；不得通过排除测试、全局关规则或缩小检查范围消除诊断。
-  Basedpyright 目标为 0 errors / 0 warnings，必要 ignore 必须精确并说明原因。
-- 先跑相关测试，交付前跑完整门槛；skip 必须说明原因，不能报告为通过：
-
-```bash
-uv sync --frozen
-uv run python scripts/generate_models.py --check
-uv run ruff check .
-uv run ruff format --check .
-uv run basedpyright
-uv run pytest
-uv build --no-build-isolation
-```
-
-若沙箱造成缓存、Node wheel 或解释器发现失败，应在沙箱外复核同一命令，不得改配置或使用未锁定工具绕过。
-
-## 依赖、版本与发布
-
-- runtime dependency 必须声明经支持 Python 版本验证的下限，并排除未经验证的下一个 major；构建后端范围和
-  wheel package 必须显式配置，不能依赖自动发现。
-- `[project].version` 是唯一 SDK 版本源；SDK 使用 SemVer，Contract Line 不是 SDK 版本。公开接口删除、重命名、
-  类型收紧或行为变化均按 breaking change 处理。
-- 发行采用 Apache-2.0；`LICENSE`、`NOTICE`、PEP 639 metadata 和制品内容必须一致，wheel 包含 `py.typed` 且
-  不公开 `_generated`。
-- Gitee `origin` 是内部主仓库，私有 GitHub mirror 只承载 PyPI Trusted Publishing。release workflow 仅由与
-  项目版本完全匹配的 `v*` tag 触发，第三方 Action 固定不可变 commit SHA。
-- release 必须来自干净 revision、锁定环境和固定 `SOURCE_DATE_EPOCH`，记录 Contract 与制品 checksum；候选
-  制品须审计内容/METADATA、验证安装后的公开导入和类型消费、覆盖 Python 版本边界并确认可复现构建。