规格机器视觉规格
测试契约摘录：TC-MEM-*（Arden · R11）
www 工作副本 · M2 摘录（Arden · 2026-10-21 Asia/Shanghai）
双轨：本页为 test-contracts.md §10 的 www 摘录（仅 TC-MEM-01…13 / S12）。完整 TC-* 表仍在 mvdocs，整篇迁入属后续波次（计划表 M2 编排 TC / M6 场景勾选口径——本波不迁全文）。
语义权威：memory-management.md；首次根范围薄指 image-model.md。
实现对拍：见下文「实现对拍状态」列；对照 tipe46c042（Arden 不改include//src/）。
相关：overview · cpp-headers · 预览 http://127.0.0.1:8792
10. 存储 / pin / 归还 TC-MEM-*（阶段 B · Arden · R11）
语义权威见 memory-management.md；首次根范围 / padding 薄指 image-model.md。本表只做可勾选断言（fake buffer 即可）。不改 Diagnostic / T9 停止矩阵与 toolflow v1.9。场景骨架 S12。交叉：句柄 H1–H10 见 §6；采集归还泵见
TC-ACQ-05（不扩本表）。
| ID | 勾 | 前置 | 动作 | 期望 code / 状态 | 对应章节 | 场景 |
|---|---|---|---|---|---|---|
| TC-MEM-01 | [ ] | 进程默认或自定义 MemoryPool 可用 | ImageBuffer::Rent(minimum_capacity, pool) 成功 / 失败两路径 | 成功→框架接管租出 owner；失败→归还内部已租出存储且无半接管实体；ReadOnly + Uninitialized 创建时拒绝；capacity>0 | memory-management「工厂约束」 | S12 |
| TC-MEM-02 | [ ] | 调用方持有独立 MemoryOwner | TakeOwnership(owner, …) 成功 / 抛错 | 成功→接管 owner，调用方不再访问/释放；抛错→不释放调用方 owner（无双释放） | memory-management「工厂约束」 | S12 |
| TC-MEM-03 | [ ] | 调用方已取得有效 SDK/原生引用 + release 回调 | ImportNative(address, capacity, access, release, …) 成功 / 抛错 | 成功→接管该份引用；抛错→不调用 releaseAsync/release；地址非零、容量合法 | memory-management「工厂约束」 | S12 |
| TC-MEM-04 | [ ] | 多 handle + 活动读/写 + 已入队权限申请 | 逐个关闭 handle / 结束访问 / 取消或完成排队申请 | 仅当全部 handle、活动访问与排队申请结束后才进入 Returning；关闭单一 handle 不触发归还 | memory-management「handle、异步等待与清理」 | S12 |
| TC-MEM-05 | [ ] | 调用方持有该实体最后一份存活引用 | 边持引用边 AwaitReturnCompleted / 等自身 ReturnCompleted | 禁止（等待环）；须先关闭自身 handle/引用，再等待可重复的 ReturnCompleted | memory-management「handle、异步等待与清理」 | S12 |
| TC-MEM-06 | [ ] | 已 OpenRead 并 Pin()；父 reader 先 Dispose | 企图 OpenWrite / 推进归还；读 pin 的 access() | pin 仍阻止写入与归还直至放 pin；读 pin Access 永为 ReadOnly（不因底层可写而提升） | memory-management「span 与 pin 的有效期」 | S12 |
| TC-MEM-07 | [ ] | 已 OpenWrite 并持有写 pin | Complete / CompleteAndOpenRead（pin 未放）；或父 writer 先 Dispose | 存在写 pin → Complete 抛 InvalidOperation（或等价）；父先 Dispose → 内容 Invalid，但独占权限持续到末写 pin 释放，期间不授新访问 | memory-management「span 与 pin」/「写入提交」 | S12 |
| TC-MEM-08 | [ ] | 存在冲突读者/写者或排队中；带 CancelToken | OpenRead/OpenWrite + cancel；发起申请的 handle 随后 Dispose | 取消令牌可撤销等待；发起 handle Dispose 不撤销已入队申请；轮到读时若未初始化/上次写失败 → 立即 InvalidOperation，不无限等未登记写者 | memory-management「访问授予」/「handle」 | S12 |
| TC-MEM-09 | [ ] | reader/writer/buffer 上并发 Share/ShareBuffer 与 Dispose | 竞争双方 | 单一协调点原子裁定；成功返回的子对象始终独立有效；已关闭对象再 Share/申请 → Disposed（或等价） | memory-management「访问授予」 | S12 |
| TC-MEM-10 | [ ] | 已获写权限；未 Complete | Dispose writer | 内容 → Invalid；不回滚字节；不得把旧 Generation 重发为有效；新读拒绝 | memory-management「写入提交」/「首次初始化」 | S12 |
| TC-MEM-11 | [ ] | 类型化 Rent 未首次发布；或已 Ready 后 ROI 写入 | 仅写 ROI 企图首次 Complete；或 ROI 写入中止 | 首次须根范围覆盖全部逻辑像素后 Complete；未完成首次前拒绝不同范围初始化视图；任一写入中止 → 整实体 Invalid（不局限矩形）；小 ROI Complete 不能把整份标回有效 | memory-management「首次初始化、ROI 写入中止与恢复」；image-model 根范围 | S12 |
| TC-MEM-12 | [ ] | 内容已 Invalid | 带 expectedVersion 的 OpenWrite；以及无期望版本的完整范围恢复写 | 带期望版本 → 拒绝（不授予）；无期望版本的完整初始化范围写入 Complete 后可回到 Ready；框架无字节级回滚 | memory-management「首次初始化…恢复」 | S12 |
| TC-MEM-13 | [ ] | 多实体并行归还；其一 releaseAsync 卡住或失败 | 关闭触发清理；观察各项 ReturnCompleted / ReturnFailed | releaseAsync 恰好一次；一项卡住不串行阻塞其他存储归还；ReturnFailed → 不自动重试、不回可用池、不恢复访问；失败可观察 | memory-management「handle、异步等待与清理」 | S12 |
实现对拍状态（tip e46c042 · 按实 · 可勾选处）
下列 不是把 stub 标成完成。头上均有
NON-STABLE ABI / STUB。勾选含义：公开声明外形是否足以起草 fake 测试；≠ 契约验收通过。
| TC | 声明外形（include） | 实现对拍状态 | 缺口归属 |
|---|---|---|---|
| TC-MEM-01 | Rent/TryRent/CanRent(size, MemoryPool*)；MemoryPool 虚基类 | 外形已有；默认 CanRent 乐观；池接管验收 未齐 | Reed · Bruno |
| TC-MEM-02 | TakeOwnership(unique_ptr<MemoryOwner>) 已有 | 外形已有；失败不释放调用方 owner 以测为准 | Reed |
| TC-MEM-05 | AwaitReturnCompleted / ReturnCompleted 实现在 cpp | 不再是头内空体；可重复等待/禁等自身环 未验收 | Reed |
| TC-MEM-03 | 带 release 的 ImportNative(address, capacity, access, release, …) 已有；另有无回调 legacy 重载 | 外形已有；恰好一次 release / 抛错不调 release 以实现为准 | Reed |
| TC-MEM-04 | Share / BufferReturnState / handle 账本在头与 detail/buffer_entity | 部分：状态枚举在；「全部 handle+访问+排队结束后才 Returning」完整协调属实现 | Reed |
| TC-MEM-06 | ImageBufferPin + ReadOnlyViewBase::Pin；读 pin Access 字段在 | 外形已有；父 Dispose 后 pin 阻写/归还以实现为准 | Reed |
| TC-MEM-07 | WritableViewBase::Complete 在写 pin 时抛错路径；close→AbortWriter 注释（HDR-ALG-04） | 已实现且有断言：写 pin 期间 Complete 抛 InvalidOperation/runtime_error、父 writer 先 Dispose 则内容 Invalid（smoke TC-MEM-06/07）；验收未勾 | Reed |
| TC-MEM-08 | CancelToken + Open* 重载在；Dispose 不撤已入队申请 | 已实现且有断言：EnqueueAndWaitRead/Write + grant_queue（kMaxGrantQueue=32）+ queue_ref 保活 + SignalCancelOnQueued；smoke 覆盖取消、Dispose 不撤已入队、队满立即拒；仍受 DEBT-IMG-003 限制（CancelToken by-value，跨线程改调用方 token 不可行） | Reed · Bruno |
| TC-MEM-09 | Share/Dispose 原子裁定（规格要求） | 已在公开头声明并有断言：ReadOnlyViewBase::ShareBuffer()（保活专用，走 AddHandleRef 非 AddReader，强制 ReadOnly 且 data_ 置空）；smoke 覆盖并发 Share/ShareBuffer vs Dispose 的原子裁定与子对象独立有效性；验收未勾 | Reed |
| TC-MEM-10 | WritableViewBase::close 注释 AbortWriter if not Completed | 声明意图在；须测未 Complete→Invalid | Reed |
| TC-MEM-11 | 首次根范围 / ROI 中止整实体 | 规格在 image-model/memory；公开头无独立「根范围」API 标记 | Reed |
| TC-MEM-12 | OpenWrite(expectedVersion) + Status::VersionMismatch | 外形已有；Invalid 恢复路径以实现为准 | Reed |
| TC-MEM-13 | ReturnFailed 枚举在；release 恰好一次 | 部分：隔离/不自动重试须实现+测 | Reed |
场景骨架 S12（完整文仍在 mvdocs examples-scenarios）：
| S12 | TC-MEM-01…TC-MEM-13 | 工厂接管；最后引用→Returning；禁等自身 ReturnCompleted；pin 阻写/归还；写 pin 阻 Complete；授予/取消与 Share/Dispose 原子；未 Complete→Invalid；首次根范围/ROI 中止整实体；Invalid 恢复；releaseAsync 一次与归还隔离/ReturnFailed | S12；memory-management；Arden · R11 |
摘录状态：2026-10-21 Asia/Shanghai · tip e46c042。完整 test-contracts 不在本波。