matelab-python-sdk 0.1.0a17__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.0a17 → matelab_python_sdk-0.1.0a22}/CHANGELOG.md

@@ -3,6 +3,66 @@
 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
+  `1a4b77721d782fccd2b1f26bcc16a7d876347686` and OpenAPI SHA-256
+  `1e737421aac636356487122ea89e20d54de07c8b9c0651cf6970a7123fe3b72b`. The published `0.1.0a18` entry below remains
+  historical evidence for the former `v0.4.2` target at `a51483f`; it is not rewritten.
+- Aligns with current Provider evidence: comment attachment multipart uses `file`; temporary-file and comment identifiers
+  allow 100 characters; code-4 `errs` accepts opaque array or object containers; and DOI extraction validates
+  `^10\.[0-9]+/\S+$` before transport.
+- Breaking: removes `RecordValueAddition.path` and `RecordFilesAttachmentAppend.folder_path` because the current
+  Provider's add-value shape no longer accepts `path`; files-module append now targets only the module root. Search
+  excludes encrypted records, and callers of arbitrary template-shaped imports must omit unset file-valued keys because
+  the Provider rejects their explicit `null`.
+
+## 0.1.0a18 - 2026-08-23
+
+- Adopts immutable `matelab-spec v0.4.2` at commit `a51483f910440fbbbc3693cc32566482064bb3ab` and OpenAPI
+  SHA-256 `4c92b96ba3dfe7122b30b4db2e2c8054c06018291c8c52c15482112b51a32920`. The wire schema, methods,
+  paths, encodings, operation count, and public interface are unchanged.
+- Records that compatibility evidence remains the stable Provider revision
+  `59101f006e9fd6d6ce0b951dfd34695a7949b54f`; the latest reviewed revision
+  `a3e6b961800f6b1ab666f0d3f6cd4c64c2a3ce27` is incompatible. The SDK retains the stable multipart comment-upload
+  field, while integrations must account for that Provider's DOI rejection, encrypted-search omission, valid
+  files-folder-path rejection, and explicit-null table-file-import failure.
+
 ## 0.1.0a17 - 2026-08-20
 
 - Adopts immutable `matelab-spec v0.4.1` at commit `6f8ab3d14797385d0075d0aba38bf3bf529e674d` and OpenAPI

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matelab-python-sdk
-Version: 0.1.0a17
+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.0a17`. `[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 immutable `matelab-spec v0.4.1` 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,12 +64,16 @@ 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.0a17-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
+`59eb05b233e5ddd023a60ccb5e5c5f2ae22a70f0`. Provider limitations that remain relevant to integrations are documented
+alongside the affected interfaces below.
+
 ## Design
 
 The public module is intentionally small:
@@ -117,8 +121,8 @@ success code it does not allow raises `MatelabProtocolError` rather than assigni
 `MatelabTransportError.status_code` remains available for HTTP failures. Provider response bodies, top-level `msg`,
 legacy `errmsg`, opaque `errs`, uncontracted debug fields, and request payloads are not attached to exceptions because
 Provider-authored diagnostics may contain stack traces, credentials, or submitted values.
-The pinned v0.4.1 Contract also declares optional code-4 `errs`, but PVD-041 and PCG-015 record incompatible observed
-item/container shapes and insufficient evidence for requiredness, cardinality, or exclusion from other codes. The SDK
+The pinned v0.4.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`
 means the identical SDK call is safe to replay without further interpretation. It is conservatively `False` for every
@@ -312,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 by default; pass
-`folder_path=(...)` for an existing folder-title path:
+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
@@ -344,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
@@ -421,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,
@@ -446,7 +454,7 @@ targets = await client.users.search("Example Researcher", global_scope=False)
 `groups.list()` returns the `GroupSummary` tuple directly. Ordering remains Provider-unspecified and is documented
 rather than repeated as a constant result field. The Provider's members for an unstable first group remain wire-only;
 `users.search()` is the public recipient-discovery interface. These two discovery interfaces are experimental because
-group order is unstable and user search is unpaged, unordered and not field-minimized (PVD-006, PVD-029, PCG-011).
+group order is unstable and user search is unpaged, unordered and not field-minimized (PVD-006, PVD-029).
 `GroupSummary.notebook_creation_available` expresses whether the group can currently host notebook creation without
 exposing the Provider's data-server routing value.
 
@@ -496,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
@@ -538,6 +549,8 @@ relations = await client.records.relations(source)
 as `modules`; it is not the template-shaped `RecordImportItem.data` accepted by record import.
 `records.search()` maps each requested field name to a stored record path. A match exposes only Provider-returned
 entries in `values`, so key membership distinguishes an absent result from an explicit JSON `null`.
+The current Provider excludes encrypted records from search (PVD-043); an empty search result therefore does
+not prove that no matching encrypted record exists.
 
 The Provider calls its notebook directory tree `subtype`; that name remains wire-only. The SDK exposes
 `RecordFolder`, `RecordSummary.folder_id`, and the `folders` returned with record listings. A top-level folder has
@@ -587,7 +600,9 @@ UID. Import validates the complete batch with generated wire models but cannot m
 individual inputs or promise atomicity (PCG-008); it therefore returns only the tuple of database IDs actually
 reported by the Provider. `RecordImportItem.keywords` is a tuple; the adapter owns the Provider's
 legacy semicolon encoding. Folder paths are ordered existing folder titles from the notebook root; they do not create
-missing folders. Delete means moving records into the recycle bin, not permanent
+missing folders. The current Provider rejects explicit-null table-file imports (PVD-045). Because the SDK accepts
+arbitrary template-shaped data and cannot identify file columns without the template definition, integrations must omit
+an unset file-valued key instead of sending it as `None`. Delete means moving records into the recycle bin, not permanent
 deletion. Delete and restore return `None`; record mutations are not automatically retried.
 
 `records.copy()` accepts an optional `new_record_uid`; when omitted, the SDK generates one locally. The Provider
@@ -605,7 +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.
+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
@@ -617,8 +634,8 @@ ignores target notebook identity (PVD-020); its mutation likewise performs autho
 `records.comments()`. Each returned `RecordRelationRef` carries only the relation row and declared target IDs.
 Deletion accepts the source `RecordLocator` and one of those observed refs.
 
-Comment upload follows the Provider's literal one-request `upload` field, not the incompatible Front fragment
-protocol (PVD-037). Comment mutations return `None` after acknowledgement. Edit first verifies that the selected
+Comment upload follows the current Provider's literal one-request `file` field (PVD-037). Comment mutations return `None`
+after acknowledgement. Edit first verifies that the selected
 comment is currently observed and caller-owned because the Provider otherwise reports a false success for a missing or
 other-user ID (PVD-004). Delete sends the typed ref directly because the Provider mutation itself enforces record and
 caller ownership. Neither operation performs a post-write read. Staged comment attachments have no Contract abort
@@ -697,7 +714,9 @@ The Provider's static literature form definition and extraction deployment flag
 `extract_metadata()` directly and handle an unavailable or failing optional backend as a Provider error. Extraction
 returns a `PublicationMetadataCandidate`: unstored, rich publication evidence rather than metadata already attached to
 a literature item. Its structured authors are `PublicationAuthorCandidate` values. Extraction accepts a DOI, a
-completed staged PDF, or both; a supplied DOI takes precedence over the staged PDF. Literature list
+completed staged PDF, or both; a supplied DOI takes precedence over the staged PDF. A non-empty DOI must match
+`^10\.[0-9]+/\S+$`; the generated request model rejects other values before sending them to the Provider (PVD-042).
+Literature list
 results likewise exclude Provider-generated citation HTML and author-highlight fragments; Consumers receive the
 underlying citation fields instead of presentation markup. `LiteratureDetail.metadata` is `None` when invalid legacy
 JSON produces the Provider's empty-array fallback; otherwise it contains decoded stored metadata without arbitrary
@@ -722,7 +741,7 @@ canonical update preflights the raw item response and refuses to drop top-level
 `allow_source_metadata_loss=True` explicitly skips that preflight and sends the canonical replacement directly. The
 default read/check/write protection is best effort rather than atomic because the Provider offers no revision or
 compare-and-swap condition; this Provider-specific behavior remains internal to the update operation (PVD-027).
-PDF replace/delete are separate acknowledged mutations and are not presented as atomic with metadata (PCG-010).
+PDF replace/delete are separate acknowledged mutations and are not presented as atomic with metadata.
 Permanent personal deletion is named `permanently_delete`, returns `None`, and is non-recoverable. Sharing requires
 list-observed item summaries, user-search summaries and a
 valid caller identity, then returns `None` because the Provider supplies no per-recipient IDs (PVD-012, PVD-036).
@@ -759,7 +778,7 @@ time strings.
 Folder create returns a `CloudFolderRef` built from the Provider ID. Other folder and file mutations return `None`
 after acknowledgement and do not automatically list the drive. Staged finalize accepts a completed `StagedFile`;
 the Provider binds by temporary row ID without checking its owner (PVD-031), and finalize atomicity/idempotency remain
-absent (PCG-012). Batch move and permanent delete do not claim Provider per-item results or atomicity. Permanent
+absent. Batch move and permanent delete do not claim Provider per-item results or atomicity. Permanent
 deletion is named `permanently_delete_files` and is non-recoverable. Cloud downloads
 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.
@@ -901,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 `matelab-spec v0.4.1`,
-commit `6f8ab3d14797385d0075d0aba38bf3bf529e674d`, and OpenAPI SHA-256
-`73d899c9e60b59f9521062ffcfaaae5f073eea36f24f3e535fcb53f12242581c`.
+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.0a17 → 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.0a17`. `[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 immutable `matelab-spec v0.4.1` 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,12 +36,16 @@ 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.0a17-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
+`59eb05b233e5ddd023a60ccb5e5c5f2ae22a70f0`. Provider limitations that remain relevant to integrations are documented
+alongside the affected interfaces below.
+
 ## Design
 
 The public module is intentionally small:
@@ -89,8 +93,8 @@ success code it does not allow raises `MatelabProtocolError` rather than assigni
 `MatelabTransportError.status_code` remains available for HTTP failures. Provider response bodies, top-level `msg`,
 legacy `errmsg`, opaque `errs`, uncontracted debug fields, and request payloads are not attached to exceptions because
 Provider-authored diagnostics may contain stack traces, credentials, or submitted values.
-The pinned v0.4.1 Contract also declares optional code-4 `errs`, but PVD-041 and PCG-015 record incompatible observed
-item/container shapes and insufficient evidence for requiredness, cardinality, or exclusion from other codes. The SDK
+The pinned v0.4.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`
 means the identical SDK call is safe to replay without further interpretation. It is conservatively `False` for every
@@ -284,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 by default; pass
-`folder_path=(...)` for an existing folder-title path:
+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
@@ -316,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
@@ -393,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,
@@ -418,7 +426,7 @@ targets = await client.users.search("Example Researcher", global_scope=False)
 `groups.list()` returns the `GroupSummary` tuple directly. Ordering remains Provider-unspecified and is documented
 rather than repeated as a constant result field. The Provider's members for an unstable first group remain wire-only;
 `users.search()` is the public recipient-discovery interface. These two discovery interfaces are experimental because
-group order is unstable and user search is unpaged, unordered and not field-minimized (PVD-006, PVD-029, PCG-011).
+group order is unstable and user search is unpaged, unordered and not field-minimized (PVD-006, PVD-029).
 `GroupSummary.notebook_creation_available` expresses whether the group can currently host notebook creation without
 exposing the Provider's data-server routing value.
 
@@ -468,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
@@ -510,6 +521,8 @@ relations = await client.records.relations(source)
 as `modules`; it is not the template-shaped `RecordImportItem.data` accepted by record import.
 `records.search()` maps each requested field name to a stored record path. A match exposes only Provider-returned
 entries in `values`, so key membership distinguishes an absent result from an explicit JSON `null`.
+The current Provider excludes encrypted records from search (PVD-043); an empty search result therefore does
+not prove that no matching encrypted record exists.
 
 The Provider calls its notebook directory tree `subtype`; that name remains wire-only. The SDK exposes
 `RecordFolder`, `RecordSummary.folder_id`, and the `folders` returned with record listings. A top-level folder has
@@ -559,7 +572,9 @@ UID. Import validates the complete batch with generated wire models but cannot m
 individual inputs or promise atomicity (PCG-008); it therefore returns only the tuple of database IDs actually
 reported by the Provider. `RecordImportItem.keywords` is a tuple; the adapter owns the Provider's
 legacy semicolon encoding. Folder paths are ordered existing folder titles from the notebook root; they do not create
-missing folders. Delete means moving records into the recycle bin, not permanent
+missing folders. The current Provider rejects explicit-null table-file imports (PVD-045). Because the SDK accepts
+arbitrary template-shaped data and cannot identify file columns without the template definition, integrations must omit
+an unset file-valued key instead of sending it as `None`. Delete means moving records into the recycle bin, not permanent
 deletion. Delete and restore return `None`; record mutations are not automatically retried.
 
 `records.copy()` accepts an optional `new_record_uid`; when omitted, the SDK generates one locally. The Provider
@@ -577,7 +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.
+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
@@ -589,8 +606,8 @@ ignores target notebook identity (PVD-020); its mutation likewise performs autho
 `records.comments()`. Each returned `RecordRelationRef` carries only the relation row and declared target IDs.
 Deletion accepts the source `RecordLocator` and one of those observed refs.
 
-Comment upload follows the Provider's literal one-request `upload` field, not the incompatible Front fragment
-protocol (PVD-037). Comment mutations return `None` after acknowledgement. Edit first verifies that the selected
+Comment upload follows the current Provider's literal one-request `file` field (PVD-037). Comment mutations return `None`
+after acknowledgement. Edit first verifies that the selected
 comment is currently observed and caller-owned because the Provider otherwise reports a false success for a missing or
 other-user ID (PVD-004). Delete sends the typed ref directly because the Provider mutation itself enforces record and
 caller ownership. Neither operation performs a post-write read. Staged comment attachments have no Contract abort
@@ -669,7 +686,9 @@ The Provider's static literature form definition and extraction deployment flag
 `extract_metadata()` directly and handle an unavailable or failing optional backend as a Provider error. Extraction
 returns a `PublicationMetadataCandidate`: unstored, rich publication evidence rather than metadata already attached to
 a literature item. Its structured authors are `PublicationAuthorCandidate` values. Extraction accepts a DOI, a
-completed staged PDF, or both; a supplied DOI takes precedence over the staged PDF. Literature list
+completed staged PDF, or both; a supplied DOI takes precedence over the staged PDF. A non-empty DOI must match
+`^10\.[0-9]+/\S+$`; the generated request model rejects other values before sending them to the Provider (PVD-042).
+Literature list
 results likewise exclude Provider-generated citation HTML and author-highlight fragments; Consumers receive the
 underlying citation fields instead of presentation markup. `LiteratureDetail.metadata` is `None` when invalid legacy
 JSON produces the Provider's empty-array fallback; otherwise it contains decoded stored metadata without arbitrary
@@ -694,7 +713,7 @@ canonical update preflights the raw item response and refuses to drop top-level
 `allow_source_metadata_loss=True` explicitly skips that preflight and sends the canonical replacement directly. The
 default read/check/write protection is best effort rather than atomic because the Provider offers no revision or
 compare-and-swap condition; this Provider-specific behavior remains internal to the update operation (PVD-027).
-PDF replace/delete are separate acknowledged mutations and are not presented as atomic with metadata (PCG-010).
+PDF replace/delete are separate acknowledged mutations and are not presented as atomic with metadata.
 Permanent personal deletion is named `permanently_delete`, returns `None`, and is non-recoverable. Sharing requires
 list-observed item summaries, user-search summaries and a
 valid caller identity, then returns `None` because the Provider supplies no per-recipient IDs (PVD-012, PVD-036).
@@ -731,7 +750,7 @@ time strings.
 Folder create returns a `CloudFolderRef` built from the Provider ID. Other folder and file mutations return `None`
 after acknowledgement and do not automatically list the drive. Staged finalize accepts a completed `StagedFile`;
 the Provider binds by temporary row ID without checking its owner (PVD-031), and finalize atomicity/idempotency remain
-absent (PCG-012). Batch move and permanent delete do not claim Provider per-item results or atomicity. Permanent
+absent. Batch move and permanent delete do not claim Provider per-item results or atomicity. Permanent
 deletion is named `permanently_delete_files` and is non-recoverable. Cloud downloads
 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.
@@ -873,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 `matelab-spec v0.4.1`,
-commit `6f8ab3d14797385d0075d0aba38bf3bf529e674d`, and OpenAPI SHA-256
-`73d899c9e60b59f9521062ffcfaaae5f073eea36f24f3e535fcb53f12242581c`.
+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.0a17 → 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.1",
-    "commit": "6f8ab3d14797385d0075d0aba38bf3bf529e674d"
+    "tag": "v0.4.5",
+    "commit": "6afac7ff151680130e6e4bc6d95782589b97f4e7"
   },
   "openapi": {
     "source_path": "openapi/matelab-integration-v1.openapi.yaml",
     "snapshot": "matelab-integration-v1.openapi.yaml",
-    "sha256": "73d899c9e60b59f9521062ffcfaaae5f073eea36f24f3e535fcb53f12242581c"
+    "sha256": "31a8d03b4366e2345dfccdbbaaaccf6754b2711428afa4295d778d121988460d"
   }
 }