feat(materials): share single-item reranking and complete receipt coverage

[loopx-agent]

A single material promoted from a long ranked backlog can displace more than 100 entries. Project adapters currently repeat the move policy and receipt chunking, and a visible Top-N can be mistaken for a fixed prefix.

This adds two helpers to the existing Material Lifecycle SDK: plan_material_single_move preserves all other relative order and derives bounds from the exact affected interval; material_rerank_receipt_chunks preserves complete coverage within the existing 100-ref receipt limit. Explicit protected ranks, existing proposal/receipt schemas, and owner-gated apply remain in place. English/Chinese capability docs and the managed skill describe the caller's preview, CAS, readback and rollback obligations.

Validation:

• 70 related tests pass, including backlog promotion, front-item demotion, explicit displaced-anchor rejection, invalid inputs, and a 167-ref transition with 100+67 receipt coverage through the existing SDK builders.
• Ruff and focused mypy pass; semantic advisory reports no new supported vocabulary carrier. Exact-head premerge passes 5 direct and 15 selected checks, with one inherited maintainability advisory in goal_topic_runtime.py.
• A private adapter uses the shared helpers: 12 existing regressions and 1,749 legal-move parity comparisons pass. A disposable real file source exercises the adapter's CAS, publication/readback, rollback, stale-preview rejection and late receipt-save recovery; its Core context is synthetic. Live source checks are read-only. Private data, paths, configuration and rehearsal scripts are excluded.

Placement/refactor: the existing Python Material Lifecycle contract module owns this SDK behavior; no typed ranking owner is introduced or duplicated. The companion extraction removes the active adapter's duplicate rules. This PR is based on main and contains none of #5562's project-ownership diff; that separate change is not required by these helpers.

This is an SDK improvement, not a new CLI writer or a claim that the full Material Lifecycle product journey is complete. Full-repository tests and CI completion remain unqualified; maintainer review and merge are required.

[loopx-agent]

Reviewer: model_agent; GPT-6; OpenAI; self_reported

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)
Exact head: 5611@1b407aec0acf22a0093bf40b7b5bf4c0714289c1; immutable base: 9fbdc43c27be0bd013f031d598d3fdd687c8657e.

动机

使用受管素材库的个人助手和来源 adapter，需要根据新证据调整一条已有素材的排名。 将第171条提升到第5位会影响167条；原单份回执无法覆盖，现在预览保留全部素材和其它条目的相对顺序，再用100＋67两份回执记录同一次变更。 当前公开 SDK 验证单条移动与完整回执覆盖；隔离真实文件来源验证CAS、读回、发布、过期拒绝及回滚。 不新增CLI写入器、素材authority、评分策略或自动排序；不把本次SDK收尾称为Bot消息全部完成。 最终安装、完整项目授权组合和真实Bot原渠道的所有待办仍需单独验收。

这里的回执记录实际发生了什么；显示窗口不能被误当成不可改变的排名保护。已有来源负责授权、写入和恢复。本 PR 只把来源已经使用的两个计算放回素材能力的 owner，避免不同 adapter 重复实现。

改动思路

最强反方是“再加两个 helper”没有实际价值：单元测试会通过，真实调用方仍可能只存第一份回执。本次检查了既有调用方的预览、重新计算、全部回执构建、CAS 和发布；使用当前 exact-head 的纯函数驱动隔离真实文件来源，核对完整覆盖和失败恢复。因此保留两函数，拒绝扩大单份100上限、新建批量写入器、聚合回执版本或自动排序 authority。

plan_material_single_move 接收完整排名，移动一个已有身份，保留其它相对顺序；变化区间决定 proposal 的精确 moved/displacement bounds。显式受保护条目既不能主动移动，也不能被挤动。同排名 protected no-op 可行；新/未排序材料走 intake。material_rerank_receipt_chunks 先验证整个唯一输入，再返回所有分块。它不能验证来源是否完整，也不能证明调用方已保存全部分块，这两件事仍由原 source owner负责。

具体改动

当前完整 PR 为6文件 +304/-1：ranking.py新增79行（含说明），4行公开 export、160行测试，其余为所属能力的中英文说明和 scoped skill。通过普通带 DCO 的 merge 整合最新主干，没有force push，没有夹带项目授权 PR #5562 的基础diff。

事先读取已接受规范 docs/reference/protocols/material-lifecycle-architecture-v0.md；固定 spec_revision 9fbdc43c27be0bd013f031d598d3fdd687c8657e。按原文标题映射 criterion_id：Position（默认关闭/显式启用、不转移 authority）、Stage-0-Contracts（有界 proposal、Decision Context、显式保护、与 apply分离）、Owner-Gated-Apply-and-Rollback（source授权/CAS/读回/回滚）、Stage-Boundary（实验性 public-safe builders，不自带解析器、原始存储或自动排序）均在本slice满足。完整项目/实时Bot验收没有被改写成已完成。

关键路径：ranking.py:49的单移动作在复制排名后只pop/insert一次，再拒绝会挤动保护条目的意图；:99的分块验证完整身份而不是静默dedup；:264的旧receipt builder仅将字面100替换为相同常量，其 schema、详细错误和默认语义不变。已有 generic token_list 会排序去重，不能直接承担完整有序输入验证，因此增加一个局部 ordered validator有必要。

正向旅程：171条素材的原source库存→第171条提升到第5位→167条变化proposal→100＋67份既有回执→同一授权下的 source CAS→发布和独立读回→保存完整回执。所有其它条目的相对顺序不变，没有丢弃材料，也不新增用户信息、重复确认或新Goal。

对主干的风险

49项当前 SDK/契约/Decision Planning 测试通过；另跑现有项目skill交付与preparation套件21项通过，核验显式安装/默认关闭。用同一个不可变 harness 在固定main和exacthead执行14组旧公开API：正常、no-change、protected、重叠非法条件、缺Goal、0/1/100/101/167回执、旧dedup、相同revision和rollback，完整输出及异常类型/详细信息完全相同，没有抹掉语义差异。新API的1439组独立 permutation、选中rank、其它相对顺序和现有proposal/receipt断言通过；4类显式保护、future/unranked/bool错误拒绝。

故意在公开 chunks→既有receipt builder链路丢掉第二份分块，独立完整覆盖oracle发现缺67条；完整路径通过同一oracle。隔离真实来源则使用actual文件内容、immutablecatalog、CAS、publisher、投影读回和回执持久化，验证preview不换authority、apply成功、stale replay不回退已有成功、rollback恢复、撤权拒绝。late receipt故障仅在确认authority已经切换之后注入，验证实际后置失败回滚；不是用发生在CAS之前的异常冒充恢复。Core context是合成，项目scope builder是另行部署的现有canary；只替换为本exacthead两个纯函数。这证明实际消费者采用和文件边界，不证明该head已包含项目scope功能、已安装或liveBot权限验收。没有修改当前真实素材库。

native premerge5direct+15selected全部通过，0failures/warnings/advisories；Ruff、focused Mypy、compile/diff通过。开发语义probe未检测到支持语法内的新carrier；这是bounded提示，完整owner/schema判断另由上述源代码和实测支持。既有v0回执100限制未放宽，历史preview约束不自动升级，完全相同的旧输出保留读回/回滚义务。默认未启用的项目没有新prompt、requiredfield、sourcewriter、调度或Goal。公开差异不含本机路径、配置、原聊天、私有素材或身份；uv.lock仍是本地未跟踪文件。按Goal政策未查询、轮询或等待CI。

我的整体评价

APPROVE；当前全PR无阻塞finding。这是独立可用、可回滚的SDK增量，long_horizon和user_experience改善来自完整排名与可追踪恢复，而不是新增手动同步或一次helper成功。需要保留的边界是调用方证明完整库存/Decision Context、保留全部chunks、原owner授权与CAS；不要把公开函数可达性当成来源authority或任务完成证明。

最有价值的简化已落实：原能力owner、原proposal/receipt、原sourceeffect路径，两个纯计算，无新runner/store/CLI。实际Bot原渠道所有任务和安装仍需后续资格；本review没有替代它们。合并权限来自用户；另一步仍须读取native exact-head ready=true才合并。

English verdict: APPROVE - 5611@1b407aec0acf22a0093bf40b7b5bf4c0714289c1; reuse the material ranking owner for pure single-item intent and complete existing-v0 receipt partitions. Fourteen legacy public API observations are identical;1439 independent new-path cases and a167-ref dropped-chunk mutation distinguish complete coverage. Real disposable file CAS/readback/publication/late-failure rollback passes with synthetic Core context and separately deployed project-scope builders. Native5+15, focused tests, Ruff/Mypy pass. No CI consulted; installed/live Bot qualification remains separate.