兼容与分发契约

首版交付 Python 库、可选能力、使用文档和版本说明。本文确定未发布首版的兼容边界；具体支持组合由实际验收建立，不能以计划代替结果。CI/CD继续负责工具和执行流程。

公共接口和版本

公开清单由 API 契约及实现的导出定义共同维护，包括类型、字段、枚举、异常、结果语义和扩展协议。以底层实现名称无下划线为理由直接使用内部类不属于兼容承诺。

0.x 补丁版本保持已发布公共签名、导入路径、错误类别、配置含义和交换格式兼容。行为纠错须列明影响和回归场景，不能借“错误修复”悄悄更换协议草案。需要破坏兼容时发布新的 0.x 次版本并提供迁移说明；正式 1.0 的弃用周期在进入该阶段前确定。

RTR v2、ASPA 标注实验性并报告确切草案版本；实验性不免除文档、测试和变更说明。升级固定草案时独立记录输入、结果及互操作差异，不能让依赖升级顺便改变算法。

弃用入口仍需 docstring、文档标记、引入/弃用版本及替代示例。使用适当 Python 弃用警告，不在包导入时向 stdout/stderr 打印公告。不维护并无用户依赖的内部实现兼容壳。

多种版本相互独立

不能只根据包版本猜数据库或草案版本。配置、普通 HTTP 响应和录制 schema 为 1；完整快照交换和数据库持久化 schema 为 2，以保留 ASPA 地址族。旧交换 schema 1 的显式兼容读取与旧数据库拒绝规则见各专题；不强制各格式同时升级。未知主格式版本拒绝，不能尝试部分加载后宣布成功。

包结构与安装隔离

采用 src/rpkiparrot 包布局，分发名与导入名均为 rpkiparrot，包含 py.typed。公共类型注解兼容 Python 3.11，不能在核心公共类型中泄漏可选框架类型。

核心直接第三方依赖仅 AnyIO；cli、http、sqlite、duckdb、service、trio、ssh 按总体设计隔离。ssh 提供 AsyncSSH 和加密私钥所需 bcrypt，内置适配器限 asyncio，Trio 启动时明确拒绝。extras 内的依赖范围由 pyproject.toml 声明，开发环境由 uv.lock 固定；发布候选仍须验证最低与最新允许组合。

http/service 显式依赖 HTTPX 与 HTTPcore；其公开传输、连接池及 network backend 接口负责 HTTP，底层默认 TCP/TLS 与核心使用相同的资源归属规则。额外的 HTTP 依赖仍延迟导入，核心及本地文件读取不要求安装。

导入核心包不读取文件、连接网络、建表、注册根日志或创建事件循环。可选模块在调用所选能力时给出 MissingExtraError；CLI 最小启动器能在没有 Typer 时提示安装方式。

用户直接依赖的版本范围允许受支持更新，开发/CI 锁文件另行固定环境。测试最低依赖与最新允许组合；不能只证明一个开发锁文件可运行。

Python 和平台

支持目标为常规 CPython 3.11、3.12、3.13、3.14；自动 CI 和候选验收仅运行 3.11、3.14，分别覆盖核心 asyncio 与 Trio。3.12、3.13 保留手动验收命令，当前提交未执行时标为未验证，不阻塞此次交付。声明 requires-python>=3.11 不自动承诺未知未来版本、PyPy、自由线程构建或所有原生扩展平台。

平台目标为 Windows 11 x86_64/AMD64，以及 macOS、Linux 的原生 x86_64/AMD64 与 ARM64，共五种组合；不含 Windows ARM64 和 32 位 x86/i686。按用户 2026-10-03 的确认，本次 CI/CD 和必需运行验收仅覆盖 Linux x86_64；其余四种组合与 Windows 11 一样，交付本机验收命令，当前候选未执行时标为未验证，不阻塞本次首版交付。此调整不表示这些平台不受支持，也不授予已经通过兼容性验收的声明。Windows ARM64 不安排适配或验收；OS 最低版本仍以实际依赖与验收结果固定，不能由纯 Python wheel 标签推导。

以上每种目标的验收命令覆盖常规 CPython 3.11–3.14，核心异步部分覆盖 asyncio/Trio，服务与内置 SSH 单独限 asyncio。Linux x86_64 的 3.11、3.14 用例、两数据库和 extras 检查仍全部必需；3.12、3.13 按需手动执行，其他平台若实际执行且遇到依赖或 OS 障碍，记录能力、版本及错误证据。历史提交的通过记录不能替代当前候选验收；缺少机器、解释器或未运行属于未验证，不能写成不支持或通过。

依赖制品核对与已知边界

2026-10-02 查阅了官方资料和 PyPI 元数据，原始响应、抓取时间及哈希保存在忽略的 .local-data/platform-audit/2026-10-02/。该次调查只证明制品可得性，不是本项目运行证据。随后分阶段的真实安装、行为和矩阵结果见 Issue #5；当前依赖范围见 pyproject.toml，最终制品按同一提交验收。

目前未发现必须排除五种目标之一的制品缺口；这不等于已证明完整依赖组合可用。安装时记录最终解析版本与 wheel/source 来源，不要求用户默认具备 Rust/C++ 编译器来掩盖缺失 wheel。Windows 的 Python win32 平台字符串不代表 32 位架构，应同时检查实际解释器架构和制品标签。

文档与制品

公共 API 实现、docstring、生成参考和可执行使用示例同项交付。实现前的设计示例明确标记不可运行，实际发布文档只能指向该版本可用入口；未交付功能保留计划标签。

从发布提交构建 sdist，再从 sdist 构建 wheel，并在隔离环境安装 wheel 检查元数据、public imports、类型标记、示例及 extras。wheel 不携带规范镜像、上游源码、生产快照或 .local-data。sdist 若携带测试样本，保留对应来源、许可证和小型必要数据。

已有 LICENSE 继续作为本项目许可入口；上游镜像、源码片段和向量保留原有许可与出处，不因纳入仓库而改变许可。

每个发布版本包含变更说明、已验证支持矩阵、协议基线和已知限制。发行包、文档、测试报告关联到同一提交。当前尚未上传正式发布。开发安装与检查命令见 README 和 AGENTS.md；制品检查脚本不执行 PyPI 上传。

性能与规模

首版使用 Python 内存索引，以规模与资源基线中的约 102 万 ROA 真实输入、三来源冗余及增长场景记录加载、索引构建、单条/批量查询、热配置、更新、事件、落盘、恢复和共享延迟。ASPA 单独按实际 customer/provider 分布测量，不把百万级 VRP 当作百万级 ASPA。测量环境、数据摘要、分布及峰值 RSS 必须可复现。

尚未测量时不填写吞吐或延迟保证。初始资源限制是工程防护值；发布前依据基准确认其可用性，并测试超限后旧有效状态保持、事件可恢复和进程能清理资源。普通 CI 使用可分发固定数据，本机大型导出只作显式基准输入。

Python 3.12、3.13 手动验收命令

自动工作流只选择 3.11、3.14。需要补验 3.12、3.13 时，在待验收提交的专用工作区执行：

uv python install 3.12 3.13
uv sync --locked --all-extras --python 3.11
uv run --locked nox -s tests-3.12 tests-3.13

Nox 使用各自的真实解释器运行全部用例、asyncio/Trio、SQLite/DuckDB，并保存各版本环境、JUnit 与合并覆盖率。首次调用可由 uv 安装所需 3.11 工具解释器；测试解释器仍分别是 3.12、3.13。串行排障可在 Nox 命令末尾追加 -- -n 0。

制品复验使用同批候选命令：先下载成功 CI 的 quality-and-package，核对其提交和哈希，再将示例循环的版本列表设为 3.12 3.13；Linux x86_64 使用 target_os=Linux target_arch=x86_64。不要为每个解释器重新构建并替换候选。未执行的版本保留为当前提交未验证，不影响既有支持目标。

macOS 与 Linux ARM64 本机验收命令

在待验收提交的干净工作区执行，预先安装 Git 和 uv。以下命令与 Linux CI 使用相同的 Nox 会话；会安装四个真实解释器并执行全部行为、双异步后端、两数据库、类型、文档、依赖范围及制品检查。不要设置 RPKIPARROT_TEST_BACKEND 只运行单个后端。

根据实际原生机器选一组参数：

随后在同一个 shell 中执行以下代码块（不在 Rosetta、容器架构仿真或跨架构 Python 中执行）：

(
set -eu
: "${target_os:?Select the native OS above}"
: "${target_arch:?Select the native architecture above}"
if [ "$(uname -s)" = Darwin ]; then
    sw_vers
    if [ "$(sysctl -in sysctl.proc_translated 2>/dev/null || true)" = 1 ]; then
        echo 'Requires native execution, not Rosetta' >&2
        exit 1
    fi
fi
unset RPKIPARROT_TEST_BACKEND
uv python install 3.11 3.12 3.13 3.14
uv sync --locked --all-extras --group dev --python 3.11
uv run --locked python scripts/environment.py --expect-os "$target_os" --expect-arch "$target_arch" --output reports/native-host.json
uv run --locked nox -s lint typing tests-3.11 tests-3.12 tests-3.13 tests-3.14 docs
uv run --locked nox -s package -- --require-clean
uv run --locked nox -s dependencies
)

保存 reports/、控制台输出、提交 SHA 和 dist/ 制品及其哈希。命令尚未在目标机器执行时，仍须保持未验证状态。对已选定的同一批候选文件，按 CI/CD 的本机复验命令检出确切提交并在四个解释器中复用原制品，不能用每台机器重新打包替代同批制品验收。

Windows 11 本机验收命令

当前 Windows 11 x86_64 保留为未验证；用户已确认本次交付提供执行命令。以下在原生 x64 Windows 11 PowerShell 中运行，不能用 Windows Server、ARM64 或32位解释器的结果替代。预先安装 Git 和 uv，仓库应为待验收提交；安装制品检查会联网解析已声明的依赖。

$platform = Get-CimInstance Win32_OperatingSystem
$platform.Caption
$platform.OSArchitecture
$cpu = Get-CimInstance Win32_Processor
if ($platform.Caption -notmatch 'Windows 11' -or $platform.OSArchitecture -notmatch '64' -or ($cpu.Architecture | Where-Object { $_ -ne 9 })) {
    throw 'Requires native Windows 11 x64'
}
uv python install 3.11 3.12 3.13 3.14
if ($LASTEXITCODE -ne 0) { throw 'Required interpreter installation failed' }
Remove-Item Env:RPKIPARROT_TEST_BACKEND -ErrorAction SilentlyContinue
uv sync --locked --all-extras --group dev --python 3.11
if ($LASTEXITCODE -ne 0) { throw 'Acceptance dependency installation failed' }
uv run --locked python scripts/environment.py --expect-os Windows11 --expect-arch x86_64 --output reports/windows11-host.json
if ($LASTEXITCODE -ne 0) { throw 'Required native platform check failed' }
uv run --locked nox -s lint typing tests-3.11 tests-3.12 tests-3.13 tests-3.14 docs
if ($LASTEXITCODE -ne 0) { throw 'Acceptance failed; retain reports and logs' }
uv run --locked nox -s package -- --require-clean
if ($LASTEXITCODE -ne 0) { throw 'Artifact acceptance failed' }
uv run --locked nox -s dependencies
if ($LASTEXITCODE -ne 0) { throw 'Dependency range acceptance failed' }

检查环境报告中的实际机器架构为 AMD64/x86_64，并保留 reports/、完整控制台输出以及 dist/ 的候选制品和 SHA-256。执行成功前不把该平台写为通过。已有候选制品可在对应的干净提交用 uv run --locked python scripts/package_validation.py --reuse --require-clean --dist PATH 验收；它核对源码、提交和原制品哈希，在临时目录独立重建 sdist 对比 wheel 内容，保留原候选文件。当前 Actions 不配置 Windows 或其他非 Linux x86_64 运行器。