dpe-hash 0.1.5__tar.gz

dpe_hash-0.1.5/.gitignore

@@ -0,0 +1,16 @@
+.idea/
+.vscode/
+__pycache__/
+*.pyc
+.DS_Store
+
+# Python / uv
+.venv/
+dist/
+
+# MkDocs build output
+site/
+
+# Environment variables (敏感配置)
+.env
+.env.*

dpe_hash-0.1.5/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TuringFocus Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dpe_hash-0.1.5/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.5
+Name: dpe-hash
+Version: 0.1.5
+Summary: DPE hash 契约的独立 hash 核心：零运行时依赖、纯 Python
+Project-URL: Homepage, https://github.com/A2C-SMCP/dpe-protocol
+Project-URL: Documentation, https://doc.turingfocus.cn/dpe/
+Project-URL: Repository, https://github.com/A2C-SMCP/dpe-protocol
+Author-email: TuringFocus Team <dev@turingfocus.cn>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# dpe-hash
+
+[DPE（Document / Page / Element）协议](https://doc.turingfocus.cn/dpe/)的独立 hash 核心：按 [hash 契约 1](https://doc.turingfocus.cn/dpe/latest/spec/hash-contract-1/) 计算元素、页、文档三层 hash（`dpe1:` 前缀），并导出契约常量。
+
+- 零运行时依赖、纯 Python（≥ 3.11），带类型标记（`py.typed`）；
+- 逐字节通过规范仓库的一致性向量；
+- 规范与源码：<https://github.com/A2C-SMCP/dpe-protocol>。
+
+```bash
+pip install "dpe-hash>=0.1.5,<0.2.0"
+```
+
+## 版本约定
+
+hash 契约升级对应 minor 版本（`0.2.0` = 契约 2），不影响 hash 行为的修订走 patch。依赖时锁定 minor：`dpe-hash>=0.1.5,<0.2.0`。
+
+## API
+
+```python
+from dpe_hash import content_hash, page_hash, doc_hash, object_hash, document_hashes
+
+h = content_hash({"category": "NarrativeText", "text": "Hello, DPE."})  # 元素对象
+p = page_hash({"title": "p1"}, [h])  # 页字段 + 已有 content_hash
+d = doc_hash({"file_type": "md", "title": "报告"}, [p])  # 文档字段 + 已有 page_hash
+assert d == object_hash({"file_type": "md", "title": "报告", "pages": [p]}, "document")  # 线上原像
+```
+
+| 入口 | 用途 |
+| --- | --- |
+| `content_hash(element, contract=CONTRACT)` | 元素对象的 `content_hash` |
+| `page_hash(page, element_hashes, contract)` | 页自身字段 + 已有的 content_hash 列表；`page` 带 `elements` 即报错 |
+| `doc_hash(document, page_hashes, contract)` | 文档自身字段 + 已有的 page_hash 列表，不需加载元素；`document` 带 `pages` 即报错 |
+| `object_hash(obj, kind, contract)` | 线上原像（页带 `elements`、文档带 `pages`），`kind` 为 `"element"` / `"page"` / `"document"` |
+| `document_hashes(expanded, contract)` | 展开视图一次算出三层，结果同向量的 `expected` |
+| `children(obj, kind, contract)` | 原像引用的下一层：页 → content_hash，文档 → page_hash，元素 → blob 引用 |
+| `parse_hash(s, contracts=SUPPORTED_CONTRACTS)` / `parse_blob_ref(s)` | 校验并拆分 `dpe1:<hex>` / `sha256:<hex>` |
+| `blob_ref(data)` | blob 字节的引用 `sha256:<hex>` |
+| `jcs(value)` | RFC 8785 规范化字符串 |
+
+逐层入口的参数是 TypedDict，便于在编译期发现字段拼错；从线上反序列化、未加类型的 JSON（`Any`）可以直接传入，已标注为 `dict[str, Any]` 的数据请用 `object_hash`（接受 `Mapping[str, Any]`），或先 `cast`。
+
+所有入口都对封闭 schema 做完整校验，未定义字段、未知 category / file_type、超过 2^53−1 的整数、NaN 等一律拒绝。
+
+**原位重算**（契约 1 §6）：各入口的 `contract` 参数决定按哪个契约计算。`DRILL_CONTRACT`（`dpe2`）是仅用于升级演练的假想契约，只在显式传入时接受，不在 `SUPPORTED_CONTRACTS` 中，`parse_hash` 默认拒绝它。
+
+## 常量与类型
+
+- `CONTRACT`（`"dpe1"`）、`SUPPORTED_CONTRACTS`（服务端 capabilities 的 `hash_contracts`）、`DRILL_CONTRACT`；
+- `FILE_TYPES`：file_type 封闭枚举，按规范顺序；`CATEGORY_CONTENT_FIELDS`：category → 允许的内容字段（只读映射）。两者与规范 `vectors/manifest.json` 一致，消费方直接 import，不维护副本；
+- TypedDict：`ElementObject`、`PageObject`、`DocumentObject`（线上原像），`PageFields`、`DocumentFields`（不含子列表），`ExpandedDocument` / `ExpandedPage`（展开视图），`DocumentHashes` / `PageHashes`（结果）。
+
+## 异常
+
+全部继承 `DpeHashError`（它是 `ValueError` 的子类）。每个异常带两个属性：`.code` 是规范错误码，`.path` 是出错位置的 RFC 6901 JSON Pointer（相对于传入的对象），可直接映射为 problem 体。
+
+| 异常 | `code` |
+| --- | --- |
+| `ValidationError`，及其子类 `UndefinedFieldError`、`FileTypeUnknownError`、`IntegerOutOfRangeError` | `DPE_VALIDATION` |
+| `CategoryUnknownError` | `DPE_CATEGORY_UNKNOWN` |
+| `ContractUnsupportedError` | `DPE_CONTRACT_UNSUPPORTED` |

dpe_hash-0.1.5/README.md

@@ -0,0 +1,60 @@
+# dpe-hash
+
+[DPE（Document / Page / Element）协议](https://doc.turingfocus.cn/dpe/)的独立 hash 核心：按 [hash 契约 1](https://doc.turingfocus.cn/dpe/latest/spec/hash-contract-1/) 计算元素、页、文档三层 hash（`dpe1:` 前缀），并导出契约常量。
+
+- 零运行时依赖、纯 Python（≥ 3.11），带类型标记（`py.typed`）；
+- 逐字节通过规范仓库的一致性向量；
+- 规范与源码：<https://github.com/A2C-SMCP/dpe-protocol>。
+
+```bash
+pip install "dpe-hash>=0.1.5,<0.2.0"
+```
+
+## 版本约定
+
+hash 契约升级对应 minor 版本（`0.2.0` = 契约 2），不影响 hash 行为的修订走 patch。依赖时锁定 minor：`dpe-hash>=0.1.5,<0.2.0`。
+
+## API
+
+```python
+from dpe_hash import content_hash, page_hash, doc_hash, object_hash, document_hashes
+
+h = content_hash({"category": "NarrativeText", "text": "Hello, DPE."})  # 元素对象
+p = page_hash({"title": "p1"}, [h])  # 页字段 + 已有 content_hash
+d = doc_hash({"file_type": "md", "title": "报告"}, [p])  # 文档字段 + 已有 page_hash
+assert d == object_hash({"file_type": "md", "title": "报告", "pages": [p]}, "document")  # 线上原像
+```
+
+| 入口 | 用途 |
+| --- | --- |
+| `content_hash(element, contract=CONTRACT)` | 元素对象的 `content_hash` |
+| `page_hash(page, element_hashes, contract)` | 页自身字段 + 已有的 content_hash 列表；`page` 带 `elements` 即报错 |
+| `doc_hash(document, page_hashes, contract)` | 文档自身字段 + 已有的 page_hash 列表，不需加载元素；`document` 带 `pages` 即报错 |
+| `object_hash(obj, kind, contract)` | 线上原像（页带 `elements`、文档带 `pages`），`kind` 为 `"element"` / `"page"` / `"document"` |
+| `document_hashes(expanded, contract)` | 展开视图一次算出三层，结果同向量的 `expected` |
+| `children(obj, kind, contract)` | 原像引用的下一层：页 → content_hash，文档 → page_hash，元素 → blob 引用 |
+| `parse_hash(s, contracts=SUPPORTED_CONTRACTS)` / `parse_blob_ref(s)` | 校验并拆分 `dpe1:<hex>` / `sha256:<hex>` |
+| `blob_ref(data)` | blob 字节的引用 `sha256:<hex>` |
+| `jcs(value)` | RFC 8785 规范化字符串 |
+
+逐层入口的参数是 TypedDict，便于在编译期发现字段拼错；从线上反序列化、未加类型的 JSON（`Any`）可以直接传入，已标注为 `dict[str, Any]` 的数据请用 `object_hash`（接受 `Mapping[str, Any]`），或先 `cast`。
+
+所有入口都对封闭 schema 做完整校验，未定义字段、未知 category / file_type、超过 2^53−1 的整数、NaN 等一律拒绝。
+
+**原位重算**（契约 1 §6）：各入口的 `contract` 参数决定按哪个契约计算。`DRILL_CONTRACT`（`dpe2`）是仅用于升级演练的假想契约，只在显式传入时接受，不在 `SUPPORTED_CONTRACTS` 中，`parse_hash` 默认拒绝它。
+
+## 常量与类型
+
+- `CONTRACT`（`"dpe1"`）、`SUPPORTED_CONTRACTS`（服务端 capabilities 的 `hash_contracts`）、`DRILL_CONTRACT`；
+- `FILE_TYPES`：file_type 封闭枚举，按规范顺序；`CATEGORY_CONTENT_FIELDS`：category → 允许的内容字段（只读映射）。两者与规范 `vectors/manifest.json` 一致，消费方直接 import，不维护副本；
+- TypedDict：`ElementObject`、`PageObject`、`DocumentObject`（线上原像），`PageFields`、`DocumentFields`（不含子列表），`ExpandedDocument` / `ExpandedPage`（展开视图），`DocumentHashes` / `PageHashes`（结果）。
+
+## 异常
+
+全部继承 `DpeHashError`（它是 `ValueError` 的子类）。每个异常带两个属性：`.code` 是规范错误码，`.path` 是出错位置的 RFC 6901 JSON Pointer（相对于传入的对象），可直接映射为 problem 体。
+
+| 异常 | `code` |
+| --- | --- |
+| `ValidationError`，及其子类 `UndefinedFieldError`、`FileTypeUnknownError`、`IntegerOutOfRangeError` | `DPE_VALIDATION` |
+| `CategoryUnknownError` | `DPE_CATEGORY_UNKNOWN` |
+| `ContractUnsupportedError` | `DPE_CONTRACT_UNSUPPORTED` |

dpe_hash-0.1.5/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "dpe-hash"
+version = "0.1.5"
+description = "DPE hash 契约的独立 hash 核心：零运行时依赖、纯 Python"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+# 仓库根 LICENSE 的副本（构建后端只收录包目录内的文件），测试断言两者一致
+license-files = ["LICENSE"]
+authors = [
+    {name = "TuringFocus Team", email = "dev@turingfocus.cn"}
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+]
+# 零运行时依赖是硬约束（内核直接依赖本包），tools/check_packages.py 在 CI 中断言
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/A2C-SMCP/dpe-protocol"
+Documentation = "https://doc.turingfocus.cn/dpe/"
+Repository = "https://github.com/A2C-SMCP/dpe-protocol"
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dpe_hash"]
+
+# 测试依赖 workspace 根的 conftest 与仓库 vectors/，不随 sdist 分发
+[tool.hatch.build.targets.sdist]
+exclude = ["tests"]

dpe_hash-0.1.5/src/dpe_hash/__init__.py

@@ -0,0 +1,86 @@
+"""dpe-hash：DPE hash 契约的独立 hash 核心。
+
+零运行时依赖、纯 Python；内核与 dpe-sdk 都直接依赖本包，不另行维护 hash 实现。
+实现 hash 契约 1（spec/hash-contract-1.md），并导出契约常量、三层对象类型与带规范错误码的异常。
+"""
+
+from importlib.metadata import version
+
+from dpe_hash.constants import (
+    CATEGORY_CONTENT_FIELDS,
+    CONTRACT,
+    DRILL_CONTRACT,
+    FILE_TYPES,
+    SUPPORTED_CONTRACTS,
+)
+from dpe_hash.contract1 import (
+    blob_ref,
+    children,
+    content_hash,
+    doc_hash,
+    document_hashes,
+    object_hash,
+    page_hash,
+    parse_blob_ref,
+    parse_hash,
+)
+from dpe_hash.errors import (
+    CategoryUnknownError,
+    ContractUnsupportedError,
+    DpeHashError,
+    FileTypeUnknownError,
+    IntegerOutOfRangeError,
+    UndefinedFieldError,
+    ValidationError,
+)
+from dpe_hash.jcs import jcs
+from dpe_hash.models import (
+    DocumentFields,
+    DocumentHashes,
+    DocumentObject,
+    ElementObject,
+    ExpandedDocument,
+    ExpandedPage,
+    ObjectKind,
+    PageFields,
+    PageHashes,
+    PageObject,
+)
+
+__version__ = version("dpe-hash")
+
+__all__ = [
+    "CATEGORY_CONTENT_FIELDS",
+    "CONTRACT",
+    "DRILL_CONTRACT",
+    "FILE_TYPES",
+    "SUPPORTED_CONTRACTS",
+    "CategoryUnknownError",
+    "ContractUnsupportedError",
+    "DocumentFields",
+    "DocumentHashes",
+    "DocumentObject",
+    "DpeHashError",
+    "ElementObject",
+    "ExpandedDocument",
+    "ExpandedPage",
+    "FileTypeUnknownError",
+    "IntegerOutOfRangeError",
+    "ObjectKind",
+    "PageFields",
+    "PageHashes",
+    "PageObject",
+    "UndefinedFieldError",
+    "ValidationError",
+    "__version__",
+    "blob_ref",
+    "children",
+    "content_hash",
+    "doc_hash",
+    "document_hashes",
+    "jcs",
+    "object_hash",
+    "page_hash",
+    "parse_blob_ref",
+    "parse_hash",
+]

dpe_hash-0.1.5/src/dpe_hash/constants.py

@@ -0,0 +1,68 @@
+"""契约常量：消费方（内核、服务端、dpe-sdk）直接 import，不自行维护副本。
+
+测试断言它们与 ``vectors/manifest.json`` 一致（``file_types`` / ``category_content_fields``）。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import MappingProxyType
+
+__all__ = [
+    "CATEGORY_CONTENT_FIELDS",
+    "CONTRACT",
+    "DRILL_CONTRACT",
+    "FILE_TYPES",
+    "SUPPORTED_CONTRACTS",
+]
+
+#: 当前契约版本（hash 值前缀），各 hash 函数的默认契约。
+CONTRACT = "dpe1"
+
+#: 本包支持的真实契约，供服务端 capabilities 的 ``hash_contracts`` 使用。
+SUPPORTED_CONTRACTS: tuple[str, ...] = ("dpe1",)
+
+#: 假想契约 ``dpe2``，**仅用于契约升级演练**（vectors/README.md）：摘要输入为 ASCII ``dpe2``
+#: 后接 JCS 原像字节。不在 ``SUPPORTED_CONTRACTS`` 中：只有调用方显式传 ``contract="dpe2"``
+#: 时 hash 函数才接受它，``parse_hash`` 默认拒绝。
+DRILL_CONTRACT = "dpe2"
+
+#: category 封闭枚举 → 允许的内容字段（契约 1 §4.1，字段按表中顺序）。
+#: 元素对象另有必有的 ``category`` 与可选的 ``metadata``，不在此列。
+CATEGORY_CONTENT_FIELDS: Mapping[str, tuple[str, ...]] = MappingProxyType(
+    {
+        **{
+            c: ("text",)
+            for c in (
+                "UncategorizedText",
+                "CheckBox",
+                "CompositeElement",
+                "FigureCaption",
+                "NarrativeText",
+                "ListItem",
+                "Title",
+                "Address",
+                "EmailAddress",
+                "PageBreak",
+                "TableChunk",
+                "Header",
+                "Footer",
+                "CodeSnippet",
+                "PageNumber",
+                "FormKeysValues",
+                "tfchat",
+            )
+        },
+        "Table": ("text", "text_as_html"),
+        "Formula": ("text", "text_as_html"),
+        "Image": ("text", "image_blob", "image_mime_type"),
+    }
+)
+
+#: file_type 封闭枚举（core.md §2.5，按规范顺序）。
+FILE_TYPES: tuple[str, ...] = (
+    "bmp", "csv", "doc", "docx", "eml", "epub", "heic", "html", "jpg", "json", "md", "msg",
+    "ndjson", "odt", "org", "pdf", "png", "ppt", "pptx", "rst", "rtf", "tiff", "tsv", "txt",
+    "wav", "xls", "xlsx", "xml", "zip", "java_repo", "python_repo", "javascript_repo",
+    "typescript_repo", "unk", "empty", "tfchat", "jira_project", "jira_issue",
+)  # fmt: skip

dpe_hash-0.1.5/src/dpe_hash/contract1.py

@@ -0,0 +1,377 @@
+"""hash 契约 1（``dpe1:``）——spec/hash-contract-1.md 的实现。
+
+契约 1 是三层同构的 tree：元素、页、文档三层对象统一为
+
+    H(obj) = "dpe1:" + hex(sha256(utf8(JCS(norm(obj)))))
+
+``norm``：递归删除值为 null 的键（缺省 ≡ null）；三层 metadata 字段缺省视同 ``{}``（§3.2）。
+三层对象都是封闭 schema，未定义字段一律拒绝（§3.4）。页没有页号，顺序只由上层数组表达。
+
+本模块是唯一的规范化与校验实现，全部公开函数都只是它的不同入口：
+
+- ``content_hash`` / ``page_hash`` / ``doc_hash``：逐层，用已有的子 hash 上溯（内核按页增量维护）；
+- ``object_hash``：直接接受线上原像（页带 ``elements``、文档带 ``pages``，服务端校验用）；
+- ``document_hashes``：展开视图一次算出三层；
+- ``children``：对象引用的下一层（缺失清单）。
+
+``contract`` 参数用于契约 1 §6 的原位重算；``dpe2`` 只在显式传入时接受（见 ``DRILL_CONTRACT``）。
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from collections.abc import Collection, Mapping, Sequence
+from typing import Any
+
+from dpe_hash.constants import (
+    CATEGORY_CONTENT_FIELDS,
+    CONTRACT,
+    DRILL_CONTRACT,
+    FILE_TYPES,
+    SUPPORTED_CONTRACTS,
+)
+from dpe_hash.errors import (
+    CategoryUnknownError,
+    ContractUnsupportedError,
+    FileTypeUnknownError,
+    UndefinedFieldError,
+    ValidationError,
+)
+from dpe_hash.jcs import canonical, pointer
+from dpe_hash.models import (
+    DocumentFields,
+    DocumentHashes,
+    ElementObject,
+    ExpandedDocument,
+    ObjectKind,
+    PageFields,
+    PageHashes,
+)
+
+__all__ = [
+    "blob_ref",
+    "children",
+    "content_hash",
+    "doc_hash",
+    "document_hashes",
+    "object_hash",
+    "page_hash",
+    "parse_blob_ref",
+    "parse_hash",
+]
+
+#: 各契约的摘要前缀字节：dpe2 = ASCII "dpe2" ‖ 原像（vectors/README.md）
+_SALT = {"dpe1": b"", DRILL_CONTRACT: b"dpe2"}
+_FILE_TYPES = frozenset(FILE_TYPES)
+_HEX64 = re.compile(r"[0-9a-f]{64}")
+#: 本包认识的全部契约（真实契约 + 演练契约）；hash 值的前缀不在其中即 DPE_CONTRACT_UNSUPPORTED
+_KNOWN_CONTRACTS = frozenset({*SUPPORTED_CONTRACTS, DRILL_CONTRACT})
+_BLOB_PREFIX = "sha256:"
+
+_PAGE_FIELDS = frozenset({"title", "page_metadata"})
+_DOCUMENT_FIELDS = frozenset({"file_type", "title", "doc_metadata"})
+
+
+# ---------------------------------------------------------------------------
+# 值格式（§1）
+# ---------------------------------------------------------------------------
+
+
+def _salt(contract: str) -> bytes:
+    if isinstance(contract, str) and (
+        contract in SUPPORTED_CONTRACTS or contract == DRILL_CONTRACT
+    ):
+        return _SALT[contract]
+    raise ContractUnsupportedError(f"不支持的 hash 契约：{contract!r}")
+
+
+def _digest(preimage: str, contract: str, salt: bytes) -> str:
+    return f"{contract}:{hashlib.sha256(salt + preimage.encode('utf-8')).hexdigest()}"
+
+
+def _split_hash(value: object, accepted: frozenset[str], at: str) -> tuple[str, str]:
+    if not isinstance(value, str):
+        raise ValidationError(f"hash 值必须是字符串，实际为 {type(value).__name__}", at)
+    prefix, sep, hexpart = value.partition(":")
+    if not sep:
+        raise ContractUnsupportedError("hash 值缺少契约前缀", at)
+    if prefix not in accepted:
+        raise ContractUnsupportedError(f"未知或不支持的契约前缀：{prefix!r}", at)
+    if not _HEX64.fullmatch(hexpart):
+        raise ValidationError("hash 值的摘要部分必须是 64 位小写 hex", at)
+    return prefix, hexpart
+
+
+def _blob_hex(value: object, at: str) -> str:
+    if not isinstance(value, str):
+        raise ValidationError(f"blob 引用必须是字符串，实际为 {type(value).__name__}", at)
+    if not value.startswith(_BLOB_PREFIX) or not _HEX64.fullmatch(value[len(_BLOB_PREFIX) :]):
+        raise ValidationError("blob 引用必须是 sha256:<64 位小写 hex>", at)
+    return value[len(_BLOB_PREFIX) :]
+
+
+def parse_hash(value: str, contracts: Collection[str] = SUPPORTED_CONTRACTS) -> tuple[str, str]:
+    """校验并拆分 hash 值，返回 ``(契约, 64 位 hex)``。
+
+    无前缀或前缀不在 ``contracts`` 内抛 ``ContractUnsupportedError``（契约 1 §1）；摘要格式不对抛
+    ``ValidationError``。默认只接受 ``SUPPORTED_CONTRACTS``，升级演练需显式传入
+    ``(*SUPPORTED_CONTRACTS, DRILL_CONTRACT)``。``contracts`` 是契约的集合，不能是单个字符串；
+    其中出现本包不认识的契约抛 ``ContractUnsupportedError``。
+    """
+    if isinstance(contracts, str):
+        raise TypeError('contracts 必须是契约的集合（如 ("dpe1",)），不能是单个字符串')
+    accepted = frozenset(contracts)
+    unknown = accepted - _KNOWN_CONTRACTS
+    if unknown:
+        raise ContractUnsupportedError(f"不支持的 hash 契约：{sorted(unknown)!r}")
+    return _split_hash(value, accepted, "")
+
+
+def parse_blob_ref(value: str) -> str:
+    """校验 blob 引用 ``sha256:<64 位小写 hex>``，返回 hex 部分；不合法抛 ``ValidationError``。"""
+    return _blob_hex(value, "")
+
+
+def blob_ref(data: bytes | bytearray | memoryview) -> str:
+    """blob 原始字节的引用 ``"sha256:<hex>"``（契约 1 §1）。"""
+    return _BLOB_PREFIX + hashlib.sha256(data).hexdigest()
+
+
+# ---------------------------------------------------------------------------
+# 三层对象的校验与规范化（§3–§5），返回 JCS 原像
+# ---------------------------------------------------------------------------
+
+
+def _mapping(value: object, at: str, what: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise ValidationError(f"{what}必须是 JSON 对象，实际为 {type(value).__name__}", at)
+    return value
+
+
+def _closed(obj: Mapping[str, Any], allowed: frozenset[str], at: str, what: str) -> None:
+    extra = sorted(str(k) for k in obj if k not in allowed)
+    if extra:
+        raise UndefinedFieldError(f"{what}不允许字段 {extra[0]!r}", at + pointer(extra[0]))
+
+
+def _opt_str(obj: Mapping[str, Any], field: str, at: str) -> str | None:
+    value = obj.get(field)
+    if value is not None and not isinstance(value, str):
+        raise ValidationError(
+            f"{field} 必须是字符串或 null，实际为 {type(value).__name__}", at + pointer(field)
+        )
+    return value
+
+
+def _metadata(obj: Mapping[str, Any], field: str, at: str) -> Mapping[str, Any]:
+    value = obj.get(field)
+    if value is None:
+        return {}  # 缺省视同 {}（§3.2）
+    return _mapping(value, at + pointer(field), f"{field} ")
+
+
+def _hash_list(value: object, contract: str, at: str) -> list[str]:
+    """子对象 hash 列表：每项必须是同一契约下的合法 hash 值（契约 1 §5）。
+
+    前缀不是受支持的契约 → ``ContractUnsupportedError``；是受支持的契约、但与本对象的契约不同
+    （契约混用）→ ``ValidationError``。「受支持」= ``SUPPORTED_CONTRACTS`` 加上本次调用显式选择的
+    契约：演练契约 dpe2 只在被选中时才算受支持，因此 dpe1 对象引用 dpe2 子 hash 与生产服务端一样
+    得到 ``DPE_CONTRACT_UNSUPPORTED``。
+    """
+    if isinstance(value, str) or not isinstance(value, (list, tuple)):
+        raise ValidationError(f"必须是 hash 值数组，实际为 {type(value).__name__}", at)
+    accepted = frozenset({*SUPPORTED_CONTRACTS, contract})
+    for i, item in enumerate(value):
+        prefix, _ = _split_hash(item, accepted, at + pointer(i))
+        if prefix != contract:
+            raise ValidationError(
+                f"子对象 hash 的契约 {prefix} 与本对象的契约 {contract} 不一致", at + pointer(i)
+            )
+    return list(value)
+
+
+def _element_preimage(element: object, at: str) -> str:
+    el = _mapping(element, at, "元素对象")
+    if "category" not in el:
+        raise ValidationError("元素对象缺少 category", at)
+    category = el["category"]
+    if not isinstance(category, str):
+        raise ValidationError("category 必须是字符串", at + pointer("category"))
+    allowed = CATEGORY_CONTENT_FIELDS.get(category)
+    if allowed is None:  # 封闭枚举，禁止退化为 text-only（§4）
+        raise CategoryUnknownError(f"未知 category：{category!r}", at + pointer("category"))
+    _closed(el, frozenset({"category", "metadata", *allowed}), at, f"{category} 元素")
+    obj: dict[str, Any] = {"category": category}
+    for field in allowed:
+        value = _opt_str(el, field, at)
+        if value is not None:
+            obj[field] = value
+    if "image_blob" in obj:
+        _blob_hex(obj["image_blob"], at + pointer("image_blob"))
+    obj["metadata"] = _metadata(el, "metadata", at)
+    return canonical(obj, strip_nulls=True, at=at)
+
+
+def _page_preimage(
+    page: Mapping[str, Any], element_hashes: object, contract: str, at: str, *, with_children: bool
+) -> str:
+    """``with_children``：``page`` 自带 ``elements`` 键（线上原像或展开视图），其值由调用方处理。"""
+    allowed = _PAGE_FIELDS | {"elements"} if with_children else _PAGE_FIELDS
+    if not with_children and "elements" in page:
+        raise UndefinedFieldError(
+            "page_hash 的页字段不得带 elements（子 hash 单独传入；线上原像请用 object_hash）",
+            at + pointer("elements"),
+        )
+    _closed(page, allowed, at, "页对象")
+    obj: dict[str, Any] = {}
+    title = _opt_str(page, "title", at)
+    if title is not None:
+        obj["title"] = title
+    obj["page_metadata"] = _metadata(page, "page_metadata", at)
+    obj["elements"] = _hash_list(element_hashes, contract, at + pointer("elements"))
+    return canonical(obj, strip_nulls=True, at=at)
+
+
+def _document_preimage(
+    document: Mapping[str, Any], page_hashes: object, contract: str, at: str, *, with_children: bool
+) -> str:
+    allowed = _DOCUMENT_FIELDS | {"pages"} if with_children else _DOCUMENT_FIELDS
+    if not with_children and "pages" in document:
+        raise UndefinedFieldError(
+            "doc_hash 的文档字段不得带 pages（子 hash 单独传入；线上原像请用 object_hash）",
+            at + pointer("pages"),
+        )
+    _closed(document, allowed, at, "文档对象")
+    if "file_type" not in document:
+        raise ValidationError("文档对象缺少 file_type", at)
+    file_type = document["file_type"]
+    if not isinstance(file_type, str):
+        raise ValidationError("file_type 必须是字符串", at + pointer("file_type"))
+    if file_type not in _FILE_TYPES:
+        raise FileTypeUnknownError(f"未知 file_type：{file_type!r}", at + pointer("file_type"))
+    obj: dict[str, Any] = {"file_type": file_type}
+    title = _opt_str(document, "title", at)
+    if title is not None:
+        obj["title"] = title
+    obj["doc_metadata"] = _metadata(document, "doc_metadata", at)
+    obj["pages"] = _hash_list(page_hashes, contract, at + pointer("pages"))
+    return canonical(obj, strip_nulls=True, at=at)
+
+
+def _required(obj: Mapping[str, Any], field: str, at: str, what: str) -> Any:
+    if field not in obj:
+        raise ValidationError(f"{what}缺少 {field}", at)
+    return obj[field]
+
+
+def _preimage(obj: object, kind: ObjectKind, contract: str) -> str:
+    """线上原像的 JCS 原像（``object_hash`` / ``children`` 共用）。"""
+    if kind == "element":
+        return _element_preimage(obj, "")
+    if kind == "page":
+        page = _mapping(obj, "", "页对象")
+        elements = _required(page, "elements", "", "页对象")
+        return _page_preimage(page, elements, contract, "", with_children=True)
+    if kind == "document":
+        document = _mapping(obj, "", "文档对象")
+        pages = _required(document, "pages", "", "文档对象")
+        return _document_preimage(document, pages, contract, "", with_children=True)
+    raise ValueError(f"未知的对象层级：{kind!r}")
+
+
+# ---------------------------------------------------------------------------
+# 公开入口
+# ---------------------------------------------------------------------------
+
+
+def content_hash(element: ElementObject, contract: str = CONTRACT) -> str:
+    """元素对象的 ``content_hash``（契约 1 §4）。"""
+    salt = _salt(contract)
+    return _digest(_element_preimage(element, ""), contract, salt)
+
+
+def page_hash(page: PageFields, element_hashes: Sequence[str], contract: str = CONTRACT) -> str:
+    """``page_hash``（契约 1 §5）：页自身字段 + 已有的 content_hash 列表（按页内顺序）。
+
+    ``page`` 带 ``elements`` 键即报错，避免两份元素列表的歧义；``element_hashes`` 中的错误
+    路径记为 ``/elements/<i>``。
+    """
+    salt = _salt(contract)
+    pre = _page_preimage(
+        _mapping(page, "", "页对象"), element_hashes, contract, "", with_children=False
+    )
+    return _digest(pre, contract, salt)
+
+
+def doc_hash(document: DocumentFields, page_hashes: Sequence[str], contract: str = CONTRACT) -> str:
+    """``doc_hash``（契约 1 §5）：文档自身字段 + 已有的 page_hash 列表（按页序），不需加载元素。
+
+    ``document`` 带 ``pages`` 键即报错，避免两份页序的歧义；``page_hashes`` 中的错误路径记为
+    ``/pages/<i>``。
+    """
+    salt = _salt(contract)
+    pre = _document_preimage(
+        _mapping(document, "", "文档对象"), page_hashes, contract, "", with_children=False
+    )
+    return _digest(pre, contract, salt)
+
+
+def object_hash(obj: Mapping[str, Any], kind: ObjectKind, contract: str = CONTRACT) -> str:
+    """线上原像的 hash：一步完成封闭 schema 校验、规范化、JCS 与摘要。
+
+    页对象须带 ``elements``、文档对象须带 ``pages``（子 hash 列表，契约须与 ``contract`` 一致）。
+    对同一文档，结果与 ``content_hash`` / ``page_hash`` / ``doc_hash`` 逐层相等。
+    """
+    salt = _salt(contract)
+    return _digest(_preimage(obj, kind, contract), contract, salt)
+
+
+def children(obj: Mapping[str, Any], kind: ObjectKind, contract: str = CONTRACT) -> list[str]:
+    """线上原像引用的下一层（先按 ``object_hash`` 的规则完整校验）。
+
+    页 → ``elements`` 的 content_hash；文档 → ``pages`` 的 page_hash；元素 → ``image_blob``
+    引用（没有则为空）。按出现顺序返回，重复保留，去重由调用方决定。
+    """
+    _salt(contract)
+    _preimage(obj, kind, contract)
+    if kind == "element":
+        blob = obj.get("image_blob")
+        return [blob] if isinstance(blob, str) else []
+    return list(obj["elements" if kind == "page" else "pages"])
+
+
+def document_hashes(document: ExpandedDocument, contract: str = CONTRACT) -> DocumentHashes:
+    """展开视图（vectors/README.md）的三层 hash。
+
+    结果形如 ``{"doc_hash", "pages": [{"page_hash", "elements"}…]}``，同向量的 ``expected``。
+
+    页序即 ``pages`` 数组顺序，页内元素序即 ``elements`` 数组顺序。用于整篇计算与契约 1 §6
+    的原位重算（按任一受支持契约重算已存的骨架与内容，结果按位置一一对应）。
+    """
+    salt = _salt(contract)
+    doc = _mapping(document, "", "文档")
+    pages = _required(doc, "pages", "", "文档")
+    if not isinstance(pages, (list, tuple)):
+        raise ValidationError("pages 必须是数组", pointer("pages"))
+    out_pages: list[PageHashes] = []
+    page_hashes: list[str] = []
+    for i, raw_page in enumerate(pages):
+        at = pointer("pages", i)
+        page = _mapping(raw_page, at, "页")
+        elements = _required(page, "elements", at, "页")
+        if not isinstance(elements, (list, tuple)):
+            raise ValidationError("elements 必须是数组", at + pointer("elements"))
+        element_hashes = [
+            _digest(_element_preimage(el, at + pointer("elements", j)), contract, salt)
+            for j, el in enumerate(elements)
+        ]
+        ph = _digest(
+            _page_preimage(page, element_hashes, contract, at, with_children=True), contract, salt
+        )
+        page_hashes.append(ph)
+        out_pages.append({"page_hash": ph, "elements": element_hashes})
+    dh = _digest(
+        _document_preimage(doc, page_hashes, contract, "", with_children=True), contract, salt
+    )
+    return {"doc_hash": dh, "pages": out_pages}

dpe_hash-0.1.5/src/dpe_hash/errors.py

@@ -0,0 +1,61 @@
+"""公开异常：调用方按类型或 ``code`` 分派，不解析消息字符串。
+
+``code`` 取规范错误码（core.md §6），服务端可直接映射为 problem 体；``path`` 是出错位置的
+RFC 6901 JSON Pointer，相对于传入函数的那个对象（如 ``/pages/0/elements/2/text_as_html``），
+出错位置就是对象本身时为空串。
+"""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+__all__ = [
+    "CategoryUnknownError",
+    "ContractUnsupportedError",
+    "DpeHashError",
+    "FileTypeUnknownError",
+    "IntegerOutOfRangeError",
+    "UndefinedFieldError",
+    "ValidationError",
+]
+
+
+class DpeHashError(ValueError):
+    """dpe-hash 全部异常的共同基类。"""
+
+    code: ClassVar[str]
+
+    def __init__(self, message: str, path: str = "") -> None:
+        super().__init__(f"{message}（位置 {path}）" if path else message)
+        self.message = message
+        self.path = path
+
+
+class ValidationError(DpeHashError):
+    """输入不合法（``DPE_VALIDATION``）：类型错误、非法 hash / blob 引用、契约混用等。"""
+
+    code = "DPE_VALIDATION"
+
+
+class UndefinedFieldError(ValidationError):
+    """封闭 schema 违例：对象出现规范未定义（或其 category 未允许）的字段（core.md §2）。"""
+
+
+class FileTypeUnknownError(ValidationError):
+    """file_type 不在封闭枚举内（core.md §2.5）。"""
+
+
+class IntegerOutOfRangeError(ValidationError):
+    """整数字面量绝对值超过 2^53−1（契约 1 §3.3、core.md §2.6）。"""
+
+
+class CategoryUnknownError(DpeHashError):
+    """category 不在契约的封闭枚举内（``DPE_CATEGORY_UNKNOWN``，契约 1 §4）。"""
+
+    code = "DPE_CATEGORY_UNKNOWN"
+
+
+class ContractUnsupportedError(DpeHashError):
+    """hash 契约不被支持，或 hash 值缺少 / 带未知契约前缀（``DPE_CONTRACT_UNSUPPORTED``）。"""
+
+    code = "DPE_CONTRACT_UNSUPPORTED"

dpe_hash-0.1.5/src/dpe_hash/jcs.py

@@ -0,0 +1,146 @@
+"""RFC 8785 JCS 序列化（spec/hash-contract-1.md §3.3）。
+
+按规范文本独立实现，与 ``scripts/gen_vectors.py`` 的一致由向量逐字节校验，而不是共享代码。
+
+输入是 JSON 值：``None`` / ``bool`` / ``int`` / ``float`` / ``str``，对象为 ``Mapping``（键必须是
+``str``），数组为 ``list`` 或 ``tuple``。其余类型、NaN / Infinity、超过 2^53−1 的整数、含孤立代理项
+的字符串一律拒绝，异常带出错位置的 JSON Pointer。
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from collections.abc import Mapping
+from json.encoder import encode_basestring
+from typing import Any
+
+from dpe_hash.errors import DpeHashError, IntegerOutOfRangeError, ValidationError
+
+__all__ = ["jcs"]
+
+_MAX_SAFE_INTEGER = 2**53 - 1
+_SURROGATE = re.compile("[\ud800-\udfff]")
+
+
+class _Invalid(Exception):
+    """序列化中途的错误：逐层回溯时收集路径分量，最外层再转换为公开异常。"""
+
+    def __init__(self, error: type[DpeHashError], message: str) -> None:
+        self.error = error
+        self.message = message
+        self.segments: list[str | int] = []
+
+
+def pointer(*segments: str | int) -> str:
+    """把路径分量拼成 RFC 6901 JSON Pointer。"""
+    return "".join(
+        "/" + (str(s) if isinstance(s, int) else s.replace("~", "~0").replace("/", "~1"))
+        for s in segments
+    )
+
+
+def _number(x: int | float) -> str:
+    """ECMAScript ``Number::toString``（base 10）。"""
+    if isinstance(x, int):
+        if abs(x) > _MAX_SAFE_INTEGER:
+            raise _Invalid(IntegerOutOfRangeError, f"整数超出 ±(2^53−1)：{int.__repr__(x)}")
+        return int.__repr__(x)  # 不走子类（如 IntEnum）的 __str__
+    if math.isnan(x) or math.isinf(x):
+        raise _Invalid(ValidationError, "JCS 不允许 NaN / Infinity")
+    if x == 0:
+        return "0"  # 含 -0.0
+    sign = x < 0
+    # float.__repr__ 即最短往返十进制（如 "0.1"、"1e-07"、"1.5e+22"）。直接解析该字符串，
+    # 不经 Decimal：Decimal 运算受线程全局的 decimal 上下文（精度）影响，会静默改变 hash。
+    mantissa, _, exponent = float.__repr__(abs(x)).partition("e")
+    int_part, _, frac_part = mantissa.partition(".")
+    digits = int_part + frac_part
+    n = len(int_part) + int(exponent or "0")  # value = 0.digits × 10^n
+    stripped = digits.lstrip("0")
+    n -= len(digits) - len(stripped)
+    s = stripped.rstrip("0")
+    k = len(s)
+    if k <= n <= 21:
+        body = s + "0" * (n - k)
+    elif 0 < n <= 21:
+        body = s[:n] + "." + s[n:]
+    elif -6 < n <= 0:
+        body = "0." + "0" * (-n) + s
+    else:
+        mantissa = s[0] + ("." + s[1:] if k > 1 else "")
+        e = n - 1
+        body = f"{mantissa}e{'+' if e >= 0 else '-'}{abs(e)}"
+    return ("-" if sign else "") + body
+
+
+def _string(s: str) -> str:
+    if _SURROGATE.search(s):
+        raise _Invalid(ValidationError, "字符串含孤立代理项，不是合法的 Unicode")
+    # 标准库（ensure_ascii=False 时）的转义恰好是 JCS 要求的集合：
+    # " \ \b \f \n \r \t 与其余 < 0x20 的小写 \u00XX，其他字符原样输出
+    return encode_basestring(s)
+
+
+def _utf16_key(key: str) -> bytes:
+    return key.encode("utf-16-be")  # 大端字节序比较 = UTF-16 码元序
+
+
+def _serialize(value: Any, strip_nulls: bool) -> str:
+    if value is None:
+        return "null"
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    if isinstance(value, str):
+        return _string(value)
+    if isinstance(value, (int, float)):
+        return _number(value)
+    if isinstance(value, (dict, Mapping)):  # dict 在前：常见情形免走 ABC 检查
+        for key in value:
+            if not isinstance(key, str):
+                raise _Invalid(
+                    ValidationError, f"对象的键必须是字符串，实际为 {type(key).__name__}"
+                )
+            if _SURROGATE.search(key):
+                err = _Invalid(ValidationError, "键含孤立代理项，不是合法的 Unicode")
+                err.segments.append(key)
+                raise err
+        keys = sorted(
+            (k for k, v in value.items() if not (strip_nulls and v is None)), key=_utf16_key
+        )
+        parts = []
+        for key in keys:
+            try:
+                parts.append(f"{_string(key)}:{_serialize(value[key], strip_nulls)}")
+            except _Invalid as err:
+                err.segments.append(key)
+                raise
+        return "{" + ",".join(parts) + "}"
+    if isinstance(value, (list, tuple)):
+        items = []
+        for i, item in enumerate(value):  # 数组元素不受 null 删除影响
+            try:
+                items.append(_serialize(item, strip_nulls))
+            except _Invalid as err:
+                err.segments.append(i)
+                raise
+        return "[" + ",".join(items) + "]"
+    raise _Invalid(ValidationError, f"不是 JSON 值：{type(value).__name__}")
+
+
+def canonical(value: Any, *, strip_nulls: bool = False, at: str = "") -> str:
+    """JCS 规范化字符串；``strip_nulls`` 为 True 时同时递归删除值为 null 的键（契约 1 §3.2）。
+
+    ``at`` 是 ``value`` 自身的 JSON Pointer，用作异常路径的前缀。
+    """
+    try:
+        return _serialize(value, strip_nulls)
+    except _Invalid as err:
+        raise err.error(err.message, at + pointer(*reversed(err.segments))) from None
+
+
+def jcs(value: Any) -> str:
+    """把 JSON 值序列化为 RFC 8785 规范化字符串（不做 null 键删除等任何 DPE 规范化）。"""
+    return canonical(value)

dpe_hash-0.1.5/src/dpe_hash/models.py

@@ -0,0 +1,96 @@
+"""三层对象的类型（TypedDict，标准库实现）：供 mypy strict 下的调用方在编译期发现字段拼错。
+
+运行时校验（封闭 schema、各 category 允许的字段）由 hash 函数完成，与类型无关。
+TypedDict 在类型系统中是开放的：带多余键的字典（如带 ``elements`` 的页）仍可通过
+``PageFields`` 的类型检查。封闭 TypedDict（PEP 728）需要第三方的 ``typing_extensions``，与本包
+零依赖冲突，因此这类误用只在运行时拒绝（``page_hash`` / ``doc_hash`` 抛 ``UndefinedFieldError``）。
+
+- 线上原像（契约 1 §4–§5）：``ElementObject``、``PageObject``（带 ``elements``）、
+  ``DocumentObject``（带 ``pages``）；
+- 不含子对象列表的自身字段：``PageFields``、``DocumentFields``，配合 ``page_hash`` /
+  ``doc_hash`` 用已存的子 hash 上溯；
+- 展开视图（vectors/README.md）：``ExpandedDocument`` / ``ExpandedPage``，配合
+  ``document_hashes``；其输出为 ``DocumentHashes`` / ``PageHashes``。
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, NotRequired, Required, TypedDict
+
+__all__ = [
+    "DocumentFields",
+    "DocumentHashes",
+    "DocumentObject",
+    "ElementObject",
+    "ExpandedDocument",
+    "ExpandedPage",
+    "ObjectKind",
+    "PageFields",
+    "PageHashes",
+    "PageObject",
+]
+
+#: ``object_hash`` / ``children`` 的对象层级
+ObjectKind = Literal["element", "page", "document"]
+
+
+class ElementObject(TypedDict):
+    """元素对象（core.md §2.3）。内容字段是否允许取决于 ``category``（契约 1 §4.1）。"""
+
+    category: str
+    text: NotRequired[str | None]
+    text_as_html: NotRequired[str | None]
+    image_blob: NotRequired[str | None]
+    image_mime_type: NotRequired[str | None]
+    metadata: NotRequired[dict[str, Any] | None]
+
+
+class PageFields(TypedDict, total=False):
+    """页对象除 ``elements`` 之外的字段。"""
+
+    title: str | None
+    page_metadata: dict[str, Any] | None
+
+
+class PageObject(PageFields):
+    """页对象（core.md §2.2）：``elements`` 为 content_hash 列表。"""
+
+    elements: Required[list[str]]
+
+
+class DocumentFields(TypedDict):
+    """文档对象除 ``pages`` 之外的字段。"""
+
+    file_type: str
+    title: NotRequired[str | None]
+    doc_metadata: NotRequired[dict[str, Any] | None]
+
+
+class DocumentObject(DocumentFields):
+    """文档对象（core.md §2.1）：``pages`` 为 page_hash 列表。"""
+
+    pages: list[str]
+
+
+class ExpandedPage(PageFields):
+    """展开视图中的页：``elements`` 为元素对象本身。"""
+
+    elements: Required[list[ElementObject]]
+
+
+class ExpandedDocument(DocumentFields):
+    """展开视图中的文档：``pages`` 为展开的页。"""
+
+    pages: list[ExpandedPage]
+
+
+class PageHashes(TypedDict):
+    page_hash: str
+    elements: list[str]
+
+
+class DocumentHashes(TypedDict):
+    """``document_hashes`` 的结果，形状同向量的 ``expected``。"""
+
+    doc_hash: str
+    pages: list[PageHashes]