matelab-python-sdk 0.2.0a8__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.0a8 → matelab_python_sdk-0.2.0a10}/CONTEXT.md

@@ -86,8 +86,8 @@ A notebook-scoped hierarchical container used to organize records. Records at th
 _Avoid_: Subtype, record type, template
 
 **Record import value**:
-A template-shaped value composed of JSON-compatible scalars and containers, with a staged attachment
-allowed wherever the template expects a file.
+A template-shaped value composed of JSON-compatible scalars and containers, with a staged attachment or existing
+cloud file allowed wherever the template expects a file.
 _Avoid_: Arbitrary object, stored record module, Provider attachment reference
 
 **Encrypted record modules**:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matelab-python-sdk
-Version: 0.2.0a8
+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.0a8 → 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.10.4",
-    "commit": "c422f4f7425ade81eb5a65d9448ca4ea8bcacc79"
+    "tag": "v2026.11.2",
+    "commit": "a986f73b0edc6bb67f2993a9ee1291aba31df5e5"
   },
   "openapi": {
     "source_path": "openapi/matelab-integration-v1.openapi.yaml",
     "snapshot": "matelab-integration-v1.openapi.yaml",
-    "sha256": "1bc28a61647b7b8f38b86c8ea0085415616857f967c997031794a88deb2e377c"
+    "sha256": "4a485f0ab2b589136cdcccad77407d8b5768e6e8cbb8e3a7636d8b9a07649991"
   }
 }

{matelab_python_sdk-0.2.0a8 → 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.10.4"
+  version: "2026.11.2"
   description: |
     Current PHP wire contract for generating SDKs against the selected
     `matelab-server` Provider version.
@@ -10,15 +10,20 @@ info:
     and attachment operations that resolve a data server support the
     `localhost` branch; remote forwarding is excluded pending downstream
     wire evidence and end-to-end verification (PVD-049).
+    Integration requests omit the optional browser `Version` header. If it is
+    supplied, PHP applies `intval` and compares it with the current minimum
+    20261029; a lower value returns HTTP 200 with string `code` and `errcode`
+    equal to `reload`. That browser refresh branch is outside the integer
+    response envelopes selected by this integration contract.
   x-contract-line: integration-v1
   x-provider-evidence:
     repository: /home/tnzhu/projects/matelab-server
-    commit: 161c4560ae1cb6267d46841d6fe8adc8270ee1bc
+    commit: f5a714e17cd76076efe7579db279936ac29b50a6
     verificationRuntime:
-      baseUrl: http://127.0.0.1:18080/api
+      baseUrl: https://matelab.iphy.ac.cn/eln-test/api
       container: matelab-test-server-1
       coreSourceComparison: sha256-exact
-      coreSourceFileCount: 157
+      coreSourceFileCount: 153
       dataServerScope: localhost
     files:
       - controller/Actions.php
@@ -48,6 +53,7 @@ info:
       - lib/Route.php
       - lib/HttpServer.php
       - lib/WsServer.php
+      - start.php
       - lib/MultiException.php
       - config/Db.php
       - config/Channel.php
@@ -56,9 +62,9 @@ info:
       - sql/matelab.sql
       - sql/recommend.sql
   x-provider-audit:
-    currentCommit: 161c4560ae1cb6267d46841d6fe8adc8270ee1bc
-    previousReleaseEvidenceCommit: b70f590571b860f043365c9f2d6f95818d595862
-    lastProviderVerifiedCommit: 161c4560ae1cb6267d46841d6fe8adc8270ee1bc
+    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
@@ -66,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: stageTemporaryFile, change: filename-extension-selects-continuation-bytes-and-abort-cleans-incomplete-extension-variants}
-      - {operationId: uploadRecordAttachment, change: temporary-bytes-retain-sanitized-source-extension}
+      - {operationId: stageTemporaryFile, change: filename-independent-continuation-with-final-fragment-name-and-extensionless-abort}
   x-consumer-evidence:
     - repository: /home/tnzhu/projects/matelab-mcp
       commit: 94a129b2df0ef0fbcf179c10550fb7c9a5dd2e6f
@@ -88,10 +93,11 @@ 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: 89332767c2f20de210baed1e1e42df56e7071ad6
+      commit: f7a7b952d7981f169d5c2585aea5c94b418086a3
       files:
         - src/App.vue
         - src/fn/index.js
+        - src/store/index.js
         - src/components/fullview.vue
         - src/components/userSelect.vue
         - src/components/users.vue
@@ -107,7 +113,8 @@ info:
         The current Front dev commit reads environment/menu from GET
         `/actions/app` and obtains session identity from token issuance.
         The shared upload client sends byte offsets to `/actions/bigupload`
-        and uses the acknowledged offset for the next fragment.
+        and uses the acknowledged offset for the next fragment. GET requests
+        also carry the browser version stored in `src/store/index.js`.
         Existing record, comment, template, literature and cloud-drive calls
         retain their Consumer use cases; no new routes are added by this audit.
   x-record-attachment-staging:
@@ -1627,7 +1634,13 @@ paths:
         Template-shaped file values supplied by the request must be strings in
         the `#file{name}` or `#hash{filename.ext, hash}` form. The current
         validator rejects even valid `#base64` input (PVD-042); inline base64
-        is outside the callable contract. In particular,
+        is outside the callable contract. Existing cloud-drive files can be
+        referenced by `#hash{filename.ext, hash}` when the selected notebook
+        owner's userid owns the personal-root file (`root_id=0`), or has a
+        `files_permissions` row for its shared root. An existing cloud quote
+        alone does not grant access. The reference creates a record attachment
+        quote without consuming the cloud-drive file.
+        In particular,
         table/form file arrays cannot contain explicit JSON null values on the
         current Provider. To create empty table file cells, omit the file column
         and let the Provider complete it with canonical null cells.
@@ -1645,6 +1658,17 @@ paths:
                   template: Example Template
                   dataset:
                     - {uid: GENERATED-WIRE-UID, title: Imported Example, data: {Notes: Sanitized}, keyword: calibration}
+              existing_cloud_attachment:
+                summary: Reuse an authorized cloud-drive file without consuming it
+                value:
+                  eln: Example Notebook
+                  template: Example Template
+                  dataset:
+                    - uid: REC-CLOUD-EXAMPLE-001
+                      title: Existing cloud attachment
+                      data:
+                        Attachments:
+                          File: ["#hash{evidence.zip, 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef}"]
               preuploaded_attachment:
                 summary: Upload-event UID and future record UID are deliberately different
                 value:
@@ -1678,6 +1702,12 @@ paths:
                   value: {code: 0, msg: Data imported, errcode: 0, errmsg: Data imported, id: [9004], eln_id: 12}
                 error:
                   value: {code: 4, msg: Multiple errors, errcode: 4, errmsg: Multiple errors, errs: [Invalid imported field]}
+                inaccessible_hash:
+                  value:
+                    code: 2
+                    msg: The referenced hash 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef does not exist
+                    errcode: 2
+                    errmsg: The referenced hash 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef does not exist
   /eln_api/export:
     post:
       operationId: exportRecords
@@ -1772,7 +1802,12 @@ paths:
         strings containing canonical `elnurl://h=...&s=...&f=...` references.
         The Provider scans the incoming richtext value, resolves hashes against
         caller-owned staging or authorized existing file quotes, and binds the
-        resulting attachments while saving the record.
+        resulting attachments while saving the record. Template-shaped
+        `#hash{filename.ext, hash}` values also accept existing cloud-drive
+        files: permission is checked against the selected notebook owner's
+        userid, using personal-root ownership or a `files_permissions` row for
+        the shared root. The cloud file is retained; an inaccessible hash is
+        rejected before record content is written.
 
         This operation does not modify record title or other record metadata.
         `UpdateRecordRequest` rejects a top-level `title`; the Front uses the
@@ -1827,6 +1862,15 @@ paths:
             examples:
               update:
                 value: {eln: Example Notebook, uid: REC-EXAMPLE-001, modify: [{path: [Notes], data: Sanitized update}]}
+              add_existing_cloud_attachment_field:
+                value:
+                  eln: Example Notebook
+                  uid: REC-EXAMPLE-001
+                  add:
+                    - module: Attachments
+                      name: Cloud file
+                      type: file
+                      data: ["#hash{evidence.zip, 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef}"]
               add_preuploaded_attachment_field:
                 value:
                   eln: Example Notebook
@@ -1930,6 +1974,12 @@ paths:
                   value: {code: 0, msg: Collaboration data update completed, errcode: 0, errmsg: Collaboration data update completed}
                 error:
                   value: {code: 4, msg: Multiple errors, errcode: 4, errmsg: Multiple errors, errs: [Invalid update path]}
+                inaccessible_hash:
+                  value:
+                    code: 2
+                    msg: The referenced hash 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef does not exist
+                    errcode: 2
+                    errmsg: The referenced hash 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef does not exist
   /eln_api/delete:
     post:
       operationId: deleteRecordsByUid
@@ -1970,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]
@@ -3685,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
@@ -7440,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]