docs(runtime): explain import proof and identity ownership

This commit is contained in:
2026-11-12 13:14:06 +08:00
parent 3c8953e842
commit 238e4dd4c5
3 changed files with 44 additions and 15 deletions
+10 -4
View File
@@ -8,10 +8,14 @@ import {fault} from '../canvas-core/values.ts';
/** 源记录/依赖键到目标ID的只读字典,element/canvas前缀由调用者约定。 */
type Ids=Readonly<Record<string,Id>>;
/** One runner's last immutable ID index. Copies are deferred until allocation. */
/** 返回带clear方法的捕获工厂,每次为一个源记录的准备提供reserve/has/finish私有上下文。 */
/** 一个 runner 的捕获工厂,缓存最近一张可复用表及其 used Set;每次 capture 创建独立分配上下文。
* 初始表的值域/空 ID/已有重复映射未在此完整校验,Set 只用于拦截后续 createId 与已知 ID 碰撞。
* 不查项目文档、墓碑、其它 runner 或服务身份空间;稳定映射须由 job 校验与发布层共同保证。 */
export function createImportIdentities(){
let cached:{ids:Ids;used:Set<Id>}|undefined;
/** 相同已冻结纯字符串属性表可复用used索引;其它输入先复制为无原型字典。 */
/** 同引用命中缓存时直接复用;否则仅将冻结且描述符为字符串数据值的输入视为可复用。
* 这是性能准入,不是完整 schema/普通对象证明;其余输入以 Object.assign 捕获到无原型字典,getter 会在此求值。
* 首次分配前共享基表/used;写时再分离,避免每条只查既有键的记录重扫整张映射。 */
const capture=(input:Ids,createId:()=>Id)=>{
let identity=cached?.ids===input?cached:undefined;
if(!identity){
@@ -30,10 +34,12 @@ export function createImportIdentities(){
},
/** 判断目标ID是否已被本映射使用,不声称该ID已加入文档或已同步。 */
has:(id:Id)=>used.has(id),
/** 返回本次分配后的只读映射;没有新分配时保留输入身份便于下一记录复用索引。 */
/** owned 缓冲通过 dataRecord 再捕获不可变值,后续 reserve 不改变已经返回的结果。
* 可复用输入且无分配时沿用原表;可变/getter 输入即使未分配也返回捕获表,每次 finish 可重新捕获。
* 返回不代表映射已落盘;runner 须与导入进度/文档同次发布和持久化。 */
finish:():Ids=>owned?dataRecord(ids):ids,
});
};
/** clear只丢弃临时复用索引,不清除已持久化job的stableIds。 */
/** clear 只丢工厂最近索引;现有 capture 上下文仍能使用,不清已发布/持久 job.stableIds,也不回收 ID。 */
return Object.freeze(Object.assign(capture,{clear(){cached=undefined;}}));
}