matelab-python-sdk 0.1.0a3__tar.gz → 0.1.0a4__tar.gz

{matelab_python_sdk-0.1.0a3 → matelab_python_sdk-0.1.0a4}/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.1.0a4 - 2026-07-28
+
+- Further reduces the alpha public surface from 150 to 126 symbols by accepting direct keyword arguments and existing
+  domain values instead of request-shaped wrapper dataclasses.
+- Centralizes safe request-model validation, strengthens generated Contract constraints, and preserves structured field
+  diagnostics without exposing credentials, tokens, or sensitive payload values.
+- Tightens Session replacement, refresh races, multipart retry safety, streaming cleanup, and exact HTTP success
+  handling while retaining stable transport, authentication, Provider, protocol, usage, and verification errors.
+- Collects all business capabilities under `matelab.domains`, keeps client/session/error/transport primitives at the
+  package root, and hardens generation and release-artifact audits.
+
 ## 0.1.0a3 - 2026-07-28
 
 - Replaces HTTPX with HTTPX2 2.9.1 and raises the Pydantic compatibility floor to 2.13.4. Injected clients must now

{matelab_python_sdk-0.1.0a3 → matelab_python_sdk-0.1.0a4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matelab-python-sdk
-Version: 0.1.0a3
+Version: 0.1.0a4
 Summary: Reusable async Python client for the Matelab Integration Contract
 Author-email: 朱天念 <zhutiannian@gmail.com>
 License-Expression: Apache-2.0
@@ -28,7 +28,7 @@ Description-Content-Type: text/markdown
 
 Reusable async Python client for the Matelab Integration Contract.
 
-The current alpha is `0.1.0a3`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a4`. `[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.1.1` Contract Release. The sole release pin is
@@ -57,7 +57,7 @@ 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.0a3-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a4-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -82,6 +82,24 @@ async with AsyncMatelab() as client:
 `AsyncMatelab()` uses `https://matelab.iphy.ac.cn/api` by default. Pass another Provider API root
 explicitly when needed, for example `AsyncMatelab("https://custom.example/api")`.
 
+### Error handling
+
+Catch `MatelabError` for one application-level fallback, or a specific subclass when recovery differs:
+
+| Error | Meaning and normal response |
+|---|---|
+| `MatelabUsageError` | The call cannot be represented safely; correct its arguments. |
+| `MatelabAuthenticationError` | The Session is missing, expired, invalid, or rejected; refresh or authenticate again as appropriate. |
+| `MatelabProviderError` | The Provider rejected a valid request with a business error; inspect `code` and do not assume a mutation was applied. |
+| `MatelabTransportError` | The HTTP exchange failed; `status_code` is present for HTTP failures, and a mutation outcome may be unknown. |
+| `MatelabProtocolError` | The Provider response does not match the pinned Contract; treat it as Provider drift or an SDK defect. |
+| `MatelabVerificationError` | A mutation was acknowledged but its readback failed; the mutation may already have persisted. |
+
+`code`, `status_code`, and the sanitized `payload` are diagnostics. The `payload` shape may contain private wire
+field names and is not a stable Consumer interface; application control flow should use the exception class and
+documented scalar attributes. Never automatically retry a mutation solely because it raised a transport or
+verification error.
+
 ### Session ownership
 
 Each `AsyncMatelab` instance owns at most one current, process-local `Session`. The SDK injects its bearer
@@ -176,7 +194,7 @@ notebook selector used for upload:
 ```python
 import hashlib
 
-from matelab import RecordImportItem, RecordImportTemplate, TemplateRef
+from matelab import RecordImportItem, TemplateRef
 
 content = b"measurement data"
 staged = await client.records.stage_attachment(
@@ -188,7 +206,8 @@ staged = await client.records.stage_attachment(
 )
 result = await client.records.import_dataset(
     notebook=notebook,
-    template=RecordImportTemplate(template=TemplateRef(template_id=8), title="Example Template"),
+    template=TemplateRef(template_id=8),
+    template_title="Example Template",
     items=(
         RecordImportItem(
             record_uid="REC-IMPORT-001",
@@ -203,19 +222,17 @@ The same staged handle may instead be consumed by one safe update that adds a ne
 module:
 
 ```python
-from matelab import RecordFormAttachmentFieldAddition, RecordPatch
+from matelab import RecordFormAttachmentFieldAddition
 
 # Alternative to the import above; do not run both with the same staged handle.
 result = await client.records.update(
     source,
-    RecordPatch(
-        attachment_changes=(
-            RecordFormAttachmentFieldAddition(
-                module="Attachments",
-                name="Measurement",
-                attachment=staged,
-            ),
-        )
+    attachment_changes=(
+        RecordFormAttachmentFieldAddition(
+            module="Attachments",
+            name="Measurement",
+            attachment=staged,
+        ),
     ),
 )
 ```
@@ -295,11 +312,9 @@ Provider returns members for an unstable first group and user search is unpaged,
 Notebook create/update and direct sharing keep write acknowledgement separate from what a readback can prove:
 
 ```python
-from matelab import NotebookMetadata, NotebookSharePermissionGrant
-
-await client.notebooks.create(NotebookMetadata(title="Example Notebook"))
+await client.notebooks.create(title="Example Notebook")
 shares = await client.notebooks.share(notebook, [target.ref])
-updated = await client.notebooks.update_share(shares[0].ref, NotebookSharePermissionGrant(write=True, create=True))
+updated = await client.notebooks.update_share(shares[0].ref, write=True, create=True)
 ```
 
 Create returns `None` because the Provider returns no identity. Owned updates return the notebook row observed by
@@ -314,7 +329,7 @@ relation identities:
 ```python
 templates = await client.templates.list()
 market = await client.templates.search_market("calibration", page=1, page_size=20)
-content = await client.templates.read(templates.owned[0].ref)
+modules = await client.templates.read(templates.owned[0].ref)
 ```
 
 The market result reports the Provider `total_count`, the requested and effective page sizes, and a `has_more`
@@ -334,12 +349,10 @@ limitations are documented operation semantics rather than constant fields on ev
 Extended record reads stay behind the same `records` interface:
 
 ```python
-from matelab import RecordFieldExtraction, RecordLocator
+from matelab import RecordLocator
 
 exported = await client.records.export([RecordLocator(notebook=notebook, record=record)])
-matches = await client.records.search(
-    notebooks=[notebook], extractions=[RecordFieldExtraction(alias="notes", path=("Notes",))]
-)
+matches = await client.records.search(notebooks=[notebook], extractions={"notes": ("Notes",)})
 page = await client.records.page(notebook)
 deleted = await client.records.recycle_bin(notebook)
 relations = await client.records.relations(notebook=notebook, record=record)
@@ -354,12 +367,13 @@ remain unspecified, and no continuation token is invented.
 Record creation keeps blank creation and structured import as separate capabilities:
 
 ```python
-from matelab import RecordImportItem, RecordImportTemplate, TemplateRef
+from matelab import RecordImportItem, TemplateRef
 
 blank = await client.records.create_blank(notebook=notebook, title="Blank Record", record_uid="caller-generated-uid")
 imported = await client.records.import_dataset(
     notebook=notebook,
-    template=RecordImportTemplate(template=TemplateRef(template_id=8), title="Example Template"),
+    template=TemplateRef(template_id=8),
+    template_title="Example Template",
     items=[RecordImportItem(record_uid="import-uid", title="Imported", data={"Notes": "value"})],
 )
 ```
@@ -397,7 +411,7 @@ Attachment bytes are streamed and must be consumed or closed explicitly:
 from matelab import ByteRange
 
 comments = await client.records.comments(notebook=notebook, record=record)
-attachment = comments.comments[0].attachments[0]
+attachment = comments[0].attachments[0]
 async with await client.records.download_comment_attachment(attachment, byte_range=ByteRange.from_start(0)) as download:
     async for chunk in download:
         consume(chunk)
@@ -436,7 +450,7 @@ Staging mutations are never automatically retried.
 Literature identities distinguish the personal library, shared libraries and pending incoming copies:
 
 ```python
-from matelab import DoiMetadataSource, LiteratureMetadata
+from matelab import LiteratureMetadata
 
 libraries = await client.literature.libraries()
 page = await client.literature.list(libraries.personal.ref)
@@ -444,7 +458,7 @@ detail = await client.literature.read(page.items[0].ref)
 schema = await client.literature.creation_schema()
 
 if schema.metadata_extraction_available:
-    candidates = await client.literature.extract_metadata(DoiMetadataSource("10.0000/example"))
+    candidates = await client.literature.extract_metadata(doi="10.0000/example")
 
 await client.literature.create(LiteratureMetadata(title="Example import", doi="10.0000/example"), staged_pdf=staged)
 ```
@@ -467,10 +481,8 @@ stable `ByteRange` subset.
 The personal cloud-drive surface keeps root, folder, final file and temporary staging identities separate:
 
 ```python
-from matelab import CloudFolderMetadata
-
 listing = await client.cloud_drive.list()
-folder_result = await client.cloud_drive.create_folder(CloudFolderMetadata(name="Example data"))
+folder_result = await client.cloud_drive.create_folder(name="Example data")
 matches = await client.cloud_drive.bind_staged_file(staged, target=folder_result.folder)
 
 if len(matches) == 1:
@@ -479,13 +491,13 @@ if len(matches) == 1:
     )
 ```
 
-`CloudDriveListing` contains a typed file page, complete folder tree, quota usage and personal-root permissions rather
+`CloudDriveListing` contains a typed file page, complete folder snapshot, quota usage and personal-root permissions rather
 than flattening them into one ambiguous collection. Folder browse results retain their location; filename searches
 are explicitly root-wide and return `location=None` because the Provider omits each match's folder ID. Ordering has
 no stable ID tie-breaker (PCG-003, PVD-013).
 
 Folder create returns the Provider ID plus an optional observed folder, and all folder mutations read back the
-complete tree. Staged finalize accepts a completed `StagedFile`, then paginates the target folder and returns all
+complete folder snapshot. Staged finalize accepts a completed `StagedFile`, then paginates the target folder and returns all
 exact filename/hash/size matches; zero, one, or multiple results preserve missing and ambiguous observations without
 another result model. This is useful evidence, not an uploader-ownership guarantee: the Provider binds by
 temporary row ID without checking its owner (PVD-031), and finalize atomicity/idempotency remain absent (PCG-012).

{matelab_python_sdk-0.1.0a3 → matelab_python_sdk-0.1.0a4}/README.md

@@ -2,7 +2,7 @@
 
 Reusable async Python client for the Matelab Integration Contract.
 
-The current alpha is `0.1.0a3`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a4`. `[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.1.1` Contract Release. The sole release pin is
@@ -31,7 +31,7 @@ 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.0a3-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a4-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -56,6 +56,24 @@ async with AsyncMatelab() as client:
 `AsyncMatelab()` uses `https://matelab.iphy.ac.cn/api` by default. Pass another Provider API root
 explicitly when needed, for example `AsyncMatelab("https://custom.example/api")`.
 
+### Error handling
+
+Catch `MatelabError` for one application-level fallback, or a specific subclass when recovery differs:
+
+| Error | Meaning and normal response |
+|---|---|
+| `MatelabUsageError` | The call cannot be represented safely; correct its arguments. |
+| `MatelabAuthenticationError` | The Session is missing, expired, invalid, or rejected; refresh or authenticate again as appropriate. |
+| `MatelabProviderError` | The Provider rejected a valid request with a business error; inspect `code` and do not assume a mutation was applied. |
+| `MatelabTransportError` | The HTTP exchange failed; `status_code` is present for HTTP failures, and a mutation outcome may be unknown. |
+| `MatelabProtocolError` | The Provider response does not match the pinned Contract; treat it as Provider drift or an SDK defect. |
+| `MatelabVerificationError` | A mutation was acknowledged but its readback failed; the mutation may already have persisted. |
+
+`code`, `status_code`, and the sanitized `payload` are diagnostics. The `payload` shape may contain private wire
+field names and is not a stable Consumer interface; application control flow should use the exception class and
+documented scalar attributes. Never automatically retry a mutation solely because it raised a transport or
+verification error.
+
 ### Session ownership
 
 Each `AsyncMatelab` instance owns at most one current, process-local `Session`. The SDK injects its bearer
@@ -150,7 +168,7 @@ notebook selector used for upload:
 ```python
 import hashlib
 
-from matelab import RecordImportItem, RecordImportTemplate, TemplateRef
+from matelab import RecordImportItem, TemplateRef
 
 content = b"measurement data"
 staged = await client.records.stage_attachment(
@@ -162,7 +180,8 @@ staged = await client.records.stage_attachment(
 )
 result = await client.records.import_dataset(
     notebook=notebook,
-    template=RecordImportTemplate(template=TemplateRef(template_id=8), title="Example Template"),
+    template=TemplateRef(template_id=8),
+    template_title="Example Template",
     items=(
         RecordImportItem(
             record_uid="REC-IMPORT-001",
@@ -177,19 +196,17 @@ The same staged handle may instead be consumed by one safe update that adds a ne
 module:
 
 ```python
-from matelab import RecordFormAttachmentFieldAddition, RecordPatch
+from matelab import RecordFormAttachmentFieldAddition
 
 # Alternative to the import above; do not run both with the same staged handle.
 result = await client.records.update(
     source,
-    RecordPatch(
-        attachment_changes=(
-            RecordFormAttachmentFieldAddition(
-                module="Attachments",
-                name="Measurement",
-                attachment=staged,
-            ),
-        )
+    attachment_changes=(
+        RecordFormAttachmentFieldAddition(
+            module="Attachments",
+            name="Measurement",
+            attachment=staged,
+        ),
     ),
 )
 ```
@@ -269,11 +286,9 @@ Provider returns members for an unstable first group and user search is unpaged,
 Notebook create/update and direct sharing keep write acknowledgement separate from what a readback can prove:
 
 ```python
-from matelab import NotebookMetadata, NotebookSharePermissionGrant
-
-await client.notebooks.create(NotebookMetadata(title="Example Notebook"))
+await client.notebooks.create(title="Example Notebook")
 shares = await client.notebooks.share(notebook, [target.ref])
-updated = await client.notebooks.update_share(shares[0].ref, NotebookSharePermissionGrant(write=True, create=True))
+updated = await client.notebooks.update_share(shares[0].ref, write=True, create=True)
 ```
 
 Create returns `None` because the Provider returns no identity. Owned updates return the notebook row observed by
@@ -288,7 +303,7 @@ relation identities:
 ```python
 templates = await client.templates.list()
 market = await client.templates.search_market("calibration", page=1, page_size=20)
-content = await client.templates.read(templates.owned[0].ref)
+modules = await client.templates.read(templates.owned[0].ref)
 ```
 
 The market result reports the Provider `total_count`, the requested and effective page sizes, and a `has_more`
@@ -308,12 +323,10 @@ limitations are documented operation semantics rather than constant fields on ev
 Extended record reads stay behind the same `records` interface:
 
 ```python
-from matelab import RecordFieldExtraction, RecordLocator
+from matelab import RecordLocator
 
 exported = await client.records.export([RecordLocator(notebook=notebook, record=record)])
-matches = await client.records.search(
-    notebooks=[notebook], extractions=[RecordFieldExtraction(alias="notes", path=("Notes",))]
-)
+matches = await client.records.search(notebooks=[notebook], extractions={"notes": ("Notes",)})
 page = await client.records.page(notebook)
 deleted = await client.records.recycle_bin(notebook)
 relations = await client.records.relations(notebook=notebook, record=record)
@@ -328,12 +341,13 @@ remain unspecified, and no continuation token is invented.
 Record creation keeps blank creation and structured import as separate capabilities:
 
 ```python
-from matelab import RecordImportItem, RecordImportTemplate, TemplateRef
+from matelab import RecordImportItem, TemplateRef
 
 blank = await client.records.create_blank(notebook=notebook, title="Blank Record", record_uid="caller-generated-uid")
 imported = await client.records.import_dataset(
     notebook=notebook,
-    template=RecordImportTemplate(template=TemplateRef(template_id=8), title="Example Template"),
+    template=TemplateRef(template_id=8),
+    template_title="Example Template",
     items=[RecordImportItem(record_uid="import-uid", title="Imported", data={"Notes": "value"})],
 )
 ```
@@ -371,7 +385,7 @@ Attachment bytes are streamed and must be consumed or closed explicitly:
 from matelab import ByteRange
 
 comments = await client.records.comments(notebook=notebook, record=record)
-attachment = comments.comments[0].attachments[0]
+attachment = comments[0].attachments[0]
 async with await client.records.download_comment_attachment(attachment, byte_range=ByteRange.from_start(0)) as download:
     async for chunk in download:
         consume(chunk)
@@ -410,7 +424,7 @@ Staging mutations are never automatically retried.
 Literature identities distinguish the personal library, shared libraries and pending incoming copies:
 
 ```python
-from matelab import DoiMetadataSource, LiteratureMetadata
+from matelab import LiteratureMetadata
 
 libraries = await client.literature.libraries()
 page = await client.literature.list(libraries.personal.ref)
@@ -418,7 +432,7 @@ detail = await client.literature.read(page.items[0].ref)
 schema = await client.literature.creation_schema()
 
 if schema.metadata_extraction_available:
-    candidates = await client.literature.extract_metadata(DoiMetadataSource("10.0000/example"))
+    candidates = await client.literature.extract_metadata(doi="10.0000/example")
 
 await client.literature.create(LiteratureMetadata(title="Example import", doi="10.0000/example"), staged_pdf=staged)
 ```
@@ -441,10 +455,8 @@ stable `ByteRange` subset.
 The personal cloud-drive surface keeps root, folder, final file and temporary staging identities separate:
 
 ```python
-from matelab import CloudFolderMetadata
-
 listing = await client.cloud_drive.list()
-folder_result = await client.cloud_drive.create_folder(CloudFolderMetadata(name="Example data"))
+folder_result = await client.cloud_drive.create_folder(name="Example data")
 matches = await client.cloud_drive.bind_staged_file(staged, target=folder_result.folder)
 
 if len(matches) == 1:
@@ -453,13 +465,13 @@ if len(matches) == 1:
     )
 ```
 
-`CloudDriveListing` contains a typed file page, complete folder tree, quota usage and personal-root permissions rather
+`CloudDriveListing` contains a typed file page, complete folder snapshot, quota usage and personal-root permissions rather
 than flattening them into one ambiguous collection. Folder browse results retain their location; filename searches
 are explicitly root-wide and return `location=None` because the Provider omits each match's folder ID. Ordering has
 no stable ID tie-breaker (PCG-003, PVD-013).
 
 Folder create returns the Provider ID plus an optional observed folder, and all folder mutations read back the
-complete tree. Staged finalize accepts a completed `StagedFile`, then paginates the target folder and returns all
+complete folder snapshot. Staged finalize accepts a completed `StagedFile`, then paginates the target folder and returns all
 exact filename/hash/size matches; zero, one, or multiple results preserve missing and ambiguous observations without
 another result model. This is useful evidence, not an uploader-ownership guarantee: the Provider binds by
 temporary row ID without checking its owner (PVD-031), and finalize atomicity/idempotency remain absent (PCG-012).

{matelab_python_sdk-0.1.0a3 → matelab_python_sdk-0.1.0a4}/docs/roadmap.md

@@ -49,7 +49,7 @@ small domain-oriented public interface
 - Contract commit：`047746ad37d827a85f93d947942f1e5fab80d54c`
 - OpenAPI SHA-256：`1d437b071968d2df165c712092fba4a283832e0ac19bc791e0d5af82294d1cca`
 - Contract operation：71
-- SDK 当前版本：`0.1.0a3`
+- SDK 当前版本：`0.1.0a4`
 - Python：3.11+
 - 生成器：`datamodel-code-generator 0.71.0`
 
@@ -73,7 +73,7 @@ goal 期间不得跟踪 `matelab-spec/main`，也不得自动升级 Contract Rel
   领域 interface；
 - 71 条 Contract operation 的 public-interface、wire adapter、测试与 coverage；
 - opt-in 的隔离 Provider smoke；
-- reproducible `0.1.0a3` build。
+- reproducible `0.1.0a4` build。
 
 当前 operation coverage：71 implemented / 0 planned。每条 operation 的领域入口、稳定性和已知问题以
 [`operation-coverage.yaml`](operation-coverage.yaml) 为准。
@@ -908,3 +908,13 @@ reproducible build 基线。
 - records 与 literature 拆分为领域 package，wire model 继续只通过私有 namespace 使用；
 - Provider smoke 仅验证少量 SDK consumer flow，并与隔离测试服务的 `MATELAB_PROVIDER_*` 配置对齐；
 - Python 3.11 与 3.14 完整测试、生成检查、Ruff、Basedpyright、制品审计和安装后类型消费均作为发布门槛。
+
+## 28. `0.1.0a4` validation and package-boundary simplification
+
+本阶段保持 `matelab-spec v0.1.1` 和 71-operation 覆盖不变，完成全库精简后的发布收口：
+
+- 公共符号从 150 个进一步收敛到 126 个，简单输入直接使用关键字参数或已有领域值；
+- request wire validation 集中处理并只暴露脱敏的字段诊断，response schema mismatch 继续归类为 protocol error；
+- 收紧生成模型无法直接表达的 Contract 约束、并发 Session 替换、multipart 重放边界和 streaming 清理；
+- 所有业务能力统一进入 `matelab.domains`，根目录只保留 client、session、errors 和 transport 等核心模块；
+- release audit 从 `pyproject.toml` 读取唯一版本与 metadata 权威，并拒绝不安全或重复的制品成员。

{matelab_python_sdk-0.1.0a3 → matelab_python_sdk-0.1.0a4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "matelab-python-sdk"
-version = "0.1.0a3"
+version = "0.1.0a4"
 description = "Reusable async Python client for the Matelab Integration Contract"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -52,7 +52,6 @@ lint.extend-select = ["I"]
 include = ["src", "tests", "scripts"]
 exclude = ["src/matelab/_generated"]
 pythonVersion = "3.11"
-failOnWarnings = false
 
 [tool.pytest.ini_options]
 markers = [

{matelab_python_sdk-0.1.0a3 → matelab_python_sdk-0.1.0a4}/scripts/check_installed_package.py

@@ -5,13 +5,11 @@ from typing import cast
 
 import matelab
 
-_EXPECTED_PUBLIC_SYMBOLS = 150
-
 
 def main() -> None:
     exports = matelab.__all__
-    if len(exports) != _EXPECTED_PUBLIC_SYMBOLS or len(set(exports)) != _EXPECTED_PUBLIC_SYMBOLS:
-        raise RuntimeError(f"Expected {_EXPECTED_PUBLIC_SYMBOLS} unique public symbols, found {len(exports)}.")
+    if not exports or len(exports) != len(set(exports)):
+        raise RuntimeError("The installed package must expose a non-empty set of unique public symbols.")
     for name in exports:
         value = cast(object, getattr(matelab, name))
         module = cast(object, getattr(value, "__module__", ""))

{matelab_python_sdk-0.1.0a3 → matelab_python_sdk-0.1.0a4}/scripts/check_release.py

@@ -2,18 +2,24 @@
 
 import argparse
 import hashlib
+import stat
 import tarfile
+import tomllib
 from email import policy
 from email.parser import BytesParser
 from pathlib import Path, PurePosixPath
 from typing import cast
 from zipfile import ZipFile
 
-_VERSION = "0.1.0a3"
-_DIST_INFO = f"matelab_python_sdk-{_VERSION}.dist-info"
+_ROOT = Path(__file__).resolve().parents[1]
+_PROJECT = cast(dict[str, object], tomllib.loads((_ROOT / "pyproject.toml").read_text())["project"])
+_PROJECT_NAME = cast(str, _PROJECT["name"])
+_VERSION = cast(str, _PROJECT["version"])
+_DIST_INFO = f"{_PROJECT_NAME.replace('-', '_')}-{_VERSION}.dist-info"
 _EXPECTED_REQUIRES_DIST = {"httpx2<3,>=2.9.1", "pydantic<3,>=2.13.4"}
-_EXPECTED_LICENSE_FILES = {"LICENSE", "NOTICE"}
-_EXPECTED_AUTHOR_EMAIL = "朱天念 <zhutiannian@gmail.com>"
+_EXPECTED_LICENSE_FILES = set(cast(list[str], _PROJECT["license-files"]))
+_AUTHOR = cast(list[dict[str, str]], _PROJECT["authors"])[0]
+_EXPECTED_AUTHOR_EMAIL = f"{_AUTHOR['name']} <{_AUTHOR['email']}>"
 _ALLOWED_ENV_EXAMPLE = ".env.example"
 _FORBIDDEN_PARTS = {
     ".env",
@@ -43,12 +49,21 @@ def _sha256(path: Path) -> str:
 
 
 def _check_member_names(artifact: Path, names: list[str]) -> None:
+    if len(names) != len(set(names)):
+        raise ValueError(f"{artifact.name} contains duplicate archive member names")
     offenders: list[str] = []
     for name in names:
-        parts = PurePosixPath(name).parts
+        path = PurePosixPath(name)
+        parts = path.parts
         filename = parts[-1] if parts else ""
         if (
-            any(
+            not name
+            or "\\" in name
+            or path.is_absolute()
+            or any(part in {".", ".."} for part in parts)
+            or name not in {path.as_posix(), f"{path.as_posix()}/"}
+            or not parts
+            or any(
                 part in _FORBIDDEN_PARTS or (part.startswith(".env.") and part != _ALLOWED_ENV_EXAMPLE)
                 for part in parts
             )
@@ -65,10 +80,32 @@ def _check_payload(artifact: Path, name: str, payload: bytes) -> None:
         raise ValueError(f"{artifact.name} contains a private key marker in {name}")
 
 
+def _check_metadata(artifact: Path, metadata_bytes: bytes) -> None:
+    metadata = BytesParser(policy=policy.default).parsebytes(metadata_bytes)
+    requires_dist = set(cast(list[str], metadata.get_all("Requires-Dist", [])))
+    if metadata["Name"] != _PROJECT_NAME or metadata["Version"] != _VERSION:
+        raise ValueError(f"{artifact.name} contains unexpected name/version metadata")
+    if metadata["Requires-Python"] != _PROJECT["requires-python"]:
+        raise ValueError(f"{artifact.name} contains unexpected Requires-Python metadata")
+    if requires_dist != _EXPECTED_REQUIRES_DIST:
+        raise ValueError(f"{artifact.name} contains unexpected Requires-Dist metadata: {sorted(requires_dist)}")
+    if metadata["License-Expression"] != _PROJECT["license"]:
+        raise ValueError(f"{artifact.name} contains unexpected License-Expression metadata")
+    if set(metadata.get_all("License-File", [])) != _EXPECTED_LICENSE_FILES:
+        raise ValueError(f"{artifact.name} contains unexpected License-File metadata")
+    if metadata["Author-email"] != _EXPECTED_AUTHOR_EMAIL:
+        raise ValueError(f"{artifact.name} contains unexpected Author-email metadata")
+
+
 def _audit_wheel(path: Path) -> None:
     with ZipFile(path) as wheel:
-        names = wheel.namelist()
+        members = wheel.infolist()
+        names = [member.filename for member in members]
         _check_member_names(path, names)
+        for member in members:
+            member_type = stat.S_IFMT(member.external_attr >> 16)
+            if member_type not in {0, stat.S_IFREG, stat.S_IFDIR}:
+                raise ValueError(f"{path.name} contains unsupported archive member type: {member.filename}")
         required = {
             "matelab/__init__.py",
             "matelab/py.typed",
@@ -89,20 +126,7 @@ def _audit_wheel(path: Path) -> None:
                 _check_payload(path, name, wheel.read(name))
         metadata_bytes = wheel.read(f"{_DIST_INFO}/METADATA")
 
-    metadata = BytesParser(policy=policy.default).parsebytes(metadata_bytes)
-    requires_dist = set(cast(list[str], metadata.get_all("Requires-Dist", [])))
-    if metadata["Name"] != "matelab-python-sdk" or metadata["Version"] != _VERSION:
-        raise ValueError(f"{path.name} contains unexpected name/version metadata")
-    if metadata["Requires-Python"] != ">=3.11":
-        raise ValueError(f"{path.name} contains unexpected Requires-Python metadata")
-    if requires_dist != _EXPECTED_REQUIRES_DIST:
-        raise ValueError(f"{path.name} contains unexpected Requires-Dist metadata: {sorted(requires_dist)}")
-    if metadata["License-Expression"] != "Apache-2.0":
-        raise ValueError(f"{path.name} contains unexpected License-Expression metadata")
-    if set(metadata.get_all("License-File", [])) != _EXPECTED_LICENSE_FILES:
-        raise ValueError(f"{path.name} contains unexpected License-File metadata")
-    if metadata["Author-email"] != _EXPECTED_AUTHOR_EMAIL:
-        raise ValueError(f"{path.name} contains unexpected Author-email metadata")
+    _check_metadata(path, metadata_bytes)
 
 
 def _audit_sdist(path: Path) -> None:
@@ -110,14 +134,21 @@ def _audit_sdist(path: Path) -> None:
         members = source.getmembers()
         names = [member.name for member in members]
         _check_member_names(path, names)
+        for member in members:
+            if not (member.isfile() or member.isdir()):
+                raise ValueError(f"{path.name} contains unsupported archive member type: {member.name}")
         roots = {PurePosixPath(name).parts[0] for name in names}
         if len(roots) != 1:
             raise ValueError(f"{path.name} must contain exactly one top-level directory")
         root = roots.pop()
+        expected_root = f"{_PROJECT_NAME.replace('-', '_')}-{_VERSION}"
+        if root != expected_root or path.name != f"{root}.tar.gz":
+            raise ValueError(f"{path.name} contains an unexpected source-distribution root")
         required = {
             f"{root}/CHANGELOG.md",
             f"{root}/LICENSE",
             f"{root}/NOTICE",
+            f"{root}/PKG-INFO",
             f"{root}/README.md",
             f"{root}/pyproject.toml",
             f"{root}/src/matelab/__init__.py",
@@ -126,12 +157,20 @@ def _audit_sdist(path: Path) -> None:
         missing = sorted(required - set(names))
         if missing:
             raise ValueError(f"{path.name} is missing required files: {missing}")
+        metadata_bytes: bytes | None = None
         for member in members:
             if member.isfile():
                 extracted = source.extractfile(member)
                 if extracted is None:
                     raise ValueError(f"{path.name} could not read {member.name}")
-                _check_payload(path, member.name, extracted.read())
+                payload = extracted.read()
+                _check_payload(path, member.name, payload)
+                if member.name == f"{root}/PKG-INFO":
+                    metadata_bytes = payload
+        if metadata_bytes is None:
+            raise ValueError(f"{path.name} could not read PKG-INFO")
+
+    _check_metadata(path, metadata_bytes)
 
 
 def audit_artifact(path: Path) -> str: