本文定义 NInfer 在有限 Device/Host 资源下选择、验证并提交上下文状态的规则。它是 admission materialization、prefix reuse、cache retention 和 pressure planning 的维护者权威。
本文解决的问题是：
Scheduler 已经选择一个等待请求后，应从哪个可恢复位置开始，保留或降级哪些 inactive context， 才能以最低预测代价得到一个物理可执行且不会破坏 active request 完成保证的终态？
顶层请求顺序和生命周期由 Engine 架构定义。KV page、address space、 replica 和 consumer view 的物理合同由 Paged KV Context Store定义。
本文使用以下术语：
| 术语 | 含义 |
|---|---|
| owner | 一个 active sequence、private continuation 或 shared prefix |
| checkpoint | owner 内某个可恢复 frontier 的不可变完整状态 |
| candidate | incoming request 可以采用的一个 root 或 exact checkpoint source |
| planning target | candidate 与全部受影响 inactive owners 的完整逻辑终态 |
| reservation | 已从全局可用容量中扣除、为未来物化或事务目的保留的容量 |
| resource plan | Program 针对一个 target seal 的有序物理 transition |
| placement | 一个完整 StateImage 或一个 KV logical page 的 Device/Host replica 状态 |
本文后续简称 planning target 为 target，表示一次资源决策的终态。
Prefix reuse 是 admission 的一种来源选择。它复用具有完整身份和状态覆盖的已计算前缀，减少重复 prefill，保持模型语义和请求顺序。不同 prefill 分块或数值路径之间不要求 logits 或生成 token 完全相同。
当前产品条件为单 GPU、单 resident model、固定 max_concurrency=1..8 和非抢占 active requests。
由此得到两个基本规则：
- Scheduler 先确定本次尝试的 request，资源层只优化该 request 的 materialization；
- 一个 request 发布为 Active 后，其最大合法执行范围已经获得完整资源保证，inactive cache policy 不能再借用这部分容量。
Scheduler 选择：
- 当前 FIFO head 或已经证明安全的 backfill request；
- admission 尝试时机；
- prefill、control 和 decode 的执行顺序。
Scheduler 不读取 checkpoint placement、victim、page 或 allocator facts。
ResourceManager 拥有逻辑缓存策略：
- private/shared catalog 与 SessionIndex；
- candidate shortlist 和 logical claim；
- retention class、命中历史与 publication order；
- 跨 candidates 的 target 搜索和成本比较；
- Program 终态结果的逻辑采用。
ResourceManager 可以知道“某个 checkpoint 可从 Device、Host 或 root 恢复”的 Program summary， 但不保存物理 occupancy、refcount、free page 或 Host arena 几何的副本。
ResourceManager 对 active request 的逻辑保护保存为 owner edge，而不是 catalog capability 或引用计数镜像。 Capability generation 是 planning/transaction 的瞬时结构快照；owner edge 是持续到 active request terminal settlement 的逻辑 lease。另一个 reader 改变同一 owner 的 Device/Host residency 时可以推进 generation，但不 使已有 owner edge stale。所有 active logical reference counts 都从这些 edges 派生。
Program 是唯一物理 authority，拥有：
- State 与 KV 的真实 objects、references 和 replicas；
- Device pools、Host stores、allocators 和 reservations；
- continuation completeness 与 exact prefix identity；
- Move、Fork、COW、transfer 和 last-reference release；
- 完整 post-state、每个 transition stage 的物理可行性；
- 与当前资源状态绑定的
ResourcePlan。
调用关系为：
Scheduler selects one request
│
▼
ResourceManager enumerates candidates and compares targets
│
▼
Program projects each complete target from real physical state
│
▼
Program seals and executes one ResourcePlan
│
▼
ResourceManager adopts one stable ResourceResult
逻辑策略与物理事实通过 candidate assessment、opaque target handle、ResourcePlan 和
ResourceResult 交互，不通过一份跨层共享的物理账本交互。
Program 在启动时建立一个固定容量向量：
PhysicalCapacity = {
Device StateImage slots,
Host StateImage slots,
Device page groups for each typed KV pool,
Host KV arena bytes and allocator geometry,
}
容量依据加载后的模型配置、实际权重绑定、启用组件及启动选项推导。权重的物理表示影响执行 workspace 和可用预算；KV/GDN 的数学状态、具体存储和容量由模型实现与 Program 分别负责。
这些轴相互独立。一个资源轴的余量不能补偿另一个轴的缺口。Host KV 的总空闲字节也不能替代 allocator 对具体 extent 几何的可分配性判断。
Engine 另有固定的逻辑容量：
- active lanes；
- private continuation catalog slots；
- shared prefix catalog slots；
- 每个 continuation 的 checkpoint/anchor 上限。
Lane 和 catalog slot 不计入物理 bytes，但 target 只有同时满足逻辑容量和物理容量才可发布。
对任一物理资源维度 (r)，状态 (S) 的占用为：
[ Used_r(S)= \sum_{x\in UniqueAllocations(S)} size_r(x) + \sum_{y\in ConcreteReservations(S)} size_r(y) ]
UniqueAllocations 包括：
- Device/Host StateImage replicas；
- Device KV page replicas；
- Host KV extents。
ConcreteReservations 包括：
- active request 尚未 materialize 的未来增长；
- partial-tail COW destination；
- resource transition 的 copy destination 和 replacement capacity。
同一个物理 allocation 被多个 checkpoints 或 address spaces 引用时只计一次。已经物化的容量计 allocation，尚未物化但被保护的容量计 reservation；同一容量单位不能同时计入两项。
全局物理占用与 owner-exclusive resources 是两个不同视图。前者直接来自 State/KV stores 的 unique allocations 与 concrete reservations；后者只表示单独移除一个 owner 时能够结算的资源。一个同时被 private checkpoint 与 shared prefix 引用的 allocation 在全局占用中计一次，但在任一 owner 的 exclusive resources 中都不计。Owner-exclusive resources 可用于 eviction effect、ownership transfer 和 active entitlement 校验，不能用于判断一个 checkpoint 是否具有 resident replica；后者只能查询对应 physical store。
每个稳定状态和 transition 中间状态都必须满足：
[ Used_r(S)\le Capacity_r ]
资源回收由最终剩余引用决定。对一组 logical actions (V)：
[ Reclaim_r(S,V)= Used_r(S)-Used_r(PostState(S,V)) ]
PostState 必须同时应用：
- selected source 的 retain 或 consume；
- 所有 victim owner/checkpoint outcomes；
- 所有 surviving Device/Host placements；
- active destination references 和 reservations；
- 零引用 objects 的 release。
因此通常有：
[ Reclaim(S,A\cup B)\ne Reclaim(S,A)+Reclaim(S,B) ]
删除一个 alias 可能不释放任何 allocation；两个 owners 一起删除最后一批 references 时，同一 allocation 只释放一次。ResourceManager 不计算或相加 per-owner reclaim credit。
Move、Fork、partial-tail COW 和 source placement 也由完整 post-state 决定。一个 source 在初始状态中 存在多个引用，并不意味着最终一定 Fork；反之，保留任一 checkpoint 所需的引用后也不能把它当作 Move。
一个物理 plan 是稳定状态之间的有序阶段：
[ S_0\rightarrow S_1\rightarrow\cdots\rightarrow S_n ]
它可执行当且仅当：
[ \forall r,\qquad \max_{0\le i\le n} Used_r(S_i)\le Capacity_r ]
阶段顺序必须表达真实 dependency：
reserve destination
-> copy
-> verify and publish replacement
-> release old replica
State restore、KV H2D/D2H、D2D fork、partial-tail COW 和 Host extent replacement 都遵循这一规则。 最终净占用不能掩盖 copy-before-release 的瞬时峰值。
Program 暴露单调 resource_revision，使只读 assessment 和 sealed plan 与一个稳定物理状态绑定。
以下变化会推进 revision：
- owner/reference topology 改变；
- inactive Device/Host placement 改变；
- global free/reserved capacity 改变；
- 会改变后续 allocator feasibility 的几何状态改变。
Active request 在自己的 reservation 内进行 mapped/reserved 转换、推进 committed frontier 或更新 state 内容时，不改变全局可用容量，因此不推进 revision。
一个 open resource transition 的中间阶段不向外发布 revision。它到达稳定 commit/abort 状态后， 若全局物理事实发生变化，只推进一次。Handle 的 owner/generation validation 独立阻止 slot reuse 产生的 stale capability。
当前 Qwen3.5 模型同时包含可分页 Full Attention KV 和不能从任意较晚状态无损回退的 recurrent state。 因此某个 frontier 可以复用，当且仅当 Program 能证明：
- 存在该 frontier 的完整 StateImage；
- Main KV 满足 target 定义的 typed coverage；
- selected backend 的 KV 与 fixed state 满足同一 continuation；
- token、position、Vision 和 mode identity 与 incoming prompt 精确一致。
只有 token match、KV bytes 或 page match 时，缺少的是完整 continuation，不是一次部分 cache hit。
Private continuation 表示一条可继续演化的会话历史：
PrivateContinuation
├── exact target/token history
├── Main KV address space
├── optional backend KV address space
└── one or more immutable checkpoints
Shared prefix 是不可变的复用来源，可以被多个 private branches Fork。一个 continuation 内的多个 checkpoints 可以引用相同 address space 的不同 prefix，但每个 checkpoint 都有自己的完整 StateImage identity。
Session persistence（ninfer-serve --slot-save-path）是唯一一条不经 materialization 或 capture
transaction 就发布 catalog owner 的路径。它只在没有打开的 context transaction、目标 cell 没有 active
edge 时于 execution mutex 下运行：Program::save_continuation 只读地把 catalogued continuation 的
ledger、exact identity、shortlist digests、checkpoint 目录、去重后的 StateImage 和 committed frontier
以内的 KV pages 复制到 host bytes；Program::restore_continuation 在空闲 lane 的 execution row 上临时
激活新的 address space 上传 pages，StateImage 优先落 Device slot、否则落 HostOnly replica，endpoint
必需、放不下的可选 checkpoint 被丢弃，然后以 Catalogued 角色发布并推进 resource revision；
ResourceManager::adopt_restored 把它作为匿名 RecentPrivate owner 放入空 cell，之后只按 prefix
匹配复用。格式与字段见 src/models/qwen3_5/program/storage/session_snapshot.cpp。
| Kind | 语义 |
|---|---|
SessionEndpoint |
已完成请求的最新可继续状态 |
TurnClosure |
当前 turn 中可替换 assistant suffix 之前的稳定状态 |
ResponseReplay |
generation opener 之前、可重新生成 response 的稳定状态 |
LongAnchor |
retention policy 选择的较早长上下文恢复点 |
SharedStablePrefix |
多条历史共同使用的不可变稳定前缀 |
TurnClosure 和 ResponseReplay 的 frontier 必须位于下一请求可能替换的 assistant suffix 之前。
这样对话系统追加新的 user message 或改写生成尾部时，仍能复用稳定历史，而不会把可变 suffix 错当成
prefix identity 的一部分。
Checkpoint 发布后：
- identity、frontier 和 required coverage 不变；
- StateImage 与受保护的 KV prefix 不再原地修改；
- Device/Host placement 可以由 resource transition 改变。
Checkpoint (c) 有效，当且仅当：
- StateImage 至少有一个完整 Device 或 Host replica；
- 每个 required KV logical page 至少有一个 content epoch 一致且 coverage 足够的 Device 或 Host replica。
[ \forall p\in RequiredPages(c),\qquad ValidDevice(p,c)\lor ValidHost(p,c) ]
有效 checkpoint 可能需要 H2D restore。只有全部 execution requirements 已在 Device，且 active future reservation 可以取得时，它才是 Device-ready。
Program 的 exact verification 可以使用：
- token IDs 和 token types；
- position/MRoPE axes 与 RoPE delta；
- Vision spans 和 media digest；
- template/runtime mode；
- checkpoint frontier。
Session key、marker、hash 和 prefix index 只缩小 candidate 集合，不证明命中。
rewrite_execution_frontiers 也是 exact identity 的一部分。它记录 replay/root prefill 必须分段的 exact
token frontiers，使重建路径采用与原生成路径一致的 execution decomposition；不能为了采用 endpoint 而忽略。
当 NInfer 自己生成的 accepted output 形成可由历史 renderer 精确重建的边界时，所有权链固定为：
Frontend detects the model-output reconstruction boundary
-> Engine transports relative accepted-prefix metadata
-> Program atomically commits resident identity and shortlist digest
Frontend 只在 canonical boundary 恰好结束于 token frontier 时发布 metadata，并让 preview rollback、stop truncation 和 speculative partial accept 服从同一个 accepted-prefix transaction。Program 把相对位置转换为 resident absolute frontier，并与 token ledger、State/KV 和 backend state 一起提交；它不扫描输出文本。 ResourceManager 不推断或放宽这个事实。这样未经客户端改写的 NInfer 输出可以继续采用 exact endpoint；客户端 重排 tool JSON、补默认值或改写历史仍是不同的 rendered identity，只能匹配更早的合法 checkpoint。
每个请求在进入 Engine 前固定一种语义：
ReadWrite：允许读取 exact candidates、capture checkpoints，并在 finish 时发布 continuation；Disabled：只允许 root materialization，结束时释放全部 active context resources。
Disabled 请求仍获得正常 active completion guarantee，但不会留下 private/shared catalog entry、
SessionIndex binding 或 Device/Host checkpoint replica。Serve warmup 使用这一语义。
StateImage 是完整迁移单位。设最大 active concurrency 为 (C)，额外 Device checkpoint slots 为 (H)， 则：
[ Capacity_{DeviceState}=C+H ]
前 (C) 份容量形成 active guarantee，全部 slots 仍由同一个 Program pool 管理，不与 lane 固定配对。 Host State 以完整 image 和独立 slot 容量计费。
State transition 的语义只有：
| 操作 | 条件与结果 |
|---|---|
| InPlace | 唯一 active writer 在自己的 destination 上推进 |
| Move | private source 被 consume，原 StateImage 成为 active destination |
| Fork | immutable 或仍需保留的 source 写入新的 private destination |
| Freeze | committed active StateImage 转为 immutable checkpoint |
| Snapshot/Restore | 完整 StateImage 在 Device 与 Host 之间复制 |
Program 根据完整 post-state 选择 Move 或 Fork。Fork source 在 destination 首次 state-writing commit 完成前 保持 pin；该结算属于 active model transaction，不能与新的 global resource transition 重叠。
Active State binding 同时记录 read source 的生命周期归属。Root、Move、Restore 和 active-capture Fork 的初始 read 由当前 sequence 提供；从 retained source 或仍有 surviving checkpoint reference 的 consumed source 建立 Fork 时，read 由 surviving owner/reference graph 保留，active primary binding 只拥有 write destination。这个 borrowed read 参与全局物理占用并由 source pin 保护，但不能通过 primary binding 再次计费，也不能仅凭 primary binding 在 abort/release 时释放；若 surviving checkpoint 本身是 active lineage 独占的 optional checkpoint，它只通过该 checkpoint ownership 计入 entitlement，并在该 ownership 结算后决定 source 是否可释放。Fork settlement 后 read/write 都切换到 destination，生命周期重新归属 active sequence。
每个 continuation 对 Main KV 及 selected backend KV 分别持有 typed address space。各 pool 的 frontier、 capacity 和 placement 独立。
资源规划只使用以下语义：
- required logical pages 与 committed coverage；
- 每页可用的 Device/Host replica；
- immutable references 和唯一 writer；
- partial-tail COW requirement；
- restore、demote 或 release 对 capacity 与 machine work 的影响。
具体 page geometry、Host packed extent、COW 和 block-table publication 由 Paged KV Context Store定义。
Prefix Fork 后的 active address 可以按以下顺序同时包含共享与私有页：
immutable full pages | unique mutable full pages | optional unique mutable tail
Active capture 对不可变整页只增加引用，对唯一可写整页原地 Freeze；非对齐尾页保留给 checkpoint，并只 复制一页作为新的 active writer。对齐 frontier 不发生 KV copy，后续增长再物化新的 writer page。 Program 的 capture assessment、reservation 和 commit 使用同一个 snapshot-shape 分析，因此资源信用、 transfer cost 与实际可提交的页所有权条件一致。
State 与 KV 可以独立 placement，例如 State 在 Device、Main KV 部分在 Device、其余 Main KV 在 Host， backend KV 采用另一种 coverage。Checkpoint 只有在全部 required components 至少保留一份有效 replica 时才继续存在。
一个 candidate 发布为 Active 前，Program 为它保障：
required Device checkpoint prefix
+ remaining prompt growth
+ maximum effective output growth
+ target-defined provisional/speculative growth
+ State and partial-tail COW destinations
+ selected backend requirements
这些资源绑定在返回的 SequenceHandle 中。物化进度只在 allocation 与 reserved-but-unmapped 之间转换，
不会把容量交给另一个 request。
Active truncate 或 speculative rollback 可以解除 mappings，但对应容量仍属于该 active reservation。 只有 terminal release 或明确缩减 active entitlement 的资源 transition 才能把容量归还全局。
Active entitlement 只包含 active owner 的 destination、私有增长 reservation 和已归属于该 lineage 的
exclusive optional resources。启用 kv_lease_growth 时，私有增长 reservation 是按需扩充的有界 Device page
window，而不是 request 尚未取得的整个 output budget（见 Paged KV cache §6.2）。Fork 期间借用的 immutable
StateImage/KV source 不能通过 primary binding 再次计费：它若由其他 surviving owner 保留则只存在于全局
physical occupancy，若由 active lineage 的 optional checkpoint 独占则只通过该 checkpoint 计一次。否则同一
allocation 会被重复收费，并把合法的 Fork 错判为超出 active guarantee。
TerminalPending request 继续持有 SequenceHandle 和完整 reservation，直到 Program 完成：
- Finish：发布一个完整 immutable checkpoint；或
- Discard：释放整个 active continuation。
若 Finish 无法形成合法保留终态，必须采用 Discard。Optional capture 可以通过同一 pressure graph 改变 inactive owners，但只有严格优于 private-only baseline 的完整终态才会提交；否则跳过 shared publication， 不阻塞 active request，也不改变同一 frontier 原本可执行的 private capture。
Scheduler 是否允许 backfill 由 Engine 架构决定。Program 提供的物理证明使用同一 feasibility oracle：
hypothetical state =
current stable state
- protected donor active reservations after their terminal release
+ borrower full active reservation
+ head root materialization
with all unprotected inactive cache releasable
只有该完整状态可行，borrower 才具有 persistent-safe backfill 资格。证明与 resource_revision 绑定，
不使用 borrower 或 donor 的预计完成时间。
ResourceManager 为已选 request 建立有界 candidate 集合：
- root；
- matching private endpoint；
- typed rewrite checkpoint；
- retained long anchor；
- shared stable prefix。
相同 capability 经不同 index 命中时先去重。Program 对每个 shortlist entry 执行 exact verification，
并产生一个 AdmissionCandidate。Candidate 固定 source、destination、prompt 和 request work，但不提前
决定 Move/Fork、victims 或最终 placements。
Root 始终存在。它不复用 continuation state，代表从 prompt 开始正常 prefill。
Shared prefix 的三个状态不能混为一谈：
- boundary 是协议或 Engine 指出的逻辑内容边界；
- candidate 是 Frontend 已解析到 exact token frontier 的可选写入机会；
- owner 是 Program 已发布、具有完整 State/KV identity 与 placement 的 immutable checkpoint。
外部协议或 C++ PromptInput 每个请求最多提交四个显式 markers。Frontend 还可以生成最多三个 Engine
candidates：全部 tools 之后、连续 leading System/Developer 之后，以及 full prompt。相同 frontier 合并，
因此每个请求最多七个 prepared candidates。这个固定上限不是启动配置。
这三个 Engine candidates 由 ContextCacheHints::allow_engine_automatic_shared_prefixes 控制，默认开启。
自带写入策略的协议（例如显式请求了 Anthropic 顶层 cache_control 的请求）可以关闭它们，但只应在该协议
确实会把 marker 放在别的请求也能匹配的位置时关闭：协议的 automatic marker 通常落在自己 prompt 的末尾，
任何内容不同的请求都无法匹配，因此关掉结构性 candidates 会让共享前缀永远不被发布。
ContextCacheHints::allow_engine_prefix_grid（ninfer-serve --auto-prefix-grid，默认关闭）额外在与内容
无关的 token 栅格上提供 candidates：步长从 256 tokens 起按 2 倍增长，直到栅格点不超过八个，frontier 取
步长的绝对倍数而不是从 prompt 末尾倒推，因此长度不同的两个 prompt 在仍然一致的位置上会给出同一个
frontier。栅格 candidate 只带 EngineObserved，既不是 declared 也不是 surplus，所以永远不会被投机性地
占用空闲 shared slot；只有当两个独立 reuse domain 都提出同一个 key 时才会发布。开启后单请求最多十五个
prepared candidates。
ContextCacheHints::automatic_private_anchors（ninfer-serve --auto-long-anchors N，默认等于
max_long_anchors_per_continuation）让 Frontend 在最后 N 个位于 prompt 内部的 message boundary 上各提出一个
PrivateLongAnchor candidate：跳过第一条 message 之前的空 boundary，也跳过最后一条 message 之后的 boundary
（endpoint 与 rewrite checkpoint 已覆盖尾部）。Chat Completions 与 Anthropic 请求无法表达显式的
PrivateLongAnchor marker，没有它们时，改写 rewrite checkpoint 以下历史的请求没有 reuse candidate，只能从
token 0 重新 prefill。它们是 candidates 而非 markers：不计入显式 marker 上限，与同一 frontier 上的显式 anchor
合并，并使单请求 prepared candidates 上限增加 N；保留数量仍受 max_long_anchors_per_continuation 限制，满额时替换最浅的
anchor。
原始 token prompt（Engine::prepare_tokens，serving 的 /completion 与 /v1/completions）没有 message
结构，因此没有 rewrite checkpoint，也没有 message boundary 可供锚定；它的 endpoint 仍让续写该 prompt 及其输出的请求
复用。prepare_tokens(..., anchor_prompt_end = true) 在 prompt - 1 处提出一个 PrivateLongAnchor candidate
（EngineStructural）和一个 GenerationOpener tap hint，使同一 prompt 再次到来（重新生成）时从该处恢复，只重算最后一个
token。它不进入 prompt identity，所以不妨碍 endpoint 复用；代价是一次额外的 prefill pass 与一个 StateImage。
ninfer-serve 只对至少 512 token 的 raw prompt 打开它（RTX 3090、27B：额外 pass 约 20 ms，重复的 1,602-token prompt
TTFT 从 615 ms 降到 26 ms）；benchmark 与测试的 prepare_tokens 默认不打开，执行分解保持不变。
Endpoint anchor（ContextCacheOptions::endpoint_anchors，默认开启，ninfer-serve --no-endpoint-anchors
关闭）由 Engine 而不是 Frontend 提出：base plan 之前，ResourceManager 找出 prompt 逐 token 且 identity 一致地
匹配到其 endpoint 的最深 catalogued private continuation；该 endpoint 若比此 owner 的 long anchors 至少高
kEndpointAnchorMinimumGainTokens（1024），base plan 就在这个 frontier 加入一个 PrivateLongAnchor capture
（与 branch anchor 同一条 engine-anchor 通道，获得 identity 并按 client marker 定价）。请求以 in-place Move
恢复该 endpoint（PrivateEndpoint、ConsumeToActive、无 state fork）时，这个 capture 正好落在 reuse base：
它在 suffix prefill 之前从 endpoint 自己的 StateImage 取得（有空闲 Device slot 时 Device Fork，否则 Host
snapshot），不增加 prefill split。恢复会让 endpoint 随对话推进，新的 endpoint 与 TurnClosure 都位于新 turn
之后；没有这个 anchor，在旧 endpoint 处分叉的请求（对同一回答的另一条回复、编辑最后一条 message）找不到
root 与新 turn 之间的任何 checkpoint。其他 reuse 路径下，这个 capture 位于 reuse base 之上时照常在 prefill
中执行，在 reuse base 及以下时丢弃。它占用 max_long_anchors_per_continuation，满额时由
select_long_anchor_replacement 按覆盖损失选出被替换的 anchor。
从 private long anchor 恢复（PrivateLongAnchor）与 rewrite restore 使用同一条 source 规则。必须保留 source
的请求（不发布 continuation、在该 frontier 声明显式 boundary、属于另一 session）Retain：Fork anchor，对话
保持不变。其余请求先检查 cache 现状下能否把分支放在对话旁边：anchor 的 Retain candidate 在 identity 上物理
可行，且 private catalog 有空位可发布分支时，同样 Retain；否则 ConsumeToActive，对话从 anchor 处改写：
endpoint、rewrite checkpoint 与 reuse base 之上的 anchors 被释放，被选中的 anchor 本身仍是新 lineage 的
checkpoint，所以 state 走 Fork 而不是 Move。默认 C=1、H=1 时，续写一轮之后两个 Device slot 由对话 endpoint
与 endpoint anchor 占满，兄弟分支于是改写对话并从 anchor 恢复，而不是从 root 重新 prefill；代价是旧分支的
endpoint，之后回到旧分支的请求同样从 anchor 恢复。
Shared catalog 是 Engine-wide 公共容量，不是每条 lineage 的配额。启用 context cache 时，默认 logical
capacity 同时覆盖 active concurrency 下限和单请求最多七个 prepared candidates，即
max(max_concurrency, kMaximumPreparedPromptCacheCandidatesPerRequest)；显式配置仍完整覆盖默认值。这个下限允许较早的
稳定层与较晚的滚动 marker 同时成为 owner，但是否 capture、保留或替换仍只由通用 portfolio/pressure
planning 决定，不提供 Claude、compact 或 token-position 特例。
Candidate 保存 evidence flags。策略含义为：
| Evidence | 首次出现时的准入能力 |
|---|---|
ExplicitBoundary |
可以参与 pressure，但仍须有严格正净收益 |
RequestedAutomatic |
可以参与 pressure，但仍须有严格正净收益 |
DefaultAutomatic |
至少两个独立 reuse domains 观测到相同 key 后才可创建 |
EngineStructural |
只能使用不降低现有 owner 的空余终态 |
EngineObserved |
至少两个独立 reuse domains 观测到相同 key 后才可创建 |
EngineStructural 标记的是 prompt 自身结构暴露的 frontier（leading instructions 之后、tools 之后），
内容不同的请求也可能落在同一位置，因此用空余 slot 做投机是合理的。DefaultAutomatic 不是：协议按自己的
策略放置它，而 OpenAI 与 Anthropic 都放在该请求 prompt 的末尾，每个请求的副本都位于任何内容不同的请求都
无法匹配的 frontier 上。让它占用空余 slot 会把 shared catalog 填满一次性 checkpoint，并饿死结构性
candidate——后者只能等到 catalog 没有空位、pressure 生效后才能被提升。实测（八个不同前缀轮询）：十六个
slot 的 catalog 到第四轮才完全命中（整体 32.8%），反而不如八个 slot；同一请求流在抑制该 automatic marker
后两种容量都在第二轮完全命中（98.3%）。该 marker 真正被共享时仍会通过 repeated 获得 slot。
Shared catalog 没有空位时，不带 declared credit（ExplicitBoundary、RequestedAutomatic）的 candidate
可以回收最近最少使用的 automatic entry：该 entry 没有 explicit credit、没有 transaction pin、没有 active
reuse edge，按最近一次命中或发布的 retention epoch 排序，相同时取更早发布者。回收只作为一个把该 slot
视为空位的 capture scenario 参与规划；只有该 scenario 被选中后才通过 Program 释放 entry，然后针对空出的
slot 重新规划 capture，因此无法完成的 capture 不会白白丢掉 entry。materialization 选择时可回收 slot 与空位
一起计入 surplus 容量。没有这条路径时，catalog 一旦被 automatic entries 填满，之后的普通请求在 Engine
重启前都拿不到 shared-prefix reuse（Neroued/ninfer issue #251）。
请求自身延伸的 entry（其 materialization 在该 entry 的 frontier 上精确匹配过的 resident key）不会为该请求
的 capture 回收：凡是能用这个更长 prefix 的请求也都匹配那个更短的 entry，回收只会让 slot 缩窄到一个会话；
materialization 计算可回收 slot 时同样排除这些 entry。
Marker、evidence 和 shortlist key 都不证明命中；Program 对 read、dedup 和 publication 重新验证完整 identity。候选创建 source 的顺序为：exact shared owner 直接 dedup；selected exact private reuse base 在 第一次模型 mutation 前做零-prefill promotion；更晚 frontier 由 active prefill capture。早于 selected reuse base 且没有现成 exact source 的候选只保留为需求观察，不回滚状态或重新 prefill。
Shared candidate 必须在 prefill 前决定是否增加 split，而物理状态只能在 frontier 到达时确定。因此实现 分为两步：
- admission 已选定 materialization source 后，ResourceManager 用完整逻辑 portfolio 的乐观收益上界和 Program 返回的精确 split cost 选择 candidate subset；这一步不预留资源，也不承诺 publication；
- capture offer 到达后，
SharedCapturePlanner从当前resource_revision搜索完整物理 targets，可以联合 demote/evict 多个合法 inactive private/shared owners。shared catalog 已满时，logical replacement 与其他 物理 victims 属于同一个 target 和同一个 transaction。
实际 planner 的 baseline 是同一 frontier 的 private-only policy。Shared publication 是可选投资：没有可行 且严格正收益的 target 时执行 private baseline 或 Skip。
Planner 的搜索节点是完整 target，而不是一条孤立 eviction action。一个 target 同时确定：
selected candidate
selected source retained or consumed-to-active
every eligible owner retained or evicted
every surviving checkpoint and required coverage
every surviving State/KV Device/Host placement
logical publication destination
Eligible victims 只包括未被 active reference、selected-source protection 或 open transaction pin 保护的 inactive owners。Target 应用后产生的零引用 objects 自动释放。
Program 从该完整终态重新推导：
- Move 或 Fork；
- State/KV replacement 与 partial-tail COW；
- last-reference releases；
- active completion reservation；
- Host allocator geometry；
- ordered stage peaks；
- immediate work 与未来 recovery work。
一个 candidate 的 identity target 只应用 incoming activation 与必需的 source disposition，保持其他
eligible inactive owners 的 checkpoint contents 和 placements 不变。它是该 candidate 压力降级图的根。
Pressure target 从 candidate 的 identity target 沿单调降级方向扩展：
- 移除冗余 Device 或 Host replica；
- 将 Device State/KV 降为 Host-only；
- 缩短不再保留的 checkpoint coverage；
- 删除 checkpoint；
- evict 完整 inactive owner。
Program 根据当前 residual deficit、checkpoint frontiers、page/extent boundaries 和共享引用生成语义 successors。搜索不枚举物理操作的排列；每个 target 由 Program 映射到唯一规范 stage order。
单个 owner action 暂时不产生 reclaim，也不能在联合 post-state 之前被删除，因为它可能与另一 action 共同形成 last-reference release。
本节中的 incumbent 指当前已经找到的最佳可行完整 target。
Program 先判断 target 是否结构合法、物理可行以及是否仍可继续降级。ResourceManager 只在物理可行且 logical publication 可采用的 targets 之间比较价值。
成本模型不参与容量判定。任何预测误差都只能改变“选择哪个可行方案”，不能让不可行方案通过。
Program 将物理工作折叠为：
Immediate =
ordered transfer phases
+ remaining Text/Vision prefill
+ required State/KV copy work
一次同 phase、同 direction 的 transfer batch 使用：
[ Transfer = \max(batch_ns+operations\cdot operation_ns,\ bytes\cdot ns_per_byte) ]
Text suffix 的 prefill work 使用：
[ AttentionPairs = B,S+\frac{S(S+1)}{2} ]
其中 (B) 是已复用 prefix tokens，(S) 是剩余 suffix tokens。Vision item/patch work 使用同一 startup-resolved machine model 的独立分量。
Transfer 系数按硬件选择，prefill 系数按硬件与实际 Text/Vision config、绑定结构和 Use 生成的
prefill_signature 选择。签名不使用 checkpoint/release 名称，也不包含权重数值。两组系数独立
解析；没有匹配的标定时使用对应的通用系数。成本只影响可行方案之间的排序，不是加载或执行门槛。
ResourceManager 保存最近 32 个成功 materialize 为 Active 的请求。每条 demand record 保存 reuse domain 以及该请求 exact-matched、selected 或可创建的 prefix keys；不保存 prompt、媒体内容、session 原文或 API cache key。有 Engine session key 的请求使用其稳定 digest 作为 domain；无 session key 的每个请求形成独立 domain。
对 checkpoint (p) 和完整 portfolio state (S)：
[ Saving(p,S)=\max(0,\ Rebuild(p)-Recovery(p,S)) ]
Rebuild 是从 root 到该 frontier 的 canonical prefill cost。Program 根据实际 State/KV placement 枚举所有
受支持的 restore/copy/interval-prefill recovery recipes；common runner 用本次 planning problem 的同一个
immutable machine cost model 定价并取最小值作为 Recovery。Program 不接收 cost model，也不替策略层选择
recipe。每条 demand 只取所有 matching checkpoints 中的最大 saving：
[ EmpiricalValue(S)=\sum_q\max_{p\ matches\ q}Saving(p,S) ]
因此 tools、instructions 和 full-prompt 等嵌套 prefixes 不会对同一个未来请求重复计价。再加上尚未到期 的显式 shared credit，得到公共价值：
[ PublicValue(S)=EmpiricalValue(S)+SharedCredit(S) ]
Private retention 表示每个 owner 还有一次未观测的后续复用。比较 baseline (S_b) 与 target (S_t) 时， 保持 checkpoint identity 不变，先计算每个 checkpoint 的 saving 损失，再在 owner 内取最大值：
[ PrivateLoss_o(S_b,S_t)=w_o\max_{p\in o} \max(0,Saving(p,S_b)-Saving(p,S_t)) ]
不同 owners 的 PrivateLoss 相加。这样不会把同一 continuation 的嵌套 checkpoints 全部当作未来请求，
也不会让一个仍然可用的末端 checkpoint 掩盖较早 TurnClosure 或 long anchor 的损失。权重为：
| Private retention | prior weight |
|---|---|
| Disposable | 1 |
| RecentPrivate | 4 |
| LiveSession | 16 |
Shared owner 没有固定 retention multiplier。ExplicitBoundary 或 RequestedAutomatic 在 publication 时带来
一个 owner-scoped credit；它在第一次后续 exact match 时消费，或在 32 次成功 materialization 后到期。
同一 frontier 的多个 evidence 不叠加 credit。
对 mandatory materialization 的 candidate identity state (I_c) 和 pressure target (T)：
[ FutureLoss_c(T)=\max(0,PublicValue(I_c)-PublicValue(T)) +\sum_o PrivateLoss_o(I_c,T),\qquad J(c,T)=Now(c,T)+FutureLoss_c(T) ]
对 optional shared capture，比较 private-only state (S_b) 与 complete shared target (S_t)：
[ NetGain=PublicValue(S_t)-PublicValue(S_b) -\sum_o PrivateLoss_o(S_b,S_t)-ImmediateDelta ]
执行前 candidate subset 另减精确 SplitCost；capture offer 到达后 split 已经发生，不再重复计费。
ImmediateDelta 包括 shared target 相对 private baseline 的 transfer/copy cost，并乘以当前 capture owner
及被该 global transition 阻塞的其他请求数。只有 NetGain>0 才发布；相等、溢出或饱和无法证明严格
正收益时保持 baseline。
Selected source 的合法 ConsumedToActive 是 ownership transfer，不计作 eviction。其他随 pressure
删除或降级的 checkpoints 通过 public value 与 private transition loss 进入 future loss。
Program 为未 assessment 的 target 返回 physical residual、预计剩余步数、transfer/recovery work 和 稳定 ordinal。ResourceManager 将这些事实与 portfolio policy、logical publication 条件合并成 priority。 构造目标同时包含物理容量和逻辑可采用性；物理缺口为零不能代替 publication slot 检查。
这些值只决定探索顺序及 optional 额度边界是否值得继续搜索：不能标记 target feasible，不能证明 incumbent 最优，不能参与 physical readiness。组合动作可能取消拷贝，预测成本不是可用于剪枝的 数学下界。只有完整 exact assessment 与 logical-adoption check 可以产生可采用方案。
Planner 必须先读取全部 exact candidate identities。只有 Program 明确表示所有 candidate 均不需要也不能 通过 pressure 改善当前 materialization work 时，才直接 seal 最佳可采用 identity。只要任一 candidate 仍 expandable，就建立同一 bounded pressure domain；不能因为估计成本高于 incumbent 而跳过它。
最终 shared-capture split 由 ResourceManager 在 selected candidate 已确定后选择。Program 在 seal 内验证并
消费 FinalScheduleIntent；返回的 ResourcePlan 不再具有 post-seal mutation API，Scheduler 看到的
summary 已是最终值。
若没有 identity target 同时满足物理与 logical publication 条件，Planner 在 optional budget 之外 assessment：
root candidate
+ release all unprotected inactive cache
root maximal target 由 candidate-specific eligible domain 构造；selected source 没有 victim cell。它不保留 可牺牲 cache value，但保证 heuristic、target budget 或 wall budget 失败不会把本可运行请求误判为 blocked。 active requirements、source required coverage、writer 和 transaction pins 始终留在 Program 的 requirement union 中。
若 isolated root 超过静态合同，结果为 permanently infeasible；若 isolated root 可行但 active guarantee、 lane 或 open transaction 阻塞，结果为 temporarily blocked。
Materialization 与 shared capture 使用两个 typed entrypoint。Materialization 的 incumbent 是已验证
identity 或 root maximal；启用 ContextCacheOptions::recency_eviction（ninfer-serve --recency-eviction，默认关闭）时，root maximal 之前先取 escape-hatch recency ladder 中「sacrifice 最少且
可 adoption」的一级 rung，root maximal（clear-all）只作为 liveness backstop。shared capture 的 incumbent
是 Skip，只有 exact NetGain>0 才替换。
ResourceManager 只在该开关打开时把 recency 排名交给 planning session；没有排名时 session 不生成 demote-to-host 的 preserve outcome，完全 evict 对每个 owner 都可达，与原有经济搜索一致。
Escape-hatch rung 把 private owner 与 shared owner 放进同一个 recency 排名（最近一次命中或发布优先—— 刚发布、尚未被命中的 continuation 或 shared prefix 也算最近使用；tie 保持输入顺序）：rung k 完全 evict 最旧的 k 个 owner，其余 owner 保持不变——其中仍可由 Host 承载的 owner（private 或 shared）通过 demote-to-host 释放 device 资源并保留 host copy。Shared prefix 不再被每一级 rung 无条件销毁：一个仍被 新会话频繁命中的 shared prefix 会比闲置的会话活得更久。Rung 只有在 physical 可行且 logical adoption 成功 时才算数，因此 publication-only 这类物理上放得下、但需要一个 released owner 的 admission 也能找到 最小 sacrifice；没有 host tier 的池同样能表达「evict 最旧的 k 个、其余保留」。该最小 sacrifice 同时 licence 增量搜索：incremental enumeration 只能完全 evict 这条 LRU tail，tail 之外的 owner 只能被 demote/degrade/ 保留，所以计划不会用一个更近 prefix 的内容换取更旧 prefix 的 device KV。identity 可行时 licence 为空，即 不需要 eviction。
一次 planning problem 中：
- ResourceManager mint candidate/owner IDs，保留到 catalog capability 的唯一映射；Program 为每个 candidate 建立 selected source 结构性缺席的 eligible victim domain。
- Program 持有 opaque targets 与分片构造状态；Runtime 按预计完整 J 和缺口改善排列合法选项， 兼顾价值与尽快形成可行方案，不构造 State/KV action。
- 优先评估完整候选，失败后根据精确物理与逻辑反馈继续修复。Host geometry 等不能由总字节量 证明的条件需要更早的 exact feedback。局部构造以外保留普通 alternatives。
- 完整联合 post-state 结算 unique objects、alias、Move/Fork、COW、Host geometry 与 stage peak。 只有物理可行且 logical adoption 成功的结果参与最终 J 与稳定 tie-break 比较。
- 任意 optional 时间、工作或容量预算耗尽，返回最佳已验证 incumbent。
构造、修复、普通 expansion、maximal target 与 seal 共用 candidate-specific domain 和 exact evaluator。 游标、target arena 与借用摘要只在同一 planning session/revision 内有效；批次停止或丢弃不能产生 真实资源 mutation。结束搜索后不跨 decode/prefill 恢复旧状态。
Engine 提供 admission boundary 共享的 optional 时间额度，head/backfill inspections 不能各自重置。 预算考虑其他 runnable 请求及本 boundary 已花费的时间。Planner 先用短窗口搜索，再根据尚可获得 的预计改善和完成成本决定是否续额；不完整预测只有受限探索机会，已实现收益不能反复用于续额。 Target、工作量和 session storage 仍独立有界。
Identity 与 root maximal correctness assessment 不因 optional 额度耗尽而取消。时间在 Program operation 之间检查，估计误差可造成单步越界；最终 seal 仍必须完成。因此预算只影响 cache quality， 不改变 mandatory readiness，也不承诺整个 planning 调用可在任意时刻中断。 Shared capture 维持独立的固定 target budget 与 Skip incumbent。
对 exact feasible assessment：
J = price(Program machine work)
+ ResourceManager portfolio loss
Program 只形成 canonical transfer/prefill work，并为 checkpoint recovery 枚举受支持的物理 recipes； ResourceManager 提供 demand、retention 和 shared credit；runner 使用同一次 planning problem 的 immutable machine cost model 统一定价并比较。成本模型不会进入 Program API，只能改变已验证 targets 的探索和选择 顺序，不能改变 physical status、readiness、source protection 或 target generation。
相同 J 下依次偏好：
- 少影响已观测命中的 checkpoints，保留最近命中；
- 少 owner eviction、checkpoint deletion、copy operation 和 transferred bytes；
- 少剩余 Text/Vision prefill；
- 多复用 prompt tokens；
- 当前 session binding；
- candidate 与 target 的稳定 ordinal。
停止原因只描述实际边界：no_pressure、queue_exhausted、target_budget、
expansion_capacity、time_budget、work_budget 或 insufficient_expected_gain。
time_budget 也包括预计下一不可分操作无法放入余量的情况。它们不声明当前 target graph 或真实
TTFT 的全局最优性。
最终结果只有四类：
| 结果 | 含义 |
|---|---|
PermanentlyInfeasible |
isolated root completion requirement 超过当前 Engine 合同 |
TemporarilyBlocked |
单请求可行，但当前 active/lane/transaction 状态阻塞 |
NeedsTransfer |
target 可行，需要异步 transfer 或 pressure stages |
Ready |
target 已 Device-ready，可在当前 boundary 同步发布 |
TemporarilyBlocked 只在 lane、FIFO protection、open transaction 或 resource revision 变化后重新检查。
普通 decode 不重复运行 planner。
需要 allocation、pressure 或 transfer 的终态通过：
ResourcePlan
-> RunningTransaction
-> ResourceResult
ResourcePlan：Program seal 的 immutable、move-only、revision-bound transition；RunningTransaction：Program 当前执行中的唯一 global resource transition；ResourceResult：Committed 或 Aborted 的完整稳定结果。
Active reservation 已经覆盖且不需要新 allocation/transfer 的 finish、discard 或 inactive release 可以作为 零阶段原子 transition 完成，但仍遵守同一串行化、revision 和完整结果规则。
Program 在第一次 mutation 前重新验证：
- plan 的
resource_revision； - source、victim 和 destination capability generation；
- ResourceManager 已保留的 logical publication capacity；
- 当前 allocator 对每个 ordered stage 的容量和几何；
- source/victim dependencies 与 active protections。
Stale 或不再可行的 plan 在 start 前无物理副作用。Start 成功后，source、victims 和 destinations 被 claim/pin，plan 被线性消费，不再更换 candidate 或 target。
ResourceManager 在调用 Program start 前先建立唯一 logical transaction record，并把所有 source/victim 与 publication destinations 置为 claimed/reserved。Program 在第一次物理 mutation 前完成自己的 preflight。 同步 start 返回 Aborted 时，ResourceManager 回滚完整 logical claim；start 成功后 logical record 与 Program transaction 一直同时存在，直到 stable result adoption 或 Engine-wide cleanup。
Transaction 可以跨同步 copy 或 CUDA event 推进。每个 replacement 遵循：
destination reserved
-> copy complete
-> epoch/coverage verified
-> replacement published
-> old replica released when unreferenced
Materialization 与 active capture 共用一条单调 pressure phase：
HostReleases -> CopyPreparation -> CopiesInFlight? -> CopyPublication -> Committed
phase 是全局 pressure 顺序的唯一 authority。每个 owner work 可以保存 destination/copy 是否已实际提交以及
mutation 是否已发布的执行事实，用于形成 absolute result；这些事实不能改变或绕过全局 phase。无 copy 时从
CopyPreparation 直接进入 CopyPublication。Cancellation 只在稳定 phase boundary 采用，已发布的 Host
release 或 victim eviction 通过绝对 ResourceResult 报告。
同一时间至多一个 global resource transition。既有 active execution 只有在使用自身既有 reservation、 且不触碰 transaction mappings 时才能与 transfer 交错。
Commit 发布：
- new active sequence 或 checkpoint；
- selected source disposition；
- 已提交的 owner/checkpoint degradation；
- stable State/KV placements；
- transaction pin/reservation cleanup；
- 必要的
resource_revision变化。
ResourceResult 包含 ResourceManager 采用逻辑终态所需的绝对结果，不包含供上层重建物理 occupancy 的
delta。每个 owner claim 绑定确切的 CheckpointRef 删除集合，而不是只绑定删除数量；ResourceManager
逐项核对最终 summary 恰好等于原 checkpoint 集合减去该集合。因此同数量但不同 checkpoint 的替换会在任何
catalog mutation 前失败。ResourceManager 在 start 前已预留 adoption storage，因此 commit 后的 adoption
不能进行新的容量判断。
Publication 前的 cancellation 或执行失败可以得到 request-local abort，只要 Program 仍能形成稳定物理状态。 Abort 保证：
- selected source 仍有效；
- target 没有半 Active 或半 published checkpoint；
- unused destinations、reservations 和 pins 已释放；
- 已安全完成的 victim demotion/deletion 被明确记录在
ResourceResult中。
已经发布 replacement 后完成的合法 pressure degradation 不需要逆向复制回原 placement。ResourceManager 采用 abort result 中的实际终态，而不是回放中间 receipts。
若 Program 已无法形成可解释的稳定状态，则进入 Engine-wide failure。
Private retention class 通过 owner prior 影响 portfolio value，不提供固定 eviction 顺序。Shared owner 的价值 来自真实 demand 与尚未到期的 explicit credit。Planner 可以组合：
- 删除冗余 replica；
- 将 Device replica 降为 Host-only；
- 删除不再保留的 checkpoint 或 suffix coverage；
- evict 完整 inactive owner。
如果一个 placement change 会删除 checkpoint 的最后一份完整 State 或 required KV coverage，同一个 target 必须先建立 replacement，或同时删除该 checkpoint。
Placement 只在 admission、capture、finish 或显式 inactive release 的 resource boundary 改变。普通 decode 不运行周期性 promotion/demotion。
SessionKey 属于 ResourceManager，只提供 candidate lookup 与 binding。Program 不读取 SessionKey。
每个可更新 SessionIndex 的请求取得单调 publication_order：
- 新结果只有 order 更大时才能替换当前 binding；
- 较旧请求晚完成时成为 anonymous cache 或按 policy 释放；
- matching private source 可以在合法时 consume-to-active；
- shared source 始终保持 immutable；
- abort 只能恢复自己仍持有 exact claim 的 former binding。
Capability generation 判断 handle 是否仍有效，publication order 判断哪个完成结果更新 session；两者职责不同。
ResourceManager 必须在 Program mutation 前预留 active/private/shared destination slot。Program commit 后的 logical adoption 不再扩容或搜索 slot。
Private Move 可以复用 source descriptor；root 或 Fork 需要 destination。Optional capture 没有 slot 时跳过； terminal Finish 没有合法 publication capacity 时采用 Discard。
ContextCacheOptions 在 Engine 构造时解析为固定容量：
| 配置轴 | 架构含义 |
|---|---|
device_state_slots |
active guarantee 之外可保留的 Device checkpoint StateImages |
host_state_slots |
完整 Host StateImages |
host_kv_capacity_bytes |
typed packed Host KV arena 总容量 |
max_private_continuations |
private owner/catalog 容量 |
max_shared_prefixes |
shared immutable owner/catalog 容量 |
max_long_anchors_per_continuation |
每条 private history 的 retained long checkpoints 上限 |
所有 stores、catalogs、Program unique-object scratch 和 reusable planner frontiers 都按解析后的上限建立。 每个 pressure planning session 的 target arena、hash 和 assessment storage 在 session 开始时按固定上限取得 容量；target expansion 不得突破该容量。Logical claim manifests 与 adoption 所需容量必须在 Program mutation 前取得。每请求 external markers 固定最多四个、Frontend candidates 固定最多三个、demand window 固定为 32；这些是产品语义与算法有界性，不是可调容量轴。 配置必须满足：
- private continuation capacity 至少覆盖全部 active requests；
- Device State 总容量为
max_concurrency + device_state_slots； - Host State 与 Host KV 独立计费；
- logical counts、address-space counts 和 storage sizes 可表示；
- Program 可以兑现最小 active capacity 与 selected backend requirements。
Context cache disabled 时采用 root-only 语义：不读取或发布 inactive continuation，Device/Host checkpoint 容量为零，但 active execution 所需的 State/KV reservation 保持不变。
公开默认值和启动命令由 EngineOptions、CLI与 Serving维护，不在本架构
文档中复制。
- Scheduler 先选择 request；资源层不能以 cache value 改变请求顺序。
- ResourceManager 是 logical cache policy 的唯一 authority，Program 是 physical state 的唯一 authority。
- Physical occupancy 按 unique allocations 与 concrete reservations 计数，不按 logical references 重复计数。
- Reclaim、Move/Fork 和 COW 必须从完整联合 post-state 推导。
- 每个有序 transition stage 都必须满足容量与 allocator geometry。
- Prefix hit 必须具有 exact identity、完整 StateImage 和全部 required typed KV coverage。
- Published checkpoint immutable；每条 active continuation 至多一个 mutable writer。
- Active completion reservation 在 terminal resource result 采用前不可被借用或回收。
- 同一时刻至多一个 global resource transition，且 sealed plan 与
resource_revision绑定。 - Start 前 stale rejection 无物理副作用；start 后不能更换 candidate 或 target。
- Program commit/abort 都返回完整稳定终态；ResourceManager adoption 已预分配且不能失败。
- Root 加释放全部 unprotected inactive cache 是 bounded search 之外的 correctness fallback。
- Planner 成本模型只排序可行 targets，不参与物理正确性。
- Session binding 只接受更大的 publication order。
- Retention 或 capture 失败必须退化为 skip/release，使 active lane 有有限终态。
- Shared publication 必须严格优于 private-only baseline；单个 demand 对嵌套 prefixes 只能贡献一次最大 saving。
- Candidate selection 不是资源预留；实际 capture target 必须在 frontier 到达后按当前 revision 重新 证明完整物理终态。
| 职责 | 主要位置 |
|---|---|
| logical catalog、claims、session policy | src/runtime/engine/context_cache/resource_manager.h |
| bounded target ledger 与 common search primitives | src/runtime/engine/context_cache/resource_search.h |
| cross-candidate bounded planner | src/runtime/engine/context_cache/materialization_planner.h |
| typed shared-capture bounded entrypoint | src/runtime/engine/context_cache/shared_capture_planner.h |
| shared/private portfolio value | src/runtime/engine/context_cache/context_portfolio_value.h |
| machine cost model | src/runtime/engine/context_cache/context_cost.cpp |
| prefill measurement signature | src/models/qwen3_5/measurement.cpp |
| common resource summaries | src/runtime/contract/resources.h |
| unique-object projection contract | src/models/qwen3_5/program/planning/resource_projection.h |
| target domain、projection 与 transaction | src/models/qwen3_5/program/planning/、src/models/qwen3_5/program/transactions/ |
| State stores | src/models/qwen3_5/program/storage/state_store.h |
| logical KV/address spaces | src/models/qwen3_5/program/storage/kv_store.h |
| Host KV extents | src/models/qwen3_5/program/storage/host_kv_store.h |
| public capacity options | include/ninfer/types.h |
路径用于定位当前实现，不改变本文定义的所有权边界。