matelab-python-sdk 0.2.0a9__tar.gz → 0.2.0a10__tar.gz

matelab_python_sdk-0.2.0a10/.agents/skills/matelab-sdk-release/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: matelab-sdk-release
+description: 完成 matelab-python-sdk 的 spec 增量同步、必要适配、完整验证、审查和 PyPI 发布。用于该项目的完整交付；仅同步、验证或提交推送时遵守用户限定的终点。
+---
+
+# Matelab SDK 完整交付
+
+在包含本 skill 的 `matelab-python-sdk` 仓库根目录执行。
+以下项目路径均相对此仓库。先读适用 `AGENTS.md`；具体规范以仓库当前文件为准。
+
+## 调用范围
+
+- 用户要求执行 `$matelab-sdk-release` 且未限制阶段时，完成同步、适配、测试、审查、提交、推送、tag 和
+  PyPI 发布；可附目标版本。不重复索取已覆盖目标和副作用的授权。
+- “只同步”“只验证”“仅提交推送”等限制优先，停在相应阶段；解释、制作或修改本技能不执行发布。
+- 待发布内容包括相对上次已发布 tag 的提交及工作区改动，不能仅凭工作区干净就认定无变更。
+  无待发布内容且当前版本已发布时，核对状态后结束；目标 tag 已推送时，优先继续其 CI/PyPI 核验。
+- 依赖更新仅在用户要求时进行。真实业务 mutation、生产访问及新增发布目标不属于默认范围。
+
+## 1. 定界与 spec 增量
+
+先检查 status、当前版本、Contract lock、最近发布 tag 和实际 remotes，保留用户已有改动。
+按 `docs/agent-workflows.md#contract-adoption` 选择新的远端 annotated spec tag，固定 tag object、peeled commit、
+snapshot 和 SHA-256。
+
+比较相对当前 pin 的 request、response、security、examples、成功码及 PVD/PCG，只适配本次增量。
+即使仅 description/examples 改变，也检查现有 public 输入能否表达新能力。专用 schema 与顶层请求可能服务不同
+流程，先核对适用范围，再判断是否确有契约矛盾；把 SDK 尚未实现的能力如实归为 SDK 缺项。
+
+从 release commit 复制快照、更新 lock、运行生成脚本，审查生成差异；同步受影响的 adapter、public 类型、测试、
+coverage 和当前态文档。公开接口和生命周期沿 public intent → wire operation → Provider evidence 核对。
+按需读 `docs/agent-architecture.md`，邻接仓库仅作只读证据，不运行 spec 测试或修改其配置。
+
+## 2. 验证与审查
+
+执行 `docs/agent-workflows.md#delivery-gate`，具体命令取 `docs/development.md#development`。
+代码、契约、依赖或构建行为变化先聚焦再完整测试；聚焦用例不能代替完整 `pytest`。修复需补充的用例来自契约、
+独立示例或可验证属性，不复刻实现，不增加 Provider 逐路由 conformance。
+
+真实 smoke 按 `docs/agent-workflows.md#provider-validation` 确认目标、ignore 和授权。授权覆盖隔离服务的登录、
+Session 恢复、刷新和查询时，完整测试显式加载 SDK 自己的配置：
+
+```bash
+uv run --frozen --env-file .env.test pytest -ra
+```
+
+否则运行不加载 Provider 连接变量的完整测试，明确报告 smoke 的 skip 及原因；用户要求的实时验证缺失时不能声称
+已经完成。区分 MockTransport 的 SDK 映射证据与真实服务证据，禁止将凭证或敏感 payload 打印或提交。
+
+对实质代码差异使用系统 `review-agent` skill，委派一个全新、只读子代理（`fork_turns: "none"`）。根代理处理
+可证实问题并验证受影响部分。复用仍覆盖当前差异的完整测试、静态检查和审查结果，记录命令、结果及其覆盖的
+commit/diff；只改版本后补版本一致性检查，不重跑未受影响的全套。
+
+## 3. 收敛并一次提交
+
+按 `docs/development.md#versioning` 选择兼容的下个 SDK 版本；使用用户指定版本时先检查 tag 和 PyPI 是否占用。
+SDK 版本与 spec 日历版本独立，不跳过未占用的预发布序号。`pyproject.toml` 是唯一版本来源，更新 `uv.lock` 的
+本项目版本。仅改版本时保持其余 lock 内容，使用发布 workflow 固定的 uv 检查兼容性。
+
+按需读配置/依赖章节；不因发布顺手升级依赖、Node 或 Actions。文档在提交前完成，仅维护受影响的当前态，不新建
+CHANGELOG。正常发布由 CI 完成可复现构建、制品审计和安装后消费；只有打包故障或打包配置变化需要时才本地构建，
+使用临时目录，不积累 `dist/`。
+
+复核最终 diff、版本、Contract pin 和有效验证证据，将本次尚未提交的实现、测试、文档及版本号放入同一个
+release commit。已有提交的历史仅在另有授权时改写。
+
+## 4. 推送、发布并核验
+
+执行 `docs/agent-workflows.md#release`：创建指向 release commit 的 annotated `v{version}` tag，按规定顺序推送
+同一 branch/tag 到两个远端，并验证远端 refs。跟踪该 commit/tag 的发布 workflow，逐项确认测试、可复现构建、
+制品审计、安装后消费和 PyPI 上传成功；tag 推送成功不等于发布完成。
+
+使用可用的 GitHub 工具读取 jobs 和构建日志；能力不足时用 `gh`。从本次 CI 构建审计输出或下载的 CI 制品取得
+wheel/sdist 的 SHA-256，不能仅用 PyPI 自报哈希证明 CI/PyPI 一致。在 SDK 锁定开发环境中运行本技能的只读核验器：
+
+```bash
+uv run --frozen --no-sync python -B .agents/skills/matelab-sdk-release/scripts/verify_pypi.py \
+  --repo "$PWD" --ref RELEASE_COMMIT \
+  --sha256 'WHEEL_FILENAME=CI_SHA256' --sha256 'SDIST_FILENAME=CI_SHA256'
+```
+
+参数替换为这次发布的 commit、文件名和 CI 哈希。
+纯核验使用现有环境；`--no-sync` 禁止自动同步虚拟环境，`-B` 禁止写入字节码，环境缺失时如实报告。
+[核验器](scripts/verify_pypi.py) 在内存中下载制品，比对发布提交的源码、配置、版本、依赖和 README，不构建或保留
+历史制品。PyPI 暂未可读时允许短暂重试，等待期间保持进度更新。
+
+失败时定位具体阶段，优先重试失败环节；不通过删测试、跳检查或自动另选版本制造成功。改变已推送历史或处理失败
+候选前核对现有授权，已发布版本不可覆盖。最后报告版本/链接、单次提交、两个远端 refs、CI/PyPI 核验和工作区状态；
+明确剩余失败或未验证项。

matelab_python_sdk-0.2.0a10/.agents/skills/matelab-sdk-release/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Matelab SDK 完整发布"
+  short_description: "Matelab SDK 的 spec 同步、完整验证、单次提交与 PyPI 发布"
+  default_prompt: "使用 $matelab-sdk-release 完成 Matelab Python SDK 的 spec 增量同步、必要适配、完整测试和审查，将版本号与全部改动放进同一个提交，推送并发布到 PyPI。"

matelab_python_sdk-0.2.0a10/.agents/skills/matelab-sdk-release/scripts/verify_pypi.py

@@ -0,0 +1,165 @@
+"""Read-only comparison of a Matelab SDK release, CI hashes and PyPI artifacts."""
+
+import argparse
+import hashlib
+import io
+import json
+import re
+import subprocess
+import tarfile
+import tomllib
+import zipfile
+from email.message import Message
+from email.parser import BytesParser
+from pathlib import Path
+from urllib.parse import quote, urlsplit
+from urllib.request import urlopen
+
+from packaging.requirements import Requirement
+
+
+def require(condition: bool, message: str) -> None:
+    if not condition:
+        raise ValueError(message)
+
+
+def git_bytes(repo: Path, commit: str, path: str) -> bytes:
+    return subprocess.check_output(["git", "-C", str(repo), "show", f"{commit}:{path}"])
+
+
+def ci_hash(value: str) -> tuple[str, str]:
+    name, separator, digest = value.partition("=")
+    if not separator or not name or re.fullmatch(r"[a-fA-F0-9]{64}", digest) is None:
+        raise argparse.ArgumentTypeError("Expected FILENAME=64_HEX_SHA256 from this release's CI artifacts")
+    return name, digest.lower()
+
+
+def metadata_matches(metadata: Message, project: dict, readme: str) -> None:
+    require(metadata["Version"] == project["version"], "Artifact version mismatch")
+    require(metadata["Requires-Python"] == project["requires-python"], "Artifact Python requirement mismatch")
+    expected = {Requirement(value) for value in project["dependencies"]}
+    actual = {Requirement(value) for value in metadata.get_all("Requires-Dist", [])}
+    require(actual == expected, "Artifact dependency mismatch")
+    require(metadata["License-Expression"] == project["license"], "Artifact license mismatch")
+    author = ", ".join(entry["name"] for entry in project["authors"])
+    require(metadata["Author"] == author, "Artifact author mismatch")
+    description = metadata.get_payload()
+    require(isinstance(description, str) and description.strip() == readme.strip(), "Artifact README mismatch")
+
+
+def verify_wheel(payload: bytes, repo: Path, commit: str, project: dict, readme: str, tracked: set[str]) -> int:
+    package = {path.removeprefix("src/"): path for path in tracked if path.startswith("src/matelab/")}
+    metadata_dir = f"matelab_python_sdk-{project['version']}.dist-info"
+    with zipfile.ZipFile(io.BytesIO(payload)) as archive:
+        names = archive.namelist()
+        require(len(names) == len(set(names)), "Duplicate wheel members")
+        require({name for name in names if name.startswith("matelab/")} == set(package), "Wheel package file mismatch")
+        for name, source in package.items():
+            require(archive.read(name) == git_bytes(repo, commit, source), f"Wheel source mismatch: {source}")
+        metadata_matches(BytesParser().parsebytes(archive.read(f"{metadata_dir}/METADATA")), project, readme)
+        for license_file in project["license-files"]:
+            require(
+                archive.read(f"{metadata_dir}/licenses/{license_file}") == git_bytes(repo, commit, license_file),
+                f"Wheel license file mismatch: {license_file}",
+            )
+    return len(package)
+
+
+def verify_sdist(payload: bytes, repo: Path, commit: str, project: dict, readme: str, tracked: set[str]) -> int:
+    prefix = f"matelab_python_sdk-{project['version']}/"
+    seen: set[str] = set()
+    with tarfile.open(fileobj=io.BytesIO(payload), mode="r:gz") as archive:
+        for member in archive.getmembers():
+            require(member.name.startswith(prefix) or member.name == prefix.rstrip("/"), "Unexpected sdist root")
+            if member.isdir():
+                continue
+            require(member.isfile(), "Unexpected sdist link or special member")
+            path = member.name.removeprefix(prefix)
+            require(path not in seen, f"Duplicate sdist member: {path}")
+            seen.add(path)
+            stream = archive.extractfile(member)
+            require(stream is not None, f"Unreadable sdist member: {path}")
+            contents = stream.read()
+            if path == "PKG-INFO":
+                metadata_matches(BytesParser().parsebytes(contents), project, readme)
+            else:
+                require(path in tracked, f"Untracked sdist member: {path}")
+                require(contents == git_bytes(repo, commit, path), f"Sdist source mismatch: {path}")
+    required = {path for path in tracked if path.startswith("src/matelab/")}
+    required.update({"PKG-INFO", "pyproject.toml", "uv.lock", project["readme"], *project["license-files"]})
+    required.update(path for path in tracked if path.startswith("contracts/"))
+    require(required <= seen, f"Missing sdist files: {sorted(required - seen)}")
+    return len(seen - {"PKG-INFO"})
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--repo", type=Path, default=Path.cwd())
+    parser.add_argument("--ref", required=True, help="Release commit or immutable release tag")
+    parser.add_argument(
+        "--sha256", action="append", type=ci_hash, required=True, help="FILENAME=CI_SHA256; repeat per file"
+    )
+    args = parser.parse_args()
+    repo = args.repo.resolve()
+    commit = subprocess.check_output(
+        ["git", "-C", str(repo), "rev-parse", "--verify", "--end-of-options", f"{args.ref}^{{commit}}"], text=True
+    ).strip()
+    project = tomllib.loads(git_bytes(repo, commit, "pyproject.toml").decode())["project"]
+    require(project["name"] == "matelab-python-sdk", "This verifier is for matelab-python-sdk")
+    expected_hashes = dict(args.sha256)
+    require(len(expected_hashes) == len(args.sha256), "Duplicate expected artifact names")
+    readme = git_bytes(repo, commit, project["readme"]).decode()
+    tracked = set(
+        subprocess.check_output(
+            ["git", "-C", str(repo), "ls-tree", "-r", "--name-only", commit], text=True
+        ).splitlines()
+    )
+    url = f"https://pypi.org/pypi/{quote(project['name'], safe='')}/{quote(project['version'], safe='')}/json"
+    with urlopen(url, timeout=30) as response:
+        published = json.load(response)
+    info = published["info"]
+    require(info["version"] == project["version"], "PyPI version mismatch")
+    require(info["requires_python"] == project["requires-python"], "PyPI Python requirement mismatch")
+    require(info["description"].strip() == readme.strip(), "PyPI README mismatch")
+    require(
+        {Requirement(value) for value in info["requires_dist"] or []}
+        == {Requirement(value) for value in project["dependencies"]},
+        "PyPI dependency mismatch",
+    )
+    entries = published["urls"]
+    require(len(entries) == len(expected_hashes), "PyPI/CI artifact count mismatch")
+    require({entry["filename"] for entry in entries} == set(expected_hashes), "PyPI/CI artifact names mismatch")
+    counts = {}
+    for entry in entries:
+        name = entry["filename"]
+        digest = expected_hashes[name]
+        require(entry["digests"]["sha256"] == digest, f"CI/PyPI hash mismatch: {name}")
+        location = urlsplit(entry["url"])
+        require(
+            location.scheme == "https" and location.hostname == "files.pythonhosted.org", "Unexpected artifact host"
+        )
+        with urlopen(entry["url"], timeout=30) as response:
+            payload = response.read()
+        require(hashlib.sha256(payload).hexdigest() == digest, f"Downloaded hash mismatch: {name}")
+        if entry["packagetype"] == "bdist_wheel":
+            counts["wheel_package_files"] = verify_wheel(payload, repo, commit, project, readme, tracked)
+        elif entry["packagetype"] == "sdist":
+            counts["sdist_source_files"] = verify_sdist(payload, repo, commit, project, readme, tracked)
+        else:
+            raise ValueError(f"Unexpected artifact type: {entry['packagetype']}")
+    require("wheel_package_files" in counts and "sdist_source_files" in counts, "Wheel and sdist are both required")
+    print(json.dumps({"version": project["version"], "commit": commit, "files": expected_hashes, **counts}, indent=2))
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except (
+        OSError,
+        ValueError,
+        KeyError,
+        subprocess.CalledProcessError,
+        tarfile.TarError,
+        zipfile.BadZipFile,
+    ) as error:
+        raise SystemExit(f"Release verification failed: {error}") from None

{matelab_python_sdk-0.2.0a9 → matelab_python_sdk-0.2.0a10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matelab-python-sdk
-Version: 0.2.0a9
+Version: 0.2.0a10
 Summary: Reusable async Python client for the Matelab Integration Contract
 Author: CMPDC, Institute of Physics, Chinese Academy of Sciences
 License-Expression: Apache-2.0

{matelab_python_sdk-0.2.0a9 → matelab_python_sdk-0.2.0a10}/contracts/matelab-integration-v1.lock.json

@@ -2,12 +2,12 @@
   "schema_version": 1,
   "contract_line": "integration-v1",
   "release": {
-    "tag": "v2026.11.1",
-    "commit": "402a158052995850e0b7fad5ed5399c8a2eed294"
+    "tag": "v2026.11.2",
+    "commit": "a986f73b0edc6bb67f2993a9ee1291aba31df5e5"
   },
   "openapi": {
     "source_path": "openapi/matelab-integration-v1.openapi.yaml",
     "snapshot": "matelab-integration-v1.openapi.yaml",
-    "sha256": "f9d3bd0baa4e5e70fe13870c21d9be70e40e2686831a0ffcc4632b39f83a3257"
+    "sha256": "4a485f0ab2b589136cdcccad77407d8b5768e6e8cbb8e3a7636d8b9a07649991"
   }
 }

{matelab_python_sdk-0.2.0a9 → matelab_python_sdk-0.2.0a10}/contracts/matelab-integration-v1.openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: Matelab Integration Contract
-  version: "2026.11.1"
+  version: "2026.11.2"
   description: |
     Current PHP wire contract for generating SDKs against the selected
     `matelab-server` Provider version.
@@ -18,12 +18,12 @@ info:
   x-contract-line: integration-v1
   x-provider-evidence:
     repository: /home/tnzhu/projects/matelab-server
-    commit: 00f17b6ce0906bb78b0a3e9bb8c50abee90ca3d0
+    commit: f5a714e17cd76076efe7579db279936ac29b50a6
     verificationRuntime:
       baseUrl: https://matelab.iphy.ac.cn/eln-test/api
       container: matelab-test-server-1
       coreSourceComparison: sha256-exact
-      coreSourceFileCount: 152
+      coreSourceFileCount: 153
       dataServerScope: localhost
     files:
       - controller/Actions.php
@@ -53,6 +53,7 @@ info:
       - lib/Route.php
       - lib/HttpServer.php
       - lib/WsServer.php
+      - start.php
       - lib/MultiException.php
       - config/Db.php
       - config/Channel.php
@@ -61,9 +62,9 @@ info:
       - sql/matelab.sql
       - sql/recommend.sql
   x-provider-audit:
-    currentCommit: 00f17b6ce0906bb78b0a3e9bb8c50abee90ca3d0
-    previousReleaseEvidenceCommit: 161c4560ae1cb6267d46841d6fe8adc8270ee1bc
-    lastProviderVerifiedCommit: 00f17b6ce0906bb78b0a3e9bb8c50abee90ca3d0
+    currentCommit: f5a714e17cd76076efe7579db279936ac29b50a6
+    previousReleaseEvidenceCommit: 00f17b6ce0906bb78b0a3e9bb8c50abee90ca3d0
+    lastProviderVerifiedCommit: f5a714e17cd76076efe7579db279936ac29b50a6
     contractStatus: current-provider-aligned
     # Summary of changes adopted by current Supported Routes since the last
     # released contract, including contract corrections. The Provider diff is
@@ -71,8 +72,7 @@ info:
     # updates against that fixed release baseline; use [] if no relevant changes.
     # Entries are not per-change verification results or a cumulative history.
     incorporatedChanges:
-      - {operationId: importRecordDataset, change: authorized-cloud-drive-hash-references-pass-permission-query}
-      - {operationId: updateRecordData, change: authorized-cloud-drive-hash-references-pass-permission-query}
+      - {operationId: stageTemporaryFile, change: filename-independent-continuation-with-final-fragment-name-and-extensionless-abort}
   x-consumer-evidence:
     - repository: /home/tnzhu/projects/matelab-mcp
       commit: 94a129b2df0ef0fbcf179c10550fb7c9a5dd2e6f
@@ -93,7 +93,7 @@ info:
         identity must come from token issuance. ELN-group and notebook-list
         calls still provide Consumer evidence for their canonical GET forms.
     - repository: /home/tnzhu/projects/matelab-front
-      commit: 55bc8d95d9d4ef02841621f0b793d273cea66137
+      commit: f7a7b952d7981f169d5c2585aea5c94b418086a3
       files:
         - src/App.vue
         - src/fn/index.js
@@ -2020,11 +2020,11 @@ paths:
         workflow therefore preserves the exact upload `eln`/`user` selector and
         permits one occurrence in one target record. The operation has no
         contracted abort, status, expiration, or idempotent retry. A hash
-        mismatch in this one-fragment flow rolls back the temporary row and
-        new bytes. Errors after import/update writing starts still do not prove
-        whether the stage was consumed. Temporary bytes retain the multipart
-        filename's extension after removing non-ASCII-alphanumeric characters;
-        the response still reports the original source filename.
+        mismatch in this one-fragment flow occurs before row registration and
+        removes the new bytes. Errors after import/update writing starts still
+        do not prove whether the stage was consumed. On completion, bytes retain
+        the multipart filename's extension after removing characters outside
+        `[A-Za-z0-9]`; the response still reports the original source filename.
         Raw identifiers identify the staging row;
         their filesystem components are sanitized and can alias (PVD-051).
       x-known-provider-issues: [PVD-014, PVD-051]
@@ -3735,18 +3735,18 @@ paths:
         successful response's `offset`. Omitting it defaults to zero and
         restarts incomplete bytes rather than appending. The final fragment
         returns the combined SHA-256, size, source filename, temporary row id,
-        and legacy preview query. The multipart filename's final extension,
-        stripped of characters outside `[A-Za-z0-9]` with case preserved,
-        also selects the temporary bytes. Repeat that extension on every
-        fragment; changing it cannot continue the previous bytes and returns
-        code 2 when the requested offset has no matching file. A different
-        filename stem with the same sanitized extension can continue them.
+        and legacy preview query. Incomplete bytes are selected by the same
+        `uid` and `tempid`, independently of the multipart filename and extension.
+        Both may change between fragments. Only after final hash validation does
+        PHP append the final fragment's extension, stripped of characters outside
+        `[A-Za-z0-9]` with case preserved, and register the completed row. The
+        response `filename` is the final fragment's original source filename.
 
         `abort=1` is the compensating cleanup operation. It requires the same
         `uid` and `tempid` and omits `file`. If no completed row exists for
-        those identifiers, it removes incomplete bytes for all extension
-        variants, including the extensionless file. If a completed row exists,
-        it preserves the row and bytes without cleaning any variants. Both
+        those identifiers, it removes the extensionless incomplete file.
+        It does not scan extension-suffixed orphan files. If a completed row
+        exists, it preserves the row and bytes without cleaning any files. Both
         states return the standard HTTP 200 code-2 error envelope ("upload
         cancelled"); that response does not prove completed staging was deleted.
         Complete uploads must be consumed by their intended finalizer; this
@@ -7490,9 +7490,9 @@ components:
           type: string
           format: binary
           description: |
-            Required for upload branches and omitted for abort. The multipart
-            filename's sanitized final extension selects the temporary bytes;
-            keep that extension unchanged throughout continuation.
+            Required for upload branches and omitted for abort. Filename and
+            extension may change between fragments in the same uid/tempid
+            session. Completion uses the final fragment's source filename.
       allOf:
         - if:
             required: [abort]

{matelab_python_sdk-0.2.0a9 → matelab_python_sdk-0.2.0a10}/docs/api.md

@@ -5,15 +5,15 @@ See the [README](../README.md) for installation and quick start and [CONTEXT.md]
 
 ## Contract
 
-The SDK is pinned to the immutable `matelab-spec v2026.11.1` Contract Release. The sole pin,
+The SDK is pinned to the immutable `matelab-spec v2026.11.2` Contract Release. The sole pin,
 [contracts/matelab-integration-v1.lock.json](../contracts/matelab-integration-v1.lock.json), records peeled commit
-`402a158052995850e0b7fad5ed5399c8a2eed294`, source `openapi/matelab-integration-v1.openapi.yaml`, the local snapshot path,
-and SHA-256 `f9d3bd0baa4e5e70fe13870c21d9be70e40e2686831a0ffcc4632b39f83a3257`. The annotated tag object is
-`18dbfd99f36ee7fc8cd620a251c7973d86e8dedd`.
+`a986f73b0edc6bb67f2993a9ee1291aba31df5e5`, source `openapi/matelab-integration-v1.openapi.yaml`, the local snapshot path,
+and SHA-256 `4a485f0ab2b589136cdcccad77407d8b5768e6e8cbb8e3a7636d8b9a07649991`. The annotated tag object is
+`dc7a09dccf4187100cd05241757fc3f500107bdd`.
 
-The Contract uses Provider source evidence from `00f17b6ce0906bb78b0a3e9bb8c50abee90ca3d0`; v2026.11.1 validation ran
+The Contract uses Provider source evidence from `f5a714e17cd76076efe7579db279936ac29b50a6`; v2026.11.2 validation ran
 against an isolated test instance and does not establish production behavior. The Front Consumer evidence
-`55bc8d95d9d4ef02841621f0b793d273cea66137` informs cross-Consumer capability review but does not define the SDK interface.
+`f7a7b952d7981f169d5c2585aea5c94b418086a3` informs cross-Consumer capability review but does not define the SDK interface.
 
 This snapshot covers the Workerman runtime with the `localhost` data-server branch for ELN records and attachments;
 remote data-server forwarding is outside its verified callable scope (PVD-049).
@@ -723,25 +723,27 @@ assert isinstance(staged, StagedFile)
 The SDK derives `fragment_size` and computes the complete SHA-256 for a single `bytes` fragment. File-like content
 must declare its fragment size. For multiple fragments, pass the returned `StagedUploadSession` into the next call and
 supply `complete_sha256` on the final call. `next_offset` is the Provider-acknowledged byte offset, checked against the
-declared fragment size and sent with the next fragment. Repeat the filename's final extension across fragments:
-the Provider removes characters outside `[A-Za-z0-9]` and preserves case, so `paper.P-d_f` and `renamed.Pdf` select
-the same bytes. Changing that sanitized extension cannot resume the upload and returns code 2 when no matching
-file exists at the requested offset. The SDK sends each filename unchanged, checks the returned filename and total
+declared fragment size and sent with the next fragment. Incomplete bytes use the same binding and upload-session
+identities independently of filename or extension, so both may change between fragments. After final hash validation,
+the Provider appends the final fragment's extension, removing characters outside `[A-Za-z0-9]` and preserving case;
+its response retains that fragment's original filename. The SDK sends each filename unchanged, checks the returned filename and total
 size, and compares hashes when a local expected hash is available. A final result contains the Provider hash, temporary row
 identity and direct `binding`; it no longer embeds resumable session state. The temporary Provider URL and upload-session
 identity needed by internal binding and cleanup remain hidden. Callers do not need to
 splice either into content. The result does not claim that a later literature/cloud operation checks the uploader or
 consumes the file exactly once. `uploads.abort()` accepts either an active `StagedUploadSession` or a completed
 `StagedFile` and returns `None` for the Provider's code-2 cancellation signal. Without a completed staging row, it
-removes all incomplete extension variants, including extensionless bytes. A completed row prevents any cleanup for
-that identity; completed staging must be consumed by its intended finalizer (PVD-052).
+removes only the extensionless incomplete file, without scanning extension-suffixed orphan files. A completed row
+prevents any cleanup for that identity; completed staging must be consumed by its intended finalizer (PVD-052).
 Binding UIDs allow up to 100 characters; upload-session IDs allow up to 45 (PVD-024). Use fresh identities: different
 raw identifiers can alias after Provider filename sanitization (PVD-051). Workerman upload errors supply no usable
 resume offset (PVD-050). After a failed non-final fragment, cancel incomplete bytes and restart with fresh identities.
 An ambiguous final response can leave completed staging that `abort()` cannot delete.
 Staging mutations are never automatically retried.
-After upgrading from the previous Provider's extensionless storage, restart old incomplete uploads from offset zero
-or cancel them and use fresh session identities.
+When upgrading from the previous Provider's extension-suffixed partial storage, restart with fresh session identities:
+old incomplete files cannot resume through the new path and the new abort does not remove them. Existing completed
+staging keeps its registered finalizer path. Hash-mismatch cleanup does not guarantee byte preservation after later
+rename or row-registration failures; those fault paths have no verification evidence.
 
 Literature identities distinguish the personal library from shared libraries:
 

{matelab_python_sdk-0.2.0a9 → matelab_python_sdk-0.2.0a10}/docs/operation-coverage.yaml

@@ -3,7 +3,7 @@
 schema_version: 1
 contract:
   line: integration-v1
-  release: v2026.11.1
+  release: v2026.11.2
   operation_count: 71
 
 operations:

{matelab_python_sdk-0.2.0a9 → matelab_python_sdk-0.2.0a10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "matelab-python-sdk"
-version = "0.2.0a9"
+version = "0.2.0a10"
 description = "Reusable async Python client for the Matelab Integration Contract"
 requires-python = ">=3.11"
 keywords = ["matelab", "electronic-lab-notebook", "eln", "asyncio", "sdk"]

{matelab_python_sdk-0.2.0a9 → matelab_python_sdk-0.2.0a10}/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 = "2026.11.1"
+OPENAPI_INFO_VERSION = "2026.11.2"
 
 
 class ResponseEnvelope(WireModel):
@@ -2759,9 +2759,9 @@ class StageTemporaryFileRequest(WireModel):
     """
     file: bytes | None = None
     """
-    Required for upload branches and omitted for abort. The multipart
-    filename's sanitized final extension selects the temporary bytes;
-    keep that extension unchanged throughout continuation.
+    Required for upload branches and omitted for abort. Filename and
+    extension may change between fragments in the same uid/tempid
+    session. Completion uses the final fragment's source filename.
 
     """
 

{matelab_python_sdk-0.2.0a9 → matelab_python_sdk-0.2.0a10}/src/matelab/domains/uploads.py

@@ -79,7 +79,7 @@ class Uploads:
         complete_sha256: str | None = None,
         content_type: str = "application/octet-stream",
     ) -> StagedUploadSession | StagedFile:
-        """Stage bytes; preserve the sanitized, case-sensitive filename extension when resuming."""
+        """Stage bytes; continuation filenames may change, and completion uses the final filename."""
         if session is None:
             session = StagedUploadSession(
                 binding=UploadBindingRef.new(), upload_session_id=f"tmp-{secrets.token_urlsafe(24)}"
@@ -163,7 +163,7 @@ class Uploads:
         )
 
     async def abort(self, upload: StagedUploadSession | StagedFile) -> None:
-        """Cancel incomplete extension variants; completed staging identities remain untouched (PVD-052)."""
+        """Cancel extensionless incomplete bytes; completed staging identities remain untouched (PVD-052)."""
         if isinstance(upload, StagedFile):
             # The completed file keeps this Provider identity private except for same-module cleanup.
             upload_session_id = upload._upload_session_id  # pyright: ignore[reportPrivateUsage]

{matelab_python_sdk-0.2.0a9 → matelab_python_sdk-0.2.0a10}/tests/test_uploads_and_literature.py

@@ -209,7 +209,7 @@ async def test_stage_single_bytes_creates_session_and_computes_hash(
 
 @pytest.mark.asyncio
 @pytest.mark.parametrize(
-    ("first_filename", "final_filename"), [("paper.pdf", "paper.pdf"), ("paper.P-d_f", "renamed.Pdf")]
+    ("first_filename", "final_filename"), [("paper.pdf", "paper.pdf"), ("paper.txt", "renamed.P-d_f")]
 )
 async def test_stage_fragments_sends_acknowledged_offset_and_maps_completion_and_abort(
     provider_session: Session,

{matelab_python_sdk-0.2.0a9 → matelab_python_sdk-0.2.0a10}/uv.lock

@@ -433,7 +433,7 @@ wheels = [
 
 [[package]]
 name = "matelab-python-sdk"
-version = "0.2.0a9"
+version = "0.2.0a10"
 source = { editable = "." }
 dependencies = [
     { name = "httpx2" },