straw-queue 0.1.4__tar.gz → 0.1.6__tar.gz

straw_queue-0.1.6/.agents/skills/straw-protocol-review/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: straw-protocol-review
+description: Review or change straw's persistence, ownership, recovery, GC, publication and read protocols. Use for protocol review, TODO acceptance, TLA+ changes, or Rust changes affecting durable ordering, crash/retry, request/attempt/epoch admission, reader roots or authentication. Compare the human protocol document to TLA+, then TLA+ to actual implementation; identify discrepancies and validate fixes with relevant regressions.
+---
+
+# straw 协议审查
+
+以仓库根目录为工作目录。先读 `docs/DESIGN_zh.md`
+（英文版去掉 `_zh`），再按三部分中的“模型与实现对应”定位模型、调用链和测试。
+文档是人审查的规则入口；映射表只是导航，不能替代阅读当前源码。
+
+## 1. 确定规则与范围
+
+从用户要求、diff 和 `TODO.md` 确定受影响的规则：
+
+- **分布式协议 C1/C2/C4**：跨日志 handoff、请求/attempt/epoch、checkpoint 回退。
+- **WAL 与数据 I/O C3/R1–R4**：日志与派生状态恢复、准备与发布重试、认证读取、独立可见性与有限重试。
+- **所有权与 GC G1–G4**：完整根、认证与缓存、删除屏障与回执、writer 退休和条件活性。
+
+追踪一条完整流程，包括入口、成功返回、报错但已生效、崩溃恢复和重复调用。
+区分 accepted、applied、protected、reclaimed。禁止通过扩大环境假设或把失败步骤
+合成原子动作来消除反例。没有格式变化就保留现有 wire format 和 API。
+
+## 2. 文档 → TLA+
+
+逐条检查对应 `.tla`、`.cfg` 和 `verification/runners/check_tla.py` 的实际配置：
+
+1. 文档的状态、前置条件、持久化点、错误路径分别对应哪些变量和动作？
+2. 锁、write、sync、apply、release、unlink、目录屏障、receipt 的可观察顺序是否保留？
+3. 关键性质是否在运行配置中启用？正例能否成功，避免“一律拒绝”假安全？
+4. 负例是否因为指定不变量/时序性质失败？解析错误、超时和工具错误不是有效反例。
+5. 有限实例抽象了什么？跨日志模型的完整事务不能替代 WAL 的碎片写入模型。
+6. 活性是否单列公平性、锁/I/O 返回、环境稳定和实际调用者继续重试？永久 owner
+   与永久无效输入应有独立安全/拒绝场景，不能假设它们最终消失或成功。
+
+审查 `verification/environment_contracts.json` 和 `docs/DESIGN_zh.md#environment`：
+环境保证与 straw 调用者义务分别列出。尤其不能把“已认证闭包”“正确根集合”或
+“正确 callback”当成外部保证，跳过实际构造与调用。
+
+## 3. TLA+ → 实现
+
+从公开入口向下读真实 Rust/Python/FFI 调用路径，不能只核对同名 helper。
+对每个关键动作记录：实际函数、guard、数据身份、持久化效果、错误后可用状态和恢复入口。
+同时检查返回值和后续调用者是否真的遵守 guard。
+
+重点反查这些越界：
+
+- queue WAL 确认前释放 staging/根；旧 handoff 消耗新一代 staging。
+- 部分 apply、I/O 错误或 caught unwind 后仍允许写入、缓存回复或 GC；恢复用了另一条日志。
+- stale attempt/epoch 被新请求接受；旧成功请求因数据已回收而不能重放。
+- reader/checkpoint/其他队列/传递依赖根遗漏；锁外认证后没有锁内重查。
+- 缓存跨 pool/run/namespace/reference 复用；既有可变 owner 名不保护所请求的根。
+- unlink/NotFound 后目录屏障未完成就记回执；回执删除永久 tombstone。
+- writer fence 未排空旧 I/O；未认证结果就恢复 staging；release 与登记 settlement 混成一步。
+- warm index cache 跳过 frame/envelope/payload 校验；失败读取不关闭重开；永久损坏被当成功。
+
+对发现的实现错误，先保留可失败的实际回归，再修复并跑正常路径。
+修改模型和文档时同步中英文、规则 ID、映射和环境登记；不添加重复的协议正文。
+普通确定性 helper 优先编译器、Clippy 和有意义的边界测试，不重建局部证明体系。
+
+## 4. 验证与交付
+
+按风险运行 `CONTRIBUTING.md#checks` 中的命令。模型改动至少运行对应 area、
+关联组合模型和环境登记检查；完整版本验收运行全部保留模型、Rust/FFI 回归及 crash campaign。
+运行 Python 测试前确认加载的 native 扩展由当前源码构建，避免测试旧 wheel。
+只有新的修改、失败或未解决疑点才需要重复已通过的检查。
+
+输出须能让人复查：
+
+- 结论及受影响规则；文档→TLA、TLA→实现分别有哪些一致点和差异。
+- 每个问题的具体触发/崩溃窗口、影响、源码位置、复现及修复证据。
+- 实际运行命令、输入/工具版本或哈希、结果，以及未运行的部分。
+- 有意保留的抽象差异、环境前提和剩余风险；没有发现问题时也报告这些边界。
+- 删除验证时说明原来防止的错误、保留证据、减少的保证与维护成本；性能只报可比实测。
+
+有限模型检查、源码审查和具体回归是三种不同证据。不能把 CI 全绿写成完整实现等价证明，
+也不能仅删除 TODO 或改标记来宣布完成。只有对应交付物与验收结果齐全才勾选。

straw_queue-0.1.6/.agents/skills/straw-protocol-review/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "straw 协议审查"
+  short_description: "Review straw docs, TLA+ models and implementation consistency"
+  default_prompt: "Use $straw-protocol-review to review the affected protocol flows, compare docs to TLA+ and TLA+ to implementation, and validate any fixes with relevant evidence."

{straw_queue-0.1.4 → straw_queue-0.1.6}/.github/workflows/tests.yml

@@ -44,37 +44,6 @@ jobs:
             target/tla/**/*.cfg
           if-no-files-found: error
 
-  verus:
-    name: Verus / shard ${{ matrix.shard }}
-    runs-on: ubuntu-latest
-    timeout-minutes: 60
-    strategy:
-      fail-fast: false
-      matrix:
-        shard: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]
-    steps:
-      - uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@1.99.1
-        with:
-          components: rustc-dev, llvm-tools
-      - uses: actions/setup-python@v5
-        with:
-          python-version: '3.12'
-      - name: Verify pinned Rust contracts and semantic mutants
-        run: >-
-          python verification/runners/check_verus.py --download --timeout 600
-          --shard-index ${{ matrix.shard }} --shard-count 16
-      - uses: actions/upload-artifact@v4
-        if: always()
-        with:
-          name: verus-verification-${{ matrix.shard }}
-          path: |
-            target/verus/report.json
-            target/verus/environment_contracts.json
-            target/verus/**/*.log
-            target/verus/**/*.rs
-          if-no-files-found: error
-
   checks:
     name: Rust tests and code checks
     runs-on: ubuntu-latest
@@ -102,6 +71,14 @@ jobs:
           cargo clippy --locked --all-targets --features python -- -D warnings
       - name: Run Rust tests
         run: cargo test --locked
+      - name: Check concrete protocol mutation regressions
+        run: python verification/runners/check_mutations.py
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: implementation-mutations
+          path: target/implementation-mutations/
+          if-no-files-found: warn
 
   python:
     name: Full suite / Python ${{ matrix.python }}
@@ -138,7 +115,7 @@ jobs:
 
   verification:
     name: Verification passed
-    needs: [formal, verus, checks, python]
+    needs: [formal, checks, python]
     if: always()
     runs-on: ubuntu-latest
     timeout-minutes: 5
@@ -152,7 +129,7 @@ jobs:
           import os
 
           results = json.loads(os.environ["RESULTS"])
-          assert set(results) == {"formal", "verus", "checks", "python"}
+          assert set(results) == {"formal", "checks", "python"}
           failed = {name: job["result"] for name, job in results.items() if job["result"] != "success"}
           if failed:
               raise SystemExit(f"Verification did not pass: {failed}")

{straw_queue-0.1.4 → straw_queue-0.1.6}/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 [中文版](CHANGELOG_zh.md)
 
+## 0.1.6
+
+- Reuse confirmed writer-registry state and index operation lookup; rebuild after uncertain outcomes. Cache only successfully synchronized writer directories with pinned inode identity. Keep existing publication WAL barriers and wire formats.
+- Move physical GC deletion and directory synchronization outside the pool catalog lock. Bind receipts to the completed plan and support overlapping collectors without consuming newly added pending work.
+- Cache up to eight authenticated extent indexes for alternating reads. Extend protocol models and concrete regressions; add real Rust mutation checks to CI and a reproducible metadata-scaling probe. Metadata history/receipt retirement and compaction remain out of scope.
+
+## 0.1.5
+
+### Ownership safety
+
+- Fix reactivation reusing an existing public owner without checking that it protects the requested root, including owner changes after authentication outside the lock. Check the retained pack closure both initially and under the fresh lock; internal queue owners bind the reference digest. Correct reuse still succeeds; public owner reuse adds closure/metadata checks.
+- Preserve public APIs, WAL/pack formats and durability ordering. Add regressions for existing-owner and post-authentication changes, and for staging remaining protected until queue WAL confirmation.
+
+### Specification, verification and maintenance
+
+- Remove all Verus source, inline specifications, ghost state, library contracts, runner, negative controls and CI; simplify Rust wrappers. Remove six deterministic local TLA+ models while retaining complete protocol models and product fault regressions.
+- Extend cross-log attempt/epoch and checkpoint rewind, WAL caller/cache, reactivation, authenticated read, writer retirement and conditional-progress scenarios. Distinguish model checking, execution tests and source review without claiming complete implementation equivalence.
+- Merge design, protocol, environmental premises and model-to-code correspondence into the [design and spec](docs/DESIGN.md). Move application integration into usage and checks/builds/releases into contributing; update both languages and add the `straw-protocol-review` skill.
+- Delete per-iteration proof, measurement and acceptance reports. Retain only three public benchmarks cited by the performance guide and explicitly list them in source-package manifests. Their results describe the original 0.1.4 candidate, not this version's performance.
+
 ## 0.1.4
 
 ### Recovery and continuation
@@ -43,7 +63,7 @@
 
 - Scan source distributions and wheel contents, including native libraries, for local paths and recognizable credentials. Remap Rust build paths before compilation so released binaries omit local source, home and toolchain locations; CI checks artifacts before upload and rejects findings without printing matched secrets.
 - Require TLA+/Verus checks, semantic negative controls, environment-contract audits, Rust/Python tests, formatting and Clippy before release builds and publishing. TLC records its jar hash without enforcing a checksum; Verus logs distinguish successful proofs from expected semantic rejections. Verification files are organized by protocol, WAL, GC, storage and offline recovery, with independently reviewable environment assumptions.
-- Freeze new formal-verification work for this release. Integrated proofs cover specific production bodies and models; complete retain/reactivation, cross-log recovery, authentication and liveness composition remain deferred and receive regression/fault-injection coverage. See the [release scope and boundaries](docs/FORMAL_VERIFICATION.md#verification-scope-for-this-release). Passing tests does not complete these proofs, and prior performance measurements do not establish this build's throughput or latency.
+- Freeze new formal-verification work for this release. Integrated proofs cover specific production bodies and models; complete retain/reactivation, cross-log recovery, authentication and liveness composition remain deferred and receive regression/fault-injection coverage. That scope describes the historical release. Passing tests does not complete these proofs, and prior performance measurements do not establish this build's throughput or latency.
 
 ## 0.1.3
 
@@ -119,4 +139,4 @@ Each queue requires one externally fenced coordinator. Automatic failover,
 live-pack compaction, journal compaction and a general distributed application
 checkpoint transaction are not provided. Additional network filesystems require
 deployment validation. See the [filesystem requirements](docs/FILESYSTEM.md) and
-[protocol guarantees](docs/PROTOCOL_AND_VERIFICATION.md).
+[protocol guarantees](docs/DESIGN.md).

{straw_queue-0.1.4 → straw_queue-0.1.6}/CHANGELOG_zh.md

@@ -2,6 +2,26 @@
 
 [English](CHANGELOG.md)
 
+## 0.1.6
+
+- 复用已确认的 writer registry 状态并为操作查找建立索引；不确定结果后重建。只缓存完整同步成功的 writer 目录，并保持 inode 身份。保留既有 publication WAL 屏障与 wire format。
+- 将 GC 物理删除与目录同步移到 pool catalog 锁外；回执绑定本轮完成的计划，允许 collector 重叠执行且不消费新加入的 pending 工作。
+- 为交替读取缓存最多八条已认证 extent 索引。扩展协议模型与实际回归，将真实 Rust 代码变异检查加入 CI，新增可重放的元数据开销探针。暂不实现元数据历史／回执退休和压缩。
+
+## 0.1.5
+
+### 所有权安全
+
+- 修复 reactivation 复用既有公共 owner 名时没有确认其保护请求根的问题，包括锁外认证后 owner 被变更的竞态。在初次检查与重新加锁后核对实际 pack 闭包；内部 queue owner 绑定引用摘要。正确复用仍可成功，公共 owner 复用增加闭包／元数据检查。
+- 保持公开 API、WAL 和 pack 格式及持久化顺序。新增既有 owner／认证后变更回归，以及 queue WAL 确认前 staging 不得被消费的回归。
+
+### 规格、验证与维护
+
+- 完全移除 Verus 源码、内嵌规格、ghost state、库契约、运行器、负例与 CI，简化 Rust 包装层。删除六个确定性局部 TLA+ 模型，保留完整协议模型和产品故障回归。
+- 补齐跨日志 attempt／epoch 与 checkpoint 回退、WAL 调用者／缓存、reactivation、认证读取、writer 退休及条件进展场景。模型检查、实际回归和源码审查分别说明，不宣称完整实现等价证明。
+- 将设计、协议、环境假设及模型／实现对应合并到[设计与 spec](docs/DESIGN_zh.md)。应用集成并入使用指南，检查／构建／发布并入贡献指南；中英文同步，新增 `straw-protocol-review` skill。
+- 删除逐轮证明、测量和验收过程报告，仅保留性能文档引用的三份公开基准；源码包明确列出允许包含的数据。保留结果对应原 0.1.4 候选构建，不代表本版性能。
+
 ## 0.1.4
 
 ### 恢复与续读
@@ -43,7 +63,7 @@
 
 - 扫描源码分发包与 wheel 内容（包括原生库），检查本机路径和可识别的凭据。编译时 remap Rust 路径，避免发布二进制携带本机源码、用户目录和工具链位置；CI 上传产物前检查，发现问题即拒绝，报告不输出命中的秘密内容。
 - release 构建和发布以前置检查为条件，包括 TLA+／Verus、语义负例、environment contract 审计、Rust／Python 测试、格式和 Clippy。TLC 只记录 jar 哈希、不做校验；Verus 日志明确区分证明通过与预期语义拒绝。验证目录按协议、WAL、GC、存储与离线恢复组织，环境假设可独立审查。
-- 本次发布冻结新增形式化验证。已集成证明覆盖具体生产函数和模型；完整 retain／reactivation、跨日志恢复、认证与活性组合延期，以回归和故障注入测试覆盖。见[本次发布范围与边界](docs/FORMAL_VERIFICATION_zh.md#本次发布的验证范围)。测试通过不等于这些证明已完成，历史性能测量也不能代表当前构建的吞吐或延迟。
+- 本次发布冻结新增形式化验证。已集成证明覆盖具体生产函数和模型；完整 retain／reactivation、跨日志恢复、认证与活性组合延期，以回归和故障注入测试覆盖。该范围描述当时的版本。测试通过不等于这些证明已完成，历史性能测量也不能代表当前构建的吞吐或延迟。
 
 ## 0.1.3
 
@@ -80,4 +100,4 @@ straw 首次发布：面向 AI 应用、基于文件系统的持久化队列与
 - 本地与多机 I/O benchmark、应用负载采集与重放、独立协议模型，以及进程崩溃与恢复检查。
 - CPython 3.10–3.13 的 Linux x86_64 wheel、自动化产物测试与 PyPI Trusted Publishing、独立使用示例和配套中英文指南。
 
-每个队列需要一个由外部机制隔离保护的协调器。尚不提供自动故障切换、存活 pack 整理、日志压缩或通用分布式应用 checkpoint 事务。其他网络文件系统需要单独验证部署语义。详见[文件系统要求](docs/FILESYSTEM_zh.md)与[协议保证](docs/PROTOCOL_AND_VERIFICATION_zh.md)。
+每个队列需要一个由外部机制隔离保护的协调器。尚不提供自动故障切换、存活 pack 整理、日志压缩或通用分布式应用 checkpoint 事务。其他网络文件系统需要单独验证部署语义。详见[文件系统要求](docs/FILESYSTEM_zh.md)与[协议保证](docs/DESIGN_zh.md)。

straw_queue-0.1.6/CONTRIBUTING.md

@@ -0,0 +1,145 @@
+# Contributing
+
+[中文版](CONTRIBUTING_zh.md)
+
+Read the [design and spec](docs/DESIGN.md) before changing durable ordering,
+recovery, ownership or authentication. Use the
+[straw-protocol-review skill](.agents/skills/straw-protocol-review/SKILL.md)
+to compare rules to TLA+, then trace the models to actual callers.
+
+Protocol changes should explain success, uncertain effects, crash/retry and
+compatibility. Add a reproducer for a real failure boundary and preserve a valid
+success path. Update the rule, model, caller and regression together. Ordinary
+local functions use compiler checks, Clippy and meaningful tests; do not rebuild
+per-function proof scaffolding. Unknown wire versions fail explicitly; framing
+changes require a format version.
+
+When changing an environmental premise, update its stable ID in
+[environment_contracts.json](verification/environment_contracts.json), the
+[spec](docs/DESIGN.md#environment), consuming models and sensitivity controls.
+Do not turn straw caller obligations into assumed filesystem guarantees.
+User/contributor guides have paired English `.md` and Chinese `_zh.md` versions;
+keep links, APIs and commands aligned. Application codecs and scheduling belong
+in the consuming application. The project uses the [MIT license](LICENSE).
+
+<a id="checks"></a>
+
+## Development and checks
+
+Use Rust 1.89+, a C linker, CPython 3.10+ and Java 17+ for TLC. Install the
+appropriate CPU/CUDA PyTorch build, then the editable development package:
+
+```sh
+python -m pip install -e '.[test,build,dev]'
+python -m black --check src tests examples tools verification
+python -m isort --check-only src tests examples tools verification
+cargo fmt --check
+cargo clippy --locked --all-targets -- -D warnings
+cargo clippy --locked --all-targets --features python -- -D warnings
+cargo test --locked
+python -m pytest
+python verification/runners/environment_manifest.py --check
+python verification/runners/check_tla.py
+python verification/runners/check_mutations.py
+python verification/protocol/checks/ownership_model.py --output /tmp/straw-ownership.json
+python verification/wal/checks/crash_campaign.py --output /tmp/straw-crashes.json
+```
+
+Rebuild/reinstall the native extension after Rust changes before running Python
+tests. For focused model work, use `check_tla.py --area wal --area gc` or
+`--case NAME`; run the full retained suite for release acceptance. Supply
+`--jar /path/to/tla2tools.jar` to select TLC; otherwise the runner downloads its
+configured release. It records the actual jar hash without enforcing a checksum.
+Logs, configs and counterexamples default to `target/tla/`. Positives must pass;
+negatives must fail the named invariant/temporal property. Parse errors, timeouts
+and launch failures never count as semantic rejection.
+
+The implementation mutation runner first passes an unmodified regression baseline,
+then edits isolated Rust copies to reuse uncertain registry state, cache a directory
+before its barriers, and skip GC parent barriers. Each must fail its named runtime
+test; compilation failures, missing tests and timeouts do not count. Reports default
+to `target/implementation-mutations/` and are retained by CI.
+
+The inventory checks declared IDs, paths and environment imports. The independent
+ownership model explores a bounded abstraction; the crash campaign checks byte
+prefixes/corruption and process exits. None certifies storage-service or power-loss
+behavior. Multi-client qualification is in [deployment](docs/FILESYSTEM.md#qualification).
+
+<a id="build"></a>
+
+## Build and check distributions
+
+Only the build machine needs Rust. Dependencies are declared in `pyproject.toml`
+and pinned by `Cargo.lock`:
+
+```sh
+python -m pip install build maturin twine
+python tools/release_build.py python -m build --wheel --sdist
+python -m twine check dist/*
+python tools/check_artifact_privacy.py dist/*
+python tools/check_wheel.py dist/<compatible-wheel>.whl --tests --report /tmp/straw-wheel-check.json
+python tools/release_build.py python -m pip wheel --no-deps dist/straw_queue-*.tar.gz --wheel-dir rebuilt
+```
+
+Use the actual compatible wheel filename and check the rebuilt wheel too.
+`check_wheel.py` creates a temporary environment, reuses installed NumPy/PyTorch,
+installs only the wheel without an index, rejects source imports and removes Rust
+from the test PATH. It runs examples, multiprocess recovery, benchmark/GC and
+trace checks; `--tests` adds the full Python suite, ownership model and crash campaign.
+
+The release wrapper removes local source/toolchain paths from Rust output.
+Artifact scans check archive contents for recognizable paths/secrets without
+printing their values. Rust SBOM generation is disabled because it embeds local
+crate paths; locked dependency versions remain in `Cargo.lock`.
+
+The release workflow targets Linux x86_64, CPython 3.10–3.13 and manylinux/glibc
+2.28+. Wheels use interpreter-specific buffer APIs, not ABI3. Local builds receive
+the platform tag they actually satisfy; never rename a tag to imply compatibility.
+Use the [manylinux workflow](.github/workflows/wheels.yml), or on Linux:
+
+```sh
+python -m pip install 'maturin[zig,patchelf]>=1.12,<2'
+python tools/release_build.py maturin build --release --locked --strip --zig \
+  --compatibility manylinux_2_28 --out dist
+```
+
+<a id="release"></a>
+
+## CI and releases
+
+[Tests](.github/workflows/tests.yml) run all TLA cases in 16 disjoint shards,
+formatting, both Clippy configurations, Rust tests and installed-wheel checks on
+CPython 3.10–3.13. [Wheels](.github/workflows/wheels.yml) requires that same-commit
+workflow, checks each portable wheel and a wheel rebuilt from the sdist, then
+uploads artifacts. Failed, cancelled, skipped or timed-out checks block release.
+Hosted CI uses a local Linux filesystem and CPU PyTorch; inspect hosted results
+separately from local checks and distributed deployment tests.
+
+For a release, align the versions in `Cargo.toml`, `pyproject.toml` and the
+`straw` entry in `Cargo.lock`; record compatibility/limits in the changelog.
+A matching new `v*` tag triggers publication of the already tested artifacts.
+PRs and manual dispatch build/test without publishing. Keep the source revision
+and wheel hash with release artifacts; rebuilding changes the artifact identity.
+Do not overwrite an existing published version/tag.
+
+The publish job uses GitHub OIDC with environment `pypi`. Configure PyPI's
+publisher for project `straw-queue`, repository `zhuzilin/straw`, workflow
+`wheels.yml`, environment `pypi`; the workflow filename has no directory prefix.
+No PyPI token is required by this workflow. See the
+[PyPI publisher setup](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/)
+for service setup. Both workflows also support manual dispatch from Actions.
+
+<a id="evidence"></a>
+
+## Reports and public benchmarks
+
+Keep per-run verification reports, attempted fixes, wheels, credentials, machine
+addresses, payloads and raw logs in CI artifacts or ignored local directories.
+Use fresh bounded test roots and clean them only after owned processes stop.
+
+`verification/measurements/` contains only selected public benchmark data cited
+by [benchmarks](docs/BENCHMARKS.md#published-results). A retained result needs
+workload/method, build/probe identity, units, samples and limitations. Compare
+payload sizes, publication granularity, fanout, durability and cache conditions;
+do not imply an old build's numbers describe current code. Record one-off task
+acceptance in the PR or CI result rather than adding another dated JSON file.

straw_queue-0.1.6/CONTRIBUTING_zh.md

@@ -0,0 +1,82 @@
+# 贡献指南
+
+[English](CONTRIBUTING.md)
+
+修改持久化顺序、恢复、所有权或认证前，阅读[设计与 spec](docs/DESIGN_zh.md)。使用 [straw-protocol-review skill](.agents/skills/straw-protocol-review/SKILL.md) 先核对规则与 TLA+，再沿实际调用链核对实现。
+
+协议改动说明成功、报错但已生效、崩溃／重试及兼容性。针对真实故障边界添加复现，并保留合法成功路径；同步规则、模型、调用者与回归。普通局部函数使用编译器、Clippy 和有意义的测试，不重建逐函数证明。未知 wire 版本明确拒绝，framing 变化需要格式版本。
+
+修改环境前提时，同步 [environment_contracts.json](verification/environment_contracts.json) 的稳定 ID、[spec](docs/DESIGN_zh.md#environment)、模型与敏感性负例，不把 straw 调用者义务改成文件系统假设。用户／贡献者文档有中英文两版，链接、API 与命令保持一致。应用 codec 与调度留在使用方。项目使用 [MIT 许可证](LICENSE)。
+
+<a id="checks"></a>
+
+## 开发与检查
+
+需要 Rust 1.89+、C linker、CPython 3.10+；TLC 需要 Java 17+。安装适合环境的 CPU/CUDA PyTorch，再安装开发包：
+
+```sh
+python -m pip install -e '.[test,build,dev]'
+python -m black --check src tests examples tools verification
+python -m isort --check-only src tests examples tools verification
+cargo fmt --check
+cargo clippy --locked --all-targets -- -D warnings
+cargo clippy --locked --all-targets --features python -- -D warnings
+cargo test --locked
+python -m pytest
+python verification/runners/environment_manifest.py --check
+python verification/runners/check_tla.py
+python verification/runners/check_mutations.py
+python verification/protocol/checks/ownership_model.py --output /tmp/straw-ownership.json
+python verification/wal/checks/crash_campaign.py --output /tmp/straw-crashes.json
+```
+
+Rust 修改后先重新构建／安装 native 扩展，再跑 Python 测试。局部模型工作可用 `check_tla.py --area wal --area gc` 或 `--case NAME`；发布验收运行全部保留场景。`--jar /path/to/tla2tools.jar` 指定 TLC，否则 runner 下载配置的发行包；记录实际 jar 哈希，不强制 checksum。日志、配置和反例默认在 `target/tla/`。正例必须通过，负例必须违反指定不变量／时序性质；解析错误、超时和启动失败不算检出。
+
+环境登记检查核对声明的 ID、路径与模块导入。独立所有权模型探索有限抽象；crash campaign 检查逐字节前缀／损坏和进程退出，都不认证存储服务故障或掉电行为。多客户端验证见[部署指南](docs/FILESYSTEM_zh.md#qualification)。
+
+实现 mutation runner 先通过未修改的回归基线，再在隔离 Rust 副本中复用不确定 registry 状态、提前缓存目录、跳过 GC 父目录屏障。每项必须使指定运行时测试失败；编译错误、缺失测试和超时不算检出。报告默认保存在 `target/implementation-mutations/`，由 CI 留存。
+
+<a id="build"></a>
+
+## 构建与检查发行包
+
+只有构建机需要 Rust。依赖由 `pyproject.toml` 声明、`Cargo.lock` 固定：
+
+```sh
+python -m pip install build maturin twine
+python tools/release_build.py python -m build --wheel --sdist
+python -m twine check dist/*
+python tools/check_artifact_privacy.py dist/*
+python tools/check_wheel.py dist/<compatible-wheel>.whl --tests --report /tmp/straw-wheel-check.json
+python tools/release_build.py python -m pip wheel --no-deps dist/straw_queue-*.tar.gz --wheel-dir rebuilt
+```
+
+使用实际兼容 wheel 的文件名，并检查从 sdist 重建的 wheel。`check_wheel.py` 创建临时环境，复用已安装 NumPy/PyTorch，不访问索引，只安装 wheel，拒绝源码导入，并从测试 PATH 移除 Rust。它运行示例、多进程恢复、benchmark／GC 和 trace 检查；`--tests` 加上全部 Python 回归、所有权模型和 crash campaign。
+
+发布包装器移除 Rust 产物中的本地源码／工具链路径。隐私检查扫描 archive 内可识别的路径／凭据，不打印匹配值。自动 Rust SBOM 因嵌入本地 crate 路径而关闭；依赖版本仍保存在 `Cargo.lock`。
+
+发布工作流面向 Linux x86_64、CPython 3.10–3.13、manylinux/glibc 2.28+。绑定使用区分解释器版本的 buffer API，不是 ABI3。本地构建只获得实际满足的平台 tag，不得改名冒充兼容性。使用 [manylinux 工作流](.github/workflows/wheels.yml)，或在 Linux 上运行：
+
+```sh
+python -m pip install 'maturin[zig,patchelf]>=1.12,<2'
+python tools/release_build.py maturin build --release --locked --strip --zig \
+  --compatibility manylinux_2_28 --out dist
+```
+
+<a id="release"></a>
+
+## CI 与发布
+
+[测试工作流](.github/workflows/tests.yml)运行全部 TLA 场景的 16 个独立分片、格式、两种 Clippy 配置、Rust 测试，以及 CPython 3.10–3.13 的已安装 wheel 检查。[Wheel 工作流](.github/workflows/wheels.yml)先要求同一提交通过上述工作流，再验证每个可移植 wheel 和从 sdist 重建的 wheel，之后上传产物。失败、取消、跳过或超时阻止发布。托管 CI 使用本地 Linux 文件系统和 CPU PyTorch；本地验收、托管结果与分布式部署测试分别确认。
+
+发布前同步 `Cargo.toml`、`pyproject.toml` 和 `Cargo.lock` 中 `straw` 的版本，并在 changelog 写明兼容性与限制。新的匹配 `v*` tag 触发发布已经测试过的产物；PR 和手动触发只构建／测试。源码 revision 与 wheel 哈希随发布产物保存，重新构建会改变产物身份。不要覆盖已发布版本／tag。
+
+发布使用 GitHub OIDC 和 `pypi` environment。PyPI publisher 配置为项目 `straw-queue`、仓库 `zhuzilin/straw`、workflow `wheels.yml`、environment `pypi`；workflow 文件名不带目录。本工作流不需要 PyPI token，服务端配置见 [PyPI 指南](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/)。两条工作流都支持从 Actions 手动触发。
+
+<a id="evidence"></a>
+
+## 报告与公开基准
+
+逐轮验证报告、尝试过程、wheel、凭据、机器地址、载荷和原始日志保存在 CI artifacts 或忽略的本地目录。使用全新、有界的测试根，仅在自有进程停止后清理。
+
+`verification/measurements/` 只保留[性能文档](docs/BENCHMARKS_zh.md#published-results)引用的精选公开基准：说明负载／方法、构建／探针身份、单位、样本和限制。比较时保持载荷大小、发布粒度、fanout、持久化与缓存条件可比，不把旧构建结果当成当前代码性能。单次任务验收写入 PR 或 CI 结果，不再新增逐日 JSON 流水账。

{straw_queue-0.1.4 → straw_queue-0.1.6}/Cargo.lock

@@ -370,7 +370,7 @@ checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
 
 [[package]]
 name = "straw"
-version = "0.1.4"
+version = "0.1.6"
 dependencies = [
  "pyo3",
  "serde",

{straw_queue-0.1.4 → straw_queue-0.1.6}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "straw"
-version = "0.1.4"
+version = "0.1.6"
 edition = "2024"
 rust-version = "1.89"
 license = "MIT"
@@ -9,8 +9,9 @@ description = "Durable shared-filesystem queues and immutable packed records"
 include = [
     "Cargo.toml", "Cargo.lock", "pyproject.toml", "README*.md", "LICENSE",
     "CHANGELOG*.md", "CONTRIBUTING*.md", ".github/workflows/*.yml",
+    ".agents/skills/straw-protocol-review/**",
     "rust/*.rs", "src/**/*.py", "docs/**/*.md", "examples/*.py",
-    "tests/*.py", "tests/native.rs", "verification/**/*.md", "verification/**/*.py", "verification/**/*.rs", "verification/**/*.c", "verification/environment_contracts.json", "verification/measurements/*.json", "verification/**/tla/*.tla", "verification/**/tla/*.cfg", "tools/*.py",
+    "tests/*.py", "tests/native.rs", "verification/**/*.md", "verification/**/*.py", "verification/**/*.rs", "verification/**/*.c", "verification/environment_contracts.json", "verification/measurements/20261026-release-comparison.json", "verification/measurements/20261026-release-100gb.json", "verification/measurements/20261026-release-visibility.json", "verification/**/tla/*.tla", "verification/**/tla/*.cfg", "tools/*.py",
 ]
 readme = "README.md"
 
@@ -33,9 +34,6 @@ pyo3 = { version = "0.23.5", optional = true }
 [dev-dependencies]
 tempfile = "3.27"
 
-[lints.rust]
-unexpected_cfgs = { level = "warn", check-cfg = ["cfg(straw_verus)"] }
-
 [[example]]
 name = "large_extent_probe"
 path = "verification/storage/probes/large_extent_probe.rs"

{straw_queue-0.1.4 → straw_queue-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: straw-queue
-Version: 0.1.4
+Version: 0.1.6
 Classifier: Development Status :: 3 - Alpha
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python :: 3
@@ -46,7 +46,7 @@ straw currently serves the rollout and training pipelines in
 **[slime](https://github.com/THUDM/slime)**, including rollout-to-rollout and
 rollout-to-training queues that share tensor storage. It is an independent AI
 application library, also suited to preprocessing and inference pipelines. See
-the [design rationale](docs/DESIGN.md) and [application integration](docs/APPLICATIONS.md).
+the [design rationale](docs/DESIGN.md) and [application integration](docs/USAGE.md#integration).
 
 ## Multi-machine parallel reads and writes
 
@@ -57,7 +57,7 @@ results and consumer progress, and coordinates shared ownership and GC through
 cross-client catalog locks. Reader pins and explicit completion signals protect
 data until every consumer has finished. See the
 [concurrency rules](docs/USAGE.md#concurrency-processes-and-threads) and
-[protocol](docs/PROTOCOL_AND_VERIFICATION.md).
+[protocol](docs/DESIGN.md).
 
 ## Avoid the small-file bottleneck
 
@@ -71,7 +71,7 @@ File counts grow with packs and writer lifetimes instead of individual samples;
 **Status:** early release, Linux/POSIX. One externally fenced coordinator per
 queue; no automatic leader election or journal/live-pack compaction. Applications
 must provide real reader-completion signals before reclamation. See
-[filesystem requirements](docs/FILESYSTEM.md) and [protocol guarantees](docs/PROTOCOL_AND_VERIFICATION.md).
+[filesystem requirements](docs/FILESYSTEM.md) and [protocol guarantees](docs/DESIGN.md).
 
 ## Install
 
@@ -85,7 +85,7 @@ pip selects a compatible wheel containing the Rust extension.
 **Installing a wheel does not require Rust or maturin.**
 NumPy and PyTorch are runtime dependencies; an existing compatible PyTorch
 installation can be reused. Distribution name: `straw-queue`; import: `straw`.
-See [supported platforms, offline installation and source builds](docs/BUILDING.md).
+See [supported platforms, offline installation and source builds](CONTRIBUTING.md#build).
 
 ## Write, read, keep, reclaim
 
@@ -172,34 +172,20 @@ workers stop. [Multi-host benchmarks and trace replay](docs/BENCHMARKS.md).
 
 ## Read next
 
-- [Rationale and architecture](docs/DESIGN.md)
-- [Records, tensors, tasks, recovery and GC](docs/USAGE.md)
-- [Filesystem deployment and file-count planning](docs/FILESYSTEM.md)
-- [Protocol, prior work and correctness boundaries](docs/PROTOCOL_AND_VERIFICATION.md)
-- [TLA+ / Verus verification](docs/FORMAL_VERIFICATION.md): layered coverage, production Rust proofs and counterexamples
-- [Executable verification](docs/VERIFICATION.md) and [binary format](docs/FORMAT.md)
-- [Wheel builds and release checks](docs/BUILDING.md)
-- [Release notes](CHANGELOG.md)
-- [Application integration](docs/APPLICATIONS.md) and [contributing](CONTRIBUTING.md)
-
-## Build and test on GitHub
-
-- [Full tests](.github/workflows/tests.yml): Rust tests, formatting and Clippy,
-  plus the complete Python suite, ownership model, crash campaign, examples and
-  bounded I/O/GC benchmark against installed wheels on CPython 3.10–3.13.
-- [Wheels](.github/workflows/wheels.yml): build and verify Linux x86_64 wheels
-  for CPython 3.10–3.13 (manylinux/glibc 2.28+), plus a source archive and rebuild
-  check. Download the outputs from the run's **Artifacts** section. Version-tag
-  pushes publish the verified artifacts to PyPI through Trusted Publishing. The
-  same-commit complete verification workflow must pass before package uploads.
-
-Both workflows support **Actions → select workflow → Run workflow**. Tests also
-run on pushes and pull requests; wheels run on pull requests and `v*` tags.
-Hosted CI uses a local filesystem and CPU PyTorch; deployment qualification on
-multiple JuiceFS clients and GPU training use [separate checks](docs/VERIFICATION.md).
-See [build and release instructions](docs/BUILDING.md).
+- [Design and protocol spec](docs/DESIGN.md): architecture, premises, distributed protocol/WAL/GC and model-to-code correspondence
+- [Usage](docs/USAGE.md): installation, APIs, recovery and application integration
+- [Filesystem deployment](docs/FILESYSTEM.md): mount requirements, storage planning and multi-client checks
+- [Benchmarks](docs/BENCHMARKS.md): measurement, trace replay and selected public results
+- [Binary format](docs/FORMAT.md): compatible readers and format changes
+- [Contributing](CONTRIBUTING.md): tests, builds and releases; [changelog](CHANGELOG.md)
+
+The [tests](.github/workflows/tests.yml) and [wheels](.github/workflows/wheels.yml)
+workflows provide CI checks and downloadable artifacts; version tags publish
+tested artifacts. See [contributing](CONTRIBUTING.md#release) for setup and release steps.
 
 ## License
 
 [MIT](LICENSE).
 
+[straw-protocol-review skill](.agents/skills/straw-protocol-review/SKILL.md): review document → TLA+ → implementation.
+