matelab-python-sdk 0.2.0a9__tar.gz → 0.3.0a1__tar.gz

matelab_python_sdk-0.3.0a1/.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、uv 或流水线插件。文档在提交前完成，仅维护受影响的当前态，不新建
+CHANGELOG。正常发布由 CI 完成可复现构建、制品审计和安装后消费；只有打包故障或打包配置变化需要时才本地构建，
+使用临时目录，不积累 `dist/`。
+
+复核最终 diff、版本、Contract pin 和有效验证证据，将本次尚未提交的实现、测试、文档及版本号放入同一个
+release commit。已有提交的历史仅在另有授权时改写。
+
+## 4. 推送、发布并核验
+
+执行 `docs/agent-workflows.md#release`：创建指向 release commit 的 annotated `v{version}` tag，推送
+`origin` 的 main/tag，并验证远端 refs；tag 推送自动触发发布 CI。跟踪该 commit/tag 的 CI，确认测试、
+可复现构建、制品审计、安装后消费和 PyPI 上传成功；tag 推送成功不等于发布完成。
+
+从本次 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 暂未可读时允许短暂重试，等待期间保持进度更新。
+
+失败时定位具体阶段，优先重试失败环节；不通过删测试、跳检查或自动另选版本制造成功。改变已推送历史或处理失败
+候选前核对现有授权，已发布版本不可覆盖。最后报告版本/链接、单次提交、`origin` 的 main/tag refs、CI/PyPI 核验和工作区状态；
+明确剩余失败或未验证项。

matelab_python_sdk-0.3.0a1/.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.3.0a1/.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.3.0a1/.python-version

@@ -0,0 +1 @@
+3.15

matelab_python_sdk-0.3.0a1/.workflow/release.yml

@@ -0,0 +1,89 @@
+version: "1.0"
+name: sdk-release
+displayName: Publish SDK to PyPI
+ref_variable:
+  - UV_PUBLISH_TOKEN
+triggers:
+  push:
+    tags:
+      prefix:
+        - v
+stages:
+  - name: release
+    displayName: Test, build and publish
+    strategy: naturally
+    trigger: auto
+    steps:
+      - step: build@python
+        name: build-and-publish
+        displayName: Validate and publish release
+        # Gitee's Python bootstraps uv; the SDK runs on uv-managed Python 3.15.
+        pythonVersion: "3.14"
+        commands: |
+          set +x
+          set -eu
+          # Gitee injects its pytest tooling into Python's import path.
+          unset PYTHONPATH PYTHONHOME
+          python -m pip install --user --index-url https://pypi.org/simple "uv==0.13.7"
+          export PATH="$(python -m site --user-base)/bin:$PATH"
+          uv --version
+          release_tag="v$(uv version --short)"
+          build_ref="${GITEE_BRANCH:?Gitee build ref is required}"
+          if [ "$build_ref" != main ] && [ "$build_ref" != "$release_tag" ]; then
+            echo "Release ref must be $release_tag; received $build_ref" >&2
+            exit 1
+          fi
+          if [ "$(git rev-parse HEAD)" != "${GITEE_COMMIT:?Gitee trigger commit is required}" ]; then
+            echo "Checkout does not match the Gitee build commit" >&2
+            exit 1
+          fi
+          export SOURCE_DATE_EPOCH="$(git show -s --format=%ct HEAD)"
+          unset MATELAB_PROVIDER_BASE_URL MATELAB_PROVIDER_USERNAME MATELAB_PROVIDER_PASSWORD
+
+          test_status=0
+          for python_version in 3.12 3.13 3.14 3.15; do
+            uv run --frozen --exact --python "$python_version" pytest -rs || test_status=1
+          done
+          test "$test_status" -eq 0
+
+          export UV_PYTHON="$(cat .python-version)"
+          uv run --frozen python scripts/generate_models.py --check
+          uv run --frozen ruff check .
+          uv run --frozen ruff format --check .
+          uv run --frozen basedpyright
+
+          mkdir -p dist/release dist/reproducible
+          uv build --no-build-isolation --out-dir dist/release
+          uv build --no-build-isolation --out-dir dist/reproducible
+          cmp dist/release/*.whl dist/reproducible/*.whl
+          cmp dist/release/*.tar.gz dist/reproducible/*.tar.gz
+          uv run --frozen python scripts/check_release.py dist/release/*.whl dist/release/*.tar.gz
+          (cd dist/release && sha256sum *.whl *.tar.gz > SHA256SUMS)
+          cat dist/release/SHA256SUMS
+
+          sdk_consumer_dir="$(mktemp -d)"
+          trap 'rm -rf -- "$sdk_consumer_dir"' EXIT
+          uv venv "$sdk_consumer_dir/venv"
+          uv pip install \
+            --python "$sdk_consumer_dir/venv/bin/python" \
+            dist/release/*.whl \
+            "basedpyright>=1.40.2" \
+            "nodejs-wheel-binaries==22.20.0"
+          "$sdk_consumer_dir/venv/bin/python" scripts/check_installed_package.py
+          "$sdk_consumer_dir/venv/bin/basedpyright" \
+            --pythonpath "$sdk_consumer_dir/venv/bin/python" \
+            --project tests/typing/pyproject.toml
+
+          if [ "$build_ref" = main ]; then
+            echo "Validation passed on main; publishing requires tag $release_tag"
+            exit 0
+          fi
+          : "${UV_PUBLISH_TOKEN:?Configure UV_PUBLISH_TOKEN as a protected pipeline secret}"
+          uv publish --trusted-publishing never \
+            --publish-url https://upload.pypi.org/legacy/ \
+            dist/release/*.whl dist/release/*.tar.gz
+        artifacts:
+          - name: RELEASE_ARTIFACT
+            path:
+              - ./dist/release
+            type: .tar.gz

{matelab_python_sdk-0.2.0a9 → matelab_python_sdk-0.3.0a1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matelab-python-sdk
-Version: 0.2.0a9
+Version: 0.3.0a1
 Summary: Reusable async Python client for the Matelab Integration Contract
 Author: CMPDC, Institute of Physics, Chinese Academy of Sciences
 License-Expression: Apache-2.0
@@ -12,24 +12,24 @@ Classifier: Framework :: AsyncIO
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
-Requires-Python: >=3.11
+Requires-Python: >=3.12
 Requires-Dist: httpx2>=2.16.0
 Requires-Dist: jsonschema>=4.26.0
-Requires-Dist: pydantic>=2.14.1
+Requires-Dist: pydantic>=2.14.3
 Requires-Dist: typing-extensions>=4.16.0
 Description-Content-Type: text/markdown
 
 # matelab-python-sdk
 
 Async Python client for the Matelab Integration Contract, with typed interfaces for authentication,
-notebooks, records, attachments, cloud files, templates, and literature. Requires Python 3.11 or newer.
+notebooks, records, attachments, cloud files, templates, and literature. Requires Python 3.12 or newer.
 
 ## Installation
 
@@ -64,6 +64,6 @@ asyncio.run(main())
 
 ## Documentation
 
-- [API reference](https://github.com/tiannianzhu/matelab-python-sdk/blob/main/docs/api.md): Session persistence, errors, examples, and Provider limits.
-- [Operation coverage](https://github.com/tiannianzhu/matelab-python-sdk/blob/main/docs/operation-coverage.yaml): supported operations.
-- [Development and releases](https://github.com/tiannianzhu/matelab-python-sdk/blob/main/docs/development.md): checks, Provider smoke, versioning, and builds.
+- [API reference](https://gitee.com/mat-code/matelab-python-sdk/blob/main/docs/api.md): Session persistence, errors, examples, and Provider limits.
+- [Operation coverage](https://gitee.com/mat-code/matelab-python-sdk/blob/main/docs/operation-coverage.yaml): supported operations.
+- [Development and releases](https://gitee.com/mat-code/matelab-python-sdk/blob/main/docs/development.md): checks, Provider smoke, versioning, and builds.

{matelab_python_sdk-0.2.0a9 → matelab_python_sdk-0.3.0a1}/README.md

@@ -1,7 +1,7 @@
 # matelab-python-sdk
 
 Async Python client for the Matelab Integration Contract, with typed interfaces for authentication,
-notebooks, records, attachments, cloud files, templates, and literature. Requires Python 3.11 or newer.
+notebooks, records, attachments, cloud files, templates, and literature. Requires Python 3.12 or newer.
 
 ## Installation
 
@@ -36,6 +36,6 @@ asyncio.run(main())
 
 ## Documentation
 
-- [API reference](https://github.com/tiannianzhu/matelab-python-sdk/blob/main/docs/api.md): Session persistence, errors, examples, and Provider limits.
-- [Operation coverage](https://github.com/tiannianzhu/matelab-python-sdk/blob/main/docs/operation-coverage.yaml): supported operations.
-- [Development and releases](https://github.com/tiannianzhu/matelab-python-sdk/blob/main/docs/development.md): checks, Provider smoke, versioning, and builds.
+- [API reference](https://gitee.com/mat-code/matelab-python-sdk/blob/main/docs/api.md): Session persistence, errors, examples, and Provider limits.
+- [Operation coverage](https://gitee.com/mat-code/matelab-python-sdk/blob/main/docs/operation-coverage.yaml): supported operations.
+- [Development and releases](https://gitee.com/mat-code/matelab-python-sdk/blob/main/docs/development.md): checks, Provider smoke, versioning, and builds.

{matelab_python_sdk-0.2.0a9 → matelab_python_sdk-0.3.0a1}/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.3.0a1}/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.3.0a1}/docs/agent-workflows.md

@@ -31,8 +31,9 @@
 - `[tool.basedpyright]` 字段依次为 `pythonVersion`、`typeCheckingMode`、`include`、`exclude`、
   `reportUnannotatedClassAttribute`、`reportIncompatibleUnannotatedOverride`，其他设置放在其后。沿用 SDK 的目标
   Python 版本与检查路径，不照搬其他项目的值。
-- runtime、build 和 dev 依赖仅声明已验证的 `>=` 下限；`nodejs-wheel-binaries` 保留系统所需的精确版本。
-  更新声明时同步 lock 和安装后消费检查使用的 CI requirement。
+- 升级 runtime、build 或 dev 依赖时，必须将验证通过的新版本同步为 `pyproject.toml` 中对应依赖的 `>=` 下限，
+  同时更新对应 CI 约束（包括安装后消费检查）。`uv.lock` 必须通过 `uv lock` 等 uv 命令自动更新，不手工编辑。
+  例外：`nodejs-wheel-binaries` 保留系统所需的精确版本，并同步 lock 和对应 CI 约束。
 - 构建后端依赖和 wheel package 显式配置；metadata 与制品检查从这些声明推导预期值。
 
 完成标准：配置可解析、声明与 lock 一致、受影响 CI 使用同一约束；字段重排不改变配置含义。
@@ -85,16 +86,15 @@ Ruff/Basedpyright 诊断通过修复代码或精确 ignore 解决，不缩小检
 ## Release
 
 普通 commit/push 只处理已授权的 diff，不自动改版本、建 tag 或发布。发布准备完成但缺少外部操作授权时，
-先交付可审查结果，再请求执行授权。以下步骤适用于实际发布：
+先交付可审查结果，再请求执行授权。发布与普通推送只同步 `origin`。以下步骤适用于实际发布：
 
 1. 按 [版本规则](development.md#versioning) 选择 SDK 版本，读取 `[project].version`，确认待发布版本未发布
    且 Contract pin 完整。公开接口删除、重命名、类型收紧或不兼容行为变化按 breaking change 处理。
    完成标准：版本、当前文档和 tag 名 `v{version}` 一致。
 2. 提交前同步受影响的当前文档，完成 [delivery gate](#delivery-gate)。构建元数据或发布流程变化时，核对
-   metadata 版本与固定的 PyPI 发布 Action 是否兼容；需要本地制品证据时使用
+   metadata 与流水线固定版本的 uv 是否兼容；需要本地制品证据时使用
    [手工构建命令](development.md#reproducible-release-build)。创建已审查、已授权的 release commit。
-3. 创建指向 release commit 的 annotated `v{version}` tag。先推送 `origin` 的 main/tag，再推送 GitHub mirror 的
-   main/tag；只有与项目版本完全匹配的 tag 触发 Trusted Publishing workflow，第三方 Action 固定 immutable
-   commit SHA。
-4. 跟踪 [发布 CI](../.github/workflows/release.yml) 的测试、可复现构建、制品审计、安装后消费和 PyPI publish。
-   完成标准：两个远端 main/tag 对应 release commit，CI 全部通过，PyPI 对应版本可读取。
+3. 创建指向 release commit 的 annotated `v{version}` tag，推送 `origin` 的 main/tag；tag 推送自动触发
+   [发布 CI](../.workflow/release.yml)。
+4. 跟踪发布 CI 的测试、可复现构建、制品审计、安装后消费和 PyPI publish。
+   完成标准：`origin` 的 main/tag 对应 release commit，CI 全部通过，PyPI 对应版本与 CI 制品哈希一致。