docs(service): explain run admission and event validation

Reviewed-on: #11

src/lib/canvas-bindings/compat-types.ts

@@ -1,6 +1,7 @@
 /**
  * 旧卡片 renderer 使用的结构化输入类型，与 headless 元素 schema 分离。
  * 这些类型描述投影/显示约定，不能用类型断言替代 registry 对原始数据、版本和引用的运行时校验。
+ * 本文件仅定义 TypeScript 形状，不运行默认值/迁移/编辑行为；投影器负责从标准 element 生成这些显示字段。
  */
 /** 旧绘制路径使用的二维点；是否局部/场景由投影路径的调用约定决定。 */
 type Point={x:number;y:number};

src/lib/canvas-bindings/connection-paint.ts

@@ -11,7 +11,9 @@ import {compatConnector} from './connectors.ts';
 /** Conservative cubic control hull + half stroke, in the displayed scene space.
  * Missing/custom geometry stays unknown so a host cannot interpret it as invisible. */
 /** 可选缓存的共享实现，限制本次边数和总曲线段数。
- * 缓存命中仍扣减段预算，不让缓存历史悄悄放宽相同查询的工作量语义。 */
+ * 缓存命中仍扣减段预算，不让缓存历史悄悄放宽相同查询的工作量语义。
+ * maxEdges 限访问的边数，maxSegments 同时作单边与总段数限；存在待查端点时仍遍历所有 projected nodes。
+ * 几何回调同步执行且没有时间抢占，回调产出数组前的成本不由预算控制；输入须属于同一有效显示帧。 */
 function connectionPaint(projection:ReturnType<typeof projectCanvas>,registry:Registry,services:HitServices={},maxEdges=4096,maxSegments=4096,cache?:Map<string,{signature:unknown;segments:number;region?:PaintRegion}>){
  if(![maxEdges,maxSegments].every(n=>Number.isSafeInteger(n)&&n>0&&n<=1000000))throw Error('invalid_paint_budget');
  const regions:PaintRegion[]=[],unknown:string[]=[],nodes=new Map<string,typeof projection.nodes[number]>(),endpoints=new Set<string>();
@@ -29,21 +31,25 @@ function connectionPaint(projection:ReturnType<typeof projectCanvas>,registry:Re
    const anchor=(node:typeof source,handle:string|null|undefined,end:'source'|'target')=>services.anchor?services.anchor(node,handle,end,edge):node.data.__headlessRecord?undefined:compatConnector(node,handle,end==='source'?'right':'left');
    const from=anchor(source,edge.sourceHandle,'source'),to=anchor(target,edge.targetHandle,'target'),transform=projection.transforms.get(record.ownerCanvasId);if(!from||!to||!transform||![from.point,from.normal,to.point,to.normal].every(point=>point&&Number.isFinite(point.x)&&Number.isFinite(point.y))||![transform.x,transform.y,transform.scale,transform.rotation].every(Number.isFinite)||transform.scale<=0)throw Error();
    const protocol=edge.type!=='unsupported'&&registry.resolve(record)==='known'?registry.components.get(record.componentId)?.geometry:undefined;
-   // 同时捕获显示边、真实记录、端点位置/大小、锚点及变换；预览/移动都可能改变曲线范围。
+   // 签名复制锚点/端点数值/transform，但 record 与 edge 借用原不可变引用，缓存不深捕获它们。
+   // 外部几何服务/协议配置不在签名内，须通过下方 geometryRevision 或 registry 对象变化失效。
    const signature={record,edge,from:{point:{...from.point},normal:{...from.normal}},to:{point:{...to.point},normal:{...to.normal}},transform:{...transform},source:{position:{...source.position},width:source.width,height:source.height},target:{position:{...target.position},width:target.width,height:target.height}},old=cache?.get(edge.id);
-   // 即使本边范围是空，也可缓存“已证明没有额外范围”，避免重复调用几何服务。
+   // 锚点与基础输入每轮仍重新求取；签名相等才复用曲线范围/段数，跳过 segments/stroke 计算。
+   // 空 region 可表示笔画未超原生范围或空 segments，不能将其误当“整条边没有显示内容”。
    if(old&&equal(old.signature,signature)){if(old.segments>remainingSegments){unknown.push('paint_budget');break;}remainingSegments-=old.segments;if(old.region)regions.push(old.region);continue;}
    computed++;
    // renderer 服务优先，随后用组件几何协议；stroke 也必须来自同一显示语义。
    const segments=services.edgeGeometry?.(edge,from,to)??(protocol?.kind==='connection'?protocol.segments({element:record,source:from,target:to,displayPath:edge.data?.__headlessRecord?undefined:edge.data?.path??null,transform}):undefined),stroke=services.strokeWidth?.(edge)??(protocol?.kind==='connection'?protocol.strokeWidth({element:record,transform}):undefined);
-   // 校验每边段数、线宽，再扣全局剩余段数；空段列表是已知无笔画，不应误标 unknown。
+   // 非空段数超过本次剩余预算则追加全局 paint_budget 并终止后续边；空数组仍要求有效 stroke。
+   // 空数组缓存0段/无region，属本几何协议声明无笔画，不误标 unknown。
    if(!segments||!Array.isArray(segments)||segments.length>maxSegments||typeof stroke!=='number'||!Number.isFinite(stroke)||stroke<0)throw Error();if(!segments.length){cache?.set(edge.id,{signature,segments:0});continue;}if(segments.length>remainingSegments){unknown.push('paint_budget');break;}remainingSegments-=segments.length;
    let left=Infinity,top=Infinity,right=-Infinity,bottom=-Infinity;
    // 三次曲线完全位于控制点凸包内，所有控制点的轴对齐包围盒提供保守范围。
    for(const segment of segments){if(!Array.isArray(segment)||segment.length!==4)throw Error();for(const point of segment){if(!point||!Number.isFinite(point.x)||!Number.isFinite(point.y))throw Error();left=Math.min(left,point.x);top=Math.min(top,point.y);right=Math.max(right,point.x);bottom=Math.max(bottom,point.y);}}
    // 向四侧扩半线宽，同时检查端点相加不溢出，否则当前边转 unknown。
    const half=stroke/2,x=left-half,y=top-half,width=right-left+stroke,height=bottom-top+stroke;if(![x,y,width,height,x+width,y+height].every(Number.isFinite))throw Error();
-   // 原生范围由两端节点矩形并集包围；只有实际笔画包围盒超出它，才添加补充空间行。
+   // 原生范围取两端节点未旋转矩形的联合 AABB；曲线控制点凸包+半线宽 AABB 超出时才添整块补充范围。
+   // 这是保守估计而非曲线精确极值，允许额外保留可见候选；不计算命中距离或直接控制 renderer 挂载。
    const native={left:Math.min(source.position.x,target.position.x),top:Math.min(source.position.y,target.position.y),right:Math.max(source.position.x+source.width!,target.position.x+target.width!),bottom:Math.max(source.position.y+source.height!,target.position.y+target.height!)};
    if(!Object.values(native).every(Number.isFinite))throw Error();const region=x<native.left||y<native.top||x+width>native.right||y+height>native.bottom?{id:edge.id,bounds:{x,y,width,height}}:undefined;if(region)regions.push(region);cache?.set(edge.id,{signature,segments:segments.length,region});
   // 异常几何不保留过时缓存；单边失败隔离为该 ID 的 unknown，不影响其它已知范围。
@@ -56,11 +62,15 @@ function connectionPaint(projection:ReturnType<typeof projectCanvas>,registry:Re
 export function projectedConnectionPaintOverflow(projection:ReturnType<typeof projectCanvas>,registry:Registry,services:HitServices={},maxEdges=4096,maxSegments=4096){return connectionPaint(projection,registry,services,maxEdges,maxSegments);}
 /** Host revision invalidates geometry services whose external configuration changes. */
 /** 视图级曲线范围缓存与网格。外部锚点/样式服务配置改变时，宿主必须同步推进 geometryRevision，
- * 仅换闭包或修改服务内部状态不在元素签名中，不能指望缓存自行察觉。 */
+ * 仅换闭包或修改服务内部状态不在元素签名中，不能指望缓存自行察觉。
+ * 每视图独立实例；缓存按 registry 对象/project/canvas/revision 隔离，不另核 editor owner。
+ * cache 保留边几何结果，index 存本轮额外区域；超过预算的其它边可暂留缓存但不进入本轮 regions。 */
 export function createConnectionPaintIndex(){
  const cache=new Map<string,{signature:unknown;segments:number;region?:PaintRegion}>(),index=createPaintIndex();let owner:Registry|undefined,project:string|undefined,canvas:string|undefined,revision:unknown,computed=0;
  /** 同步当前场景；范围身份或 geometryRevision 变化整体失效，删除已移出的边缓存。
-  * query 与 unknown 配套使用；computed 是累计重新计算数，不把缓存命中记成一次曲线计算。 */
+  * unknown 中元素 ID 表示该边无法解释，字符串 paint_budget 表示余下查询不完整，不能据空 regions 判不可见。
+  * query 是可变 index 的方法，旧返回对象也查最新网格，unknown 则是本轮冻结列表。
+  * computed 计通过锚点/变换检查后未命中的几何尝试（可随后失败），不等于成功区域数；clear 不重置累计值。 */
  return Object.freeze({sync(projection:ReturnType<typeof projectCanvas>,registry:Registry,services:HitServices={},geometryRevision?:unknown,budget:{maxEdges?:number;maxSegments?:number}={}){
   if(owner!==registry||project!==projection.document.projectId||canvas!==projection.canvasId||!Object.is(revision,geometryRevision)){cache.clear();index.clear();owner=registry;project=projection.document.projectId;canvas=projection.canvasId;revision=geometryRevision;}
   const result=connectionPaint(projection,registry,services,budget.maxEdges??4096,budget.maxSegments??4096,cache),seen=new Set(projection.edges.map(edge=>edge.id));for(const id of cache.keys())if(!seen.has(id))cache.delete(id);index.sync(result.regions);computed+=result.computed;return Object.freeze({query:index.query,unknown:Object.freeze(result.unknown)});

src/lib/canvas-bindings/connectors.ts

@@ -9,7 +9,9 @@ import {nodeConnector,type Connector,type ConnectorSide} from '../canvas-geometr
 type CompatNode=CanvasGeometryNode&{data:ProjectionNode['data']};
 /** Same card-border and port layout used by CanvasEdge. Never infer it for record-v1 DOM. */
 /** 方向优先取降级外壳提示，再取标准 handle 名、port 方向或调用方 fallback。
- * 同方向多个 port 沿高度均匀分布，与兼容 CanvasEdge 使用同一布局。 */
+ * 找到具名 port 时，同 direction 的 port 沿高度均匀分布，与兼容 CanvasEdge 使用同一布局。
+ * 即使 fallback hint 选择了另一侧，已识别 port 仍按高度做 y 偏移；这是旧布局协议，不适用于原生 Handle。
+ * nodeConnector 先负责节点边界/旋转，下面直接叠加 y 偏移，不再把这段偏移当局部向量旋转。 */
 export function compatConnector(node:CompatNode,handle:string|null|undefined,fallback:ConnectorSide):Connector{
  const port=Array.isArray(node.data.ports)?node.data.ports.find(port=>port&&`port:${port.id}`===handle):undefined,hints=(node.data as ProjectionNode['data']&{__headlessFallback?:{handles?:{id:string;side:ConnectorSide}[]}}).__headlessFallback?.handles,projected=Array.isArray(hints)?hints.find(hint=>hint?.id===handle&&['top','right','bottom','left'].includes(hint.side))?.side:undefined,side=projected??(['top','right','bottom','left'].includes(handle??'')?handle as ConnectorSide:port?.direction==='input'?'left':port?'right':fallback),result=nodeConnector(node,side);
  // 输入/输出各自独立排序，用测量高度优先；默认400仅属于旧卡片布局约定。
@@ -21,7 +23,9 @@ export type MeasuredNode={readonly internals:{readonly positionAbsolute:{x:numbe
 type MeasuredHandle={readonly id?:string|null;readonly position:ConnectorSide;readonly x:number;readonly y:number;readonly width:number;readonly height:number};
 /** Native Handle outer edge, matching the installed React Flow loose connection mode. */
 /** 从实际 Handle 外侧中心生成锚点与朝外法线。target 可采用 source 把手以匹配 loose 模式，
- * 指定 handleId 未找到或尚无测量时返回 undefined，不编造中心点。 */
+ * source 仅查 source 列表；target 按 target 再 source 顺序查，匹配 loose 模式。
+ * 非空 handleId 精确查找，空字符串/null/undefined 取首项；无匹配或未测量返回 undefined。
+ * 假定 positionAbsolute 与 Handle 尺寸采用同一场景单位；直接叠加，不在这里验证有限值或再次处理节点旋转。 */
 export function measuredConnector(node:MeasuredNode|undefined,handleId:string|null|undefined,end:'source'|'target'):Connector|undefined{
  const bounds=node?.internals.handleBounds;if(!node||!bounds)return;const handles=end==='source'?bounds.source??[]:[...(bounds.target??[]),...(bounds.source??[])],handle=handleId?handles.find(handle=>handle.id===handleId):handles[0];if(!handle)return;
  const {x,y}=node.internals.positionAbsolute,side=handle.position,normals={top:{x:0,y:-1},right:{x:1,y:0},bottom:{x:0,y:1},left:{x:-1,y:0}},point={x:x+handle.x+(side==='left'?0:side==='right'?handle.width:handle.width/2),y:y+handle.y+(side==='top'?0:side==='bottom'?handle.height:handle.height/2)};return{point,normal:normals[side]};

src/lib/canvas-bindings/element-sources.ts

@@ -16,7 +16,9 @@ export type ElementSourcePorts={
 };
 /** One upstream subscription, ID buckets and cached lookup values, never another document.
  * Explicit changes use ID routing; replacement/coverage cuts retain a checked fallback. */
-/** 创建惰性订阅中心；每个 forElement 源缓存自身读取值，同 ID 的监听共享上游桶。 */
+/** buckets 按 elementId 共享上游查询结果/观察器，每个 forElement 另有即时读取缓存。
+ * 首次 subscribe 才接上游，全部桶退订才释放 previous 根引用；创建源或直接读不持有上游租约。
+ * 依赖不可变快照与完整 Commit.changes 合同，不从队列/网络结果猜测元素是否已改变。 */
 export function createElementSources(ports:ElementSourcePorts){
  // 失败标记使下次成功查询即使值等价也通知恢复；不把异常缓存成一条虚假元素记录。
  type Bucket={value:ElementLookup;listeners:Set<()=>void>;failed?:boolean};
@@ -28,11 +30,13 @@ export function createElementSources(ports:ElementSourcePorts){
   const before=previous!;previous=next;
   const ids=new Set<Id>();
   if(before.document!==next.document){
-   // 显式元素/字段改动走 ID 路由；无 changes 的文档替换无法精确定位，复查全部已订阅元素。
+   // 显式变化只路由 field.target.id / element.id，不按 canvas 变更自动扩散到全体子元素。
+   // 文档替换且无 changes 时复查全部已订阅桶；路由准确性依赖发布者提供完整变更及 lookup 的依赖合同。
    if(commit.changes.length){for(const change of commit.changes)if(change.kind==='field')ids.add(change.target.id);else if(change.kind==='element')ids.add(change.id);}
    else for(const id of buckets.keys())ids.add(id);
   }
-  // loading 的已知范围改变会把 absent/unloaded 变成可查询；原先非 present 的桶必须复查。
+  // loading 对象或其读取基线变动可改变 absent/unloaded 判定，因此复查非 present 桶。
+  // 不将任意 runtime 更新都当元素变化；failed 桶也只有进入本次候选 IDs 才会在此重新查询。
   const coverageChanged=before.runtime.loading!==next.runtime.loading||!!next.runtime.loading&&(before.runtime.loadingRead?.document??before.runtime.acknowledged)!==(next.runtime.loadingRead?.document??next.runtime.acknowledged);
   if(coverageChanged)for(const[id,bucket]of buckets)if(bucket.value.status!=='present')ids.add(id);
   const notifications=new Set<()=>void>();
@@ -50,7 +54,8 @@ export function createElementSources(ports:ElementSourcePorts){
  return Object.freeze({forElement(id:Id):ExternalSource<ElementLookup>{
   let value:ElementLookup|undefined;
   return Object.freeze({
-   /** 每次从当前根查询并按值保留稳定引用，不能只依赖通知时机猜测最新数据。 */
+   /** 每次查询当前根，用 equal 保持等价 ElementLookup 的局部引用；读取不改共享桶通知基线。
+    * 不深复制查询值，lookup 必须返回适合不可变使用的结果；异常直接抛给调用方读取边界。 */
    getSnapshot(){const next=ports.lookup(ports.getSnapshot(),id);if(!value||!equal(value,next))value=next;return value;},
    /** 每个订阅包装独立 listener，即使调用方传同一个函数也能分别释放。 */
    subscribe(notify:()=>void){
@@ -59,7 +64,8 @@ export function createElementSources(ports:ElementSourcePorts){
     const listener=()=>notify();bucket.listeners.add(listener);
     // 首次连上游抛错时撤销这次 listener/空桶，避免半注册泄漏。
     if(!stop){previous=ports.getSnapshot();try{stop=ports.subscribe(changed);}catch(error){bucket.listeners.delete(listener);if(!bucket.listeners.size)buckets.delete(id);if(!buckets.size)previous=undefined;throw error;}}
-    // 最后一个桶清空才退订上游，释放 previous 根引用；其它元素仍有监听时继续共享。
+    // 最后一个桶清空才 stop 上游并释放 previous；同回调的多次订阅因 listener 包装仍分别退订。
+    // stop 异常不被捕获，后续状态重置不保证执行；宿主的取消订阅端口应不抛错。
     let active=true;return()=>{if(!active)return;active=false;bucket!.listeners.delete(listener);if(!bucket!.listeners.size)buckets.delete(id);if(!buckets.size){stop?.();stop=undefined;previous=undefined;}};
    },
   });

src/lib/canvas-bindings/frame-queue.ts

@@ -6,23 +6,28 @@ import type {ExternalSource} from './selectors.ts';
 /** Presentation invalidations only. Commands, history and network work never wait here. */
 /** 宿主注入帧请求/取消能力，可接 requestAnimationFrame 或测试时钟；handle 不保存业务身份。 */
 export type FrameClock={request(callback:()=>void):unknown;cancel(handle:unknown):void};
-/** 创建一条可手动 flush 的通知队列；同一 key 在一次批次中只出现一次。 */
+/** 创建一条可手动 flush 的通知队列；Set 按键身份去重，并保留首次插入顺序。
+ * clock/publish 由宿主实现，不读取 DOM/模型；调度器异常原样抛出，不另设重试或全局错误处理。 */
 export function createFrameQueue<K>(clock:FrameClock,publish:(dirty:ReadonlySet<K>)=>void){
  let dirty=new Set<K>(),scheduled:{handle?:unknown}|undefined,disposed=false;
- /** 同步排空已有脏项，先换新 Set 再回调，回调中的新失效留给下一批，不会被本批 clear 擦掉。 */
+ /** 同步排空：先撤当前调度并换新 Set，再 publish，回调中的 invalidate 留给下一批。
+  * batch 以 ReadonlySet 类型借出但未运行时冻结，与新 dirty 已分离；publish 抛错不把本批自动放回队列。 */
  function flush(){if(disposed)return;const pending=scheduled;scheduled=undefined;if(pending)clock.cancel(pending.handle);if(!dirty.size)return;const batch=dirty;dirty=new Set();publish(batch);}
  return Object.freeze({
-  /** 合并 keys 并最多安排一个帧回调；pending 对象身份防止已取消的旧回调误刷后来的批次。 */
+  /** 逐项加入 dirty，至多安排一个帧回调；pending 对象身份防旧回调误刷后来一批。
+   * request 抛错会清 scheduled，但保留 dirty 供后续 invalidate/flush 重试；不自动再 request。 */
   invalidate(keys:Iterable<K>){if(disposed)return;for(const key of keys)dirty.add(key);if(!dirty.size||scheduled)return;const pending: {handle?:unknown}={};scheduled=pending;try{pending.handle=clock.request(()=>{if(scheduled!==pending)return;scheduled=undefined;flush();});}catch(error){scheduled=undefined;throw error;}},
   flush,
-  /** 幂等关闭并撤销帧句柄，关闭后失效通知无效果；不会替上游关闭 editor。 */
+  /** 标记 disposed 后尽力取消帧并清 dirty；后续 invalidate/flush 无效，不替上游关闭 editor。
+   * 这里不捕获 clock.cancel 异常，宿主取消端口须可靠清理；重复 dispose 不会重试一次失败取消。 */
   dispose(){if(disposed)return;disposed=true;if(scheduled)clock.cancel(scheduled.handle);scheduled=undefined;dirty.clear();},
  });
 }
 
 /** Coalesce presentation notifications; immediate invalidations flush pending work synchronously. */
 /** 给普通外部数据源加通知节流：读取始终透传当前快照，每个订阅独有可释放的帧队列。
- * 上游标 immediate 时同步 flush，常用于不能等下一帧才反映的状态边界。 */
+ * 上游标 immediate 时先 invalidate 再同步 flush，合并的旧失效也一起通知；读取从不等待帧。
+ * 同一工厂的不同订阅不共享队列；退订函数每次都会调用上游 stop，幂等性依赖该 stop 合同。 */
 export function createFrameSource<S>(source:{getSnapshot():S;subscribe(notify:(immediate?:boolean)=>void):()=>void},clock:FrameClock):ExternalSource<S>{
  return Object.freeze({getSnapshot:()=>source.getSnapshot(),subscribe(notify:()=>void){
   const queue=createFrameQueue<number>(clock,()=>notify());

src/lib/canvas-bindings/geometry-cache.ts

@@ -12,21 +12,26 @@ const sameGeometry=(a:Geometry,b:Geometry)=>a.x===b.x&&a.y===b.y&&a.width===b.wi
 /** 子画布变换只依赖 presentation 中 contentScale/unitScale，忽略无关样式字段。 */
 const units=(value:Json|undefined)=>value&&typeof value==='object'&&!Array.isArray(value)?[value.contentScale,value.unitScale]:[];
 /** View-local numeric/path projection only. No editable records, history, visibility or task facts. */
-/** 缓存实例应归一个显示上下文；计数器累计实际计算次数供性能诊断，不是模型版本。 */
+/** 一个显示上下文使用一份缓存：三个 Map 分别缓存节点几何、子 canvas 变换和连线路径。
+ * 调用方须按 begin→若干 node/child/edge→end 使用；这里不校验调用配对，也不提供失败回滚/并发帧隔离。
+ * 累计计数只在实际重算后增加，不是文档版本或当前命中次数；返回投影值冻结，键只保留所需输入。 */
 export function createGeometryProjectionCache(){
  let owner:object|undefined,project:Id|undefined,canvas:Id|undefined,nodesComputed=0,childrenComputed=0,edgesComputed=0;
  type NodeResult={position:{x:number;y:number};width:number;height:number;rotation:number};
  const nodes=new Map<Id,{incarnation:number;geometry:Geometry;transform:Transform;value:NodeResult}>(),children=new Map<Id,{incarnation:number;geometry:Geometry;transform:Transform;units:unknown;value:Transform}>(),edges=new Map<Id,{incarnation:number;path:Json;transform:Transform;value:Json}>();let seenNodes=new Set<Id>(),seenChildren=new Set<Id>(),seenEdges=new Set<Id>();
  return Object.freeze({
-  /** 开始一轮投影并重置 seen；owner 身份隔离不同 renderer/editor，即使 projectId 相同也不能混用。 */
+  /** scope 按对象身份、project/canvas 按 ID 隔离；任一变化清三张表，累计计数不清。
+   * 每轮重建 seen，随后命中缓存也记一次访问；begin 不自行遍历文档或判断元素仍可见。 */
   begin(scope:object,projectId:Id,canvasId:Id){if(owner!==scope||project!==projectId||canvas!==canvasId){nodes.clear();children.clear();edges.clear();owner=scope;project=projectId;canvas=canvasId;}seenNodes=new Set();seenChildren=new Set();seenEdges=new Set();},
   /** 将节点中心转到场景，按变换比例缩放宽高并合成旋转；缓存复制输入数值防止外部修改污染键。 */
   node(id:Id,incarnation:number,g:Geometry,t:Transform):NodeResult{seenNodes.add(id);const before=nodes.get(id);if(before&&before.incarnation===incarnation&&sameGeometry(before.geometry,g)&&sameTransform(before.transform,t))return before.value;const center=toWorld(t,{x:g.x+g.width/2,y:g.y+g.height/2}),width=g.width*t.scale,height=g.height*t.scale,value=freeze({position:{x:center.x-width/2,y:center.y-height/2},width,height,rotation:(g.rotation+t.rotation)%360});nodes.set(id,{incarnation,geometry:{...g},transform:{...t},value});nodesComputed++;return value;},
-  /** 计算分区内部坐标到场景的变换，单位比例变化也会使缓存失效。 */
+  /** 分区入口几何+父变换+contentScale/unitScale 生成内部 canvas→场景变换，单位变化也使缓存失效。
+   * 不含 collapsed 等显示决策，是否调用 child 由投影器决定；使用核心 childCanvasTransform 解释单位。 */
   child(id:Id,incarnation:number,g:Geometry,t:Transform,presentation:Json|undefined):Transform{seenChildren.add(id);const before=children.get(id),currentUnits=units(presentation);if(before&&before.incarnation===incarnation&&sameGeometry(before.geometry,g)&&sameTransform(before.transform,t)&&equal(before.units,currentUnits))return before.value;const value=freeze(childCanvasTransform(t,g,presentation));children.set(id,{incarnation,geometry:{...g},transform:{...t},units:currentUnits,value});childrenComputed++;return value;},
   /** JSON 路径按值比较；先复制/冻结输入再投影，不持有调用方可变路径作为历史缓存。 */
   edge(id:Id,incarnation:number,path:Json,t:Transform):Json{seenEdges.add(id);const before=edges.get(id);if(before&&before.incarnation===incarnation&&equal(before.path,path)&&sameTransform(before.transform,t))return before.value;const captured=freeze(clone(path)),value=freeze(transformPath(captured,t));edges.set(id,{incarnation,path:captured,transform:{...t},value});edgesComputed++;return value;},
-  /** 删除本轮未访问的缓存项，避免浏览多个分区后无限保留旧节点和路径。 */
+  /** 扫描三张缓存表，删除本轮未访问项；保留规则按调用访问，不等于元素已经从文档删除。
+   * 调用方若提前抛错且不执行 end，未访问旧项可暂留至下次完整清理，缓存不是业务恢复事实。 */
   end(){for(const id of nodes.keys())if(!seenNodes.has(id))nodes.delete(id);for(const id of children.keys())if(!seenChildren.has(id))children.delete(id);for(const id of edges.keys())if(!seenEdges.has(id))edges.delete(id);},
   /** 返回当前缓存大小和累计计算量的冻结快照；begin 不重置累计计数。 */
   stats:()=>Object.freeze({nodesComputed,childrenComputed,edgesComputed,nodes:nodes.size,children:children.size,edges:edges.size}),

src/lib/canvas-bindings/hit-query.ts

@@ -29,7 +29,10 @@ const finitePoint=(point:Point)=>!!point&&Number.isFinite(point.x)&&Number.isFin
 function geometry(node:ProjectionNode,t:Transform):Geometry{const width=node.width!/t.scale,height=node.height!/t.scale,center=toLocal(t,{x:node.position.x+node.width!/2,y:node.position.y+node.height!/2});return{x:center.x-width/2,y:center.y-height/2,width,height,rotation:((node.data.rotation??0)-t.rotation+360)%360};}
 /** Query the captured display frame. It neither edits nor replaces the native input router. */
 /** 必须使用投影对应的同一 document 和 registry。先取空间候选再精测，返回有序命中及完整性诊断；
- * 此函数不触发编辑、不消费原生事件，也不替宿主决定是否认领一次输入。 */
+ * 此函数不触发编辑、不消费原生事件，也不替宿主决定是否认领一次输入。
+ * 同步消费借入的 projection/query/services，不捕获另一份文档；几何服务须按此显示帧返回同坐标系的结果。
+ * maxCandidates 约束节点精测+边访问，maxCurveSteps 由全部边共享，maxSegments 则是每边上限；
+ * 前置 Map/层序/空间候选收集和用户几何回调不被这些计数抢占，不能据此承诺总耗时硬上限。 */
 export function hitProjectedCanvas(projection:Projection,queries:DocumentQueries,registry:Registry,viewSessionId:Id,query:HitPoint,services:HitServices={},budget:HitBudget={}){
  // 强制快照/registry 身份一致；旧投影搭配新索引可能产生看得见却点不中的结果，直接拒绝。
  if(projection.document!==queries.document||!viewSessionId)throw fault('stale_query_snapshot');if(queries.registry!==registry)throw fault('query_registry_changed');const zoom=query.space==='scene'?query.zoom:query.viewport.zoom,tolerancePx=query.tolerancePx??6,errorPx=budget.errorPx??.25,maxCandidates=budget.maxCandidates??4096,maxSteps=budget.maxCurveSteps??8192,maxDepth=budget.maxCurveDepth??20,maxSegments=budget.maxSegments??4096;
@@ -38,34 +41,43 @@ export function hitProjectedCanvas(projection:Projection,queries:DocumentQueries
  // 屏幕位置减容器 origin 与 viewport 平移后除 zoom；容差同样换算，不随缩放改变视觉点击范围。
  const point=query.space==='scene'?query.point:{x:(query.point.x-query.viewport.origin.x-query.viewport.x)/zoom,y:(query.point.y-query.viewport.origin.y-query.viewport.y)/zoom},tolerance=tolerancePx/zoom,document=projection.document,nodes=new Map(projection.nodes.map(node=>[node.id,node])),rank=new Map(queries.orderedElements([...nodes.keys(),...projection.edges.map(edge=>edge.id)]).map((id,index)=>[id,index])),candidates=new Set<Id>(services.previewIds??[]),hits:SceneHit[]=[],diagnostics:{target?:Id;code:string}[]=[];let work=0,remaining=maxSteps;
  if(!finitePoint(point)||!Number.isFinite(tolerance)||!Number.isFinite(errorPx/zoom))throw fault('invalid_hit_query');
- // 分别把场景点与容差变回各 canvas，查询本地节点索引；previewIds 可补上索引尚未覆盖的预览位置。
+ // 先收集 previewIds，再逐 canvas 反变换查局部索引，以 Set 合并；真正精测前会排除未出现在投影中的 ID。
+ // 索引几何未随瞬态 preview 改动时，renderer 必须补 previewIds，不能只靠原位置的空间候选。
  for(const[id,t]of projection.transforms){if(!Number.isFinite(t.scale)||t.scale<=0)throw fault('invalid_hit_transform');const p=toLocal(t,point),r=tolerance/t.scale;for(const candidate of queries.candidateNodes(id,{x:p.x-r,y:p.y-r,width:2*r,height:2*r}))candidates.add(candidate);}
- /** 由真实 owner 向当前显示根回溯，生成 canvas/入口路径；检测循环和无效父关系。 */
+ /** 从元素真实 owner 沿 parent 回到当前显示根，反转成根→owner 路径；不是修改元素归属。
+  * 每条命中都生成显示路径，循环/父关系断裂作为该目标诊断；viewSessionId 只沿用调用值，不查询 session 注册表。 */
  function path(owner:Id){const canvases:Id[]=[],entries:Id[]=[],seen=new Set<Id>();let id=owner;while(id!==projection.canvasId){if(seen.has(id))throw fault('canvas_cycle');seen.add(id);const parent=document.canvases.get(id)?.parent;if(!parent)throw fault('invalid_display_path');canvases.push(id);entries.push(parent.entryElementId);id=parent.canvasId;}return{viewSessionId,canvasIds:[projection.canvasId,...canvases.reverse()],entryIds:entries.reverse()};}
  /** 自定义层级必须有限；否则记入对应目标诊断，而不是用无效数值打乱排序。 */
  const layer=(id:Id,kind:'node'|'connection',fallback:number)=>{const value=services.layer?.(id,kind)??fallback;if(!Number.isFinite(value))throw fault('invalid_hit_layer');return value;};
- // 节点精测只处理投影中实际存在的候选；未知/降级组件使用矩形协议，单元素协议失败隔离为诊断。
+ // 节点精测只处理投影中实际存在的候选；unknown/fallback/非 node 几何协议统一用矩形显示外壳。
+ // confirmed 仅证明采用的显示几何命中，不宣称已经理解未知组件原始轮廓。目标回调须按 Error 风格抛错。
  for(const id of candidates){const node=nodes.get(id);if(!node)continue;if(++work>maxCandidates){diagnostics.push({code:'geometry_query_budget'});break;}try{const record=document.elements.get(id);if(!record||record.structure!=='node')throw fault('invalid_hit_projection');const t=projection.transforms.get(record.ownerCanvasId);if(!t)throw fault('invalid_hit_transform');const g=geometry(node,t),resolved=!node.data.__headlessFallback&&registry.resolve(record)==='known'?registry.components.get(record.componentId)?.geometry:undefined,protocol=resolved?.kind==='node'?resolved:rectangleGeometry,p=toLocal(t,point),localTolerance=tolerance/t.scale;
-   // 组件协议返回的几何边界也要校验；精测依据局部旋转几何和按比例换算的容差。
+   // bounds 在此用于合法性检查，最终命中由 hit 返回布尔值；不能把通过 bounds 检查当成已经命中。
+   // geometry 使用 node 的显示尺寸/位置（含预览）反算，element 仍是同帧文档记录，容差换算为 owner 局部单位。
    const bounds=protocol.bounds({element:record,geometry:g,role:'hit'});if(![g.x,g.y,g.width,g.height,g.rotation,bounds.x,bounds.y,bounds.width,bounds.height].every(Number.isFinite)||g.width<0||g.height<0||bounds.width<0||bounds.height<0)throw fault('invalid_geometry_bounds');
    const result=protocol.hit({element:record,geometry:g,point:p,tolerance:localTolerance});if(typeof result!=='boolean')throw fault('invalid_geometry_response');if(result)hits.push({target:{id,incarnation:record.incarnation},kind:'node',ownerCanvasId:record.ownerCanvasId,displayPath:path(record.ownerCanvasId),layer:layer(id,'node',node.zIndex??0),certainty:'confirmed'});
   }catch(error){diagnostics.push({target:id,code:(error as{code?:string}).code??'geometry_handler_failed'});}}
  // 优先采用 renderer 锚点。原生 headless 记录不能用旧卡片的兼容锚点猜位置，缺少服务就给出诊断。
  const anchor=(node:ProjectionNode,handle:string|null|undefined,end:'source'|'target',edge:ProjectionEdge)=>services.anchor?services.anchor(node,handle,end,edge):node.data.__headlessRecord?undefined:compatConnector(node,handle,end==='source'?'right':'left');
- // 连线与节点共用候选预算；逐边解析真实显示端点和画笔，失败不影响其它边的查询。
+ // 节点精测在先，连线随后遍历 projection.edges（不再做空间粗筛），两者共用 work 预算。
+ // 单边解析显示端点/画笔失败记诊断，继续其它边；某些边因节点预算已耗尽可能尚未访问。
  for(const edge of projection.edges){if(++work>maxCandidates){diagnostics.push({code:'geometry_query_budget'});break;}try{const record=document.elements.get(edge.id);if(!record||record.structure!=='connection')throw fault('invalid_hit_projection');const source=nodes.get(edge.source),target=nodes.get(edge.target);if(!source||!target)throw fault('geometry_anchor_unavailable');const from=anchor(source,edge.sourceHandle,'source',edge),to=anchor(target,edge.targetHandle,'target',edge);if(!from||!to||![from.point,from.normal,to.point,to.normal].every(finitePoint))throw fault('geometry_anchor_unavailable');
    const transform=projection.transforms.get(record.ownerCanvasId);if(!transform)throw fault('invalid_hit_transform');const protocol=edge.type!=='unsupported'&&registry.resolve(record)==='known'?registry.components.get(record.componentId)?.geometry:undefined,context={element:record,source:from,target:to,displayPath:edge.data?.__headlessRecord?undefined:edge.data?.path??null,transform};
-   // renderer 曲线优先，随后才用组件协议；验证段数及每段四个有限点，避免异常几何耗尽查询。
+   // 自定义 edgeGeometry 非 null/undefined 的结果优先（包括空数组），否则调用已知 connection 协议。
+   // 先检查每段4个有限点及每边段数，再求距；回调本身仍同步执行，没有超时或抢占。
    const segments=services.edgeGeometry?.(edge,from,to)??(protocol?.kind==='connection'?protocol.segments(context):undefined);if(!segments)throw fault('geometry_unavailable');if(!Array.isArray(segments)||segments.length>maxSegments||segments.some(segment=>!Array.isArray(segment)||segment.length!==4||!segment.every(finitePoint)))throw fault('invalid_geometry_response');
-   // 有效点击半径 = 场景容差 + 实际线宽/2；不把只点中心线误当成整条可见线的命中范围。
+   // strokeWidth 同样优先服务回调，再用组件协议，要求是场景单位的有限非负数。
+   // 有效点击半径=场景容差+线宽/2；不能把模型局部宽度或屏幕像素宽度未经换算直接送进来。
    const width=services.strokeWidth?.(edge)??(protocol?.kind==='connection'?protocol.strokeWidth({element:record,transform}):undefined);if(typeof width!=='number'||!Number.isFinite(width)||width<0)throw fault('invalid_geometry_paint');let possible:ReturnType<typeof hitCubic>|undefined,confirmed:ReturnType<typeof hitCubic>|undefined;
    // 曲线细分步数由所有边共享剩余预算；无法继续证明时保守返回 possible，不伪造 confirmed。
    for(const segment of segments){if(remaining<=0){possible??={hit:true,certainty:'possible',steps:0,distance:Infinity,error:Infinity,budget:true};break;}const result=hitCubic(segment,point,tolerance+width/2,{error:errorPx/zoom,maxDepth,maxSteps:remaining});remaining-=result.steps;if(result.hit){if(result.certainty==='confirmed'){confirmed=result;break;}possible=result;}}
    // 同一边任一段确定命中即可 confirmed；只有不确定命中则同时说明精度或预算诊断。
    const result=confirmed??possible;if(result?.hit){if(!confirmed)diagnostics.push({target:edge.id,code:result.budget?'geometry_query_budget':'geometry_precision'});hits.push({target:{id:edge.id,incarnation:record.incarnation},kind:'connection',ownerCanvasId:record.ownerCanvasId,displayPath:path(record.ownerCanvasId),displayedEndpoints:{source:edge.source,target:edge.target},layer:layer(edge.id,'connection',edge.zIndex??0),certainty:confirmed?'confirmed':'possible',...(Number.isFinite(result.distance)?{distanceScene:result.distance}:{}),...(Number.isFinite(result.error)?{errorScene:result.error}:{})});}
   }catch(error){diagnostics.push({target:edge.id,code:(error as{code?:string}).code??'geometry_handler_failed'});}}
- // 尚未完整加载的显示分区可能漏掉未收到元素，命中列表存在也不代表整场景查询完整。
+ // 只核当前 projection.transforms 覆盖的显示 canvas 是否完整；不推断折叠内部的未显示元素。
+ // 命中列表非空仍可能不完整，diagnostics 汇总几何解释/预算/精度与模型覆盖问题。
  if([...projection.transforms.keys()].some(id=>!queries.coverage.completeCanvasIds.includes(id)))diagnostics.push({code:'model_scope_incomplete'});
- // 排序按显示层级从高到低，同层节点优先于边，再按文档层序倒序；只返回结果，不直接改变选择。
+ // 排序：layer 降序→同层 node 优先→文档层序倒序，不以 confirmed/possible 抢改显示层级顺序。
+ // complete 仅等于本次 diagnostics 为空；消费者仍需理解命中 certainty，函数不改变 selection 或手势。
  hits.sort((a,b)=>b.layer-a.layer||(a.kind===b.kind?0:a.kind==='node'?-1:1)||(rank.get(b.target.id)??0)-(rank.get(a.target.id)??0));return freeze({projectId:document.projectId,revision:queries.revision,viewSessionId,pointScene:{...point},toleranceScene:tolerance,hits,complete:diagnostics.length===0,diagnostics});
 }

src/lib/canvas-bindings/index.ts

@@ -1,6 +1,7 @@
 /**
  * 可移植 bindings 的公共入口，集中导出投影、查询、输入与显示租约工具。
  * 不导入 React/React Flow；框架 hooks、组件注册与命令 Context 通过 react-flow.ts 明确选择。
+ * 此入口只重导出，不创建 view、订阅或缓存实例；scene coordinator 与分桶源的内部接线不在此集中公开。
  */
 /** Portable scene projection and hit queries: no React or React Flow imports. */
 // 模型到场景投影、几何缓存和受预算控制的命中查询。

src/lib/canvas-bindings/input-router.ts

@@ -16,7 +16,8 @@ const overlayTarget = '[data-canvas-overlay-view],[role="dialog"],[role="menu"],
 /** Inspect the composed path as well as the retargeted host (portals/shadow DOM).
  * This uses a structural DOM port so pure consumers need no browser globals. */
 /** 检查 target 和 composedPath 上所有可 closest 的节点，识别 shadow DOM 重定向后的输入上下文。
- * portal 需要自身携带浮层标记/角色；这里只检查实际路径，不推断不存在于 DOM 路径的 React 父关系。 */
+ * portal 需要自身携带浮层标记/角色；这里只检查实际路径，不推断不存在于 DOM 路径的 React 父关系。
+ * closest 可查节点的祖先；两个标记独立累计，可同时为 true。DOM 端口异常原样传播，不在此兜底成未编辑。 */
 export function canvasKeyContext(event:{readonly target?:unknown;composedPath?:()=>readonly unknown[]}):Pick<CanvasKeyInput,'textEditing'|'overlay'>{
  let textEditing=false,overlay=false;
  for(const target of [event.target,...(event.composedPath?.()??[])]){
@@ -28,7 +29,9 @@ export function canvasKeyContext(event:{readonly target?:unknown;composedPath?:(
  }
  return {textEditing,overlay};
 }
-/** 已被宿主处理的事件不再认领；输入法/文本与浮层直接截住，随后按固定优先级短路调用处理器。 */
+/** 已 defaultPrevented 的事件先返回 unclaimed，即使同时是文本/浮层输入也不再次认领。
+ * composing/textEditing 返回 text，overlay 返回 overlay；这两层只是上下文判断，不调用下方 handler。
+ * gesture→tool→shortcut 同步短路，抛错直接传播；返回 claim 不会自行 preventDefault/stopPropagation。 */
 export function routeCanvasKey(input:CanvasKeyInput,handlers:{gesture?:KeyHandler;tool?:KeyHandler;shortcut?:KeyHandler}):InputClaim{
  if(input.defaultPrevented)return 'unclaimed';
  if(input.composing||input.textEditing)return 'text';

src/lib/canvas-bindings/node-internals.ts

@@ -3,10 +3,12 @@
  * owner token 区分同 ID 的不同挂载实例；卸载实例的迟到失效不能触发后来新实例的测量。
  */
 /** One renderer store's transient measurement requests. Not model or history state. */
-/** 每个 renderer store 独立创建；默认微任务调度，也可注入测试或宿主 defer。 */
+/** 每个 renderer store 独立创建：owners 记录挂载 token→nodeId，dirty 只记录待测 token。
+ * defer 默认为微任务；update 接收执行时仍有效的 ID，不接触文档。工厂没有全局 dispose/flush 公开入口。 */
 export function createNodeInternalsBatch(update:(ids:string[])=>void,defer:(flush:()=>void)=>void=queueMicrotask){
  const owners=new Map<symbol,string>(),dirty=new Set<symbol>();let queued=false;
- /** 执行时才解析仍有效的 owner，按节点 ID 去重；先清 dirty 再回调，让重入失效进入下一轮。 */
+ /** 执行时解析仍有效 owner 并按 ID 去重，清 queued/dirty 后 update；重入 invalidate 可安排下一轮。
+  * update 异常直接传播，本批不自动回队重试；卸载 token 的请求被排除，新 token 须自行 invalidate 才入本批。 */
  function flush(){
   queued=false;const ids=new Set<string>();for(const owner of dirty){const id=owners.get(owner);if(id!==undefined)ids.add(id);}dirty.clear();
   if(ids.size)update([...ids]);
@@ -16,7 +18,8 @@ export function createNodeInternalsBatch(update:(ids:string[])=>void,defer:(flus
   acquire(id:string){
    const owner=Symbol(id);owners.set(owner,id);
    return Object.freeze({
-    /** 仅活跃租约可以变脏，同一批最多安排一次延后 flush。 */
+    /** 活跃 token 去重变脏，queued 防重复 defer；多个 token 若同 nodeId，flush 时再合成一个 ID。
+     * 不捕获 defer 异常：若宿主抛错但未排任务，queued 不自动复位，宿主应使用可靠调度端口。 */
     invalidate(){if(!owners.has(owner))return;dirty.add(owner);if(!queued){queued=true;defer(flush);}},
     /** 卸载同时移除 owner 和其未执行请求；已排微任务可自然执行为空，不取得新实例权限。 */
     dispose(){owners.delete(owner);dirty.delete(owner);},

src/lib/canvas-bindings/overlays.ts

@@ -9,19 +9,24 @@ import {fault} from '../canvas-core/values.ts';
 /** bounds 使用屏幕空间；target 仍是真实元素 ID+代次，viewId 限定所属交互视图。 */
 export type OverlayEntry={readonly id:string;readonly viewId:string;readonly placement:string;readonly target:Target;readonly bounds:Rect;readonly focused:boolean;readonly composing:boolean};
 /** Ephemeral screen-space placements. A lease prevents late cleanup from removing a replacement. */
-/** 为一个有效 viewId 创建租约表、冻结快照和可重建 paint 网格。 */
+/** entries 保存 overlayId→{token,entry}，snapshot 沿用 Map 插入顺序（替换同 ID 不移位），index 只按屏幕 bounds 查询。
+ * 不订阅文档/视口，不自行核 target 存活；调用者更新位置，并在 visible 时提供当前目标有效性判断。 */
 export function createOverlayIndex(viewId:string){
  if(typeof viewId!=='string'||!viewId)throw fault('view_session_required');let serial=0,snapshot:readonly OverlayEntry[]=Object.freeze([]);const entries=new Map<string,{token:number;entry:OverlayEntry}>(),listeners=new Set<()=>void>(),index=createPaintIndex();
- /** 从当前条目重建快照和空间索引后通知；这里只同步位置事实，不决定浮层 DOM 的挂载。 */
+ /** 先更新 snapshot/index，再同步通知监听集合副本；只发布位置事实，不挂载 DOM。
+  * 监听器异常直接传播且会中断后续通知，不回滚已发布条目；不能据 register/update 抛错推断它未生效。 */
  function publish(){snapshot=Object.freeze([...entries.values()].map(row=>row.entry));index.sync(snapshot.map(entry=>({id:entry.id,bounds:entry.bounds})));for(const listener of [...listeners])listener();}
- /** 复制并冻结目标/矩形，验证身份和位置；复用 paint 索引校验矩形，拒绝不合法的外部边界。 */
+ /** 重建并冻结 entry 外壳/target/bounds，校验 ID/placement/目标代次和合法矩形。
+  * focused/composing 的布尔值由类型合同约束，此处不另验；扩展字段浅保留，不是任意对象深克隆。 */
  function capture(id:string,value:Omit<OverlayEntry,'id'|'viewId'>):OverlayEntry{if(typeof id!=='string'||!id||typeof value.placement!=='string'||!value.placement||typeof value.target.id!=='string'||!value.target.id||!Number.isSafeInteger(value.target.incarnation)||value.target.incarnation<1)throw fault('invalid_overlay');const entry=Object.freeze({...value,id,viewId,target:Object.freeze({...value.target}),bounds:Object.freeze({...value.bounds})});const check=createPaintIndex();check.sync([{id,bounds:entry.bounds}]);return entry;}
  // 订阅只关注本视图位置变化，调用方需用返回函数解除监听；getSnapshot 返回稳定的最近发布值。
  return Object.freeze({viewId,getSnapshot:()=>snapshot,subscribe(listener:()=>void){listeners.add(listener);return()=>{listeners.delete(listener);};},
   /** 注册或替换一个浮层，返回只能操作本 token 的 update/release。
-   * update 先完整校验，新旧序列化值相同时不发布；过期租约的更新/释放均无效果。 */
+   * 注册时 ++serial 分配 token，覆盖注册使旧租约失效；update 先检查 token，再捕获并按 JSON 文本比较。
+   * 等值 update 不发布，register 替换始终发布；release/clear 只移除瞬态浮层，不删除元素。 */
   register(id:string,value:Omit<OverlayEntry,'id'|'viewId'>){const token=++serial,entry=capture(id,value);entries.set(id,{token,entry});publish();return Object.freeze({update(value:Omit<OverlayEntry,'id'|'viewId'>){if(entries.get(id)?.token!==token)return;const entry=capture(id,value),old=entries.get(id)!.entry;if(JSON.stringify(old)===JSON.stringify(entry))return;entries.set(id,{token,entry});publish();},release(){if(entries.get(id)?.token!==token)return;entries.delete(id);publish();}});},
-  /** 正常浮层按视口交集筛选；已聚焦或输入法组合中的浮层保留，但目标必须仍有效。 */
+  /** 先验证查询矩形并查网格，再按 snapshot 顺序筛选：current(target) 必须真，之后才考虑焦点/组合状态或交集。
+   * 焦点/输入法保留不会绕过目标有效性，也不自动移除过期 entries；返回新数组，不发布位置更新。 */
   visible(bounds:Rect,current:(target:Target)=>boolean){const ids=index.query(bounds);return snapshot.filter(entry=>current(entry.target)&&(entry.focused||entry.composing||ids.has(entry.id)));},
   /** 清空所有当前浮层并发布空快照；不关闭监听服务，后续仍可注册新租约。 */
   clear(){entries.clear();publish();},

src/lib/canvas-bindings/paint-index.ts

@@ -12,18 +12,23 @@ const valid=(r:Rect)=>r&&[r.x,r.y,r.width,r.height,r.x+r.width,r.y+r.height].eve
 /** 包含边界接触的保守交集，与 nativeRectVisible 的正面积判定用途不同。 */
 const intersects=(a:Rect,b:Rect)=>a.x<=b.x+b.width&&b.x<=a.x+a.width&&a.y<=b.y+b.height&&b.y<=a.y+a.height;
 /** Rebuildable view-space grid. Oversized regions/queries fall back without false negatives. */
-/** cellSize 决定网格尺度，maxCells 限制单区域/查询展开的格数，默认512和256。 */
+/** cellSize 决定网格尺度，maxCells 限单区域/查询展开格数，默认512和256。
+ * rows 存矩形，cells 存格→ID桶，members 存 ID→格键，overflow 存无法安全展开的 ID；全部可从输入重建。
+ * maxCells 不限制总区域数/总表大小；大区域或大查询保守回退扫描，可能线性耗时。 */
 export function createPaintIndex(cellSize=512,maxCells=256){
  if(!Number.isFinite(cellSize)||cellSize<=0||!Number.isSafeInteger(maxCells)||maxCells<1)throw fault('invalid_paint_index');
  const rows=new Map<Id,Rect>(),cells=new Map<string,Set<Id>>(),members=new Map<Id,readonly string[]>(),overflow=new Set<Id>();
- /** 算出覆盖格键；负坐标用 floor，过大或不安全的格范围返回 undefined 走保守路径。 */
+ /** 用 floor 算包含两端边界的格区间，负坐标也一致；恰好压格线的矩形可占相邻两格。
+  * 不安全整数或格数超 maxCells 返回 undefined，避免巨大循环，随后通过真实矩形交集排除假阳性。 */
  function keys(r:Rect){const x=Math.floor(r.x/cellSize),y=Math.floor(r.y/cellSize),right=Math.floor((r.x+r.width)/cellSize),bottom=Math.floor((r.y+r.height)/cellSize);if(![x,y,right,bottom].every(Number.isSafeInteger)||(right-x+1)*(bottom-y+1)>maxCells)return;const result:string[]=[];for(let a=x;a<=right;a++)for(let b=y;b<=bottom;b++)result.push(`${a},${b}`);return result;}
  /** 同时清除反向成员表、格桶与溢出集合，空桶立即释放。 */
  function remove(id:Id){for(const key of members.get(id)??[]){const bucket=cells.get(key)!;bucket.delete(id);if(!bucket.size)cells.delete(key);}members.delete(id);overflow.delete(id);rows.delete(id);}
  return Object.freeze({
-  /** 先验证完整输入的 ID 唯一性和矩形，再更新差异；超大区域归入 overflow，每次查询都检查。 */
+  /** 先复制全部输入矩形并验证非空 ID/唯一性/合法矩形，再移除消失项并更新变化项。
+   * 不变行保留现有桶；大区域归 overflow 每次查。格式校验失败不开始改表，但不承诺任意运行时异常都回滚。 */
   sync(regions:readonly PaintRegion[]){const incoming=new Map<Id,Rect>();for(const region of regions){if(!region.id||incoming.has(region.id)||!valid(region.bounds))throw fault('invalid_paint_region');incoming.set(region.id,{...region.bounds});}for(const id of rows.keys())if(!incoming.has(id))remove(id);for(const [id,r]of incoming){const old=rows.get(id);if(old&&old.x===r.x&&old.y===r.y&&old.width===r.width&&old.height===r.height)continue;remove(id);rows.set(id,r);const list=keys(r);if(!list){overflow.add(id);continue;}members.set(id,list);for(const key of list){let bucket=cells.get(key);if(!bucket)cells.set(key,bucket=new Set());bucket.add(id);}}},
-  /** 普通查询查覆盖格加 overflow，大查询扫描全部行，最后统一按矩形相交过滤。 */
+  /** 覆盖格+overflow 合并候选，无法安全展开的大查询改扫全部 rows；最后含边界相交精筛。
+   * 返回新 Set（只读仅是类型），外部改它不影响索引；不排序，不能用迭代次序当绘制层序。 */
   query(region:Rect):ReadonlySet<Id>{if(!valid(region))throw fault('invalid_paint_region');const list=keys(region),candidates=list?new Set([...overflow,...list.flatMap(key=>[...cells.get(key)??[]])]):new Set(rows.keys());return new Set([...candidates].filter(id=>intersects(rows.get(id)!,region)));},
   /** 释放所有可重建空间表，不保留跨场景的区域引用。 */
   clear(){rows.clear();cells.clear();members.clear();overflow.clear();},

src/lib/canvas-bindings/pointer-capture.ts

@@ -6,9 +6,11 @@
 /** 最小结构化 DOM 端口，让纯测试无需真实 HTMLElement。 */
 export type PointerCapturePort={setPointerCapture(id:number):void;hasPointerCapture(id:number):boolean;releasePointerCapture(id:number):void};
 /** 普通事件匹配 pointerId 即可；lostpointercapture 还要匹配原捕获目标且确认它已失去捕获。
- * 如果同目标已重新捕获该指针，旧 lost 事件不拥有新手势；脱离 DOM 导致查询抛错则允许匹配目标清理。 */
+ * 如果同目标已重新捕获该指针，旧 lost 事件不拥有新手势；脱离 DOM 导致查询抛错则允许匹配目标清理。
+ * 缺 hasPointerCapture 的匹配目标也视为已丢失；此函数不释放 DOM 捕获、不提交/取消 editor 手势。 */
 export function ownsPointerCapture(owner:{pointerId:number;capture:unknown}|null|undefined,input:{pointerId:number;type?:string;target?:unknown}){if(!owner||owner.pointerId!==input.pointerId)return false;if(input.type!=='lostpointercapture')return true;if(input.target!==owner.capture)return false;const capture=owner.capture as Partial<PointerCapturePort>|undefined;try{if(capture?.hasPointerCapture?.(owner.pointerId))return false;}catch{/* A detached matching target may still need cancellation. */}return true;}
-/** 平台可能因指针失效/节点卸载拒绝捕获，以布尔结果交给宿主决定是否继续手势。 */
+/** setPointerCapture 未抛错则返回 true，不再调用 hasPointerCapture 确认平台状态。
+ * 平台拒绝/节点卸载等异常统一 false，具体是否继续/取消手势仍由调用方决定。 */
 export function acquirePointerCapture(target:PointerCapturePort,id:number){try{target.setPointerCapture(id);return true;}catch{return false;}}
 /** 尽力释放且吞掉平台清理异常；DOM 释放失败不能取得 editor 的提交或取消权限。 */
 export function releasePointerCapture(target:PointerCapturePort,id:number){try{if(target.hasPointerCapture(id))target.releasePointerCapture(id);}catch{/* Detached DOM or an already released platform capture has no editor authority. */}}

src/lib/canvas-bindings/projected-paint.ts

@@ -10,7 +10,9 @@ import type {projectCanvas,ProjectionNode} from './projection.ts';
 import {createPaintIndex,type PaintRegion} from './paint-index.ts';
 /** Extra node paint extents beyond native unrotated React Flow bounds. */
 /** 对每个显示节点还原局部几何，调用组件 paint 边界，再把四角变到场景取轴对齐包围盒。
- * 只记录超出原生矩形的节点；单节点协议失败记 unknown，其余节点继续处理。 */
+ * 只输出超出原生矩形的节点完整 paint AABB，不是只输出外溢条带；每帧遍历所有显示 node。
+ * 单节点协议失败记 unknown 后继续，不包含边/selection/手势状态，也不决定 renderer 最终是否保留元素。
+ * 不检查 registry 与 projection 的来源身份，调用方须保持同解释上下文；fallback 按矩形外壳解释。 */
 export function projectedPaintOverflow(projection:ReturnType<typeof projectCanvas>,registry:Registry){
  const regions:PaintRegion[]=[],unknown:string[]=[];
  for(const node of projection.nodes)try{
@@ -36,7 +38,8 @@ const sameGeometry=(a:Geometry|undefined,b:Geometry|undefined)=>a===undefined?b=
 /** 变换值比较避免无关根发布反复计算 paint 边界。 */
 const sameTransform=(a:Transform|undefined,b:Transform|undefined)=>a===undefined?b===undefined:b!==undefined&&a.x===b.x&&a.y===b.y&&a.scale===b.scale&&a.rotation===b.rotation;
 /** 验证缓存输入是否等价；协议未声明 dataDependencies 时保守比较整个 element.data，
- * 显式声明后只比较列出的字段，声明遗漏会由协议实现者负责，不能由缓存自动推导。 */
+ * 显式声明后只比较列出的 element.data 顶层字段（不是点分路径），空数组表示声明不依赖 data。
+ * 依赖列表须随同一 protocol 对象保持不变；遗漏字段/原地修改声明不会被缓存自动推导为新协议。 */
 function sameSignature(old:PaintSignature,node:ProjectionNode,element:ElementRecord|undefined,t:Transform|undefined,protocol:NodeProtocol){
  if(old.incarnation!==element?.incarnation||old.owner!==element?.ownerCanvasId||old.component!==element?.componentId||old.version!==element?.dataVersion||old.protocol!==protocol||!sameGeometry(old.geometry,element?.structure==='node'?element.geometry:undefined)||!sameTransform(old.transform,t)||old.x!==node.position.x||old.y!==node.position.y||old.width!==node.width||old.height!==node.height||old.rotation!==node.data.rotation)return false;
  const dependencies=protocol.dataDependencies;
@@ -51,14 +54,18 @@ function captureSignature(node:ProjectionNode,element:ElementRecord|undefined,t:
  return{incarnation:element?.incarnation,owner:element?.ownerCanvasId,component:element?.componentId,version:element?.dataVersion,geometry:element?.structure==='node'?{...element.geometry}:undefined,transform:t?{...t}:undefined,x:node.position.x,y:node.position.y,width:node.width,height:node.height,rotation:node.data.rotation,protocol,data:dependencies===undefined?clone(element?.data):dependencies.map(key=>clone(element?.data[key]))};
 }
 /** View-owned incremental paint grid; unchanged rows retain their captured dependencies. */
-/** 视图级增量 paint 网格，每个节点缓存边界结果，只重新计算签名改变的条目。 */
+/** 视图级增量 paint 网格：entries 缓存每个节点的签名及 regions/unknown 结果，index 只存额外范围。
+ * 不增量维护输入成员表，每次 sync 仍遍历全部 node 并 index.sync 全部 regions；只节省未变几何计算。
+ * 由 registry 对象/project/canvas 隔离，不额外核 editor/view owner；宿主应给每个视图独立实例。 */
 export function createProjectedPaintIndex(){
  let registryOwner:Registry|undefined,canvas:string|undefined,project:string|undefined,computed=0,captured=0;
  type Projection=ReturnType<typeof projectCanvas>;
  type Entry={signature:PaintSignature;result:ReturnType<typeof projectedPaintOverflow>};
  const entries=new Map<string,Entry>(),index=createPaintIndex();
  return Object.freeze({
-  /** 切 registry/project/canvas 清空缓存；逐节点收集额外范围与 unknown，再同步网格。 */
+  /** 切 registry/project/canvas 先清表，逐节点比较签名，变化才重新捕获依赖并调用完整单节点算法。
+   * unknown 结果同样可缓存至签名变化；数据捕获/比较异常可能直接抛出，整轮并非事务回滚。
+   * query 是同一可变 index 的方法，旧返回对象的 query 会查询后续 sync 的网格；unknown 则是本轮冻结列表。 */
   sync(projection:Projection,registry:Registry){
    if(registryOwner!==registry||canvas!==projection.canvasId||project!==projection.document.projectId){entries.clear();index.clear();registryOwner=registry;canvas=projection.canvasId;project=projection.document.projectId;}
    const seen=new Set<string>(),regions:PaintRegion[]=[],unknown:string[]=[];

src/lib/canvas-bindings/projection-cache.ts

@@ -12,14 +12,17 @@ type Projection=ReturnType<typeof projectCanvas>;
 /** 原对象的生命周期证据；同 ID 的重建或移动 owner 后不能直接继承旧显示对象。 */
 type Retained<T>={incarnation:number;ownerCanvasId:Id;value:T};
 /** View-owned rendering cache, never a document store. Keep unchanged React Flow input identities. */
-/** 创建视图专属结构共享器；reuse 会就地替换传入投影数组中的等价条目，调用方应提供派生数组。 */
+/** 创建视图专属结构共享器；reuse 会就地改传入 nodes/edges 数组，调用方应提供自有可变派生数组。
+ * 不深克隆/冻结显示对象；缓存的对象须按不可变约定使用，不能传入业务记录数组或原地修改旧投影。 */
 export function createProjectionCache(){
   let scope:object|undefined,projectId:Id|undefined,canvasId:Id|undefined;
   let nodeArray:Projection['nodes']|undefined,edgeArray:Projection['edges']|undefined;
   /** 数组长度与逐项引用完全一致时沿用旧数组，顺序改变也会产生新数组身份。 */
   const stable=<T>(previous:T[]|undefined,next:T[])=>previous?.length===next.length&&next.every((value,index)=>value===previous[index])?previous:next;
   let nodes=new Map<Id,Retained<Projection['nodes'][number]>>(),edges=new Map<Id,Retained<Projection['edges'][number]>>();
-  /** 对每个显示 ID 核验模型身份，再逐层共享等价字段；返回仅包含本帧元素的新缓存表。 */
+  /** 每个显示 ID 须有文档记录；生命周期键只核 incarnation+owner，不另含 component/dataVersion，显示差异由值比较处理。
+   * 仅 data/style/position 三个嵌套字段单独等价共享，再比较整个显示对象；新表只含本帧项。
+   * 不查投影 ID 重复、不检查 node/edge 与记录的全部对应语义；这依赖上游合法投影。 */
   function retain<T extends{id:Id}>(document:Document,values:T[],previous:Map<Id,Retained<T>>){
     const next=new Map<Id,Retained<T>>();
     for(let index=0;index<values.length;index++){
@@ -35,7 +38,8 @@ export function createProjectionCache(){
     return next;
   }
   return Object.freeze({
-    /** 范围改变先整体清空；保存规范化后的对象表及稳定数组，返回包装后的投影。 */
+    /** owner/project/canvas 改变先清旧表/数组，再分别 retain 节点和边，逐项引用相同才复用整个旧数组。
+     * 总返回新的投影外壳，nodes/edges 可沿用旧引用；中途抛错可能已改传入数组，不提供事务回滚。 */
     reuse(owner:object,document:Document,viewCanvasId:Id,projection:Projection):Projection{
       if(scope!==owner||projectId!==document.projectId||canvasId!==viewCanvasId){nodes.clear();edges.clear();nodeArray=undefined;edgeArray=undefined;scope=owner;projectId=document.projectId;canvasId=viewCanvasId;}
       const nextNodes=retain(document,projection.nodes,nodes),nextEdges=retain(document,projection.edges,edges);
@@ -44,7 +48,8 @@ export function createProjectionCache(){
     },
     /** 读取本轮保留的节点显示对象，供 renderer 测量等显示流程使用。 */
     getNode(id:Id){return nodes.get(id)?.value;},
-    /** 只有上下文、生命周期、renderer type、尺寸和 data 均兼容才可沿用旧测量，不能只比较 ID。 */
+    /** 核上下文、incarnation/owner、renderer type、width/height 与 data 等价，决定能否借旧测量。
+     * 不要求 position/style/整个 node 等价，也不执行 DOM 测量；调用者仍负责应用测量结果的 UI 规则。 */
     canRetainMeasurement(owner:object,document:Document,viewCanvasId:Id,value:Projection['nodes'][number]){
       const old=nodes.get(value.id),record=document.elements.get(value.id);
       return scope===owner&&projectId===document.projectId&&canvasId===viewCanvasId&&!!old&&!!record&&old.incarnation===record.incarnation&&old.ownerCanvasId===record.ownerCanvasId&&old.value.type===value.type&&old.value.width===value.width&&old.value.height===value.height&&equal(old.value.data,value.data);

src/lib/canvas-bindings/projection.ts

@@ -16,7 +16,8 @@ import { childCanvasTransform, toWorld, transformPath, type Transform } from '..
 export { toWorld, toLocal, transformPath, type Transform } from '../canvas-core/coordinates.ts';
 /** 当前显示 canvas 自身作为场景原点，不叠加它在外层画布中的布局。 */
 const origin:Transform={x:0,y:0,scale:1,rotation:0};
-/** 无法解释或缺 renderer 时的降级外壳；只暴露类型/版本及从已知结构派生的连接把手。 */
+/** 降级原因/类型/版本及从已知结构派生的把手；节点显示还可保留字符串标题和通用身份/几何。
+ * 不透传整份未知 data 给旧 renderer，不等于删除原 payload 或保证显示完全不读取任何通用字段。 */
 export type FallbackProjection = {reason:'unknown-component'|'unsupported-version'|'renderer-unavailable';componentId:string;dataVersion:number;handles:{id:string;side:'top'|'right'|'bottom'|'left'}[]};
 /** renderer 节点形状。__headlessTarget 绑定真实身份，record-v1 另带模型记录与所属 canvas 变换。 */
 export type ProjectionNode = {id:Id;type:string;position:Point;width?:number;height?:number;selected?:boolean;draggable?:boolean;zIndex?:number;measured?:{width?:number;height?:number};style?:{width?:number|string;height?:number|string;pointerEvents?:'none'|'auto'};data:CanvasNodeData&{__headlessFallback?:FallbackProjection;__headlessRecord?:ElementRecord;__headlessTransform?:Transform}};
@@ -28,7 +29,10 @@ const object = (value: Json | undefined) => value && typeof value === 'object' &
 
 /** Construct one node. Scene updates and full traversal share exactly the same projection rules. */
 /** 优先采用手势预览几何，再计算场景中心/尺寸/旋转；已知组件的移动能力仍由 registry 判断。
- * renderer 不可用与数据未知分别记录 fallback 原因，不修改原始 payload 来伪造兼容数据。 */
+ * renderer 不可用与数据未知分别记录 fallback 原因，不修改原始 payload 来伪造兼容数据。
+ * 已知 data 字段浅展开后由通用显示字段覆盖，record-v1 另借用原 element/transform，不深复制模型记录。
+ * draggable 只按 known 与 geometry.move 能力判定，缺 renderer 的 fallback 不必自动只读；策略仍由 editor 检查。
+ * 返回可变派生对象供后续补把手/结构共享，只有 __headlessTarget 单独冻结，不是完整输出深冻结。 */
 export function projectNode(element:Extract<ElementRecord,{structure:'node'}>,canvasId:Id,registry:Registry,selected:{has(id:Id):boolean},geometry:Geometry|undefined,transform:Transform,depth:number,child:Id|undefined,renderers:RendererCatalog,cache?:GeometryProjectionCache):ProjectionNode{
   const g = geometry ?? element.geometry, projectedGeometry=cache?.node(element.id,element.incarnation,g,transform),center = projectedGeometry?undefined:toWorld(transform, { x: g.x + g.width / 2, y: g.y + g.height / 2 });
   const width = projectedGeometry?.width??g.width * transform.scale, height = projectedGeometry?.height??g.height * transform.scale, resolved=registry.resolve(element),known=resolved==='known';
@@ -47,7 +51,9 @@ export function projectNode(element:Extract<ElementRecord,{structure:'node'}>,ca
 
 /** Endpoints are already resolved to their displayed node IDs by the caller. */
 /** 调用方已确定显示 source/target；真实端点被入口替代时清除原 portId，避免端口指向错误外壳。
- * 预览只替代本条边的路径；不把 data 内可能残留的 path 混入已验证的结构路径。 */
+ * compat-v1 只对 target.id 匹配的边采用预览路径，变到场景后通过 connectionPathValid 才输出。
+ * record-v1 接原记录/transform，不在此嵌入预览或转换结构路径；原生 renderer 须从自己的受控显示上下文读取预览。
+ * data.path 从兼容 payload 中剔除，避免残留字段覆盖结构 path；输出仍是派生边，不改真实端点。 */
 export function projectEdge(element:Extract<ElementRecord,{structure:'connection'}>,source:Id,target:Id,registry:Registry,selected:{has(id:Id):boolean},transform:Transform,edgePreview:{target:{id:Id};path:Json}|null|undefined,renderers:RendererCatalog,cache?:GeometryProjectionCache):ProjectionEdge{
   const renderer=renderers.resolve(element),fallbackEdge=registry.resolve(element)!=='known'||!renderer;
   // 原生 record-v1 接记录和变换自行绘制；兼容路径转换到场景，未知边不解释自定义路径。
@@ -59,7 +65,10 @@ export function projectEdge(element:Extract<ElementRecord,{structure:'connection
 
 /** Renderer projection retains identity/owner in the model, including nested and collapsed canvases. */
 /** 从显示根深度优先投影展开分区，记录可见节点和被折叠祖先代理的子 canvas。
- * 只输出 owner 在当前显示范围的连线，再把不可见子节点端点映射到其折叠入口。 */
+ * 只输出 owner 在当前展开范围的连线，再把隐藏后代端点映射到可见折叠入口。
+ * 输入须是已验证的文档树/registry；这里查显示根与可选 queries 身份，不重做完整文档校验或检测所有递归环。
+ * 不做 viewport 裁剪或网络/资源读取；输出全体展开场景，再由 renderer/paint 索引决定屏幕保留。
+ * 派生容器虽可变，消费者仍应按只读约定使用；transforms 可复用共享 origin/几何缓存值，不应原地改它们。 */
 export function projectCanvas(document: Document, canvasId: Id, registry: Registry, selected: ReadonlySet<Id> | { has(id: Id): boolean }, geometry: (id: Id) => Geometry | undefined, edgePreview?: { target: { id: Id }; path: Json } | null, renderers:RendererCatalog=builtinRendererCatalog,services:{queries?:DocumentQueries;geometry?:GeometryProjectionCache;owner?:object}={}) {
   if (!document.canvases.has(canvasId)) throw fault('canvas_not_loaded', [canvasId]);
   // 索引必须对应同一 document/registry；几何缓存以 owner/project/canvas 隔离。
@@ -72,7 +81,8 @@ export function projectCanvas(document: Document, canvasId: Id, registry: Regist
   /** 有查询索引用其稳定成员序；无索引时由模型直接归属派生一次成员表，不维护第二份事实。 */
   const getMembers=(id:Id)=>queries?queries.members(id).map(id=>document.elements.get(id)!):members.get(id)??[];
   const nodes: ProjectionNode[] = [], visible = new Set<Id>();
-  /** 递归展开只改变投影：先输出入口，再按其当前几何/单位比例变换子分区。 */
+  /** 按成员稳定顺序深度优先：先投影入口，再用同一份预览几何/单位构造内部 canvas 变换。
+   * 隐藏分支用栈遍历后代建立 hiddenBy，不生成内部节点/边变换；无 queries 时反复从 canvas 表找子项。 */
   const visit = (id: Id, depth: number) => {
     const transform = transforms.get(id)!;
     for (const element of getMembers(id)) if (element.structure === 'node') {
@@ -91,10 +101,12 @@ export function projectCanvas(document: Document, canvasId: Id, registry: Regist
     }
   };
   visit(canvasId, 0);
-  // 只从已展开 owner 找边；边在模型中仍归其原 canvas，显示代理不是把边迁入子 canvas。
+  // 节点/hiddenBy 全部就绪后再投影边，避免端点代理依赖节点是否已遍历。
+  // queries 路径汇集展开 owner 的边再按文档层序排，无 queries 则扫描 element 表；模型归属始终不变。
   const edges: ProjectionEdge[] = [];
   for (const element of queries?queries.orderedElements([...transforms.keys()].flatMap(id=>queries.members(id).filter(id=>document.elements.get(id)?.structure==='connection'))).map(id=>document.elements.get(id)!):document.elements.values()) if (element.structure === 'connection' && transforms.has(element.ownerCanvasId)) {
-    /** 可见端点保留原 ID；隐藏端点改用折叠祖先入口。无法显示或两端同代理时仅省略本帧边。 */
+    /** 端点节点可见则保留 ID，否则按其 owner 的 hiddenBy 找折叠代理。
+     * 缺显示端点或两端同代理时仅省略本帧边，不从模型删除，也不改为自由端点。 */
     const endpoint = (id: Id) => visible.has(id) ? id : hiddenBy.get(document.elements.get(id)?.ownerCanvasId ?? '');
     const source = endpoint(element.source.elementId), target = endpoint(element.target.elementId);
     if (!source || !target || source === target) continue;
@@ -121,7 +133,8 @@ export function projectCanvas(document: Document, canvasId: Id, registry: Regist
     const field=end==='source'?'sourceHandle':'targetHandle',handle=edge[field]|| (end==='source'?'right':'left');edge[field]=handle;
     const seen=handleIds.get(edge[end])!;if(!seen.has(handle)){seen.add(handle);fallback.handles.push({id:handle,side:end==='source'?'right':'left'});}
   }
-  // 本轮遍历结束后删除未访问的几何缓存项，只返回派生场景，不发布 editor 修改。
+  // 成功遍历结束才 end 清未访问几何项；不是 finally，异常时由下次完整轮次或视图 clear 清理缓存。
+  // document 是原不可变引用，nodes/edges/transforms 是本次派生容器，不发布 editor 修改。
   cache?.end();
   return { document,canvasId,nodes, edges, transforms };
 }

src/lib/canvas-bindings/react-flow.ts

@@ -1,6 +1,7 @@
 /**
  * 显式 React/React Flow 框架入口。按需导出 hooks、组件 renderer 装配和命令 Context，
  * 可移植 bindings/index.ts 不引用这些框架依赖；use client 指令保留模块客户端边界。
+ * 重导出不自动挂 Provider、attach view 或创建 engine；ReactFlowProjection* 只是结构类型，不运行数据转换。
  */
 "use client";
 /** Explicit framework boundary; consumers install the declared optional peers. */

src/lib/canvas-bindings/react-renderers.ts

@@ -15,14 +15,17 @@ export type ReactRenderers={readonly catalog:RendererCatalog;readonly definition
 export type CanvasRuntimeExtension={readonly components?:readonly ComponentDefinition[];readonly renderers?:readonly ReactRendererDefinition[]};
 // 同一组件引用只创建一次 memo 包装，弱键不永久保留不再使用的插件组件。
 const memoizedRenderers=new WeakMap<object,NodeTypes[string]|EdgeTypes[string]>();
-/** 已是 memo 的组件原样返回；其它合法组件复用/创建包装，便于配合投影结构共享降低重绘。 */
+/** $$typeof 为 react.memo 则原样返回；其它受支持组件按原引用弱缓存 React.memo 包装。
+ * 不调用 render、不解析 lazy 内容，也不缓存组件状态；包装身份稳定不保证所有 props 变化都免渲染。 */
 function compiledRenderer(render:NodeTypes[string]|EdgeTypes[string]):NodeTypes[string]|EdgeTypes[string]{
  if((render as {$$typeof?:symbol}).$$typeof===Symbol.for('react.memo'))return render;
  const key=render as object,previous=memoizedRenderers.get(key);if(previous)return previous;
  const compiled=memo(render as NodeTypes[string]);memoizedRenderers.set(key,compiled);return compiled;
 }
 /** 先验证纯描述，再验证 React 组件形状与可选模型 registry。
- * 同 rendererId 可供多个元素类型共用，但普通/预览组件必须是同一实现，不能后注册静默覆盖。 */
+ * 同一 structure 内 rendererId 可别名共用，但普通/预览组件引用必须一致；node/edge 类型表彼此独立。
+ * 标记对象只做结构识别，不证明组件安全、纯净或必能成功渲染；安装来源仍须受信。
+ * 每次调用新建目录/表/外壳，只有组件 memo 包装共享；冻结注册表不冻结函数闭包或 React 内部状态。 */
 export function createReactRenderers(definitions:readonly ReactRendererDefinition[],registry?:Registry):ReactRenderers{
   // 类型表无对象原型，保留名也已被描述目录拒绝，防止类型键继承/原型污染歧义。
   const catalog=createRendererCatalog(definitions),nodes:NodeTypes=Object.create(null),edges:EdgeTypes=Object.create(null),previewNodes:NodeTypes=Object.create(null),previewEdges:EdgeTypes=Object.create(null),captured:ReactRendererDefinition[]=[];
@@ -31,11 +34,13 @@ export function createReactRenderers(definitions:readonly ReactRendererDefinitio
     // 接受函数及 React memo/forward_ref/lazy 标记对象；不是组件的值在装配时拒绝。
     if(typeof render!=='function'&&![Symbol.for('react.memo'),Symbol.for('react.forward_ref'),Symbol.for('react.lazy')].includes(tag as symbol))throw fault('invalid_react_renderer');
     const previewTag=preview&&typeof preview==='object'?(preview as {$$typeof?:symbol}).$$typeof:undefined;if(preview!==undefined&&typeof preview!=='function'&&![Symbol.for('react.memo'),Symbol.for('react.forward_ref'),Symbol.for('react.lazy')].includes(previewTag as symbol))throw fault('invalid_react_preview');
-    // 如提供模型 registry，就要求精确 componentId/dataVersion/structure 匹配，不能靠显示组件掩盖 schema 不兼容。
+    // 可选 registry 只核 componentId/dataVersion/structure 精确存在，不执行某个元素的数据 schema/迁移。
+    // 未提供 registry 也可装配纯显示目录，真正投影元素时仍需模型解释与 fallback 判断。
     if(registry){const model=registry.components.get(descriptor.componentId);if(!model||model.dataVersion!==descriptor.dataVersion||model.structure!==descriptor.structure)throw fault('renderer_model_mismatch',[descriptor.componentId]);}
     const table=descriptor.structure==='node'?nodes:edges,previews=descriptor.structure==='node'?previewNodes:previewEdges,compiled=compiledRenderer(render),compiledPreview=preview?compiledRenderer(preview):undefined;
     if(Object.hasOwn(table,descriptor.rendererId)&&(table[descriptor.rendererId]!==compiled||previews[descriptor.rendererId]!==compiledPreview))throw fault('renderer_id_conflict',[descriptor.rendererId]);
-    // 采用目录捕获的标准描述，冻结暴露定义和最终类型表，装配后调用方不能替换注册项。
+    // 定义保留原 render/preview 引用，类型表存编译后的 memo 引用；不混淆这两层身份。
+    // 缺 preview 则不创建对应 previewTypes 项，工厂不自动用正式组件充当预览；宿主决定降级路径。
     Object.defineProperty(table,descriptor.rendererId,{value:compiled,enumerable:true,configurable:true});if(compiledPreview)Object.defineProperty(previews,descriptor.rendererId,{value:compiledPreview,enumerable:true,configurable:true});captured.push(Object.freeze({...descriptor,render,...(preview?{preview}:{})}) as ReactRendererDefinition);
   }
   return Object.freeze({catalog,definitions:Object.freeze(captured),nodeTypes:Object.freeze(nodes),edgeTypes:Object.freeze(edges),previewNodeTypes:Object.freeze(previewNodes),previewEdgeTypes:Object.freeze(previewEdges)});

src/lib/canvas-bindings/react.ts

@@ -22,12 +22,15 @@ export type CanvasBinding={readonly engine:ProjectEngine;readonly viewId?:Id};
 // 默认空上下文用于明确检测漏装 Provider，避免 hooks 悄悄读错项目。
 const CanvasContext=createContext<CanvasBinding|null>(null);
 /** Borrows the engine and an already attached view. Unmount never closes the project. */
-/** 只 memo 化借用引用并向子组件提供上下文；不 attach/detach 视图，也不创建/销毁项目。 */
+/** value 只按 engine/viewId 引用 memo 并冻结外壳，children 使用 React Context；不是项目实例拥有者。
+ * 不 attach/detach view、不创建/销毁 engine；若使用交互 view，应由外层宿主先装配，卸载 Provider 也不关闭项目。 */
 export function CanvasProvider({engine,viewId,children}:{engine:ProjectEngine;viewId?:Id;children?:ReactNode}){const value=useMemo(()=>Object.freeze({engine,viewId}),[engine,viewId]);return createElement(CanvasContext.Provider,{value},children);}
 /** 取得当前绑定，缺 Provider 时抛出稳定领域错误交给应用错误边界。 */
 export function useCanvasBinding(){const binding=useContext(CanvasContext);if(!binding)throw fault('canvas_provider_missing');return binding;}
 /** 将派生源接到 useSyncExternalStore。committed 保存最近已提交渲染的选中值，
- * selector 或等价函数换引用后仍能复用等价结果；effect 才推进已提交基线，不在 render 中认领提交。 */
+ * selector 或等价函数换引用时重建派生 store，但可按 committed.current 复用等价结果，避免无意义选中值换身份。
+ * effect 才推进已提交基线，不在 render 中认领提交；source/selector/isEqual 须遵守同步不可变读取合同。
+ * getServerSnapshot 也使用同一 store.getSnapshot，不创建独立服务端模型，宿主须提供可稳定读取的绑定。 */
 function useSelected<S,T>(source:ExternalSource<S>,selector:(snapshot:S)=>T,isEqual:(a:T,b:T)=>boolean=Object.is):T{
  const committed=useRef<{value:T}|null>(null);
  const store=useMemo(()=>createSelectorStore(source,(snapshot:S)=>{const selected=selector(snapshot);return committed.current&&isEqual(committed.current.value,selected)?committed.current.value:selected;},isEqual),[source,selector,isEqual]);
@@ -47,7 +50,9 @@ function elementSourcesFor(engine:ProjectEngine){let sources=elementSources.get(
 /** 支持直接元素视图或自定义选中结果；下面两个签名只描述重载，实际订阅逻辑共用一个实现。 */
 export function useElement(ref:Id|Target):ElementView;
 export function useElement<T>(ref:Id|Target,selector:(view:ElementView)=>T,isEqual?:(a:T,b:T)=>boolean):T;
-/** ID 查询跟随当前元素；Target 查询额外核对代次。默认完整视图按值比较，自定义选择默认按引用。 */
+/** 字符串 ID 跟随当前生命周期；Target 仅在 present 且 incarnation 不同返回 stale，absent/unloaded 原样保留。
+ * 每个 engine 共用按 ID 源；hook 再派生代次/selector 结果，默认完整视图 equal，自定义选择默认 Object.is。
+ * stale 带当前元素供展示，但不自动把旧 Target 升级成新代次的写入权限。 */
 export function useElement<T>(ref:Id|Target,selector?:(view:ElementView)=>T,isEqual?:(a:T,b:T)=>boolean):T|ElementView{
  const {engine}=useCanvasBinding(),id=typeof ref==='string'?ref:ref.id,incarnation=typeof ref==='string'?undefined:ref.incarnation;
  const source=useMemo(()=>elementSourcesFor(engine).forElement(id),[engine,id]);
@@ -55,7 +60,9 @@ export function useElement<T>(ref:Id|Target,selector?:(view:ElementView)=>T,isEq
 }
 /** 复用 editor 的历史标签/分组选项，不在绑定层发明另一套提交参数。 */
 export type ActionOptions=Parameters<ProjectEngine['editor']['dispatch']>[1];
-/** 捕获不可变 ID+代次并提供普通数据/几何/删除/移动命令；旧组件的动作由 editor 拒绝旧代次。 */
+/** 按 engine/id/incarnation memo 动作外壳并捕获冻结 Target，之后改传入 target 对象不影响旧闭包。
+ * rename/setData/resize/remove/moveTo 都只是普通 command；resize 接 Partial<Geometry>，不只限 width/height。
+ * 调用时 editor 再核代次/策略/事务，不乐观修改 React 局部文档，也不在动作闭包里排网络请求。 */
 export function useActions(target:Target){const {engine}=useCanvasBinding(),{id,incarnation}=target;return useMemo(()=>{const ref=Object.freeze({id,incarnation});return Object.freeze({
  // 各操作只转成正常 command；校验、history 和同步依赖由 editor/runtime 在统一边界处理。
  rename:(title:string,options?:ActionOptions)=>engine.editor.dispatch({type:'element.data',target:ref,patch:{title}},options),
@@ -69,16 +76,20 @@ const sessionSources=new WeakMap<ProjectEngine,ReturnType<typeof createSessionSo
 /** 惰性绑定 session 源；已关闭 engine 不再订阅其会话。 */
 function sessionSourcesFor(engine:ProjectEngine){let sources=sessionSources.get(engine);if(!sources){sources=createSessionSources({getSnapshot:engine.sessions.getSnapshot,subscribe:notify=>engine.getDurability().closed?()=>{}:engine.sessions.subscribe(notify)});sessionSources.set(engine,sources);}return sources;}
 /** 把文档身份与瞬态状态成对读取，按两项引用保留稳定元组；第二条订阅失败时撤销第一条。
- * 它不是跨两源的独立事务，合法性由使用方的目标代次校验保证。 */
+ * 顺序读两源，不是跨源事务或原子快照锁；目标合法性仍由 hooks/命令校验。
+ * 正常退订依次 a()/b()，没有 finally 隔离，宿主取消端口须不抛错；右侧注册失败时尽量撤回左侧。 */
 function pairedSource<A,B>(left:ExternalSource<A>,right:ExternalSource<B>):ExternalSource<readonly[A,B]>{
  let previous:readonly[A,B]|undefined;
  return{getSnapshot(){const a=left.getSnapshot(),b=right.getSnapshot();if(!previous||!Object.is(previous[0],a)||!Object.is(previous[1],b))previous=Object.freeze([a,b] as const);return previous;},subscribe(notify){const a=left.subscribe(notify);try{const b=right.subscribe(notify);return()=>{a();b();};}catch(error){a();throw error;}}};
 }
-/** 需要交互所有权的 hook 必须有 viewId，不能从任意其它视图借用会话。 */
+/** 要求 Provider 有非空 viewId；这里只补绑定形状，不在此 attach 或验证该视图此刻仍注册。
+ * session 操作入口继续核视图/手势生命周期，不能凭这个返回对象绕过所有权检查。 */
 function useView(){const binding=useCanvasBinding();if(!binding.viewId)throw fault('view_session_required');return {...binding,viewId:binding.viewId};}
-/** 将绑定控制异常转为 Availability，保留领域码/目标，未知异常归 binding_failed。 */
+/** 将 Error 风格异常的 code/targets 转为 Availability，缺 code 用 binding_failed。
+ * 不归一化任意 thrown 值；null/undefined 不符合这里直接读属性的错误合同。 */
 function available(error:unknown):Availability{return{enabled:false,code:(error as {code?:string}).code??'binding_failed',targets:(error as {targets?:readonly Id[]}).targets??[]};}
-/** 同时订阅目标身份与该视图模式；旧代次返回 null，设置模式前再次读取当前元素校验。 */
+/** 成对订阅元素查询和 view/element 模式；缺元素或旧代次读成 null，不把旧元素的编辑模式套给新元素。
+ * setMode 调用时再核当前 incarnation，然后由 sessions.mode 检查视图；返回可用性，不直接编辑内容/history。 */
 export function useMode(target:Target){
  const {engine,viewId}=useView(),{id,incarnation}=target;
  const source=useMemo(()=>pairedSource(elementSourcesFor(engine).forElement(id),sessionSourcesFor(engine).mode(viewId,id)),[engine,viewId,id]);
@@ -87,7 +98,9 @@ export function useMode(target:Target){
  return useMemo(()=>Object.freeze({mode,setMode}),[mode,setMode]);
 }
 /** 组合文档几何和 session 预览。begin 取得手势 token，update/commit/cancel 必须仍拥有同 token/view。
- * effect 清理只取消本绑定取得的手势，不能因旧组件卸载取消后来另一视图的新手势。 */
+ * controls 内 lease 仅是本 hook 捕获的数字 token，不是另一份手势事实；真实 active/preview 在 sessions。
+ * effect 清理先核 token/view/active，仅取消自己取得的手势；旧组件卸载不能取消后来另一视图的新手势。
+ * begin/update/commit 沿用 session 的结果或异常；拥有手势后进入 commit 的 try/finally 才保证清 lease，未拥有则直接拒绝。 */
 export function useGestureBindings(target:Target){
  const {engine,viewId}=useView(),{id,incarnation}=target;
  const source=useMemo(()=>pairedSource(elementSourcesFor(engine).forElement(id),sessionSourcesFor(engine).gesture(viewId,{id,incarnation})),[engine,viewId,id,incarnation]);
@@ -106,7 +119,8 @@ export function useGestureBindings(target:Target){
 const runtimeSources=new WeakMap<ProjectEngine,ReturnType<typeof createRuntimeSources>>();
 /** 惰性建立 runtime 源，在 editor 成功根发布时观察表引用变化。 */
 function runtimeSourcesFor(engine:ProjectEngine){let sources=runtimeSources.get(engine);if(!sources){sources=createRuntimeSources({getSnapshot:engine.getSnapshot,subscribe:notify=>engine.getDurability().closed?()=>{}:engine.editor.subscribe(notify)});runtimeSources.set(engine,sources);}return sources;}
-/** 单操作诊断读取，返回逻辑操作及关联冻结请求，不提供直接改任务状态的方法。 */
+/** 每 engine/id memo 派生源，useSyncExternalStore 读取逻辑操作和关联请求；缺 ID 返回 undefined。
+ * 这是诊断订阅，不轮询服务、不授予直接修改 phase/request 的接口。 */
 export function useOperation(id:Id):OperationView{const {engine}=useCanvasBinding(),source=useMemo(()=>runtimeSourcesFor(engine).operation(id),[engine,id]);return useSyncExternalStore(source.subscribe,source.getSnapshot,source.getSnapshot);}
 /** 本地可靠保存状态，与网络 ACK/任务结果分开观察。 */
 type Durability=ReturnType<ProjectEngine['getDurability']>;
@@ -117,7 +131,8 @@ const inactiveOwner=(value:Durability)=>value.closing||value.closed;
 /** 使用 engine 独立的 durability 订阅，磁盘完成/错误不必伪造一次文档编辑来通知 UI。 */
 function useDurability<T>(selector:(value:Durability)=>T,isEqual:(a:T,b:T)=>boolean=Object.is){const {engine}=useCanvasBinding();const source=useMemo(()=>({getSnapshot:engine.getDurability,subscribe:engine.subscribeDurability}),[engine]);return useSelected(source,selector,isEqual);}
 /** 合成任务计数与项目保存状态，展示优先级为 closed→blocked→closing→saving→syncing→loading→synced。
- * canvas 计数局部化，但 dirty/error/closing 是项目保存层级，不能当作仅该 canvas 的独立磁盘状态。 */
+ * canvas 计数局部化，但 dirty/error/closing 是项目保存层级，不能当作仅该 canvas 的独立磁盘状态。
+ * 计数与 durability 来自两条订阅，不建立新的事务根；status 是显示优先级归纳，synced 不证明远端生成已结束。 */
 export function useSyncStatus(canvasId?:Id){
  const {engine}=useCanvasBinding(),source=useMemo(()=>runtimeSourcesFor(engine).counts(canvasId),[engine,canvasId]);
  const durable=useDurability(syncDurability,equal),counts=useSyncExternalStore(source.subscribe,source.getSnapshot,source.getSnapshot);
@@ -125,7 +140,10 @@ export function useSyncStatus(canvasId?:Id){
  return useMemo(()=>Object.freeze({...counts,dirty,error:durable.error,status:durable.closed?'closed' as const:durable.error||counts.blocked?'blocked' as const:durable.closing?'closing' as const:dirty?'saving' as const:counts.pending?'syncing' as const:counts.loading?'loading' as const:'synced' as const}),[counts,dirty,durable.error,durable.closing,durable.closed]);
 }
 /** 订阅资源元数据并在 effect 借用显示句柄。engine/id/来源 key 变化重建尝试，retry 显式重取。
- * 异步返回先核对 abort；渲染也核对 state 所属 engine/id/key，不能短暂显示上个项目或旧来源的 URL。 */
+ * 异步返回核 abort，渲染再核 state.engine/id/key；metadata 与句柄分别来自根和 effect，不另存原资源字节。
+ * key 只含上传 operationId/purge、binding.authority/digest，普通元信息变化不全都重开显示请求。
+ * attempt 只触发 effect 重试，不在返回 state 的身份键中；同来源 retry 的 loading 状态由 effect 启动时设置。
+ * ready 表示 URL 租约已取得，不等于图片 DOM 已解码/绘制或上传/同步完成。 */
 export function useAsset(id:Id){
  const {engine}=useCanvasBinding(),inactive=useDurability(inactiveOwner);
  const source=useMemo(()=>runtimeSourcesFor(engine).asset(id),[engine,id]),metadata=useSyncExternalStore(source.subscribe,source.getSnapshot,source.getSnapshot);
@@ -134,7 +152,7 @@ export function useAsset(id:Id){
  const [attempt,setAttempt]=useState(0),[state,setState]=useState<{engine:ProjectEngine;id:Id;key:string;status:'loading'|'ready'|'error';url?:string;error?:unknown}>();
  // 清理中止本次读取并归还 handle；迟到成功也立即释放，不把旧结果写入当前显示。
  useEffect(()=>{if(inactive){setState({engine,id,key,status:'error',error:fault('engine_closing')});return;}const controller=new AbortController();let handle:DisplayHandle|undefined;setState({engine,id,key,status:'loading'});void engine.displayResource(id,{signal:controller.signal}).then(value=>{if(controller.signal.aborted){value.release();return;}handle=value;setState({engine,id,key,status:'ready',url:value.url});},error=>{if(!controller.signal.aborted)setState({engine,id,key,status:'error',error});});return()=>{controller.abort();handle?.release();};},[engine,id,key,attempt,inactive]);
- /** 重试仅增加本 hook 的尝试序号，由 effect 清理旧租约再请求新显示句柄。 */
+ /** retry 仅增本 hook 的尝试序号，effect 清旧租约再取新显示句柄；不调用 engine.retry 或重新上传。 */
  const retry=useCallback(()=>setAttempt(value=>value+1),[]);
  return useMemo(()=>Object.freeze({...metadata,...(inactive?{status:'error' as const,url:undefined,error:fault('engine_closing')}:state?.engine===engine&&state.id===id&&state.key===key?{status:state.status,url:state.url,error:state.error}:{status:'loading' as const,url:undefined,error:undefined}),retry}),[metadata,state,engine,id,key,retry,inactive]);
 }

src/lib/canvas-bindings/renderer-context.ts

@@ -13,5 +13,6 @@ export type CanvasRendererCommands={dispatch(command:Command,options?:RendererCo
 /** Provider 由上层 renderer 装配；默认 null 表示组件尚未处于合法的编辑上下文。 */
 export const CanvasRendererCommandsContext=createContext<CanvasRendererCommands|null>(null);
 /** Trusted installed renderers submit normal validated commands, never write a second model. */
-/** 已安装的受信 renderer 通过此 hook 获取命令门面，所有业务修改仍经 editor 发布边界。 */
+/** 读取最近 Provider 的命令对象，缺失就同步抛错；hook 不缓存命令、不建立订阅或另建 editor。
+ * Provider 须注入 editor 的受检门面；Context 本身不验证任意自定义函数是否真的经过发布边界。 */
 export function useCanvasRendererCommands(){const commands=useContext(CanvasRendererCommandsContext);if(!commands)throw Error('Canvas renderer commands are unavailable');return commands;}

src/lib/canvas-bindings/renderers.ts

@@ -11,7 +11,8 @@ export type RendererCatalog={readonly definitions:readonly RendererDescriptor[];
 /** JSON 元组键避免拼接分隔符歧义，节点与连线即使 componentId 相同也独立匹配。 */
 const key=(value:Pick<RendererDescriptor,'componentId'|'dataVersion'|'structure'>)=>JSON.stringify([value.componentId,value.dataVersion,value.structure]);
 /** 校验并复制描述项，拒绝重复定义、危险/保留 renderer 名和未知投影协议。
- * 工厂不加载代码、不自动迁移 dataVersion，也不把高版本当成兼容旧版本。 */
+ * 工厂按声明顺序重建标准标量字段/默认 projection，未知扩展字段不复制，Map 键是精确三元组。
+ * 不加载 React/插件代码、不执行 schema 校验、不自动迁移版本；resolve 不授予编辑或网络权限。 */
 export function createRendererCatalog(definitions:readonly RendererDescriptor[]):RendererCatalog{
   const entries=new Map<string,RendererDescriptor>();
   for(const value of definitions){
@@ -31,5 +32,6 @@ export const builtinRendererCatalog=createRendererCatalog(builtinRendererDefinit
 
 /** Installed renderers without a reference declaration wait for full context. */
 /** 渐进加载仅开放 registry 中声明 copy 引用规则的组件 renderer；缺声明先走降级等待完整上下文。
- * 保留 definitions 供装配检查，但 resolve 才决定当前是否允许显示实现。 */
+ * 保留原 catalog.definitions 供装配检查，resolve 每次先查 registry 中 component 是否有 copy 声明。
+ * 这仅是局部加载门禁，不验证声明覆盖所有引用、schema 或源记录版本，也不证明依赖已加载；精确 renderer 匹配仍由 catalog 执行。 */
 export function createLoadingRendererCatalog(registry:Registry,catalog:RendererCatalog):RendererCatalog{return Object.freeze({definitions:catalog.definitions,resolve:(element:Parameters<RendererCatalog['resolve']>[0])=>registry.components.get(element.componentId)?.copy?catalog.resolve(element):undefined});}

src/lib/canvas-bindings/resource-view.ts

@@ -14,7 +14,9 @@ export type ResourceViewSource = { readonly resourceId: Id; readonly url: string
  * unchanged nodes, publish each ready source independently, and fence late work.
  */
 /** resolve 由 engine/display service 注入，onChange 收到新的已就绪集合和当前失败数。
- * sync 输入是完整目标集合，retry 只重建失败项，dispose 幂等释放所有在途/已完成句柄。 */
+ * sync 输入是完整目标集合，retry 只重建失败项，dispose 请求中止在途并归还已有句柄。
+ * 工厂不立即 resolve；每个元素一次独立尝试，同资源的多个元素不在此合并（底层缓存可共享读取）。
+ * resolve 须返回合法 DisplayHandle；本模块不校验 URL/下载权限或图片内容，回调错误仅报告。 */
 export function createResourceView(options: {
   resolve(resource: Id, signal: AbortSignal): Promise<DisplayHandle>;
   onChange(sources: Map<Id, ResourceViewSource>, failures: number): void;
@@ -24,13 +26,16 @@ export function createResourceView(options: {
   const records = new Map<Id, Record>(); let targets = new Map<Id, Id>(), disposed = false;
   /** 错误展示抛错不影响租约释放或其它图片的加载。 */
   const report = (error: unknown) => { try { options.onError?.(error); } catch { /* Observer errors do not own leases. */ } };
-  /** 只公布已拿到 handle 的元素，失败数另报；先复制 Map，不把内部记录交给界面修改。 */
+  /** 每次重建 ready 元素→{resourceId,url} 的新 Map，另计 failed；pending 不计失败也不带空 URL。
+   * Map/条目未运行时冻结，但不暴露内部 record/handle；onChange 抛错被 report 隔离，不撤销已采纳句柄。 */
   const publish = () => { try { options.onChange(new Map([...records].flatMap(([id, record]) => record.handle ? [[id, {resourceId:record.resource,url:record.handle.url}] as [Id, ResourceViewSource]] : [])), [...records.values()].filter(record => record.failed).length); } catch (error) { report(error); } };
   /** 释放器自身抛错只报告，不让一张图片阻止其它图片清理。 */
   const releaseHandle = (handle: DisplayHandle) => { try { handle.release(); } catch (error) { report(error); } };
   /** 先中止在途解析，再归还已完成句柄；未完成解析的迟到成功也由下方结果边界归还。 */
   const release = (record: Record) => { record.controller.abort(); if(record.handle)releaseHandle(record.handle); };
-  /** 完整验证元素/资源 ID 与重复项后再更新；删除或换源立即释放旧记录，未变化项继续复用。 */
+  /** 先验证并捕获完整目标映射（元素 ID 唯一，资源 ID 可重复），再删除/换源/补新尝试。
+   * 未变化项包括 failed 都保留，因此同集合 sync 不隐式重试；显式 retry 才重建失败项。
+   * 变化时先发布当前 ready 集合，各 resolve 独立完成再各自发布，不等全组 Promise.all。 */
   function sync(next: readonly (readonly [Id, Id])[]) {
     if (disposed) throw fault('resource_view_disposed');
     const desired = new Map<Id, Id>();
@@ -60,9 +65,11 @@ export function createResourceView(options: {
   }
   return Object.freeze({
     sync,
-    /** 移除失败记录后按 targets 重新 sync；成功项不重新取 URL。 */
+    /** 先撤掉失败尝试并释放，再用最近 targets 重新 sync；ready/pending 项继续复用。
+     * 没有失败项也不额外发布，不重新授权所有成功资源或重建业务元素。 */
     retry() { if (disposed) throw fault('resource_view_disposed'); for (const [id, record] of records) if (record.failed) { records.delete(id); release(record); } sync([...targets]); },
-    /** 中止并归还全部显示租约，发布空集合，后续 sync/retry 明确拒绝。 */
+    /** 同步标 disposed、请求 abort 并 release 已有句柄，清目标/记录后发布空集合。
+     * 不等待 resolve Promise 退出；迟到成功由记录身份/ disposed 检查归还，后续 sync/retry 明确拒绝。 */
     dispose() { if (disposed) return; disposed = true; for (const record of records.values()) release(record); records.clear(); targets.clear(); publish(); },
   });
 }

src/lib/canvas-bindings/runtime-sources.ts

@@ -20,7 +20,9 @@ export type SyncCounts={readonly pending:number;readonly blocked:number;readonly
 type Dependencies=readonly(object|boolean|undefined)[];
 
 /** Read-only table projections: one upstream listener, no per-hook Root/table snapshots. */
-/** 装配 operation/asset/counts 三类通道，首次订阅连上游，最后一个通道离开后断开。 */
+/** 装配 operation/asset/counts 三组：组内按 key 共享桶，所有活动组共用一个上游订阅。
+ * 只按所声明表对象身份/布尔值检测依赖，要求上游不可变；原地改 Map 成员不会自动生成新依赖戳。
+ * factories/getSnapshot 不启动网络或修改业务状态，选中记录仍借用 Root 中的不可变事实。 */
 export function createRuntimeSources(source:ExternalSource<EngineSnapshot>){
  // 每个 group 负责自己的桶更新，上游先推进所有组，再运行去重后的外部通知。
  type Group={update(root:EngineSnapshot,notifications:Set<()=>void>):void};
@@ -33,7 +35,8 @@ export function createRuntimeSources(source:ExternalSource<EngineSnapshot>){
   for(const group of active)group.update(root,notifications);
   let failed=false,error:unknown;for(const notify of notifications)try{notify();}catch(caught){if(!failed){failed=true;error=caught;}}if(failed)throw error;
  }
- /** 为共享依赖的一类按键查询创建桶。依赖不变跳过计算，失败桶即使签名未变仍可重新尝试。 */
+ /** 一组依赖对应多个 key 桶；observedSignature 决定路由，failed 键可在戳未变时再试。
+  * cachedSignature 只说明读取缓存对应哪个依赖戳，不能替代 observed 的通知基线。 */
  function group<K,V>(dependencies:(root:EngineSnapshot)=>Dependencies,read:(root:EngineSnapshot,key:K)=>V){
   // Direct reads may precede notification, so read caches cannot replace observed baselines.
   // cached 服务即时读取，observed 是上次通知基线；两者不能合并，否则渲染提前读取会漏通知。
@@ -44,7 +47,8 @@ export function createRuntimeSources(source:ExternalSource<EngineSnapshot>){
    if(bucket.cachedSignature!==stamp){const value=read(root,key);if(!equal(bucket.cached,value))bucket.cached=value;bucket.cachedSignature=stamp;}
    return bucket.cached;
   }
-  // 只更新有订阅的键；失败时仍通知使用方，让其读取/错误边界重新解释，不造一个成功值。
+  // 戳变化扫描全部已订阅 key，否则只扫描 failed；readCached 失败不会推进该桶缓存戳。
+  // 失败/失败后恢复都通知，cached/observed 不造一个假成功值；其它正常等价桶不通知。
   const owner:Group={update(root,notifications){
    const stamp=signature(dependencies(root)),all=stamp!==observedSignature;if(!all&&!failed.size)return;observedSignature=stamp;
    for(const key of all?buckets.keys():[...failed]){
@@ -67,7 +71,8 @@ export function createRuntimeSources(source:ExternalSource<EngineSnapshot>){
     const listener=()=>notify();bucket.listeners.add(listener);
     /** 撤销本订阅；空桶和空组立即删除，失败键也同时清理。 */
     const remove=()=>{bucket!.listeners.delete(listener);if(!bucket!.listeners.size){buckets.delete(key);failed.delete(key);}if(!buckets.size){active.delete(owner);observedSignature=undefined;}};
-    // 首次注册上游失败撤回桶；正常退订只有最后一个活动组离开才停止共享监听。
+    // 首次注册上游失败撤回本次 listener/空桶；各订阅包装回调身份，传同一个 notify 也可独立退订。
+    // 最后活动组离开才 stop 上游；stop 抛错不兜底重置，宿主取消端口须可靠完成。
     if(!stop)try{stop=source.subscribe(changed);}catch(error){remove();throw error;}
     let live=true;return()=>{if(!live)return;live=false;remove();if(!active.size){stop?.();stop=undefined;}};
    }});
@@ -80,7 +85,8 @@ export function createRuntimeSources(source:ExternalSource<EngineSnapshot>){
  let countStamp:string|undefined,projectCounts:SyncCounts,emptyCounts:SyncCounts,canvasCounts=new Map<Id,SyncCounts>();
  /** 同步计数只取操作表、请求表和是否 loading，不因文档几何或历史变化全表重数。 */
  const countDependencies=(root:EngineSnapshot):Dependencies=>[root.runtime.ledger.operations,root.runtime.ledger.requests,!!root.runtime.loading];
- // 同一依赖戳一次扫描得出项目及各画布计数，多个 canvas hook 共享结果。
+ // 同一依赖戳只扫描一次得到项目/各 canvas 计数，空 canvas 共享零计数；loading 是项目级布尔值。
+ // canvas 归属沿用 intent.canvasIds，不在这里从当前 owner 推导；上传等空参与者任务只进入项目计数。
  const counts=group<Id|undefined,SyncCounts>(countDependencies,(root,canvasId)=>{
   const stamp=signature(countDependencies(root));
   if(stamp!==countStamp){
@@ -92,7 +98,8 @@ export function createRuntimeSources(source:ExternalSource<EngineSnapshot>){
     const ids=operation.intent.canvasIds.length>1?new Set(operation.intent.canvasIds):operation.intent.canvasIds,blocked=operation.phase==='blocked'&&operation.blockers.some(reason=>reason!=='waiting_digest');project.pending++;if(blocked)project.blocked++;
     for(const id of ids){const row=scope(id);row.pending++;if(blocked)row.blocked++;}
    }
-   // 请求只统计仍关联未决操作的项。无 retryAt 的请求错误计 blocked，已发出但结果未知计 unknown。
+   // 请求仅在仍关联未决操作时计数，canvas 集合取这些操作参与者的并集，不直接用 request.canvasIds。
+   // 请求 blocked 可与操作 blocked 叠加，unknown 也可同时非零；它们不是互斥任务/节点数量。
    for(const request of root.runtime.ledger.requests.values())if(request.phase!=='resolved'){
     let matched=false;const ids=new Set<Id>();for(const id of request.operationIds){const operation=root.runtime.ledger.operations.get(id);if(operation&&operation.phase!=='resolved'){matched=true;for(const canvas of operation.intent.canvasIds)ids.add(canvas);}}
     if(!matched)continue;const blocked=!!request.error&&request.retryAt===undefined,unknown=request.outcome==='unresolved'&&['dispatch-marked','waiting'].includes(request.phase);

src/lib/canvas-bindings/scene-changes.ts

@@ -11,13 +11,16 @@ import type {RendererCatalog} from './renderers.ts';
 
 /** 与完整 projectCanvas 保持同一结果结构，避免增量路径自行定义另一套显示规则。 */
 type Projection=ReturnType<typeof projectCanvas>;
-/** 连续发布的可信写集合；from/to 必须恰好连接旧投影与新文档，topology 表示禁止局部修补。 */
+/** from/to 按 Document 对象身份连接连续发布，ids 是宿主提供的完整写集合；这里不重算其覆盖证明。
+ * topology=true 禁用局部修补，Set 可由 scene coordinator 累加，不是持久 Change 日志或业务事件队列。 */
 export type SceneChangeHint={from:Document;to:Document;ids:Set<Id>;topology:boolean};
 /** 几何手势的瞬态预览，不将 pointermove 变成文档修改。 */
 type Preview=NonNullable<SessionSnapshot['gesture']>['preview']|undefined;
 /** 真正影响场景内容的输入；viewport/tool/mode 等状态由别的显示通道处理。 */
 export type SceneInputs={owner:object;document:Document;registry:Registry;catalog:RendererCatalog;canvasId:Id;selection:ViewState['selection'];preview:Preview;edgeId:Id|undefined;path:NonNullable<SessionSnapshot['connectionGesture']>['path']|undefined};
-/** 为上一帧建立 ID→数组位置、分区入口及深度索引；发现降级节点/边后禁用快速修补。 */
+/** 建上一帧 ID→数组下标、入口 elementId→子 canvasId、显示 canvas 深度索引。
+ * 深度沿 transforms 迭代顺序累计，依赖完整投影按父先子后产出；不在这里重新排序/校验整棵树。
+ * unsupported 标记当前已有 fallback node/unsupported edge，供 patchScene 直接回退。 */
 export function indexScene(projection:Projection){
  const nodes=new Map(projection.nodes.map((node,index)=>[node.id,index])),edges=new Map(projection.edges.map((edge,index)=>[edge.id,index])),entries=new Map<Id,Id>(),depths=new Map<Id,number>([[projection.canvasId,0]]);
  for(const canvas of projection.document.canvases.values())if(canvas.parent)entries.set(canvas.parent.entryElementId,canvas.id);
@@ -26,14 +29,17 @@ export function indexScene(projection:Projection){
 }
 /** Reuse existing projections for checked field edits and ordinary node insertions. */
 /** 纯候选投影修补：合并文档/选择/预览脏项，先核对全体脏项再构造新数组。
- * 允许普通节点新增与受检字段编辑；删除、代次/类型/owner/连线端点变更交给完整路径。 */
+ * 允许普通节点新增与受检字段编辑；删除、代次/类型/owner/连线端点变更交给完整路径。
+ * 调用者须先核 owner/registry/catalog/canvas 兼容，layout 对应 base，queries 对应 next.document；本函数不重复全部护栏。
+ * undefined 表示本次不适合快路径，不是业务拒绝；投影器/外部服务抛错则直接传播，没有错误吞并或业务发布。 */
 export function patchScene(base:Projection,layout:ReturnType<typeof indexScene>,next:SceneInputs,previous:SceneInputs,connection:SessionSnapshot['connectionGesture'],hint?:SceneChangeHint,queries?:DocumentQueries):Projection|undefined{
  const {document,selection,preview,registry,catalog,canvasId}=next;
  const {selection:oldSelection,preview:oldPreview,edgeId:oldEdgeId,path:oldPath}=previous;
  if(layout.unsupported||document.projectId!==base.document.projectId)return;
  const dirty=new Set<Id>(),created=new Set<Id>();
  if(document!==base.document){
-  // 可信连续 changes 可直接路由 ID；拓扑提示则立刻放弃。无提示时需要逐项核对表顺序及内容。
+  // 匹配 from/to 的 hint 按完整写集合合同直接取 ids，不额外全表证明“没有遗漏其它修改”。
+  // 缺可信 hint 才比较 canvas 表及 element 表大小/顺序/内容；这条扫描路径本身不支持插入或删除。
   if(hint?.from===base.document&&hint.to===document){if(hint.topology)return;for(const id of hint.ids)dirty.add(id);}
   else{
    // Canonical replacement and missed publications carry no trustworthy write set.
@@ -59,7 +65,8 @@ export function patchScene(base:Projection,layout:ReturnType<typeof indexScene>,
   // 入口几何/单位展示或其预览变化会影响整棵子树变换，不能只修补入口本身。
   if(before.structure==='node'&&after.structure==='node'&&layout.entries.has(id)&&(!equal(before.geometry,after.geometry)||!equal(before.data.presentation,after.data.presentation)||!equal(oldPreview?.get(id),preview?.get(id))))return;
  }
- // 懒复制：未受影响的数组与节点/边对象沿用原引用，新对象仍调用完整路径共用的投影函数。
+ // 先通过脏项形状检查再懒复制受影响数组，未变对象仍共享；所有新节点/边调用完整路径共用投影函数。
+ // base.transforms 只在拓扑兼容时复用；未显示 canvas 的普通变更可以只更新返回 document 而不增加显示节点。
  let nodes=base.nodes,edges=base.edges;const inserted=new Map<Id,Projection['nodes'][number]>();
  for(const id of dirty){const element=document.elements.get(id)!;
   if(element.structure==='node'){
@@ -81,7 +88,8 @@ export function patchScene(base:Projection,layout:ReturnType<typeof indexScene>,
   // without reconstructing unaffected nodes, transforms or edge projections.
   const members=new Map<Id,Id[]>();if(!queries)for(const element of document.elements.values()){const list=members.get(element.ownerCanvasId)??[];list.push(element.id);members.set(element.ownerCanvasId,list);}
   const ordered:Projection['nodes']=[];let complete=true;
-  /** 只重排节点引用，不重算未变化节点；任一所需投影缺失就放弃这份候选。 */
+  /** 按 owner 成员顺序深度优先重排节点引用，只进已在 transforms 显示的子 canvas。
+   * 缺任一所需投影就令 complete=false 回退；依赖已验证树，无独立循环/递归深度预算。 */
   const visit=(owner:Id)=>{for(const id of queries?queries.members(owner):members.get(owner)??[]){const element=document.elements.get(id)!;if(element.structure!=='node')continue;const projected=inserted.get(id)??nodes[layout.nodes.get(id)!];if(!projected){complete=false;return;}ordered.push(projected);const child=layout.entries.get(id);if(child&&base.transforms.has(child))visit(child);}};
   visit(canvasId);if(!complete)return;nodes=ordered;
  }

src/lib/canvas-bindings/scene-projection.ts

@@ -12,13 +12,17 @@ import {indexScene,patchScene,type SceneChangeHint,type SceneInputs} from './sce
 import type {RendererCatalog} from './renderers.ts';
 
 /** One view's derived scene. Viewport/tool/mode and task status do not change scene inputs. */
-/** 每个视图独立创建；advance 接 editor 发布，project 接当前显示输入，clear 释放全部派生缓存。 */
+/** 每个视图一份 previous/value/layout/pending 与几何缓存；advance 只积写集合，project 才按需算场景。
+ * 缓存借用不可变文档/选择/预览/registry/catalog 身份，不能在原对象中改字段后期待自动发现失效。
+ * 实例不订阅 editor、不请求帧，宿主负责接线 advance/project 与视图 clear 生命周期。 */
 export function createSceneProjection(){
  let geometry=createGeometryProjectionCache();
 
  let previous:SceneInputs|undefined,value:ReturnType<typeof projectCanvas>|undefined,layout:ReturnType<typeof indexScene>|undefined,pending:SceneChangeHint|undefined;
  return Object.freeze({
-  /** 累积从上次投影文档到当前文档的连续写集合；丢发布、无 changes 的替换或大范围改动退回全量。 */
+  /** 累积上次投影文档→当前文档的连续发布链；同一文档对象直接忽略，未有场景时无需积累。
+   * 断链只在 previous.document===before 时能重起；空 changes 丢提示，canvas 改动/脏 ID>16384 只标 topology。
+   * 这里只影响快路径选择，不重放 Change、不写 doc，也不保证输入 changes 本身语义完整。 */
   advance(before:Document,after:Document,changes:readonly Change[]){
    if(before===after)return;
    if(!previous||previous.document===after){pending=undefined;return;}
@@ -31,7 +35,9 @@ export function createSceneProjection(){
    if(pending.topology)pending.ids.clear();
   },
   /** 固定 document/registry/catalog/显示 canvas 和捕获的 session 输入；相同引用直接复用场景。
-   * 可兼容才尝试 patch，失败正常回退 projectCanvas；查询必须与同一份文档/registry 绑定。 */
+   * 可兼容才尝试 patch，undefined 正常回退 projectCanvas；异常不自动吞成另一份成功结果。
+   * queries 先查 document/registry 身份；其对象身份不在场景键中，单独更换 queries 不触发重算。
+   * 空 preview 规范为 undefined，viewport/tool/mode 不在键中；传入的 sessions 是捕获帧，不读取更新的 live 会话。 */
   project(owner:object,document:Document,view:ViewState,sessions:SessionSnapshot,registry:Registry,catalog:RendererCatalog,queries?:DocumentQueries){
    if(queries&&queries.document!==document)throw fault('stale_query_snapshot');
    if(queries&&queries.registry!==registry)throw fault('query_registry_changed');
@@ -43,7 +49,8 @@ export function createSceneProjection(){
    const compatible=previous&&value&&layout&&previous.owner===owner&&previous.registry===registry&&previous.catalog===catalog&&previous.canvasId===view.canvasId;
    const patched=compatible?patchScene(value!,layout!,next,previous!,connection,pending,queries):undefined;
    const result=patched??projectCanvas(document,view.canvasId,registry,view.selection,id=>next.preview?.get(id),connection,catalog,{queries,geometry,owner});
-   // 全量重建或节点数量改变才重建布局索引；成功采用结果后消费并清掉 changes 提示。
+   // 全量结果或节点数变化才重建 layout，其余兼容 patch 沿用数组下标/拓扑索引。
+   // 成功后一次推进 previous/value 并清 pending；异常不写这三项，但本轮几何缓存可能已有计算，不承诺整缓存回滚。
    if(!patched||result.nodes.length!==value!.nodes.length)layout=indexScene(result);
    previous=next;value=result;pending=undefined;return result;
   },

src/lib/canvas-bindings/selectors.ts

@@ -5,15 +5,19 @@
 /** One immutable source, one cached selection; no second document or operation state. */
 /** 最小快照/订阅协议，可由 editor、session 或派生源实现，订阅返回释放函数。 */
 export type ExternalSource<S>={getSnapshot():S;subscribe(notify:()=>void):()=>void};
-/** 用 selector 与等价判断派生稳定快照；等价的新值沿用旧引用，避免 UI 的无效刷新。 */
+/** 一个 store 共享一份最近源快照/selection 缓存，每个订阅另存 observed 引用。
+ * selector/isEqual 须同步且适合不可变源；不 clone/freeze 选中值，不修复上游原地修改后身份不变的问题。 */
 export function createSelectorStore<S,T>(source:ExternalSource<S>,selector:(snapshot:S)=>T,isEqual:(a:T,b:T)=>boolean=Object.is){
  let initialized=false,snapshot:S,selection:T;
- /** 根未变则跳过计算；根变但结果等价也保持 selection 引用，只更新已观察的根身份。 */
+ /** 根身份相同则跳过 selector；新根等价则沿用旧 selection，仅推进已观察源身份。
+  * selector/isEqual 抛错发生在缓存赋值前，原缓存保留，getSnapshot 仍向调用者抛错。 */
  function getSnapshot():T{
   const current=source.getSnapshot();if(initialized&&Object.is(snapshot,current))return selection;
   const next=selector(current),same=initialized&&isEqual(selection,next);
   snapshot=current;if(!same)selection=next;initialized=true;return selection;
  }
- // 每个订阅单独跟踪 observed；计算失败仍通知，让使用方在自己的读取/错误边界重新处理。
+ // subscribe 先同步读取初值（失败则尚未接上游）；每个 observer 独立比较 selection 身份。
+ // 上游通知时计算失败仍 notify，供使用方重读/错误边界处理；不把 notify 的异常吞成成功。
+ // 直接返回上游 stop，无额外 dispose：退订幂等性、异常与通知时序沿用源合同。
  return Object.freeze({getSnapshot,subscribe(notify:()=>void){let observed=getSnapshot();return source.subscribe(()=>{let next:T;try{next=getSnapshot();}catch{notify();return;}if(!Object.is(observed,next)){observed=next;notify();}});}});
 }

src/lib/canvas-bindings/session-frames.ts

@@ -6,7 +6,9 @@ import type {SessionSnapshot} from '../canvas-core/gestures.ts';
 import type {ExternalSource} from './selectors.ts';
 import {createFrameQueue,type FrameClock} from './frame-queue.ts';
 /** One subscription owns one disposable frame queue. Reads always see current sessions. */
-/** 对比前后会话引用生成 view/element 脏 key；退订时同步撤销帧队列。 */
+/** 每个订阅保留上一份 session 引用，按不可变 view/gesture 身份发现失效，任意 dirty 最终只触发 notify()。
+ * key 集合是帧内去重依据，不向消费者发布逐元素差分；getSnapshot 直接借用源方法，须不依赖 this 绑定。
+ * 此包装不使用 immediate 标志，也不对上游 subscribe/stop 抛错作 finally 清理，宿主须保证正常订阅生命周期。 */
 export function createSessionFrameSource(source:ExternalSource<SessionSnapshot>,clock:FrameClock):ExternalSource<SessionSnapshot>{
  return Object.freeze({getSnapshot:source.getSnapshot,subscribe(notify:()=>void){
   let previous=source.getSnapshot();const queue=createFrameQueue<string>(clock,()=>notify());
@@ -17,6 +19,7 @@ export function createSessionFrameSource(source:ExternalSource<SessionSnapshot>,
    if(previous.gesture!==next.gesture)for(const state of [previous.gesture,next.gesture])for(const target of state?.targets??[])dirty.add(`element:${target.id}`);
    // 连线手势与普通几何手势分别跟踪，改变或取消时都让旧/新目标失效。
    if(previous.connectionGesture!==next.connectionGesture)for(const state of [previous.connectionGesture,next.connectionGesture])if(state)dirty.add(`element:${state.target.id}`);
+   // 先推进 previous 再排队，因此一帧内多次变化相对每次上游快照计算，不只比较帧起点与终点。
    previous=next;queue.invalidate(dirty);
   });return()=>{stop();queue.dispose();};
  }});

src/lib/canvas-bindings/session-sources.ts

@@ -10,7 +10,9 @@ import type {ExternalSource} from './selectors.ts';
 /** preview 可被所有匹配代次的视图读取，active 则只标记拥有该手势的视图。 */
 export type GestureSelection={readonly preview:Geometry|undefined;readonly active:boolean};
 /** Derived view/target subscriptions. Values retain no document or full per-hook session. */
-/** 建立按视图模式和元素手势分离的订阅通道，比较派生值后才通知观察者。 */
+/** 建立按视图模式和几何手势分离的通道；只追踪 modes/gesture，不把 selection/viewport/connectionGesture 混入。
+ * modes 是 viewId→elementId→观察器桶，gestures 是 elementId→观察器桶，同一上游变化先选候选再比值。
+ * 有观察器时 previous 持有一份上游快照引用供比较，不复制完整 session；最后退订后释放该引用。 */
 export function createSessionSources(source:ExternalSource<SessionSnapshot>){
  // update 先推进内部观察值，notify 后执行外部回调，避免某监听器读到其它桶尚未更新。
  type Observer={update(snapshot:SessionSnapshot):boolean;notify():void};
@@ -18,9 +20,11 @@ export function createSessionSources(source:ExternalSource<SessionSnapshot>){
  // 按不可变 targets 数组的身份弱缓存 ID→代次索引，避免每个元素订阅逐次线性搜索目标列表。
  const targetIndexes=new WeakMap<readonly Target[],ReadonlyMap<Id,number>>();
  let stop:(()=>void)|undefined,previous:SessionSnapshot|undefined;
- /** 首次遇到一组目标时建索引；相同 ID 的新 incarnation 不会匹配旧手势。 */
+ /** 按 targets 数组身份缓存 elementId→incarnation，要求上游不原地改 targets。
+  * 合法会话应保证同组 ID 唯一；Map 对重复 ID 留最后一项，此 helper 不另验目标表形状。 */
  function targets(gesture:GestureState){let index=targetIndexes.get(gesture.targets);if(!index){index=new Map(gesture.targets.map(target=>[target.id,target.incarnation]));targetIndexes.set(gesture.targets,index);}return index;}
- /** 收集可能受影响的观察器，全部 update 完再逐个 notify；一个监听器失败也不饿死其余监听器。 */
+ /** 在 changed 入口取得同一份 next，先推进 previous，再用 Set 合并所有候选，避免观察器重复更新。
+  * 先更新全部候选 observed 后 notify；各 notify 异常暂存，余者仍执行，最后重抛第一个异常（包括假值）。 */
  function changed(){
   if(!previous)return;const before=previous,next=source.getSnapshot();previous=next;
   const candidates=new Set<Observer>(),add=(items:Set<Observer>|undefined)=>{for(const item of items??[])candidates.add(item);};
@@ -40,7 +44,9 @@ export function createSessionSources(source:ExternalSource<SessionSnapshot>){
   const notifications:Observer[]=[];for(const observer of candidates)if(observer.update(next))notifications.push(observer);
   let failed=false,error:unknown;for(const observer of notifications)try{observer.notify();}catch(caught){if(!failed){failed=true;error=caught;}}if(failed)throw error;
  }
- /** 一个派生通道的稳定读取和订阅装配。读取失败通过通知触发使用方重读，不把错误吞成旧成功值。 */
+ /** 每个 channel 独享 getSnapshot 的派生值缓存；每个订阅另存 observed，二者不靠回调共享可变业务数据。
+  * equal 深比较派生 JSON 风格值，等价时保留旧引用；选中 preview 仍借用原不可变 Geometry，不做深克隆。
+  * observer.read 失败会标记失败并通知，后续成功也通知一次恢复；直接 getSnapshot 的读取异常仍向外抛出。 */
  function channel<T>(read:(snapshot:SessionSnapshot)=>T,register:(observer:Observer)=>()=>void):ExternalSource<T>{
   let initialized=false,value:T;
   return Object.freeze({
@@ -51,18 +57,21 @@ export function createSessionSources(source:ExternalSource<SessionSnapshot>){
     const remove=register(observer);
     // 第一个观察器才连上游；注册失败撤回本次桶，防止留下无人管理的观察器。
     if(!stop){previous=source.getSnapshot();try{stop=source.subscribe(changed);}catch(error){remove();previous=undefined;throw error;}}
-    // 单次退订幂等；所有桶清空后释放全局上游订阅及上一份会话快照。
+    // 退订 token 先置 inactive，remove 清桶；最后一桶消失才 stop 上游并清 previous。
+    // stop 异常不在这里捕获，状态重置不保证继续执行；正常宿主清理端口须不抛错。
     let active=true;return()=>{if(!active)return;active=false;remove();if(!modes.size&&!gestures.size){stop?.();stop=undefined;previous=undefined;}};
    },
   });
  }
  return Object.freeze({
-  /** 派生某视图中单元素的编辑模式；视图/模式缺失时返回 null。 */
+  /** 捕获 viewId/id 两个标量，按 view→element 桶登记观察器；视图/模式缺失返回 null。
+   * 调用 mode 只创建派生通道，首次 subscribe 才注册桶和必要的上游监听。 */
   mode(viewId:Id,id:Id):ExternalSource<string|null>{return channel(snapshot=>snapshot.views.get(viewId)?.modes.get(id)??null,observer=>{
    let byId=modes.get(viewId);if(!byId){byId=new Map();modes.set(viewId,byId);}let bucket=byId.get(id);if(!bucket){bucket=new Set();byId.set(id,bucket);}bucket.add(observer);
    return()=>{bucket!.delete(observer);if(!bucket!.size)byId!.delete(id);if(!byId!.size)modes.delete(viewId);};
   });},
-  /** 按目标 ID+代次读取预览；同元素跨视图可见预览，但只有原 viewId 拥有 active。 */
+  /** 入口捕获 target.id/incarnation，之后改调用者 target 不影响本通道；订阅按 ID 分桶，读值再匹配代次。
+   * 匹配元素跨视图可见 preview，只有 gesture.viewId 对应视图 active；没有 preview 不代表不在手势 targets 中。 */
   gesture(viewId:Id,target:Target):ExternalSource<GestureSelection>{const{id,incarnation}=target;return channel(snapshot=>{
    const gesture=snapshot.gesture,matched=!!gesture&&targets(gesture).get(id)===incarnation;
    return{preview:matched?gesture!.preview.get(id):undefined,active:matched&&gesture!.viewId===viewId};

src/lib/canvas-bindings/visibility.ts

@@ -4,5 +4,6 @@
 import type {Rect} from '../canvas-core/geometry.ts';
 /** Positive-area native node visibility. Degenerate nodes are retained for measurement. */
 /** 正面积矩形要求与视口有正面积交叠，只有边界接触不算可见。
- * 宽/高非正的退化节点保留，让 renderer 有机会测量它，而不是提前裁掉。 */
+ * 宽/高非正的节点直接保留，即使远离视口，让 renderer 有机会测量；负数也走同一分支，并不在此修正。
+ * 调用方须提供同一坐标系中的轴对齐矩形；此函数不处理旋转、zoom 或 NaN/Infinity 合法性。 */
 export function nativeRectVisible(node:Rect,viewport:Rect){if(node.width<=0||node.height<=0)return true;return Math.min(node.x+node.width,viewport.x+viewport.width)>Math.max(node.x,viewport.x)&&Math.min(node.y+node.height,viewport.y+viewport.height)>Math.max(node.y,viewport.y);}

src/lib/canvas-runtime/applied-recovery.ts

@@ -11,13 +11,17 @@ import { runTerminal, type RunPort } from './runs.ts';
 import type { AssetPort } from './resources.ts';
 
 /** Stage acknowledgements only. The caller must validate a complete fresh read and durably publish it. */
-/** 在私有表上解释已保存回执，返回 staged 快照与 fresh read 断言；缺证据/解释器即整体拒绝。 */
+/** 取全部非 resolved 请求，要求已有 outcome=applied 且有保存回执，再按最早逻辑 sequence 解释。
+ * 只构造 ledger/runs/resources/conflicts 候选，document/history/acknowledged/versions 仍沿用原 snapshot。
+ * 没有待处理请求时也可返回空 stage；不会自己读取 canonical、重放 pending、发布 Root 或等待持久化。
+ * 依赖输入账本及 ports 的验证/纯解释合同，表复制不隔离恶意 adapter 对传入记录的修改；now 合法性也由宿主保证。 */
 export function stageAppliedRecovery(snapshot:EngineSnapshot,ports:{persistence:PersistencePort;runs?:RunPort;assets?:AssetPort;now:number}) {
   const waiting=[...snapshot.runtime.ledger.requests.values()].filter(request=>request.phase!=='resolved');
   // 只要还有 accepted/unresolved，就不能把整组当成确定已执行恢复，也不能新建替代请求重发。
   const unknown=waiting.filter(request=>request.outcome!=='applied');
   if(unknown.length)throw fault('recovery_waiting_for_receipts',unknown.map(request=>request.id));
-  /** 同一请求可能包含多个意图，以最早逻辑 sequence 排序，保证 run 受理先于其控制动作解释。 */
+  /** 以请求成员中最小 sequence 排序；成员缺失会取 Infinity，不在此独立证明账本成员/依赖合法。
+   * 合法顺序让 run 受理先建立候选记录，后续控制动作才能定位它；不是按回执到达时间解释。 */
   const sequence=(request:FrozenRequest)=>request.operationIds.reduce((result,id)=>Math.min(result,snapshot.runtime.ledger.operations.get(id)?.intent.sequence??Infinity),Infinity);
   waiting.sort((a,b)=>sequence(a)-sequence(b));
   // 新建候选账本和资源/run 表，后面的任何校验失败不会污染原 snapshot。
@@ -37,7 +41,8 @@ export function stageAppliedRecovery(snapshot:EngineSnapshot,ports:{persistence:
     }else if(['run.start','run.cancel','run.apply'].includes(request.kind??'')){
       if(!ports.runs?.verifyApplied)throw fault('run_receipt_interpreter_unavailable',[request.id]);
       const verified=ports.runs.verifyApplied(request,receipt);proof=verified.model;
-      // 受理必须绑定原 intent/request/board/target；已有 run 也必须具有相同身份和计划。
+      // 新受理核对原 intent/request/board/target，已有同 runId 时再比较 request/operation/plan。
+      // 已有记录保留其当前进度，不用旧 admission 覆盖；完整 run 形状/服务身份还依赖 verifyApplied 与外围校验。
       if(request.kind==='run.start'){
         const run=verified.admission,intent=snapshot.runtime.ledger.operations.get(request.operationIds[0])?.intent;
         if(!run||verified.action||intent?.operationType!=='run.start'||run.operationId!==intent.id||run.requestId!==request.id||run.boardId!==intent.run.boardId||!equal(run.target,intent.run.target))throw fault('run_identity_mismatch');
@@ -50,23 +55,28 @@ export function stageAppliedRecovery(snapshot:EngineSnapshot,ports:{persistence:
         if(request.kind==='run.cancel'){
           if(!action.runStatus||action.outputId||runTerminal(run.status)&&runTerminal(action.runStatus)&&run.status!==action.runStatus)throw fault('run_status_conflict');
         }else if(!action.outputId||action.runStatus)throw fault('run_identity_mismatch');
-        // 控制 epoch 递增阻止旧 poll 盖回新状态；标 hasMore/nextPollAt 让任务按原 ID 继续追尾。
+        // 控制动作推进 epoch 并去重登记已采用 output ID，清旧 pendingPage/错误，让原 run ID 从 now 继续追尾。
+        // 这里只暂存状态，不开始 poll；clock/epoch 范围与当前身份仍需宿主最终采纳时验证。
         runs.set(run.id,freeze({...run,controlEpoch:(run.controlEpoch??0)+1,...(action.runStatus?{status:action.runStatus}:{}),...(action.outputId?{appliedOutputIds:[...new Set([...(run.appliedOutputIds??[]),action.outputId])]}:{}),hasMore:true,blocked:false,error:undefined,pendingPage:undefined,nextPollAt:ports.now}));runIds.add(run.id);
       }
     }else{
       if(!ports.persistence.verifyApplied)throw fault('document_receipt_interpreter_unavailable',[request.id]);
       proof=ports.persistence.verifyApplied(request,receipt);
     }
-    // 各请求有不同写版本范围：start 只 owner，cancel/upload 无文档写，普通/apply 要完整参与者。
+    // 证明版本键必须恰好覆盖写范围：start 只 owner，cancel/upload 空，普通/apply 为 request.canvasIds。
+    // 这里只要求 proof 版本是安全整数且高于原 expected，不独自要求恰好 +1；精确协议规则由解释器保证。
     const writes=request.kind==='run.start'?[request.ownerCanvasId!]:request.kind==='run.cancel'||request.kind==='asset.upload'?[]:request.canvasIds;
     if(writes.length!==(proof?.versions.size??0)||writes.some(id=>!proof?.versions.has(id)))throw fault('receipt_coverage_mismatch',[request.id]);
     if(proof){for(const [canvas,version]of proof.versions)if(!Number.isSafeInteger(version)||version<=request.expectedVersions[canvas])throw fault('receipt_version_mismatch',[canvas]);proofs.push(proof);}
-    // 仅在候选账本标已协调 applied；真正采用仍需外层 fresh read 校验和持久化。
+    // result 默认按 reconciled applied 归约候选账本并移除此 request 的冲突，原账本/原冻结 body 仍不变。
+    // staged 未通过 fresh read 断言前不可直接发布，也不因这一步就释放真实 writer 或开始下一请求。
     ledger.result(request.id,'applied');conflicts.delete(request.id);
   }
   const staged:EngineSnapshot=Object.freeze({...snapshot,runtime:Object.freeze({...snapshot.runtime,ledger:ledger.getSnapshot(),runs:readMap(runs),resources:readMap(resources),conflicts:readMap(conflicts)})});
   return Object.freeze({snapshot:staged,requestIds:Object.freeze(waiting.map(request=>request.id)),runIds:Object.freeze([...runIds]),
-    /** fresh read 版本不得落后于任何执行证明，并逐个执行协议专用内容断言。 */
+    /** 核对 fresh 版本至少覆盖各 proof 水位，再逐个调用协议内容断言；不拿旧回执模型覆盖 fresh。
+     * 不在此调用 validateCanonicalRead/validateDocument 或验证读取来源，engine 须先完成这些检查。
+     * proof Map/回调按端口不可变纯证据合同保留；断言成功也不是持久化完成回执。 */
     assertCanonical(canonical:CanonicalProposal){for(const proof of proofs){for(const [canvas,version]of proof.versions)if((canonical.versions.get(canvas)??-1)<version)throw fault('recovery_read_behind_receipt',[canvas]);proof.assertCanonical(canonical);}},
   });
 }

src/lib/canvas-runtime/asset-depot-storage.ts

@@ -2,6 +2,7 @@
  * 共享原图的 IndexedDB 实现：asset-depot 存身份/退休事实，asset-bytes 按摘要共享 Blob，
  * asset-pins 按项目存与 Root 版本绑定的完整保留清单。所有 execute 都经过主存储的 leader/fence 检查。
  * 回收只清本地共享字节，保留身份；同摘要还有其它活身份时不能删实际字节。
+ * 本模块不创建/提交事务：写入辅助函数借用外层事务，read/collect 借用注入的 execute；错误由其统一 abort。
  */
 import {equal,fault,freeze} from '../canvas-core/values.ts';
 import {sharedAssetRef,validateSharedAsset,type AssetDepotPort,type DepotCut,type DepotEntry,type SharedAsset} from './asset-depot.ts';
@@ -24,23 +25,31 @@ function authority(value:string){if(typeof value!=='string'||!value||value.lengt
 /** 读取身份记录时验证 ref 与键一致、退休时钟合法，损坏数据不能被回收过程忽略。 */
 function validateFact(row:Fact,scopeAuthority:string,id:string){validateSharedAsset(row?.ref);if(row.ref.authority!==scopeAuthority||row.ref.asset.id!==id)throw fault('corrupt_asset_depot');for(const n of [row.unreferencedAt,row.purgedAt])if(n!==undefined&&(!Number.isSafeInteger(n)||n<0))throw fault('corrupt_asset_depot');if(row.purgedAt!==undefined&&(row.unreferencedAt===undefined||row.purgedAt<row.unreferencedAt))throw fault('corrupt_asset_depot');}
 /** Detach descriptors before awaiting crypto. Blob data is immutable and never JSON cloned. */
-/** 第一个 await 前捕获/冻结 descriptors，校验 pin/写入唯一性；Blob 不做 JSON clone。 */
+/** 同步重建 pin 数组与标准引用字段，让外层能在第一个 await 前捕获 cut；Blob 沿用不可变字节对象。
+ * pin ID 与 write ID 分别去重，不要求两表完全相等，也不证明 complete 声明覆盖全部 Root 引用。
+ * sharedAssetRef 保留 asset 扩展属性的引用，冻结不等于任意外来对象的递归深复制。 */
 export function detachDepotCut(cut:DepotCut):DepotCut{
  if(!cut||cut.version!==1||typeof cut.complete!=='boolean'||!Array.isArray(cut.pins)||!Array.isArray(cut.writes))throw fault('invalid_depot_cut');authority(cut.authority);
+ // seen 只检查资源 ID 唯一；每条 owner 列表还要非空、非重复，再复制冻结以脱离可变数组。
  const seen=new Set<string>(),pins=cut.pins.map(row=>{if(!Array.isArray(row)||row.length!==2||typeof row[0]!=='string'||!row[0]||seen.has(row[0])||!Array.isArray(row[1])||!row[1].length||row[1].some(owner=>typeof owner!=='string'||!owner)||new Set(row[1]).size!==row[1].length)throw fault('invalid_depot_cut');seen.add(row[0]);return Object.freeze([row[0],Object.freeze([...row[1]])] as const);});
+ // write 可仅含引用以复用已存字节；提供 Blob 时这里只查类型，长度/摘要留给事务外 verifyDepotBytes。
  const written=new Set<string>(),writes=cut.writes.map(row=>{validateSharedAsset(row.ref);if(row.ref.authority!==cut.authority||written.has(row.ref.asset.id)||row.bytes!==undefined&&!(row.bytes instanceof Blob))throw fault('invalid_depot_cut');written.add(row.ref.asset.id);return Object.freeze({ref:sharedAssetRef(row.ref),...(row.bytes?{bytes:row.bytes}:{})});});
  return Object.freeze({version:1,authority:cut.authority,complete:cut.complete,pins:Object.freeze(pins),writes:Object.freeze(writes)});
 }
-/** 在 IDB 事务外计算原图 SHA256 并验长度，避免 await crypto 让事务提前失活。 */
+/** 在 IDB 事务外逐项计算原图 SHA256 并验长度，避免 await crypto 让事务提前失活。
+ * 借用已捕获 cut；未附 bytes 的项不重读存储。一次整 Blob 转 ArrayBuffer，没有分块预算/取消信号。
+ * 摘要证明内容匹配声明，不验证服务权限、实际图片解码尺寸或 MIME；这些由其它端口负责。 */
 export async function verifyDepotBytes(cut:DepotCut){
  for(const row of cut.writes)if(row.bytes){if(row.bytes.size!==row.ref.asset.bytes)throw fault('shared_asset_bytes_changed',[row.ref.asset.id]);const digest=[...new Uint8Array(await crypto.subtle.digest('SHA-256',await row.bytes.arrayBuffer()))].map(n=>n.toString(16).padStart(2,'0')).join('');if(digest!==row.ref.digest)throw fault('shared_asset_bytes_changed',[row.ref.asset.id]);}
 }
 /** Must run in the same transaction as the project Root, including idempotent reindexing. */
-/** 必须与项目 Root 同事务：校验既存身份、按 digest 写共享字节，并更新该项目 pin manifest。 */
+/** 必须与项目 Root 同事务：校验既存身份、按 digest 写共享字节，并替换该项目 pin manifest。
+ * 调用前须 detach/verify；本函数不重算摘要，也不自行核对 rootRevision/leader。完成只表示请求已排入事务。 */
 export async function writeDepotCut(tx:IDBTransaction,scope:StorageScope,rootRevision:number,cut:DepotCut){
  const base=prefix(scope,cut.authority),facts=tx.objectStore('asset-depot'),bytes=tx.objectStore('asset-bytes');
  for(const row of cut.writes){const key=[...base,row.ref.asset.id],previous=await value<Fact|undefined>(facts.get(key));if(previous){validateFact(previous,cut.authority,row.ref.asset.id);if(!equal(previous.ref,row.ref))throw fault('shared_asset_identity_conflict',[row.ref.asset.id]);}
-  // Digest-addressed bytes are shared across resource IDs and projects in this authority.
+  // 同 account/workspace/authority 的不同资源 ID 共用 digest 字节行。
+  // 再提供同一身份的已验证 bytes 可清掉软标记与 purgedAt；只有元信息的写入保持既有退休状态。
   if(row.bytes)bytes.put(row.bytes,[...base,row.ref.digest]);
   facts.put({...previous,ref:row.ref,...(row.bytes?{unreferencedAt:undefined,purgedAt:undefined}:{})},key);
  }
@@ -57,9 +66,10 @@ function depotFile(row:unknown,id:string):DepotFile{
  if(file.kind!=='asset-depot'||file.resourceId!==id||typeof file.digest!=='string'||!/^[a-f0-9]{64}$/.test(file.digest)||!Number.isSafeInteger(file.byteLength)||file.byteLength<1||file.byteLength>20*1024*1024||typeof file.mimeType!=='string')throw fault('corrupt_file_store');
  return file;
 }
-/** Undefined means bytes were explicitly evicted; identity metadata remains. */
-/** Blob 旧行直接返回；指针行核对共享身份/长度，字节已显式清理则返回 undefined。
- * 返回时恢复项目原文件 MIME，不因服务检测 MIME 与本地不同而改变原文件合同。 */
+/** Blob 旧行与不存在的行直接返回；指针行核对共享身份/长度，已 purge 或共享字节缺失均返回 undefined。
+ * undefined 本身不能区分从未写入、显式回收和缺失字节；缺少身份事实或字段冲突则抛损坏错误。
+ * 返回时恢复项目原文件 MIME，不因服务检测 MIME 与本地不同而改变原文件合同。
+ * 不重新哈希、不向服务器授权/下载；调用方须维持事务生命周期及外层读权限。 */
 export async function resolveDepotFile(tx:IDBTransaction,scope:StorageScope,id:string,row:unknown):Promise<Blob|undefined>{
  if(row===undefined||row instanceof Blob)return row;
  const file=depotFile(row,id),base=prefix(scope,file.authority),fact=await value<Fact|undefined>(tx.objectStore('asset-depot').get([...base,id]));
@@ -73,7 +83,10 @@ export async function resolveDepotFile(tx:IDBTransaction,scope:StorageScope,id:s
  return bytes.type===file.mimeType?bytes:bytes.slice(0,bytes.size,file.mimeType);
 }
 /** Convert only Root-proven stored uploads, after shared bytes and local files are written. */
-/** Root 已证明 stored upload 且共享字节存在时，把项目 Blob 行改为指针；未确认上传绝不提前转。 */
+/** 从已校验 Root 中读取 stored upload 声明，把本次 cut.writes 对应的项目 Blob 行改为共享指针。
+ * 只检查声明/身份与 Blob 长度和本地 MIME，不重新对比两份文件内容；字节摘要证明依赖外层流程。
+ * 缺 resource.stored、资源已 purge、无项目文件或无共享字节时跳过；不是扫描迁移项目中所有文件。
+ * 借用 Root/共享写入相同事务，后续任何冲突应由外层 abort，不能只保存部分已转换行。 */
 export async function promoteDepotFiles(tx:IDBTransaction,scope:StorageScope,key:string,image:RecoveryImage,cut:DepotCut){
  type Resource={id:string;digest?:string;byteLength:number;mimeType:string;stored?:SharedAsset['asset'];retirement?:{purgedAt?:number}};
  const payload=image.payload as {runtime?:{resources?:readonly (readonly [string,Resource])[]}},entries=payload?.runtime?.resources;
@@ -92,15 +105,19 @@ export async function promoteDepotFiles(tx:IDBTransaction,scope:StorageScope,key
 }
 /** 注入主 adapter 的事务执行器，统一复用 metadata/fence/事务终态屏障。 */
 type Execute=<T>(leader:StorageLeader,stores:string[],mode:IDBTransactionMode,run:(tx:IDBTransaction)=>Promise<T>)=>Promise<T>;
-/** 为主 storage 装配 read/collect；调用者不能绕开有效 leader 直接操作跨项目共享行。 */
+/** 为主 storage 装配 read/collect；leader/fence/事务终态由注入的 execute 保证，而非本工厂自行实现。
+ * 工厂不建立第二份缓存或连接；这些数据库身份检查也不替代远端资源授权。 */
 export function createDepotStorage(execute:Execute):AssetDepotPort{return Object.freeze({
  /** 读取本域身份与尚未 purge 的字节，元信息及 Blob 类型/长度都校验，缺字节不丢身份。 */
  async read(leader,scopeAuthority,id){authority(scopeAuthority);if(typeof id!=='string'||!id)throw fault('invalid_resource_id');return execute(leader,depotStores,'readonly',async tx=>{const base=prefix(leader.scope,scopeAuthority),row=await value<Fact|undefined>(tx.objectStore('asset-depot').get([...base,id]));if(!row)return;validateFact(row,scopeAuthority,id);const bytes=row.purgedAt===undefined?await value<Blob|undefined>(tx.objectStore('asset-bytes').get([...base,row.ref.digest])):undefined;if(bytes!==undefined&&(!(bytes instanceof Blob)||bytes.size!==row.ref.asset.bytes))throw fault('corrupt_asset_depot');return freeze({...row,...(bytes?{bytes}:{})}) as DepotEntry;});},
- /** 一次至多128身份的两阶段回收：先软标记，保留期过后 purge；完整性门禁覆盖所有本地项目。 */
+ /** 一页至多128身份的两阶段回收：先软标记，之后另一次访问满足保留期才 purge（即使 retentionMs=0）。
+  * 每次仍 getAll 本地项目 metadata 与本授权域全部 fact，页大小不限制全量扫描/驻留量。
+  * complete=true 只表示清单门禁通过；若有 nextAfter，调用者还需继续下一页，不等于整仓库已回收。 */
  async collect(leader,input){authority(input.authority);const {now,retentionMs,limit,after}=input;if(!Number.isSafeInteger(now)||now<0||!Number.isSafeInteger(retentionMs)||retentionMs<0||!Number.isSafeInteger(limit)||limit<1||limit>128||after!==undefined&&(typeof after!=='string'||!after))throw fault('invalid_depot_collection');
   return execute(leader,depotStores,'readwrite',async tx=>{
    const scope=leader.scope,metadata=tx.objectStore('metadata'),keys=await value(metadata.getAllKeys()),heads=await value<{throughRevision?:number}[]>(metadata.getAll()),base=prefix(scope,input.authority),manifests=tx.objectStore('asset-pins'),blockedProjects:string[]=[],pinned=new Set<string>();
-   // 包括已关闭项目：其 manifest 必须与当前 Root 头一致，任一缺失/过期/opaque 都阻止删除。
+   // getAllKeys/getAll 在同一事务按相同键序对应。包括同账号工作区的已关闭项目；尚无可靠 Root 的头跳过。
+   // 每个有 Root 项目的本授权域 manifest 必须同 revision 且 complete；不要求项目当前持有 leader。
    for(let i=0;i<keys.length;i++){let parts:unknown;try{parts=JSON.parse(String(keys[i]));}catch{throw fault('corrupt_storage_scope');}if(!Array.isArray(parts)||parts.length!==3||parts.some(p=>typeof p!=='string'||!p))throw fault('corrupt_storage_scope');if(parts[0]!==scope.accountId||parts[1]!==scope.workspaceId||heads[i].throughRevision===undefined)continue;
     const pins=await value<Pins|undefined>(manifests.get([...base,parts[2]]));if(!pins||pins.version!==1||pins.rootRevision!==heads[i].throughRevision||pins.complete!==true){blockedProjects.push(parts[2]);continue;}
     if(!Array.isArray(pins.pins))throw fault('corrupt_depot_pins');for(const row of pins.pins){if(!Array.isArray(row)||row.length!==2||typeof row[0]!=='string'||!row[0]||!Array.isArray(row[1])||!row[1].length||row[1].some(owner=>typeof owner!=='string'||!owner))throw fault('corrupt_depot_pins');pinned.add(row[0]);}
@@ -109,11 +126,14 @@ export function createDepotStorage(execute:Execute):AssetDepotPort{return Object
    if(blockedProjects.length)return freeze({complete:false,blockedProjects,markedIds:[],purgedIds:[],pinnedIds:[]});
    const store=tx.objectStore('asset-depot'),factKeys=await value(store.getAllKeys(range(scope,input.authority))),rows=await value<Fact[]>(store.getAll(range(scope,input.authority))),markedIds:string[]=[],purgedIds:string[]=[],pinnedIds:string[]=[];
    for(let i=0;i<rows.length;i++){const key=factKeys[i];if(!Array.isArray(key)||key.length!==4||typeof key[3]!=='string')throw fault('corrupt_asset_depot');validateFact(rows[i],input.authority,key[3]);}
-   // 先验证本域记录，再按资源 ID 游标截取一页，多取一条判断是否还有下一页。
+   // 所有 fact 先验证再分页：页外损坏也阻止本次回收。复合 IDB 键序提供资源 ID 顺序，after 严格排除自身。
+   // 多取一条只判断后续候选；已 purge/仍 pinned 的身份也占页名额，不是 limit 个实际删除。
    const candidates=rows.map((row,i)=>({row,key:factKeys[i] as string[]})).filter(({key})=>after===undefined||key[3]>after).slice(0,limit+1),page=candidates.slice(0,limit);
-   // repin 清软标记；无引用首次记录时刻；时钟倒退不提前 purge；永久身份不重新分配。
+   // repin 只清尚未 purge 的软标记；已 purge 身份即使重新被 pin 也不在此复活字节。
+   // 未引用首次只记录时刻；之后满足保留期才 purge，时钟倒退不提前清理；身份行始终保留。
    for(const {row,key}of page){const id=key[3];if(pinned.has(id)){pinnedIds.push(id);if(row.purgedAt===undefined&&row.unreferencedAt!==undefined){delete row.unreferencedAt;store.put(row,key);}continue;}if(row.purgedAt!==undefined)continue;if(row.unreferencedAt===undefined){row.unreferencedAt=now;markedIds.push(id);store.put(row,key);}else if(now>=row.unreferencedAt&&now-row.unreferencedAt>=retentionMs){row.purgedAt=now;purgedIds.push(id);store.put(row,key);}}
-   // Preserve a digest while any other live resource identity still owns its bytes.
+   // rows 与 page 共用本事务读出的 row 对象，已写的 purgedAt 可直接参与全域存活判断。
+   // 同摘要任一身份尚未 purge（即使未 pin、仍在保留期）都保留字节；最后一份退休后才删 digest 行。
    for(const digest of new Set(page.filter(({row})=>row.purgedAt===now).map(({row})=>row.ref.digest)))if(!rows.some(row=>row.ref.digest===digest&&row.purgedAt===undefined))tx.objectStore('asset-bytes').delete([...base,digest]);
    return freeze({complete:true,blockedProjects:[],markedIds,purgedIds,pinnedIds,...(candidates.length>limit?{nextAfter:page.at(-1)!.key[3]}:{})});
   });

src/lib/canvas-runtime/asset-depot.ts

@@ -27,32 +27,43 @@ export type AssetDepotPort={
  read(leader:StorageLeader,authority:string,id:Id):Promise<DepotEntry|undefined>;
  collect(leader:StorageLeader,input:{readonly authority:string;readonly now:number;readonly retentionMs:number;readonly limit:number;readonly after?:Id}):Promise<DepotCollection>;
 };
-/** 严格验证授权域、64位小写十六进制摘要、图片 MIME、正尺寸/字节及像素/20MiB上限。 */
+/** 校验版本、非空授权域/URL、64 字符小写摘要、图片 MIME、正整数尺寸/字节及像素/20MiB上限。
+ * 只检查元数据：URL 未限制协议/域，摘要未重算，尺寸未通过实际解码核实；授权真实性由服务端口保证。 */
 export function validateSharedAsset(value:SharedAsset):void{
  if(!value||value.version!==1||typeof value.authority!=='string'||!value.authority||value.authority.length>8192||typeof value.digest!=='string'||!/^([a-f0-9]{64})$/.test(value.digest))throw fault('invalid_shared_asset');
  const asset=value.asset;if(!asset||typeof asset.id!=='string'||!asset.id||typeof asset.url!=='string'||!asset.url||asset.url.length>8192||![asset.width,asset.height,asset.bytes].every(n=>Number.isSafeInteger(n)&&n>0)||asset.width*asset.height>40_000_000||asset.bytes>20*1024*1024||!['image/png','image/jpeg','image/gif','image/webp'].includes(asset.mime_type))throw fault('invalid_shared_asset');
 }
-/** 验证后捕获并冻结资源元信息，隔离调用者可变的 asset 对象。 */
+/** 验证后重建标准外层字段并浅复制 asset，再递归冻结，隔离标准标量元信息。
+ * asset 的扩展属性仍由 spread 保留，嵌套扩展值不深克隆，不能当作任意外部对象的完整隔离入口。 */
 export function sharedAssetRef(value:SharedAsset):SharedAsset{validateSharedAsset(value);return freeze({version:1 as const,authority:value.authority,digest:value.digest,asset:{...value.asset}});}
 /** 比较完整不可变引用，不能只因 ID 或 URL 一样就容忍摘要/尺寸变化。 */
 const same=(a:SharedAsset,b:SharedAsset)=>equal(sharedAssetRef(a),sharedAssetRef(b));
 /** Immutable metadata cache only. Every new adoption resolves current permission first. */
-/** 建立工作区门面，绑定作用域与当前身份，不把跨账号缓存混入同一个 records 表。 */
+/** 捕获 account/workspace 标量，建立仅存元信息的 Map；字节仍由 port 持有，不建立内存 Blob 缓存。
+ * 宿主 current/leader 校验约束使用生命周期，实际存储 fence/权限检查仍由端口实现。
+ * 每次 getResources 返回成员快照，旧快照不随 remember/close 改变；它不另做授权或关闭检查。 */
 export function createAssetDepot(options:{scope:Pick<StorageScope,'accountId'|'workspaceId'>;port:AssetDepotPort;current():boolean;digest(bytes:Blob,signal?:AbortSignal):Promise<string>}){
  const scope=freeze({accountId:options.scope.accountId,workspaceId:options.scope.workspaceId});let closed=false;const records=new Map<string,SharedAsset>(),controllers=new Set<AbortController>();
- /** 每个 await 前后使用：宿主仍有效且 leader 属于同账号/工作区；允许不同项目共享仓库。 */
+ /** 入口及异步结果采纳前检查宿主/leader，允许同账号工作区的不同项目共享。
+  * 不比较 projectId，不读取远端 fence；在途 I/O 是否立即停止由端口/信号决定。 */
  const check=(leader:StorageLeader)=>{if(closed||!options.current())throw fault('identity_changed');if(!leader.active||leader.scope.accountId!==scope.accountId||leader.scope.workspaceId!==scope.workspaceId)throw fault('asset_depot_scope_mismatch');};
  /** 缓存同 authority/assetId 的不可变引用；相同身份元数据改变视为冲突，不静默覆盖。 */
  function remember(ref:SharedAsset){validateSharedAsset(ref);const key=JSON.stringify([ref.authority,ref.asset.id]),previous=records.get(key);if(previous&&!same(previous,ref))throw fault('shared_asset_identity_conflict',[ref.asset.id]);records.set(key,sharedAssetRef(ref));}
  return Object.freeze({scope,getResources:()=>readMap(records),
-  /** 新采纳先远端 resolve，再比本地身份/读取原字节并验长度+SHA；每个 await 后重新检查取消/身份。
-   * 成功只返回 ref/bytes 和记元信息，目标 binding 与字节持久化由 engine 的单 Root 完成。 */
+  /** 新采纳先 resolve 当前权限，再核对缓存身份；有缓存字节仍验长度/摘要，否则向 authority 读取。
+   * combined 信号交端口，异步返回后再检查；入口不先 throwIfAborted，已取消信号仍可能传给 resolve。
+   * remember 捕获元信息，但返回 ref 沿用 resolve 结果（只冻结返回 envelope），端口须提供不可变身份。
+   * 成功不写共享字节/项目 binding；这些由 engine 同 Root 持久化，不是新上传任务。 */
   async authorize(leader:StorageLeader,authority:AssetAuthority,id:Id,signal:AbortSignal){check(leader);const controller=new AbortController(),combined=AbortSignal.any([signal,controller.signal]);controllers.add(controller);try{const ref=await authority.resolve(id,combined);check(leader);combined.throwIfAborted();validateSharedAsset(ref);if(ref.authority!==authority.scope||ref.asset.id!==id)throw fault('asset_authorization_mismatch');const cached=await options.port.read(leader,authority.scope,id);check(leader);combined.throwIfAborted();if(cached&&!same(cached.ref,ref))throw fault('shared_asset_identity_conflict',[id]);let bytes=cached?.bytes;if(!bytes)bytes=await authority.read(id,combined);check(leader);combined.throwIfAborted();if(bytes.size!==ref.asset.bytes||await options.digest(bytes,combined)!==ref.digest)throw fault('shared_asset_bytes_changed',[id]);check(leader);combined.throwIfAborted();remember(ref);return Object.freeze({ref,bytes});}finally{controllers.delete(controller);}},
-  /** 读取已绑定本地共享字节并验身份/摘要；不是新 adoption 的授权捷径，缺字节返回 undefined。 */
+  /** 按已绑定 ref 读取本地共享字节并验身份/摘要，不调用 authority.resolve 或回源下载。
+   * 无记录直接 undefined；有记录无字节也记下元信息再返回 undefined，不能据此判定服务器资产消失。
+   * 输入 ref 沿用调用方身份；本方法不单独证明调用者有权新采纳该资源。 */
   async read(leader:StorageLeader,ref:SharedAsset,signal?:AbortSignal){check(leader);signal?.throwIfAborted();const row=await options.port.read(leader,ref.authority,ref.asset.id);check(leader);signal?.throwIfAborted();if(!row)return;if(!same(row.ref,ref))throw fault('shared_asset_identity_conflict',[ref.asset.id]);if(row.bytes&&(row.bytes.size!==ref.asset.bytes||await options.digest(row.bytes,signal)!==ref.digest))throw fault('shared_asset_bytes_changed',[ref.asset.id]);check(leader);signal?.throwIfAborted();remember(ref);return row.bytes;},
-  /** 作用域检查后委托存储扫描/保留期回收，结束再检查身份，不自行删除服务器资产。 */
+  /** 作用域检查后直接委托 port.collect，结果由端口负责结构与回收证明，不在此重验。
+   * 返回后再核对身份；检查失败不代表端口之前的本地存储事务未执行，也不删除服务器资产。 */
   async collect(leader:StorageLeader,input:Parameters<AssetDepotPort['collect']>[1]){check(leader);const result=await options.port.collect(leader,input);check(leader);return result;},
-  /** 关闭门面并 abort 授权任务、清元缓存；不抹掉共享存储中的持久身份/字节。 */
+  /** 关闭后拒绝新操作，abort 本门面追踪的 authorize 并清元缓存；不删除持久身份/字节。
+   * read/collect 没有被加入 controllers，在途结果由后续 check 拒绝采纳；close 不等待底层 I/O 退出。 */
   close(){closed=true;for(const controller of controllers)controller.abort();controllers.clear();records.clear();},
  });
 }

src/lib/canvas-runtime/batch-projection.ts

@@ -10,7 +10,8 @@ import { compressChanges, type LedgerSnapshot } from './ledger.ts';
 
 /** 使用 UTF-8 实际字节衡量 wire 大小，不能把 JS 字符串长度当 HTTP payload 大小。 */
 const encoder = new TextEncoder();
-/** 仅计算候选 JSON 表示的字节成本，不在这里发送或冻结请求。 */
+/** 仅比较传入 JSON 的 UTF-8 字节；调用处测量 operation 数组，不含 HTTP 头/请求 envelope。
+ * 不在这里发送或冻结请求，也不估算压缩传输后的成本。 */
 const wireBytes = (value: unknown) => encoder.encode(JSON.stringify(value)).byteLength;
 
 /** wire 中保留的 logical ID 与对应条件 changes；不是新的本地历史单元。 */
@@ -19,9 +20,13 @@ export type WireOperation = { readonly id: Id; readonly changes: readonly Change
 const sameMap = <T>(a: ReadonlyMap<Id, T>, b: ReadonlyMap<Id, T>) => a.size === b.size && [...a].every(([id, value]) => b.has(id) && equal(value, b.get(id)));
 
 /** Pure projection for an already-selected mutable segment. Original ledger/history records never change. */
-/** 尝试无损压缩多意图的 wire 投影；不足两项或任一不安全前提直接返回 ordered。 */
+/** 为调用方已选好的未发送段尝试 wire 压缩；不足两项、基线不明或无收益时返回 ordered。
+ * 原始条件链非法会抛错，投影效果不等价也会抛错，并非所有失败都回退。
+ * 此处只比对 ledger 的 changes/phase 等局部条件，不验证完整意图身份、依赖、类型/版本或段连续性。
+ * 参与范围与选择合法性由调用方保证；这里不调用 registry/整图校验来证明所有权或权限。 */
 export function projectBatch(intents: readonly OperationIntent[], acknowledged: Document, ledger: LedgerSnapshot, participants: readonly Id[]): readonly WireOperation[] {
   const scope = new Set(participants);
+  // 回退表示创建新的外层数组/条目，但 changes 沿用输入引用；仅成功压缩的结果走末尾 freeze。
   const ordered = intents.map(({ id, changes }) => ({ id, changes }));
   if (intents.length < 2) return ordered;
   // 只收集这段触及的基线记录组成 sparse 文档，减少复制/比较完整项目的成本。
@@ -52,9 +57,11 @@ export function projectBatch(intents: readonly OperationIntent[], acknowledged:
   // wire 投影保留生命周期和 no-op 检查，完整零效果段由独立 elision 证明处理。
   const compacted = compressChanges(raw, { preserveLifecycle: true, preserveChecks: true });
   if (!compacted.length) return ordered;
+  // 原逻辑 ID 顺序逐项保留；函数本身不验证输入 ID 唯一性，去重身份由 ledger/请求编译边界保证。
   // Protocol 2 requires a nonempty change list per logical ID. Prefix IDs get an explicit
-  // conditional no-op; the final ID carries the composed effect. All IDs remain deduplicated.
-  // 从参与 owner 的少量元素 title/text 或根 canvas 选 no-op guard，不扩大原 claim 范围。
+  // conditional no-op; the final ID carries the composed effect. Input ID order is retained.
+  // 从参与 owner 的基线元素选 title/text 条件 no-op，最多查看 8 个候选元素，每个产生两个 guard。
+  // guard 表达的是基线值/存在性，不是某个前缀逻辑操作的独立最终效果；最后一项统一携带组合变化。
   const guards: Change[] = [];
   let candidates = 0;
   for (const element of elements.values()) if (scope.has(element.ownerCanvasId)) {
@@ -73,7 +80,8 @@ export function projectBatch(intents: readonly OperationIntent[], acknowledged:
   if (!guard) return ordered;
   const projected = intents.map((intent, index) => ({ id: intent.id, changes: index === intents.length - 1 ? compacted : [guard!] }));
   if (projected.reduce((count, operation) => count + operation.changes.length, 0) > 10_000 || wireBytes(projected) >= wireBytes(ordered)) return ordered;
-  // 最后执行投影并对比 elements/canvases/tombstones 全效果，不只比较可见节点内容。
+  // 在同一 sparse 片段执行投影，比较它的三张表而非完整项目；未触及记录从未纳入片段。
+  // 这证明该基线上的组合效果一致，不替代请求执行时的版本检查或最终文档校验。
   const result = applyChanges(sparse, projected.flatMap(operation => operation.changes));
   if (!sameMap(original.elements, result.elements) || !sameMap(original.canvases, result.canvases) || !sameMap(original.tombstones, result.tombstones)) throw fault('batch_projection_mismatch');
   return freeze(projected);

src/lib/canvas-runtime/browser-digests.ts

@@ -5,7 +5,10 @@
 import {fault} from '../canvas-core/values.ts';
 import {createDigestPool} from './digest-pool.ts';
 /** Browser capability stays at the adapter; WorkspaceRuntime owns the pool's lifetime. */
-/** 构建 workspace 可共享的 DigestPort；任务 ID/长度/版本共同验证响应归属。 */
+/** 在构造时选择能力：Worker 不存在就使用池的默认分块执行器，否则每个 execute 新建专用 Worker。
+ * 此选择不随后续 Worker 全局变化自动重算；创建/运行失败也不降级重试。
+ * 使用默认池预算，响应按实例内递增 ID/输入长度/版本和摘要格式核对，不独立重算摘要。
+ * 没有超时，线程无响应需外部取消/close；Worker 内原生哈希阈值由 digestWorkerSource 控制。 */
 export function createBrowserDigests(){
   let next=0;
   return createDigestPool({execute:typeof Worker==='undefined'?undefined:(bytes,signal)=>new Promise<string>((resolve,reject)=>{
@@ -15,6 +18,8 @@ export function createBrowserDigests(){
     const id=++next;let done=false;
     /** 幂等完成：解绑所有消息/错误/abort 监听并终止 Worker，防止迟到响应泄漏或重复 resolve。 */
     const finish=(error?:unknown,sha256?:string)=>{if(done)return;done=true;signal.removeEventListener('abort',abort);worker.onmessage=null;worker.onerror=null;worker.onmessageerror=null;worker.terminate();if(error)reject(error);else resolve(sha256!);},abort=()=>finish(fault('import_aborted'));
+    // 稳定 digest_worker_failed 只有身份匹配才采纳；其它响应走摘要字段校验，不把任意 error 字段当服务错误。
+    // 格式正确只表明消息可解释，真实性来自受信的专用 Worker 算法；不在 UI 线程重复计算。
     // 消息须精确匹配版本、任务 ID 和输入长度，再验64位十六进制摘要；已知错误也必须匹配身份。
     signal.addEventListener('abort',abort,{once:true});worker.onmessage=event=>{const value=event.data;if(value?.version===1&&value.id===id&&value.byteLength===bytes.size&&value.error==='digest_worker_failed'){finish(fault('digest_worker_failed'));return;}if(!value||value.version!==1||value.id!==id||value.byteLength!==bytes.size||typeof value.sha256!=='string'||!(/^[a-f0-9]{64}$/.test(value.sha256)))finish(fault('invalid_digest_response'));else finish(undefined,value.sha256);};worker.onerror=event=>{event.preventDefault();finish(fault('digest_worker_failed'));};worker.onmessageerror=()=>finish(fault('invalid_digest_response'));
     // Blob 通过结构化克隆传递，不在 UI 主线程先读取整份 arrayBuffer。

src/lib/canvas-runtime/browser-images.ts

@@ -4,7 +4,9 @@
  */
 import {fault} from '../canvas-core/values.ts';
 import {createImageDecodePool,type ImageDimensions} from './image-decoder.ts';
-/** 返回 ImageDecoderPort；版本/id/字节数验证响应归属，尺寸合法性由 pool 再检查。 */
+/** 将每次 execute 转成专用 module Worker，请求 ID 在此 decoder 实例内递增。
+ * 外围池使用默认并发/排队预算；此适配按响应版本/id/输入长度核对归属，尺寸合法性由池检查。
+ * 没有超时；Worker 无响应时要由外部取消/close 才能终止，构造失败也不回退主线程解码。 */
 export function createBrowserImageDecoder(){let next=0;return createImageDecodePool({execute:(bytes,signal)=>new Promise<ImageDimensions>((resolve,reject)=>{
  if(typeof Worker==='undefined'){reject(fault('image_decoder_unavailable'));return;}
  // 每任务一个 Worker，取消只 terminate 自己，不会打断其它图片的解码。
@@ -12,6 +14,7 @@ export function createBrowserImageDecoder(){let next=0;return createImageDecodeP
  /** finish 幂等解除消息/错误/abort 监听并 terminate；abort 在监听安装后再检查一次覆盖竞态。 */
  const id=++next;let done=false;const finish=(error?:unknown,size?:ImageDimensions)=>{if(done)return;done=true;signal.removeEventListener('abort',abort);worker.onmessage=null;worker.onerror=null;worker.onmessageerror=null;worker.terminate();if(error)reject(error);else resolve(size!);},abort=()=>finish(fault('image_decode_aborted'));
  signal.addEventListener('abort',abort,{once:true});if(signal.aborted){abort();return;}
+ // Worker error 会 preventDefault 并转稳定错误，消息无法反序列化则拒绝；所有路径共用 finish 终止线程。
  // 只采纳精确匹配请求的成功尺寸或已知错误；未知错误码/错误协议作为 invalid response 拒绝。
  worker.onmessage=event=>{const value=event.data;if(!value||value.version!==1||value.id!==id||value.byteLength!==bytes.size){finish(fault('invalid_image_response'));return;}if(value.error){finish(fault(value.error==='image_decode_failed'?'image_decode_failed':'invalid_image_response'));return;}finish(undefined,{width:value.width,height:value.height});};worker.onerror=event=>{event.preventDefault();finish(fault('image_decode_failed'));};worker.onmessageerror=()=>finish(fault('invalid_image_response'));
  // 直接传不可变 Blob，不先在 UI 线程转成像素或整份 ArrayBuffer。

src/lib/canvas-runtime/change-rebase.ts

@@ -13,7 +13,10 @@ import { equal, fault, freeze, readMap } from '../canvas-core/values.ts';
 /** 原操作相关对象的前后记录及 owner 变换；用于区分用户意图与仅由坐标转换引起的差异。 */
 export type IntentContext = { readonly before:ReadonlyMap<Id,ElementRecord>; readonly after:ReadonlyMap<Id,ElementRecord>; readonly transforms:ReadonlyMap<Id,Transform>; readonly beforeTransforms:ReadonlyMap<Id,Transform> };
 /** Reconstruct only immutable intention metadata. This mutable cursor is never published as a document. */
-/** 从当前 working 反向遍历意图，重建每项的局部前后上下文；可变 cursor 永不作为业务文档发布。 */
+/** 从已包含这些意图效果的 working 逆序退回，重建局部前后记录及 owner 变换。
+ * 输入顺序就是应用顺序；函数不按 sequence 排序，也不验证当前文档确由这些意图产生。
+ * 这里只还原意图元数据，不按 before/after 条件执行撤销，不回退墓碑、不分配新代次或发布文档。
+ * 只读 Map 捕获表成员，记录值沿用不可变输入；不是任意外部对象的深克隆边界。 */
 export function intentContexts(document:Document,intents:readonly OperationIntent[]):ReadonlyMap<Id,IntentContext> {
   const elements=new Map(document.elements),canvases=new Map(document.canvases),contexts=new Map<Id,IntentContext>();
   const cursor={...document,elements,canvases};
@@ -27,7 +30,8 @@ export function intentContexts(document:Document,intents:readonly OperationInten
     }
     const after=new Map<Id,ElementRecord>();for(const id of ids){const record=elements.get(id);if(record){after.set(id,record);owners.add(record.ownerCanvasId);}}
     const transforms=new Map<Id,Transform>();for(const owner of owners)if(canvases.has(owner))transforms.set(owner,canvasTransform(cursor,owner));
-    // 私有 cursor 按原 before 逆向退回，不执行用户可见的 restore，也不因此分配新 incarnation。
+    // 直接把记录/字段写回原 before，不检查当前是否等于 after；field 缺对象/代次不符时跳过。
+    // cursor 中间树可不完整，随后仅在 owner 仍存在时取变换；无法解析的祖先链仍可能抛错。
     for(const change of [...intent.changes].reverse()){
       if(change.kind==='element'){if(change.before)elements.set(change.id,change.before);else elements.delete(change.id);}
       else if(change.kind==='canvas'){if(change.before)canvases.set(change.id,change.before);else canvases.delete(change.id);}
@@ -51,7 +55,9 @@ function sameConvertedPath(left:Json,right:Json):boolean {
   const point=(a:Json|undefined,b:Json|undefined)=>{if(a===undefined||b===undefined)return a===b;if(!a||!b||typeof a!=='object'||typeof b!=='object'||Array.isArray(a)||Array.isArray(b))return false;const{x:ax,y:ay,...restA}=a,{x:bx,y:by,...restB}=b;return typeof ax==='number'&&typeof ay==='number'&&typeof bx==='number'&&typeof by==='number'&&closeNumber(ax,bx)&&closeNumber(ay,by)&&equal(restA,restB);};
   return equal(ar,br)&&point(as,bs)&&point(ae,be)&&a.length===b.length&&a.every((value,index)=>{const other=b[index];if(!value||!other||typeof value!=='object'||typeof other!=='object'||Array.isArray(value)||Array.isArray(other))return false;const{position:p,in:i,out:o,...rest}=value,{position:q,in:j,out:k,...remaining}=other;return equal(rest,remaining)&&point(p,q)&&point(i,j)&&point(o,k);});
 }
-/** 只把原意图实际改过的 presentation 键应用到 current；unitScale 另走视觉单位换算。 */
+/** 以键的存在性和值比较找 presentation 顶层差异，再覆盖/删除 current 的对应键。
+ * 嵌套键值作为整体处理，不递归合并；unitScale 排除在本函数外，交几何分支做视觉单位换算。
+ * 无变化时沿用 current；有变化后若结果无键则返回 undefined，交调用方处理字段存在性。 */
 function presentationDelta(current:Json|undefined,before:Json|undefined,after:Json|undefined):Json|undefined {
   if(equal(before,after))return current;
   const start=presentationRecord(before),end=presentationRecord(after),keys=new Set([...Object.keys(start),...Object.keys(end)]);keys.delete('unitScale');
@@ -63,6 +69,7 @@ function presentationDelta(current:Json|undefined,before:Json|undefined,after:Js
  * 用户明确改变的中心/尺寸/旋转取其意图值，再转到 fresh destination；不是盲加一份旧 local patch。 */
 function movedNode(current:Extract<ElementRecord,{structure:'node'}>,originalBefore:Extract<ElementRecord,{structure:'node'}>,originalAfter:Extract<ElementRecord,{structure:'node'}>,beforeBasis:Transform,afterBasis:Transform,source:Transform,destination:Transform,intent:OperationIntent){
   const world:Transform={x:0,y:0,scale:1,rotation:0},start=convertGeometry(originalBefore.geometry,beforeBasis,world),end=convertGeometry(originalAfter.geometry,afterBasis,world),fresh=convertGeometry(current.geometry,source,world);
+  // 世界中心用于分别判断横/纵移动意图；未变化的维度取 fresh，修改维度取原意图终值，而非叠加 delta。
   const center=(g:typeof start)=>({x:g.x+g.width/2,y:g.y+g.height/2}),a=center(start),b=center(end),c=center(fresh),width=closeNumber(start.width,end.width)?fresh.width:end.width,height=closeNumber(start.height,end.height)?fresh.height:end.height;
   const x=closeNumber(a.x,b.x)?c.x:b.x,y=closeNumber(a.y,b.y)?c.y:b.y,rotation=Math.abs(((start.rotation-end.rotation+540)%360)-180)<1e-9?fresh.rotation:end.rotation;
   const geometry=convertGeometry({x:x-width/2,y:y-height/2,width,height,rotation},world,destination);
@@ -75,7 +82,9 @@ function movedNode(current:Extract<ElementRecord,{structure:'node'}>,originalBef
 }
 
 /** Restore batches may have inverse storage order (canvas before entry). Only reorder adjacent creates, never move across an edit/delete. */
-/** 只在连续创建段内按 parent/entry/owner/端点依赖拓扑排序，绝不跨编辑/删除重排。 */
+/** 只在连续创建段内按 parent/entry/owner/端点依赖拓扑排序，绝不跨编辑/删除重排。
+ * 仅段内依赖参与 Kahn 计数；段外依赖是否存在留给执行/最终校验。元素与 canvas 分命名空间。
+ * ready 按发现顺序排队，不保证每次都选择剩余项中原索引最小者；重 ID 或环直接拒绝。 */
 function orderedCreates(changes:readonly Change[]):readonly Change[]{
   const result:Change[]=[];
   /** before=null 且 after 存在才是创建，整记录替换不能冒充依赖排序候选。 */
@@ -101,17 +110,22 @@ function orderedCreates(changes:readonly Change[]):readonly Change[]{
   return result;
 }
 
-/** Re-plan against current data. Whole records are used only for explicit creation/removal. */
-/** 在 fresh 私有文档上重新生成条件 changes，原 intent/context 保持不变；最终完整校验才返回。 */
+/** Re-plan against current data; whole element replacement is unsupported. */
+/** 在 fresh 私有候选上重新生成条件 changes，保留当前未被用户意图修改的数据，最终整图校验才返回。
+ * 本函数不验证恢复选择/账本依赖，不发布 Root、不记录 history、不修改原冻结请求；这些由冲突协调器负责。
+ * 整元素仅支持显式增删，canvas 记录可重建 parent；普通字段的 before 从 fresh 实值重新生成。
+ * 输入应为已捕获的不可变模型/上下文，辅助 apply 的冻结不构成任意外部对象的深隔离保证。 */
 export function rebaseIntent(document:Document,intent:OperationIntent,context:IntentContext,registry:Registry):{document:Document;changes:readonly Change[]} {
   // moved 标记需整体世界空间重规划的节点；deferredPaths 等端点/树最终确定后再算曲线。
   const before=document,changes:Change[]=[],moved=new Set<Id>(),deferredPaths:FieldChange[]=[];
   for(const change of intent.changes)if(change.kind==='field'&&change.field==='ownerCanvasId'&&context.after.get(change.target.id)?.structure==='node')moved.add(change.target.id);
   /** 每条新变化立即作用于私有 candidate，后面的条件读取已重规划后的实际 before。 */
   function apply(change:Change){document=applyChanges(document,[change]);changes.push(freeze(change));}
-  /** 同 ID 还必须同 incarnation/结构/组件/版本且 registry 可解释，防止旧意图套到新对象上。 */
+  /** 目标必须存在、代次相同且 registry 已知；上下文含 prior 时再比较结构/组件/版本。
+   * 这是字段分支共用准入，具体能力检查在各分支；上下文缺 prior 不在这里补造类型依据。 */
   function target(change:FieldChange){const current=document.elements.get(change.target.id),prior=context.before.get(change.target.id)??context.after.get(change.target.id);if(!current||current.incarnation!==change.target.incarnation)throw fault('stale_incarnation',[change.target.id]);if(prior&&(current.componentId!==prior.componentId||current.dataVersion!==prior.dataVersion||current.structure!==prior.structure))throw fault('recovery_target_type_changed',[current.id]);if(registry.resolve(current)!=='known')throw fault('unsupported_component',[current.id]);return current;}
-  /** 端点必须仍为原上下文中的同代次节点；不能把恢复出来的新节点视为旧外部引用。 */
+  /** 当前端点须为 node，且与 context.after 中对象代次一致；无上下文也拒绝。
+   * 这里不单独比较端点的 componentId/dataVersion，图关系是否合法仍由最终校验判断。 */
   function endpoint(id:Id){const current=document.elements.get(id),expected=context.after.get(id);if(!current||current.structure!=='node'||!expected||current.incarnation!==expected.incarnation)throw fault('stale_endpoint',[id]);}
   // 按受限依赖顺序处理创建；删除/字段意图的原语义顺序仍保留。
   for(const original of orderedCreates(intent.changes)){
@@ -132,7 +146,8 @@ export function rebaseIntent(document:Document,intent:OperationIntent,context:In
           after={...after,ownerCanvasId:owner,path:convertPath(after.path,basis,canvasTransform(document,owner))};
         }
         apply({...original,after});
-      // 已经不存在的删除可满足；仍存在时按 fresh 拥有树规划移除，不能直接覆盖旧整记录。
+      // 删除目标已不存在时直接满足，不在此以墓碑证明它曾是哪一代；仍存在则要求旧代次和已知类型。
+      // 按 fresh 拥有树重新规划删除，可包含远端新增子内容/关联边，而不是照抄旧删除清单。
       }else if(original.before&&original.after===null){
         if(!current)continue;
         if(current.incarnation!==original.before.incarnation)throw fault('stale_incarnation',[original.id]);
@@ -210,7 +225,8 @@ export function rebaseIntent(document:Document,intent:OperationIntent,context:In
     if(edge.ownerCanvasId!==owner)apply({kind:'field',target:original.target,field:'ownerCanvasId',before:edge.ownerCanvasId,after:owner});
     if(!equal(edge.path,path))apply({...original,before:edge.path,after:path});
   }
-  // 所有端点/树变化结束后统一修复边 owner/path，再验证最终文档，避免暴露半份图。
+  // 使用初始 fresh 与最终候选修复受影响边的 owner/path，再做整图校验；空 changes 也要校验。
+  // 抛错不返回半成品，成功仍只是规划结果；是否采纳以及新的 operation/history 身份由调用方决定。
   for(const change of repairConnectionOwners(before,document))apply(change);
   validateDocument(document,registry);return{document,changes:freeze(changes)};
 }

src/lib/canvas-runtime/conflicts.ts

@@ -26,7 +26,8 @@ export type RecoveryChoice = 'keep-local' | 'discard-local';
 export type RecoveryDecision = { readonly operationId: Id; readonly choice: RecoveryChoice; readonly replacementId?: Id; readonly resolution: 'superseded' | 'discarded' | 'satisfied' };
 /** 恢复审计记录：绑定规划时的根 revision，保留备份及可用的历史重放证据。 */
 export type RecoveryAudit = { readonly id: Id; readonly formatVersion: 1; readonly baseRootRevision: number; readonly decisions: readonly RecoveryDecision[]; readonly backup: Json; readonly historyTransition?:HistoryTransition; readonly historyReplay?:HistoryReplay };
-/** 待一次性发布的候选根及引用资源；baseRootRevision 供提交方拒绝过时方案。 */
+/** 待采纳的文档/历史/操作/账本候选及审计，非完整 EngineSnapshot；引擎还需结合 canonical 版本等事实发布。
+ * baseRootRevision 用于拒绝过时方案，resourceIds 是本次已知保留集合，operationIds 只列新替代操作。 */
 export type ConflictPlan = { readonly id: Id; readonly baseRootRevision: number; readonly document: Document; readonly history: HistoryState; readonly operations: EngineSnapshot['operations']; readonly ledger: EngineSnapshot['runtime']['ledger']; readonly audit: RecoveryAudit; readonly resourceIds: readonly Id[]; readonly operationIds: readonly Id[] };
 /** 字段身份包括元素代次，避免把删除后重建的同 ID 元素算成同一字段历史。 */
 const fieldKey = (change: FieldChange) => JSON.stringify([change.target.id,change.target.incarnation,change.field]);
@@ -41,8 +42,11 @@ function value(document: Document, change: FieldChange, allowMissing=false): {be
 /** 把文档 Map 转成备份用的 JSON 形状；序列化的是数据，不是运行时方法或索引。 */
 const documentValue = (document: Document) => ({projectId:document.projectId,canvases:[...document.canvases.values()],elements:[...document.elements.values()],tombstones:[...document.tombstones]});
 
-/** 纯规划入口：先校验权威读取与回执已全部落定，再按操作顺序投影用户决策。
- * 不复用旧请求键/请求体；未知结果尚未确认时拒绝规划，防止重复执行已经生效的修改。 */
+/** 在不可变 snapshot 上规划恢复：先验 canonical 单调性/完整性，并要求 ledger 中请求 phase 全为 resolved。
+ * 不自己查询回执、认证来源或等待磁盘；canonical/账本已捕获且可信由 engine/端口负责。
+ * 取全部非 resolved 且非 asset.upload 意图，要求 choices 精确覆盖每项；依次重规划、重建 history、退休旧项并加入替代项。
+ * 不发布/持久化/提交请求；createId 可消耗外部编号，失败不会回滚该回调副作用。
+ * 小输入/模型按既有不可变合同使用，备份 JSON 编码与全部恢复规划同步完成，没有时间片/容量预算。 */
 export function planConflictRecovery(snapshot: EngineSnapshot, canonical: CanonicalProposal, choices: ReadonlyMap<Id,RecoveryChoice>, registry: Registry, createId:()=>Id,historyLimit=100): ConflictPlan {
   if(snapshot.runtime.loading)validateLoadingCompletion(snapshot.runtime.acknowledged,snapshot.runtime.versions,snapshot.runtime.loading,canonical.document,canonical.versions,registry,true);else validateCanonicalRead(snapshot.runtime.acknowledged,snapshot.runtime.versions,canonical.document,canonical.versions,registry);
   if([...snapshot.runtime.ledger.requests.values()].some(request=>request.phase!=='resolved'))throw fault('recovery_waiting_for_receipts');
@@ -59,7 +63,8 @@ export function planConflictRecovery(snapshot: EngineSnapshot, canonical: Canoni
   // 边界记录历史单元恢复前后的文档；starts 保存首次触及字段时的基线，供混合 ACK 历史核对。
   const boundaries=new Map<Id,{before:Document;after:Document}>(),starts=new Map<string,ReturnType<typeof value>>(),historyOwner=new Map<Id,Id>(),contexts=intentContexts(snapshot.document,records.map(record=>record.intent));
   for(const entry of snapshot.history.entries.values())for(const operationId of entry.operationIds){if(historyOwner.has(operationId))throw fault('recovery_history_ambiguous');historyOwner.set(operationId,entry.id);}
-  // 有历史转移证据或之前已采用重放的操作时，优先用日志恢复保持 undo/redo 的语义。
+  // 全部 content 有原生 transition、某个遍历有 transition，或命中已有 adoption 时，进入严格日志恢复。
+  // 这只是分支选择，不证明证据齐全/可回放；journal 构造和后续 project/accept 仍可拒绝不完整/矛盾记录。
   const adopted=new Set([...snapshot.runtime.recoveries.values()].filter(audit=>audit.historyReplay!==undefined).flatMap(audit=>audit.decisions.flatMap(decision=>decision.replacementId?[decision.replacementId]:[])));
   const content=records.filter(record=>record.intent.changes.length),hasEvidence=content.length>0&&content.every(record=>record.intent.historyTransition)||records.some(record=>['undo','redo'].includes(record.intent.origin)&&record.intent.historyTransition)||content.some(record=>adopted.has(record.intent.id));
   const journal=hasEvidence?createHistoryJournalRecovery(snapshot,records.map(record=>record.intent),registry,historyLimit):undefined;
@@ -78,7 +83,8 @@ export function planConflictRecovery(snapshot: EngineSnapshot, canonical: Canoni
     }
     // 用户新建 canvas 的身份若已被服务端占用，不能悄悄视为同一对象。
     if(choice==='keep-local'&&intent.origin==='user')for(const change of intent.changes)if(change.kind==='canvas'&&!change.before&&canonical.versions.has(change.id))throw fault('recovery_identity_collision',[change.id]);
-    // keep-local 在新基线上重新计算改动；discard-local 不施加该意图，日志仍记录该决定。
+    // 每项边界 before→after 反映此前全部审阅结果；keep 在该新候选上规划，discard 不施加原文档变化。
+    // journal.project 还可能先推进已有结算历史；没有 journal 时直接走 rebaseIntent，不能并行按同一旧基线处理。
     const rebased=journal?journal.project(document,intent,contexts.get(intent.id)!,choice==='keep-local'):choice==='keep-local'?rebaseIntent(document,intent,contexts.get(intent.id)!,registry):{document,changes:[]};
     const changes=rebased.changes;document=rebased.document;
     if(entryId)boundaries.get(entryId)!.after=document;
@@ -87,7 +93,8 @@ export function planConflictRecovery(snapshot: EngineSnapshot, canonical: Canoni
       // 生成启动、取消等动作需重新发起命令；冲突审阅不能顺手重新执行可能付费的任务。
       if(intent.operationType!=='document.change'&&intent.operationType!=='run.apply')throw fault('recovery_action_requires_new_command',[intent.id]);
       if(changes.length){
-        // 依赖替换为对应的新操作，丢弃或已满足的依赖不再排队；再串联此前所有替代操作。
+        // 原依赖若已审阅：改指对应 replacement，或在丢弃/已满足时移除；未审阅的既有依赖保留原 ID。
+        // 再依赖所有此前新 replacement，保证后项看到前项的串行效果；新 sequence 从账本最大值后递增。
         const dependencyIds=intent.dependencies.flatMap(dependency=>replacements.has(dependency)?replacements.get(dependency)?[replacements.get(dependency)!.id]:[]:[dependency]);
         // New dependencies reference new logical facts; a discarded parent never silently starts a paid run.
         const dependencySet=new Set(dependencyIds);
@@ -102,6 +109,7 @@ export function planConflictRecovery(snapshot: EngineSnapshot, canonical: Canoni
     }
     journal?.accept(intent,replacement,choice==='keep-local',before,document);
     replacements.set(intent.id,replacement);
+    // satisfied 只表示这次规划无需新 changes；不是在此收到另一份服务器 applied 回执。
     decisions.push(freeze({operationId:intent.id,choice,resolution:choice==='discard-local'?'discarded':replacement?'superseded':'satisfied',...(replacement?{replacementId:replacement.id}:{})}));
   }
   // 根据现有证据选日志重放、撤销/重做重规划或兼容历史重写，拒绝无法证明安全的路径。
@@ -113,20 +121,24 @@ export function planConflictRecovery(snapshot: EngineSnapshot, canonical: Canoni
     ledger.add(replacement,presence);
   }
   const historyReplay=journal?.evidence();
-  // Conservative pins include the archived document/history and unresolved opaque local resources.
+  // 已知资源保留集合：先纳入本地 resources 全部 ID，再补原/替代 changes 与历史 replay 中可解释引用。
+  // 不在此推断 opaque payload 的所有私有引用，也不把资源 ID 清单当作已保存 Blob 字节的证明。
   const resourceIds=new Set(snapshot.runtime.resources.keys());
   for(const record of records)for(const resource of referencedResources(record.intent.changes,registry))resourceIds.add(resource);
   for(const replacement of replacements.values())if(replacement)for(const resource of referencedResources(replacement.changes,registry))resourceIds.add(resource);
   if(historyReplay)for(const transition of [historyReplay.anchor,...historyReplay.events.map(event=>event.transition)])for(const resource of referencedResources(historyTransitionChanges(transition),registry))resourceIds.add(resource);
-  // 同时备份旧 working、ACK 基线和历史；资源 pin 保护恢复证据，防止审阅后被清理。
+  // backup 捕获旧 working/ACK/版本/history 和资源 ID；不嵌入 Blob、服务回执或完整 workspace 快照。
+  // 顶层 audit transition 描述旧→新历史，journal evidence 另解释内部事件；两者都须与恢复 Root 同次保存。
   const backup=JSON.parse(JSON.stringify({document:documentValue(snapshot.document),acknowledged:documentValue(snapshot.runtime.acknowledged),versions:[...snapshot.runtime.versions],resourceIds:[...resourceIds],history:{undo:snapshot.history.undo,redo:snapshot.history.redo,entries:[...snapshot.history.entries]}})) as Json;
   const historyTransition=describeHistoryTransition(snapshot.history,history,snapshot.rootRevision+1,undefined,!!historyReplay);
   const audit=freeze({id,formatVersion:1 as const,baseRootRevision:snapshot.rootRevision,decisions,backup,...(historyTransition?{historyTransition}:{}),...(historyReplay?{historyReplay}:{})});
   return Object.freeze({id,baseRootRevision:snapshot.rootRevision,document,history,operations:readMap(operations),ledger:ledger.getSnapshot(),audit,resourceIds:Object.freeze([...resourceIds]),operationIds:Object.freeze([...replacements.values()].flatMap(intent=>intent?[intent.id]:[]))});
 }
 
-/** 无完整日志证据时的兼容历史重写。仅支持能够证明前缀/字段基线的撤销栈项，
- * 不推测交错 ACK、结构变更或不支持的历史遍历；无法验证时抛错让整个规划保持未发布。 */
+/** 无 journal 的兼容分支，仅重写受本批 pending 影响的 undo 项，且其关联操作都必须是已知 user origin。
+ * 全项未决时直接用 replacements 拼回；混合已确认贡献时，结构项要求确认贡献为完整前缀，纯字段按身份键分别审阅。
+ * 不生成完整事件 replay，不重规划 redo 或任意交错遍历；不满足证据条件即拒绝本次方案，交外层保持未发布。
+ * 返回私有 entry 表/undo 候选，未影响 entry 与 redo 数组沿用不可变快照引用。 */
 function rewriteHistory(snapshot:EngineSnapshot,pending:readonly OperationIntent[],replacements:ReadonlyMap<Id,OperationIntent|undefined>,starts:ReadonlyMap<string,ReturnType<typeof value>>,boundaries:ReadonlyMap<Id,{before:Document;after:Document}>,registry:Registry):HistoryState {
   const entries=new Map(snapshot.history.entries),affected=new Set(pending.map(intent=>intent.id));
   for(const entry of snapshot.history.entries.values()){
@@ -155,7 +167,8 @@ function rewriteHistory(snapshot:EngineSnapshot,pending:readonly OperationIntent
       if(changes.length)entries.set(entry.id,freeze({...entry,changes,operationIds}));else entries.delete(entry.id);
       continue;
     }
-    // 纯字段混合历史按“目标代次 + 字段”分组；确认部分是否保留取决于恢复起点的值和存在性。
+    // 纯字段按 ID/代次/field 分组，先验证该字段历史尾部确为 oldPending，再分离已确认 prefix。
+    // starts 记录本次审阅首次触及该字段的 fresh 值/存在性；只在它仍等于旧 pending 的 before 时保留确认前缀。
     const keys=new Map<string,FieldChange>();for(const intent of intents)for(const change of intent.changes as readonly FieldChange[])keys.set(fieldKey(change),change);
     const fields:FieldChange[]=[];
     for(const [key,example]of keys){
@@ -169,6 +182,7 @@ function rewriteHistory(snapshot:EngineSnapshot,pending:readonly OperationIntent
       if(!start.missing&&equal(start.before,first.before)&&(start.beforePresent??true)===(first.beforePresent??true))fields.push(...prefix);
       fields.push(...intents.flatMap(intent=>replacements.get(intent.id)?.changes as readonly FieldChange[]??[]).filter(change=>fieldKey(change)===key));
     }
+    // 未触及字段保留；重建字段链追加到后面。此分支已排除 owner/端点等结构变化，不用该方式重排结构依赖。
     const changes:Change[]=[...entry.changes.filter(change=>change.kind!=='field'||!keys.has(fieldKey(change))),...fields];
     const operationIds=entry.operationIds.flatMap(operationId=>affected.has(operationId)?replacements.get(operationId)?[replacements.get(operationId)!.id]:[]:[operationId]);
     if(changes.length)entries.set(entry.id,freeze({...entry,changes,operationIds}));else entries.delete(entry.id);

src/lib/canvas-runtime/contracts.ts

@@ -12,7 +12,9 @@ import type { RunRecord } from './runs.ts';
 import type { ResourceRecord } from './resources.ts';
 import type { RecoveryAudit } from './conflicts.ts';
 
-/** 持久运行事实集合；view/selection/gesture 和渲染缓存不放入该结构。 */
+/** 与 core 文档/历史同 Root 发布的运行事实；view/selection/gesture 和渲染缓存不在此持久状态中。
+ * 这是类型合同，不执行输入校验/序列化或深冻结；Map/记录的实际捕获由 engine、codec 和生产模块负责。
+ * 内存 Root 的变化不等于磁盘 durable 切点，调度仍需存储确认与 durableGeneration/rootRevision 等屏障。 */
 export type RuntimeState = {
   /** 项目资源与共享 AssetDepot 的授权/身份绑定，非第二份图片字节。 */
   readonly assetBindings?:ReadonlyMap<Id,import('./asset-depot.ts').SharedAssetBinding>;
@@ -46,17 +48,25 @@ export type RuntimeState = {
 };
 /** core Snapshot 的 runtime 具象化，单次订阅可同时看到模型和对应运行事实。 */
 export type EngineSnapshot = Snapshot<RuntimeState>;
-/** 经过服务 codec 校验的文档与版本向量候选；只有协调完成后才能成为新基线。 */
+/** 服务 codec 提供的文档/版本候选，按合同应已校验；类型没有品牌或运行时校验，任意外部对象仍需边界验证。
+ * 不包含 history/ledger/Root revision，也不自动证明完整捕获或当前授权；协调完成后才可作为 ACK 基线。 */
 export type CanonicalProposal = { readonly document: Document; readonly versions: ReadonlyMap<Id, number> };
 /** Receiving records are read deltas, not a validated Document or an ACK base. */
-/** receiving 是尚未完成的读取增量，数量/owner 证据不表示整份 payload 已通过校验。 */
+/** receiving 为尚未完成的 delta：头部一次声明 canvas/墓碑/可选范围证据，后续按读取协议增加元素。
+ * received 可包括依赖未闭合、尚不能发布的元素；不是完整 Document、ACK 或可直接提交给 editor 的 working。
+ * CanonicalReadUpdate 不携带网络 query/token/sequence 的完整围栏，那些由外层 LoadChunk 绑定。 */
 export type CanonicalReadUpdate = CanonicalReadResult | { readonly status:'receiving'; readonly canvasElementCounts?:import('./scope-counts.ts').CanvasElementCounts;readonly elementOwners?:import('./scope-counts.ts').ElementOwners; readonly projectId:Id; readonly canvases:readonly CanvasRecord[]; readonly elements:readonly ElementRecord[]; readonly tombstones:ReadonlyMap<Id,number>; readonly versions:ReadonlyMap<Id,number>; readonly receivedElements:number; readonly totalElements:number };
 /** ready 提供新模型；migration-required 描述显式迁移资格，不在读取时偷偷执行迁移。 */
 export type CanonicalReadResult = ({ readonly status: 'ready';readonly sourceToken?:string } & CanonicalProposal) | { readonly status: 'migration-required'; readonly rootId: Id; readonly sourceVersions: ReadonlyMap<Id, number> };
 /** A validated historical execution receipt; its old model is never published over a fresh read. */
-/** 验证历史 applied 回执的执行证据；assertCanonical 比对 fresh read，不发布旧回执里的旧模型。 */
+/** 由请求解释器验证历史 applied 回执后构造：versions 表示该次写入下界，assertCanonical 检查 fresh 内容兼容。
+ * proof 不包含待发布旧模型，也不持久化函数；恢复时由原请求/回执重新解释，回调应纯且基于不可变证据。
+ * 证明服务执行不等于本地已协调/已保存，更不授权再提交相同变化。 */
 export type AppliedModelProof = { readonly versions:ReadonlyMap<Id,number>; assertCanonical(proposal:CanonicalProposal):void };
-/** 增量服务端口：compile/canonical 是纯编解码，submit/query/read 是可取消外部 I/O。 */
+/** 服务适配合同：compile/canonical/verifyApplied 等同步方法负责纯编解码/验证，异步方法负责外部 I/O。
+ * 引擎拥有本地发布/重放/持久化顺序；adapter 不应直接修改 snapshot、history 或 ledger。
+ * AbortSignal 只表达取消要求，不证明远端操作没生效；任何失败/超时都须按原 request 身份处理。
+ * 接口声明不会自动执行这些规则，具体实现和协调入口必须分别校验。 */
 export type PersistencePort = {
   /** Complete canonical read for a quiescent recovery session; never a legacy fallback. */
   /** 恢复协调所需的完整 canonical read；不能拿 legacy fallback 当目标协议基线。 */
@@ -65,7 +75,8 @@ export type PersistencePort = {
   verifyApplied?: (request:FrozenRequest,receipt:Json) => AppliedModelProof;
   /** 判断是否有原冻结协议解释器，不支持时保留原 body/key 并阻塞，不能重编码换身份。 */
   supportsRequest?: (request: FrozenRequest) => boolean;
-  /** 将稳定意图与当前基线编成待冻结请求；网络发送前仍需满足持久化屏障。 */
+  /** 从稳定 intent/requestId/当前快照计算参与范围、expected versions 与待冻结 payload，不执行网络写入。
+   * scheduler/ledger 随后冻结字节并过持久屏障；重试已经冻结的请求应复用原 body，不以最新快照重编。 */
   compile(intent: OperationIntent, requestId: Id, snapshot: EngineSnapshot): CompiledRequest;
   /** Compile an ordered mutable batch; logical IDs and original intents remain independent. */
   /** 可把有序未冻结意图合并为一份 wire 请求，原 logical IDs 与意图事实仍独立保留。 */
@@ -78,6 +89,7 @@ export type PersistencePort = {
   /** 可选精简回执 codec，仅在联合已协调发布时采用；失败应保留原恢复输入。 */
   compactResolvedReceipt?: (request:FrozenRequest,receipt:Json,applied:CanonicalProposal)=>Json;
   /** Pure codec, merging only participants into the latest base, never an old working snapshot. */
-  /** 将回执参与者合并进最新已确认基线，不能拿旧 working 快照替换新本地编辑。 */
+  /** 解释原请求/结果，对最新 acknowledged 合并参与者并返回提案，不能拿旧 working 覆盖本地新编辑。
+   * 不自行发布 ACK 或重放 pending；引擎还需校验候选与版本，重建 working 后统一发布。 */
   canonical(request: FrozenRequest, status: OperationStatus, snapshot: EngineSnapshot): CanonicalProposal;
 };

src/lib/canvas-runtime/copy-budget.ts

@@ -5,12 +5,15 @@
 import {fault} from '../canvas-core/values.ts';
 import {createImportBudget,type ImportScheduling} from './import-budget.ts';
 /** Share import scheduling while retaining the copy cancellation/error contract. */
-/** 验证copy预算后包装ImportBudget；调用者只有真正await返回Promise才会交出执行权。 */
+/** 复制任务的 ImportBudget 包装：构造与每次 step 都先检查取消，错误码使用 copy_aborted。
+ * 只预校验 frameBudgetMs；units/时钟/调度器沿用底层合同，单位可以是记录数或由调用方折算的字节工作量。
+ * 与同一个包装交互应顺序 await；没有独立计数器、持久进度或强制抢占能力。 */
 export function createCopyBudget(signal:AbortSignal,options:ImportScheduling={}){
  if(signal.aborted)throw fault('copy_aborted');
  if(options.frameBudgetMs!==undefined&&(!Number.isFinite(options.frameBudgetMs)||options.frameBudgetMs<=0))throw fault('invalid_copy_budget');
  const budget=createImportBudget(signal,options);
- /** signal已取消时将同步/异步预算失败统一为copy_aborted，其它错误原样抛给宿主。 */
+ /** 只在处理错误时 signal 已取消才改成 copy_aborted；其它错误保留原对象。
+  * 因此取消和宿主调度失败并发出现时，取消优先，不一定暴露原始调度错误。 */
  const fail=(error:unknown):never=>{if(signal.aborted)throw fault('copy_aborted');throw error;};
  /** 每次step先查copy取消，保持底层同步返回undefined或异步让出的原调度语义。 */
  return Object.freeze({step(units=1):Promise<void>|undefined{

src/lib/canvas-runtime/copy-snapshot-index.ts

@@ -2,6 +2,7 @@
  * 格式2的复制源：前段保存轻量topology和payload字节定位，后段保存原完整元素记录。
  * 准备阶段只扫描索引/结构；真正复制某记录前才按range读取和校验payload，支持边转换边加入。
  * 编码仍生成完整Blob，索引/定位仍占O(records)内存，不能据lazy解码宣称总内存常数。
+ * 打开索引不证明所有 payload 已读/哈希通过；字节完整性、权限和任务准入由外层负责。
  */
 import type {CanvasRecord,Document,ElementRecord,Id,Json,Registry,Data} from '../canvas-core/types.ts';
 import {createDocument,validateDocumentTopologySteps} from '../canvas-core/document.ts';
@@ -11,7 +12,8 @@ import {createCopyBudget} from './copy-budget.ts';
 import type {ImportScheduling} from './import-budget.ts';
 /** Only ownership, endpoint and geometry fields needed to decide scope/coordinates. No component content. */
 /** 保留ID/owner/端点/几何及contentScale/unitScale，清组件内容，边path置null用于范围/坐标规划。
- * 返回结构记录不能直接作为用户元素发布，也不证明组件payload符合schema。 */
+ * 返回结构记录不能直接作为用户元素发布，也不证明组件payload符合schema。
+ * 本函数只创建外壳：geometry/端点和保留的 presentation 值仍借用原引用，没有校验或深捕获。 */
 export function copyTopology(record:ElementRecord):ElementRecord{
   const raw=record.data.presentation,presentation=raw&&typeof raw==='object'&&!Array.isArray(raw)?Object.fromEntries(['contentScale','unitScale'].filter(key=>Object.hasOwn(raw,key)).map(key=>[key,raw[key]])):{};
   const data:Data=Object.keys(presentation).length?{presentation}:{};
@@ -19,7 +21,9 @@ export function copyTopology(record:ElementRecord):ElementRecord{
   return record.structure==='node'?{...common,structure:'node',geometry:record.geometry}:{...common,structure:'connection',source:record.source,target:record.target,path:null};
 }
 /** Format 2 places a compact topology/byte-locator index before the uninterpreted payload region. */
-/** 输出完整format2源：header/canvas/element-index/tombstone/payload标记，然后原元素NDJSON区域。 */
+/** 输出完整format2源：header/canvas/element-index/tombstone/payload标记，然后原元素NDJSON区域。
+ * 借用不可变 Document 合同，逐记录 await 后仍读取原表；没有在入口同步捕获整图或执行完整校验。
+ * index/payload 两个数组都留存到最终 Blob，预算只能在记录间让出，不能打断一次原生 stringify。 */
 export async function encodeIndexedCopySnapshot(document:Document,signal:AbortSignal,scheduling:ImportScheduling={}):Promise<Blob>{
   const index:BlobPart[]=[],payload:BlobPart[]=[];const budget=createCopyBudget(signal,scheduling);let indexBytes=0,payloadBytes=0;
   /** 单记录序列化、UTF8计长与256KiB上限，保持原始记录/索引locator成本可核验。 */
@@ -38,7 +42,9 @@ export async function encodeIndexedCopySnapshot(document:Document,signal:AbortSi
 /** document只含结构投影，readElement取得完整record；调用方必须明确使用topologyOnly规划模式。 */
 export type IndexedCopySnapshot={readonly document:Document;readElement(id:Id,signal:AbortSignal):Promise<ElementRecord>};
 /** Scan only the small index. Component JSON/schema checks occur just before each record enters the runner. */
-/** 只扫描前段索引，验证locator连续/总长/项目与结构，再返回有界窗口读取器。 */
+/** 只解析前段索引，验证locator连续/总长/项目与结构，再返回有界窗口读取器。
+ * NDJSON reader 可预读越过 payload 标记的原始字节，但打开时不会解析/验证每条完整元素内容。
+ * document 是独立捕获的结构文档，locators/窗口表留在闭包；对象冻结不替代 readElement 的后续校验。 */
 export async function openIndexedCopySnapshot(bytes:Blob,projectId:Id,registry:Registry,signal:AbortSignal,scheduling:ImportScheduling={}):Promise<IndexedCopySnapshot>{
   if(!(bytes instanceof Blob)||bytes.size>64*1024*1024)throw fault('invalid_import_source');
   const budget=createCopyBudget(signal,scheduling),source=createNdjsonImportSource({bytes,fingerprint:'indexed-copy-snapshot'}),canvases:CanvasRecord[]=[],elements:ElementRecord[]=[],tombstones=new Map<Id,number>(),locators=new Map<Id,{offset:number;byteLength:number}>();let cursor=0,header=false,payloadOffset=-1,expectedOffset=0;
@@ -62,17 +68,22 @@ export async function openIndexedCopySnapshot(bytes:Blob,projectId:Id,registry:R
   for(const _ of validateDocumentTopologySteps(document,registry))await budget.step();
   if(signal.aborted)throw fault('copy_aborted');
   // Cache raw byte windows, never decoded component objects. Preserve parser batching across Blob task boundaries.
-  // 缓存原始byte窗口而非解码对象，最多4窗口/1MiB，减少每记录Blob读取任务又限制常驻字节。
+  // 缓存原始 byte 窗口而非解码对象，表内最多4窗口/1MiB；命中不更新顺序，是插入/替换顺序淘汰。
+  // 上限只约束表内窗口，不包括 Blob、本次 raw、并发未完成的读取或解码结果；没有并发请求去重。
   const windows=new Map<number,Uint8Array>(),windowBytes=64*1024;let cachedBytes=0;
-  /** readElement按locator截取原payload，fatal UTF8/JSON、topology一致及已知schema全部通过才返回冻结record。 */
+  /** readElement按locator截取原payload，fatal UTF8/JSON、topology一致及已知schema全部通过才返回冻结record。
+   * 每次命中仍重新解码/JSON.parse/校验，不缓存组件对象；此路径没有独立合作预算或异步 schema 执行。
+   * AbortSignal 只在入口及实际 Blob 读取后检查，不会打断同步 parse/validate；失败不清空已缓存字节。 */
   return Object.freeze({document,async readElement(id:Id,signal:AbortSignal){
     if(signal.aborted)throw fault('copy_aborted');const locator=locators.get(id);if(!locator)throw fault('element_missing',[id]);
+    // 从 payload 相对的64KiB边界起读，跨窗大记录扩大本次窗口；不靠 JS 字符下标定位多字节文本。
     const start=Math.floor(locator.offset/windowBytes)*windowBytes,required=locator.offset+locator.byteLength-start;let window=windows.get(start);
     if(!window||window.byteLength<required){const raw=await bytes.slice(payloadOffset+start,Math.min(bytes.size,payloadOffset+start+Math.max(windowBytes,required))).arrayBuffer();if(signal.aborted)throw fault('copy_aborted');const previous=windows.get(start);if(previous)cachedBytes-=previous.byteLength;window=new Uint8Array(raw);windows.delete(start);windows.set(start,window);cachedBytes+=window.byteLength;while(windows.size>4||cachedBytes>1024*1024){const[key,value]=windows.entries().next().value!;windows.delete(key);cachedBytes-=value.byteLength;}}
     const raw=window.subarray(locator.offset-start,required);let value:{kind:string;record:ElementRecord};
     try{value=JSON.parse(new TextDecoder('utf-8',{fatal:true}).decode(raw));}catch{throw fault('invalid_copy_snapshot');}
     if(!value||value.kind!=='element'||!validJson(value.record)||!value.record.data||typeof value.record.data!=='object'||Array.isArray(value.record.data)||!equal(copyTopology(value.record),document.elements.get(id)))throw fault('invalid_copy_snapshot');
-    // 当前registry已知版本才执行其schema；后续复制转换还会要求对应copy解释器存在。
+    // 当前 registry 已知版本才执行其 schema；未知版本保留通用 JSON/拓扑，不等于已理解内容。
+    // readElement 不迁移版本、不执行复制解释器；这些要求由后续复制转换流程处理。
     const record=value.record,definition=registry.components.get(record.componentId);if(registry.resolve(record)==='known'&&(!definition||definition.structure!==record.structure||!definition.validate(record.data)))throw fault('invalid_component_data',[id]);
     return freeze(record);
   }});

src/lib/canvas-runtime/copy-snapshot.ts

@@ -1,6 +1,7 @@
 /**
  * 格式1的完整复制源快照与复制声明签名。源字节在任务准入前从一个不可变文档捕获，
  * 后续规划/重开不读取当前用户正在改的live文档；源SHA与持久字节由外层完整性流程绑定。
+ * 编码器借用传入 Document 并在 await 后继续迭代，其不可变性是调用合同，并非函数进入时同步复制全图。
  */
 import type { CanvasRecord, Document, ElementRecord, Registry } from '../canvas-core/types.ts';
 import { createDocument, validateDocumentSteps } from '../canvas-core/document.ts';
@@ -10,7 +11,9 @@ import { createNdjsonImportSource } from './imports.ts';
 import {createCopyBudget} from './copy-budget.ts';
 import type {ImportScheduling} from './import-budget.ts';
 /** Capture immutable source bytes before a preparation job is admitted. No mutable live getters. */
-/** 逐项编码header/canvas/element/tombstone为NDJSON，检查记录/总源上限并合作让出，最终返回完整Blob。 */
+/** 逐项编码header/canvas/element/tombstone为NDJSON，检查记录/总源上限并合作让出，最终返回完整Blob。
+ * 每条 stringify/UTF8 计长仍同步完成，按含换行字节数折算预算；parts 留存全源，不是向持久层流式写入。
+ * 这里不验证 Document；借入的 getter/toJSON 如有副作用或抛错，也没有回滚机制。 */
 export async function encodeCopySnapshot(document:Document,signal:AbortSignal,scheduling:ImportScheduling={}):Promise<Blob>{
   const budget=createCopyBudget(signal,scheduling),parts:BlobPart[]=[];let bytes=0;
   /** 生成一条记录并累计实际UTF8字节，单条≤256KiB、总源≤64MiB；不省略未知组件payload。 */
@@ -19,13 +22,16 @@ export async function encodeCopySnapshot(document:Document,signal:AbortSignal,sc
   for(const[kind,records]of [['canvas',document.canvases.values()],['element',document.elements.values()],['tombstone',document.tombstones.entries()]] as const)for(const record of records){const size=append({kind,record});await budget.step(Math.max(1,Math.ceil(size/1024)));}
   if(signal.aborted)throw fault('copy_aborted');return new Blob(parts,{type:'application/x-ndjson'});
 }
-/** 旧源完整解码，验证同project/header、墓碑唯一，重建并分片校验完整Document后才返回。 */
+/** 旧源完整解码，验证同project/header、墓碑唯一，重建并分片校验完整Document后才返回。
+ * 记录读到 EOF 后才发布返回值，途中数组/Map 仅是私有暂存；不向 editor 逐项提交。
+ * 记录读取上限沿用 NDJSON reader，此入口没有 format2 那样的 Blob 总长检查；可信持久源大小由外层负责。 */
 export async function decodeCopySnapshot(bytes:Blob,projectId:string,registry:Registry,signal:AbortSignal,scheduling:ImportScheduling={}):Promise<Document>{
   const budget=createCopyBudget(signal,scheduling),source=createNdjsonImportSource({bytes,fingerprint:'captured-copy-snapshot'}),canvases:CanvasRecord[]=[],elements:ElementRecord[]=[],tombstones=new Map<string,number>();let cursor=0,header=false;
   while(true){
     if(signal.aborted)throw fault('copy_aborted');const start=cursor,line=await source.read(cursor,signal);if(!line)break;cursor=line.nextCursor;
     const value=line.value as unknown as {kind:string;version?:number;projectId?:string;record:never};if(line.error||line.skip||!value)throw fault('invalid_copy_snapshot');
     if(!header){if(value.kind!=='header'||value.version!==1||value.projectId!==projectId)throw fault('invalid_copy_snapshot');header=true;continue;}
+    // 分派只检查行种类；canvas/element 的重复 ID、结构和 schema 留给后续工厂与完整文档检查。
     if(value.kind==='canvas')canvases.push(value.record);else if(value.kind==='element')elements.push(value.record);else if(value.kind==='tombstone'){const record=value.record as [string,number];if(!Array.isArray(record)||record.length!==2||tombstones.has(record[0]))throw fault('invalid_copy_snapshot');tombstones.set(record[0],record[1]);}else throw fault('invalid_copy_snapshot');
     await budget.step(Math.max(1,Math.ceil((cursor-start)/1024)));
   }
@@ -38,7 +44,10 @@ export async function decodeCopySnapshot(bytes:Blob,projectId:string,registry:Re
 }
 
 /** Copy declarations are a versioned input; never silently reinterpret a persisted preparation. */
-/** 仅对源涉及组件的数据版本/structure/copy声明生成稳定签名，防持久准备被新声明静默重解释。 */
+/** 仅对源涉及组件的数据版本/structure/copy声明生成签名，防持久准备被新声明静默重解释。
+ * Set 去重并排序 componentId，让元素遍历顺序不影响签名；缺失定义也明确编码为 missing。
+ * 结果是 JSON 文本而非加密摘要；copy 内部键序沿用定义，不覆盖 schema/handler 函数或整个 registry。
+ * 比较与拒绝发生在消费此签名的任务流程，本函数不锁定 registry 或校验源文档。 */
 export function copyRegistrySignature(document:Document,registry:Registry):string{
   const ids=new Set([...document.elements.values()].map(element=>element.componentId));
   return JSON.stringify([...ids].sort().map(id=>{const definition=registry.components.get(id);return definition?{id,dataVersion:definition.dataVersion,structure:definition.structure,copy:definition.copy??null}: {id,missing:true};}));

src/lib/canvas-runtime/default-image-size.ts

@@ -1,7 +1,7 @@
 /**
  * 为新建图片保留一次可恢复的自动默认尺寸授权。解码/服务元数据异步到达后，只有创建历史、
  * 目标身份/类型、资源引用及初始视觉尺寸仍有效时才允许调整；实际文档/历史改写走专用 planner。
- * 用户已提交的手动 resize 撤销授权，即使以后 undo 回到初始尺寸也不自动复活。
+ * 已判为用户 resize 的授权转为 revoked，正常后续 undo 不自动复活；本模块不负责执行异步 resize 或保存磁盘。
  */
 import type { Commit, CoreSnapshot, Id, Registry, Target } from '../canvas-core/types.ts';
 import { closeNumber, unitScale } from '../canvas-core/units.ts';
@@ -9,7 +9,9 @@ import { fault, freeze, readMap } from '../canvas-core/values.ts';
 import type { EngineSnapshot, RuntimeState } from './contracts.ts';
 import type { ResourceRecord } from './resources.ts';
 
-/** 目标代次/创建entry/组件版本和初始视觉尺寸共同限定授权，status/code 描述可恢复结果。 */
+/** 以目标代次/创建 entry/组件版本和 width,height÷unitScale 的初值限定一次自动尺寸授权。
+ * pending 等候元数据/调度，blocked 可由引擎显式重试，applied/revoked 不再由本检查器自动执行。
+ * 这些状态不等同上传状态或另一个 undo 单元，也不单独证明用户权限/创建历史仍可用。 */
 export type DefaultSizeGrant = {
   readonly target: Target; readonly entryId: Id; readonly componentId: string; readonly dataVersion: number;
   readonly initialSize: { readonly width: number; readonly height: number };
@@ -18,7 +20,9 @@ export type DefaultSizeGrant = {
 /** 每资源的版本化授权列表；图片副本可有多个目标，各 grant 独立判断。 */
 export type DefaultImageSizing = { readonly version: 1; readonly grants: readonly DefaultSizeGrant[] };
 
-/** 校验解释器、目标/entry/尺寸/状态，并禁止同一 ID+incarnation 的重复 grant。 */
+/** 只验 v1、目标/entry/组件版本、正有限初始尺寸、状态/code 与单资源内目标代次唯一性。
+ * 不查真实 document/history/resource，不证明所有 grant 有效，也不捕获/冻结输入或要求尺寸为整数。
+ * 未知版本报解释器不可用；保留未来 opaque sizing 的兼容策略由恢复边界处理，不在此按 v1 解释。 */
 export function validateDefaultImageSizing(value: unknown): asserts value is DefaultImageSizing {
   const state = value as DefaultImageSizing;
   if (!state || state.version !== 1) throw fault('default_size_interpreter_unavailable');
@@ -34,7 +38,10 @@ export function validateDefaultImageSizing(value: unknown): asserts value is Def
   }
 }
 
-/** 从当前创建提交与关联 history 捕获授权，只针对引用该 assetId 的已知且可 resize 节点。 */
+/** 从有本 commit 操作贡献的 history 项与 commit 创建变化，匹配当前同代次、同 assetId、已知且能 resize 的 node。
+ * 保存提交后 width/height÷unitScale，不取文件像素/世界坐标；此时尚不需要 stored 回执或解码尺寸。
+ * entry 按“含 commit 操作 ID”筛选，不逐项证明该 entry 的 changes 恰含该目标创建；调用方须提供真实创建提交。
+ * 替换 resource.sizing 为本次 grants（可为空），不合并旧 grant 或做重复校验；完整 grant 校验由发布/恢复边界负责。 */
 export function captureDefaultImageSizing(resource: ResourceRecord, next: CoreSnapshot, commit: Commit, registry: Registry): ResourceRecord {
   const grants: DefaultSizeGrant[] = [];
   for (const entry of next.history.entries.values()) {
@@ -54,10 +61,11 @@ export function captureDefaultImageSizing(resource: ResourceRecord, next: CoreSn
   return freeze({ ...resource, sizing: { version: 1, grants } });
 }
 
-/** Runs on every publication path. Revocation is durable and does not revive when
- * undo happens to return to the default geometry. Preview-only gestures do not publish.
- */
-/** 每条 Root 发布路径检查 pending/blocked grant；失效时持久标 revoked，未变化则复用 runtime。 */
+/** Return a revocation candidate from each publication path; the engine persists the Root. */
+/** 对 next 的 v1 pending/blocked 授权检查身份/类型/资源、创建项仍在 undo、归一化尺寸和新用户意图。
+ * 失效则返回带 revoked/code 的 copy-on-write runtime，不执行 resize/网络/磁盘；未变化复用 next.runtime。
+ * applied/revoked 输入直接保留，未来版本不解释；不独自阻止受信调用方手动改写这些状态，状态所有权由引擎管理。
+ * 不读取 registry/手势/解码结果，真正消费 grant 的资格与尺寸计划由引擎随后复核。 */
 export function prepareDefaultImageSizing(previous: EngineSnapshot, next: EngineSnapshot): RuntimeState {
   let resources = next.runtime.resources;
   for (const [id, resource] of resources) {
@@ -76,7 +84,9 @@ export function prepareDefaultImageSizing(previous: EngineSnapshot, next: Engine
         if (!closeNumber(element.geometry.width / units, grant.initialSize.width) || !closeNumber(element.geometry.height / units, grant.initialSize.height)) code = 'user_resized';
         // Detect committed resize-away-and-back transactions. Pure coordinate
         // conversions may alter geometry sizes and unitScale together.
-        // 已提交事务即使最终尺寸回原值，也检查用户 geometry changes；纯 owner/unit 转换例外。
+        // 在文档变化且 operations 数量增加时扫描新 user 意图，识别 resize-away-and-back；假设操作表按正常发布追加。
+        // 同一意图含 owner 字段或 unitScale 变化就整体按转换豁免此附加检查；不逐轴拆分任意混合转换/手动缩放。
+        // 净归一化尺寸已改变仍会在上方撤销；纯预览不发布 operations，因此不会因 pointermove 单独触发。
         if (!code && previous.document !== next.document && previous.operations.size !== next.operations.size) {
           for (const [operationId, intent] of next.operations) {
             if (previous.operations.has(operationId) || intent.origin !== 'user') continue;

src/lib/canvas-runtime/depot-cut.ts

@@ -12,11 +12,15 @@ import type {StorageLeader,StoragePort} from './storage-port.ts';
 import {resourceRetentionPins} from './resource-retention.ts';
 
 /** Derive one project's shared-byte manifest from the exact Root being persisted. */
-/** 生成已确认上传/跨项目 binding 的共享身份、所需字节与保留清单；无 depot 能力明确拒绝。 */
+/** 从指定不可变 snapshot 派生共享身份/字节写入项与 pins，缺少 assetDepot 端口则拒绝。
+ * 会异步读取 depot/本地文件；不提交存储事务、不重算摘要，也不在 await 后自行校验 leader/宿主身份。
+ * 返回可变描述数组而非冻结 Root；调用方须把清单与该 snapshot 同次提交，rootRevision 不另存于返回值。
+ * snapshot 和各输入缓存需遵循宿主捕获约定，尤其 adoptedFiles 用 revision 防止混入较晚的采纳。 */
 export async function prepareDepotCut(input:{snapshot:EngineSnapshot;registry:Registry;storage:StoragePort;leader:StorageLeader;authority:string;files:ReadonlyMap<string,Blob>;displays:ReadonlyMap<string,number>;temporary:ReadonlyMap<string,readonly string[]>;adoptedFiles?:ReadonlyMap<string,{readonly bytes:Blob;readonly rootRevision:number}>}):Promise<DepotCut>{
  const {snapshot,storage,leader,authority}=input,pins=resourceRetentionPins(snapshot,input.registry,input.displays,input.temporary),writes:DepotWrite[]=[];
  if(!storage.assetDepot)throw fault('asset_depot_unavailable');
- // 仅 stored+digest 的原图可进入共享身份；未上传文件仍留在项目本地文件仓库。
+ // 每个 stored+digest 资源都登记身份（包括已 purge 的项目记录），但只有仍保留的才尝试补字节。
+ // sharedAssetRef 校验并捕获元数据，随后要求资产 ID/长度对应本地记录；未上传资源不进入共享写入清单。
  for(const resource of snapshot.runtime.resources.values())if(resource.stored&&resource.digest){
   const ref=sharedAssetRef({version:1,authority,digest:resource.digest,asset:resource.stored});
   if(ref.asset.id!==resource.id||ref.asset.bytes!==resource.byteLength)throw fault('shared_asset_identity_conflict',[resource.id]);
@@ -25,6 +29,8 @@ export async function prepareDepotCut(input:{snapshot:EngineSnapshot;registry:Re
   if(resource.retirement?.purgedAt===undefined&&pins.pins.has(resource.id)){
    const cached=await storage.assetDepot.read(leader,authority,resource.id);
    // The store enforces immutable identity even when bytes are already present.
+   // 缓存已有字节则只提交身份；否则优先项目内存文件，再读项目存储。
+   // 两处均无字节时仍可形成仅身份写入项；是否满足事务要求、摘要与不可变身份由 adapter 检查。
    if(!cached?.bytes)bytes=input.files.get(resource.id)??await storage.readFile(leader,resource.id);
   }
   writes.push({ref,...(bytes?{bytes}:{})});
@@ -34,9 +40,11 @@ export async function prepareDepotCut(input:{snapshot:EngineSnapshot;registry:Re
   if(binding.authority!==authority||binding.asset.id!==id||snapshot.runtime.resources.has(id))throw fault('shared_asset_identity_conflict',[id]);
   const pending=input.adoptedFiles?.get(id),bytes=pending&&pending.rootRevision<=snapshot.rootRevision?pending.bytes:undefined;writes.push({ref:sharedAssetRef(binding),...(bytes?{bytes}:{})});
  }
+ // binding 不以 pins 决定是否写入，只有其暂存 bytes 的采纳 revision 不晚于本 Root 才携带字节。
  // A source/run envelope may refer to resources outside this project's upload table.
  // Its complete resource interpreter must be installed before global deletion is allowed.
  // 引用、加载与任务解释都完整才允许全局回收；opaque run/未完导入不能假定无共享资源引用。
  const complete=pins.complete&&!snapshot.runtime.loading&&![...(snapshot.runtime.imports?.values()??[])].some(job=>!['completed','partial','cancelled'].includes(job.status))&&snapshot.runtime.runs.size===0;
+ // complete 是共享仓库全局删除所需的覆盖声明，不是字节写入完成回执；真正删除由仓库协议决定。
  return{version:1,authority,complete,pins:[...pins.pins].map(([id,owners])=>[id,[...owners]] as const),writes};
 }

src/lib/canvas-runtime/digest-pool.ts

@@ -8,7 +8,9 @@ import {importSourceDigest} from './import-integrity.ts';
 /** 可替换摘要端口，输出完整 Blob 的小写 SHA256；close 终止本池，不清业务数据或外部回执。 */
 export type DigestPort={digest(bytes:Blob,signal?:AbortSignal):Promise<string>;close():void};
 /** Read-only compute scheduling: bounded active slots + FIFO Map, never durable operation facts. */
-/** 默认2并发/64等待，上限8并发；可注入 Worker/native/测试执行器，默认使用分块摘要。 */
+/** 默认 2 并发/64 等待，上限 8 并发；可注入 execute，默认 importSourceDigest 分块计算。
+ * maxQueued 只计算 waiting，不含 active；不限制 Blob 大小/MIME，不做相同文件去重或结果缓存。
+ * execute 负责计算真实完整摘要，池仅用正则检查输出格式，不能证明输出确实对应输入字节。 */
 export function createDigestPool(options:{execute?:(bytes:Blob,signal:AbortSignal)=>Promise<string>;concurrency?:number;maxQueued?:number}={}):DigestPort{
   const concurrency=options.concurrency??2,maxQueued=options.maxQueued??64,execute=options.execute??importSourceDigest;
   if(!Number.isSafeInteger(concurrency)||concurrency<1||concurrency>8||!Number.isSafeInteger(maxQueued)||maxQueued<1)throw fault('invalid_digest_budget');
@@ -16,9 +18,13 @@ export function createDigestPool(options:{execute?:(bytes:Blob,signal:AbortSigna
   type Task={id:number;bytes:Blob;controller:AbortController;resolve:(value:string)=>void;reject:(error:unknown)=>void;cleanup:()=>void;done:boolean};
   // Map 既保留入队次序，又可在等待期取消时 O(1) 删除；active 保留真实未结束执行的容量占用。
   const waiting=new Map<number,Task>(),active=new Map<number,Task>();let next=0,closed=false;
-  /** 只 settle 一次并移除等待项/监听；故意不在这里 active.delete，迟到结果不能二次采纳。 */
+  /** 只 settle 一次并移除 waiting/外部监听，不在这里 active.delete，迟到结果不能二次采纳。
+   * error 用真值分支，execute 应以 Error 等真值拒绝；falsy rejection 不保证被当成失败处理。 */
   function finish(task:Task,error?:unknown,value?:string){if(task.done)return;task.done=true;task.cleanup();waiting.delete(task.id);if(error)task.reject(error);else task.resolve(value!);}
-  /** 有空槽就取最早等待项，先登记 active 再微任务执行；结果校验/取消后 finally 归还真实槽。 */
+  /** 从 Map 首项 FIFO 取任务，先占 active 再微任务调用 execute；启动前、结果返回后均复查 abort。
+   * execute 的拒绝由第二个 then 回调处理，结果校验抛错再由 catch 处理，最终统一归还槽位并泵下一项。
+   * 正则会按 JS 规则强制转字符串，未另做 typeof 检查；注入执行器应遵守 Promise<string> 合同。
+   * 无视 abort 且不 settle 的执行器会一直占槽；池没有超时或强制终止通用执行器的能力。 */
   function pump(){
     if(closed)return;
     while(active.size<concurrency&&waiting.size){const task=waiting.values().next().value!;waiting.delete(task.id);active.set(task.id,task);
@@ -31,7 +37,8 @@ export function createDigestPool(options:{execute?:(bytes:Blob,signal:AbortSigna
       if(closed)return Promise.reject(fault('digest_pool_closed'));if(signal?.aborted)return Promise.reject(fault('import_aborted'));if(!(bytes instanceof Blob))return Promise.reject(fault('invalid_digest_input'));if(active.size>=concurrency&&waiting.size>=maxQueued)return Promise.reject(fault('digest_capacity'));
       return new Promise((resolve,reject)=>{const task:Task={id:++next,bytes,controller:new AbortController(),resolve,reject,cleanup:()=>signal?.removeEventListener('abort',abort),done:false},abort=()=>{task.controller.abort();finish(task,fault('import_aborted'));pump();};signal?.addEventListener('abort',abort,{once:true});waiting.set(task.id,task);pump();});
     },
-    /** 幂等关闭，取消等待/活跃任务的调用结果；无视 signal 的执行仍由其 Promise 收尾后释放 active。 */
+    /** 幂等关闭并取消 waiting/active 的调用结果，停止接受新任务；不返回 drain Promise。
+     * 无视 signal 的执行仍由自身 Promise 收尾后释放 active，close 返回不证明底层计算已停止。 */
     close(){if(closed)return;closed=true;for(const task of [...waiting.values(),...active.values()]){task.controller.abort();finish(task,fault('import_aborted'));}},
   });
 }

src/lib/canvas-runtime/digest-worker-source.ts

@@ -11,7 +11,10 @@ export const nativeDigestByteLimit=64*1024*1024;
 
 /** Dedicated Worker only: whole-buffer native hashing never moves onto the UI thread.
  * The host still owns cancellation by terminating the request's Worker. */
-/** 验证 Blob，按能力/大小选 native 或增量实现，均返回相同的完整原字节摘要。 */
+/** 验证 Blob，SubtleCrypto 存在且大小 ≤64MiB 时读取整个 ArrayBuffer 做 SHA-256，否则流式计算。
+ * 原生读/算失败直接传播，不自动切到流式重试；注入 subtle 应遵守原生 digest 的 ArrayBuffer 合同。
+ * 本函数无 signal，取消靠宿主终止 Worker；代码本身不检测当前线程，Worker 限制由装配调用方遵守。
+ * 阈值只限制此输入的整缓冲分配，未计 Blob/原生算法内部内存及其它并发 Worker。 */
 export async function digestWorkerSource(bytes:Blob,subtle:Pick<SubtleCrypto,'digest'>|null|undefined=globalThis.crypto?.subtle):Promise<string>{
  if(!(bytes instanceof Blob))throw fault('invalid_digest_input');
  // native digest 必须返回32字节；输出固定64字符十六进制，不接受变长响应。
@@ -20,6 +23,7 @@ export async function digestWorkerSource(bytes:Blob,subtle:Pick<SubtleCrypto,'di
   if(digest.byteLength!==32)throw fault('invalid_digest_response');
   return [...new Uint8Array(digest)].map(value=>value.toString(16).padStart(2,'0')).join('');
  }
- // Worker fallback 每块1MiB，只做微任务让出；UI 让出策略由 UI fallback 的端口另行决定。
+ // 每块 1MiB，块间 yieldTask 仅完成一个 Promise 微任务，不保证 Worker 消息队列获得宏任务机会。
+ // UI fallback 用 importSourceDigest 默认定时器让出；不要把这里的微任务策略移作 UI 响应性承诺。
  return importSourceDigest(bytes,undefined,{chunkBytes:1024*1024,yieldTask:()=>Promise.resolve()});
 }

src/lib/canvas-runtime/digest.worker.ts

@@ -8,7 +8,9 @@ import {digestWorkerSource} from './digest-worker-source.ts';
 const scope=globalThis as unknown as {onmessage:((event:MessageEvent)=>void)|null;postMessage(value:unknown):void};
 /** 首条有效请求被接受后保持 true，直到整个 Worker 被宿主终止。 */
 let accepted=false;
-/** 校验协议和请求后启动只读摘要；成功/失败都回显输入 ID 与字节数，供宿主核对。 */
+/** 首条有效 version=1/正安全整数 ID/Blob 设置 accepted，之后包括失败后的重复消息都忽略。
+ * 无效请求直接忽略，不返回错误；这里不检查 MIME/大小或资源身份，不拥有持久任务。
+ * 算法拒绝会尝试回稳定错误；成功回信自身抛错不由同一个 then 的失败回调捕获，宿主仍需错误/取消收尾。 */
 scope.onmessage=event=>{
   const request=event.data;if(accepted||!request||request.version!==1||!Number.isSafeInteger(request.id)||request.id<1||!(request.bytes instanceof Blob))return;accepted=true;
   void digestWorkerSource(request.bytes).then(sha256=>scope.postMessage({version:1,id:request.id,byteLength:request.bytes.size,sha256}),()=>scope.postMessage({version:1,id:request.id,byteLength:request.bytes.size,error:'digest_worker_failed'}));

src/lib/canvas-runtime/display-cache.ts

@@ -16,12 +16,15 @@ type Entry = { readonly key: string; readonly owner: object; readonly controller
  * durable bytes before acquiring. Scope objects are never serialized or reused
  * across project engines/auth epochs. There is no idle URL retention.
  */
-/** 创建纯显示生命周期容器；owner 应绑定 engine/auth epoch，不能序列化或跨账号复用。 */
+/** 创建纯显示生命周期容器，owners 两层 Map 用对象身份+字符串 key 索引共享条目。
+ * owner 应绑定 engine/auth epoch；本模块不解释账号、资源 ID、URL 权限或实际文件 pin。
+ * 没有容量上限/空闲保留，最后 lease 释放即清理；永久撤销 owner 则另记到 WeakSet。 */
 export function createDisplayCache(options: { onError?: (error: unknown) => void } = {}) {
   // owners 仅保留活条目；retired WeakSet 禁止退役 owner 再 acquire，但不强持有其内存。
   const owners = new Map<object, Map<string, Entry>>(), retired = new WeakSet<object>();
   let closed = false;
-  /** 统一调用来源 release 并隔离错误，清理/日志失败不阻止释放其它 URL。 */
+  /** 同步调用来源 release，隔离其抛错和 onError 的抛错；onError 只报告清理失败。
+   * load 的失败通过各 lease.ready 传出，不在这里自动记录或重试；release 合同也不是异步清理任务。 */
   function dispose(source: DisplaySource) { try { source.release?.(); } catch (error) { try { options.onError?.(error); } catch { /* Reporting cannot interrupt cleanup. */ } } }
   /** 幂等退休共享条目，仅删除仍指向自己的表项，避免旧任务删掉同 key 的新 entry。 */
   function retire(entry: Entry) {
@@ -41,7 +44,9 @@ export function createDisplayCache(options: { onError?: (error: unknown) => void
     }
   }
   return Object.freeze({
-    /** 借用显示来源：同 owner/key 合并加载，但每个调用者可独立取消自己的等待。 */
+    /** 同 owner/key 复用进行中或已加载来源，命中时忽略本次传入的 load，不逐次重验权限。
+     * 每个调用者独立 ready/release；释放已兑现的 ready 不会改变 Promise 的成功结果，但 URL 可能随最后释放失效。
+     * 不自动接收 AbortSignal，取消通过 lease.release；单个释放不取消仍有其它消费者的共享加载。 */
     acquire(owner: object, key: string, load: (signal: AbortSignal) => Promise<DisplaySource>): DisplayLease {
       if (closed || retired.has(owner)) throw fault('display_scope_closed');
       if (!owner || typeof owner !== 'object' || typeof key !== 'string' || !key) throw fault('invalid_display_key');
@@ -55,6 +60,7 @@ export function createDisplayCache(options: { onError?: (error: unknown) => void
           if (created.retired) throw fault('display_released');
           return load(created.controller.signal);
         }).then(source => {
+          // 这里只检查 URL 为非空字符串及可选 release 为函数，不验证 URL 协议/可访问性或图片内容。
           if (!source || typeof source.url !== 'string' || !source.url || source.release !== undefined && typeof source.release !== 'function') { if (typeof source?.release === 'function') dispose(source); throw fault('invalid_display_source'); }
           // 即使 load 不响应 abort，迟到返回也只能 dispose，不允许挂回已无消费者的缓存。
           if (created.retired || !created.leases.size) { dispose(source); throw fault('display_released'); }
@@ -70,7 +76,8 @@ export function createDisplayCache(options: { onError?: (error: unknown) => void
         if (!shared.leases.size) retire(shared);
       };
       shared.leases.add(release);
-      // 将共享 promise 映射成每租约的独立 ready；来源失败时本租约也自动归还，不泄漏计数。
+      // 映射共享 promise 到各 lease.ready，失败逐个归还；校验 source 时抛错也沿这条失败路径清理。
+      // 缓存不吞 ready 的拒绝，消费者需接住取消/加载错误；释放后迟到成功不能再次 resolve 本租约。
       const ready = new Promise<string>((resolve, reject) => {
         rejectReady = reject;
         shared.promise.then(source => { if (!released) resolve(source.url); }, error => { if (!released) { reject(error); release(); } });

src/lib/canvas-runtime/duplicate-source.ts

@@ -13,7 +13,10 @@ import { duplicateImportLine } from './import-duplicate.ts';
 import type { ImportSource } from './imports.ts';
 
 /** A seekable record cursor over the original SHA-bound snapshot, not a second mapped Blob. */
-/** 要求未输出的emit起点、当前registry签名及有效绑定，ID工厂在恢复重校验中禁止意外再分配。 */
+/** 要求 emit 起点/零输出计数与当前 registry 签名，调用 planner 复核 checkpoint 结构绑定且禁止再分配 ID。
+ * 映射复制为私有 Map，但 document/registry/state 及 readElement 仍沿用调用方引用，须保持不可变/稳定。
+ * sourceToken/fingerprint 的真实字节绑定由上层验证；本函数不读取文件或重新计算 SHA。
+ * 构造后可按 ordinal 任意重读，read 不推进 state.emitted；持久进度由 runner 的 job.cursor 保存。 */
 export function createDuplicatePlanSource(document:Document,registry:Registry,state:DuplicateCheckpoint,fingerprint:string,readElement?:(id:Id,signal:AbortSignal)=>Promise<ElementRecord>):ImportSource{
   if(state.phase!=='emit'||state.emitted!==0||state.emittedEdges!==0||state.schemaToken!==copyRegistrySignature(document,registry))throw fault('copy_interpreter_changed');
   // Structural/source binding checks; the decoded source has already passed document validation.
@@ -22,7 +25,9 @@ export function createDuplicatePlanSource(document:Document,registry:Registry,st
   const elements=new Map(state.elementIds),canvases=new Map(state.canvasIds),copiedCanvases=new Set(state.canvases),keys=new Map<Id,string>(),reverseElements=new Map(state.elementIds.map(([id,mapped])=>[mapped,id])),reverseCanvases=new Map(state.canvasIds.map(([id,mapped])=>[mapped,id]));
   for(const[id,mapped]of elements)keys.set(mapped,`element:${id}`);for(const[id,mapped]of canvases)keys.set(mapped,`canvas:${id}`);
   // Edge geometry needs mapped endpoint/owner records. Compute these on demand; retain a bounded cache.
-  /** 给边计算提供新端点/owner视图，get按需转换并只保留32条缓存，不批量生成所有副本对象。 */
+  /** 给边计算提供原表+映射表的只读投影，get 按需转换映射 ID，每个投影最多缓存 32 项。
+   * 淘汰按插入顺序，缓存命中不刷新顺序，因此是 FIFO 而非 LRU；不缓存 readElement 的完整 payload。
+   * size/迭代将两组成员拼接，依赖映射不与原 ID 碰撞的 planner 合同，不能当可发布的规范文档表。 */
   function projection<T extends ElementRecord|CanvasRecord>(base:ReadonlyMap<Id,T>,reverse:ReadonlyMap<Id,Id>,kind:'element'|'canvas'):ReadonlyMap<Id,T>{
     // 未映射ID沿用原表，新ID转换源记录；缓存淘汰只影响计算成本，不改变稳定映射/源数据。
     const cache=new Map<Id,T>();const get=(id:Id):T|undefined=>{const old=reverse.get(id);if(!old)return base.get(id);const found=cache.get(id);if(found)return found;const original=base.get(old);if(!original)throw fault('invalid_copy_stream_checkpoint');const record=duplicateTreeChange(document,registry,kind,original,elements,canvases,copiedCanvases,state.offset).after as T;cache.set(id,record);if(cache.size>32)cache.delete(cache.keys().next().value!);return record;};
@@ -32,7 +37,11 @@ export function createDuplicatePlanSource(document:Document,registry:Registry,st
   }
   // projected只服务边端点和公共owner的坐标计算；length是tree order+edges的固定ordinal总数。
   const projected:Document={...document,elements:projection(document.elements,reverseElements,'element'),canvases:projection(document.canvases,reverseCanvases,'canvas')},length=state.order.length+state.edges.length;
-  /** read按ordinal选择共享tree/edge转换器；单记录错误返回error，源指纹/完整性与调度另由宿主约束。 */
+  /** 前 state.order.length 项用树转换器，其余用边转换器，生成同一预映射 CopyLine。
+   * readElement 可按需异步加载元素；其身份/源一致性由注入端口保证，canvas 直接从已捕获文档取。
+   * 预先取消/非法 ordinal 在 try 外拒绝；try 内失败（含读取后取消）转成 ImportLine.error，runner 必须复查信号。
+   * 成功检查单行 JSON 的 UTF-8 长度 ≤256KiB（不含 NDJSON 换行），不限制完整输出总字节或在单条内让出。
+   * 失败不会推进此源的全局游标；是否保留失败、跳过或停止由 runner 管理。 */
   return Object.freeze({fingerprint,parserVersion:2,async read(cursor:number,signal:AbortSignal){
     if(signal.aborted)throw fault('import_aborted');if(!Number.isSafeInteger(cursor)||cursor<0||cursor>length)throw fault('invalid_import_cursor');if(cursor===length)return null;
     const task=state.order[cursor],key=task?`${task.kind}:${task.id}`:`element:${state.edges[cursor-state.order.length]}`;

src/lib/canvas-runtime/duplicate.ts

@@ -23,7 +23,10 @@ export type DuplicateScheduling = {
  * No document publication or network effects. The caller must persist source/mapping and
  * revalidate external identities before applying a plan; this is not the import executor.
  */
-/** 分片消费完整plan迭代器，每片默认6ms/512步；返回前全部记录已生成并校验，但不执行导入。 */
+/** 分片消费完整 plan 生成器，默认每片 6ms/512 个语义步，完成后返回全量计划而非逐条发布。
+ * checkpoint 仅接收累计步数，不含映射/生成器状态，不能用该数字恢复规划；最终返回前不保证再调用一次。
+ * 每次 next 本身可包含同步固定成本，软预算不能抢占它；now/yieldTask 决定实际调度，默认 timer 让出。
+ * 异常/取消关闭生成器，不回滚已调用 createId 或 checkpoint 的外部副作用；调用方负责可靠源/映射保存。 */
 export async function planDuplicateAsync(document: Document, registry: Registry, selection: readonly Target[], options: DuplicateOptions, scheduling: DuplicateScheduling = {}): Promise<DuplicatePlan> {
   const budget = scheduling.frameBudgetMs ?? 6, limit = scheduling.maxStepsPerSlice ?? 512;
   if (!Number.isFinite(budget) || budget <= 0 || !Number.isSafeInteger(limit) || limit < 1) throw fault('invalid_copy_budget');
@@ -58,7 +61,11 @@ export async function planDuplicateAsync(document: Document, registry: Registry,
 }
 
 /** Resume semantic planning cursors. Source/output validation and derived output caches are rebuilt. */
-/** 以完整checkpoint恢复语义游标，仍重做源验证/派生输出缓存，不声称从任意字节零重算。 */
+/** 从完整 DuplicateCheckpoint 恢复语义游标/已分配 ID，源验证和派生输出缓存仍由 planner 重建。
+ * 每个未完成时间片可将不可变 checkpoint 交宿主 await；回调成功只代表宿主 Promise 成功，不独自证明落盘。
+ * planner.step 完成后直接 result，不额外回调最终状态；需要最终可靠切点时由调用方保存返回计划/状态。
+ * selection/偏移/映射在入口捕获，document/registry 沿不可变快照合同使用；调度选项应保持稳定。
+ * 与完整生成器入口一样，不发布业务文档、不补偿已分配 ID 或宿主 checkpoint 副作用。 */
 export async function planDuplicateResumable(document:Document,registry:Registry,selection:readonly Target[],options:DuplicateOptions,binding:{sourceToken:string;schemaToken:string;checkpoint?:DuplicateCheckpoint},scheduling:Omit<DuplicateScheduling,'checkpoint'>&{checkpoint?:(state:DuplicateCheckpoint)=>Promise<void>}={}):Promise<DuplicatePlan>{
   const budget=scheduling.frameBudgetMs??6,limit=scheduling.maxStepsPerSlice??512,now=scheduling.now??(()=>performance.now()),yieldTask=scheduling.yieldTask??(()=>new Promise<void>(resolve=>setTimeout(resolve,0)));
   if(!Number.isFinite(budget)||budget<=0||!Number.isSafeInteger(limit)||limit<1)throw fault('invalid_copy_budget');
@@ -73,7 +80,12 @@ export async function planDuplicateResumable(document:Document,registry:Registry
 
 
 /** Stop before record conversion: the stable order/mappings are sufficient for seekable lazy output. */
-/** 只推进到emit起点：范围/顺序/全部新ID已固定，但尚未转换全部payload，可交lazy source逐条输出。 */
+/** 仅推进至 ready/emit 起点，返回顺序/映射已固定的 checkpoint；尚未完成所有 payload 转换与输出校验。
+ * planner 捕获小输入与私有语义 state；此层只调度 step/checkpoint，不用另一个 live 文档替换源。
+ * checkpointIntervalMs=0 默认每个未完成切片保存；>0 时按阶段/首次分配/时间/步数门槛节奏化保存。
+ * 阈值只在切片末检查，maxStepsPerCheckpoint 可能多跨一片；不是逐语义步的硬持久间隔。
+ * ready 时只有 interval>0 且有回调才补一次保存；默认路径可直接返回，宿主仍须持久化返回状态。
+ * topologyOnly 仅选择源拓扑检查，不证明全部组件 payload 可复制；懒源逐条转换时仍可报记录失败。 */
 export async function prepareDuplicateStream(document:Document,registry:Registry,selection:readonly Target[],options:DuplicateOptions,binding:{sourceToken:string;schemaToken:string;checkpoint?:DuplicateCheckpoint;topologyOnly?:boolean},scheduling:Omit<DuplicateScheduling,'checkpoint'>&{checkpoint?:(state:DuplicateCheckpoint)=>Promise<void>;checkpointIntervalMs?:number;maxStepsPerCheckpoint?:number}={}):Promise<DuplicateCheckpoint>{
   const budget=scheduling.frameBudgetMs??6,limit=scheduling.maxStepsPerSlice??512,now=scheduling.now??(()=>performance.now()),yieldTask=scheduling.yieldTask??(()=>new Promise<void>(resolve=>setTimeout(resolve,0)));
   if(!Number.isFinite(budget)||budget<=0||!Number.isSafeInteger(limit)||limit<1)throw fault('invalid_copy_budget');
@@ -82,7 +94,8 @@ export async function prepareDuplicateStream(document:Document,registry:Registry
   const interval=scheduling.checkpointIntervalMs??0,maxCheckpointSteps=scheduling.maxStepsPerCheckpoint??8192;
   if(!Number.isFinite(interval)||interval<0||!Number.isSafeInteger(maxCheckpointSteps)||maxCheckpointSteps<1)throw fault('invalid_copy_budget');
   const planner=createDuplicatePlanner(document,registry,selection,options,binding);
-  // savedSteps等只记录上次已等待checkpoint回调成功的位置，保存耗时不冒充新增规划工作。
+  // saved* 是调度内存，不是另一份持久 checkpoint；首次 savedPhase 未知会在首片触发回调。
+  // savedAt 只在回调成功后重取，保存耗时不算新增规划工作，也不会单因慢存储强迫下一片立即再存。
   let savedPhase:DuplicateCheckpoint['phase']|undefined,savedSteps=binding.checkpoint?.steps??0,savedAllocated=(binding.checkpoint?.elementIds.length??0)+(binding.checkpoint?.canvasIds.length??0),savedAt=now();
   while(true){
     const start=now();let count=0;

src/lib/canvas-runtime/elision.ts

@@ -13,7 +13,8 @@ export type ElisionProof = { readonly version: 1; readonly operationIds: readonl
 
 /** Reconstruct a closed lifetime from an empty fragment. Existing objects cannot enter this proof. */
 /** 在空记录片段上重建至多 64 意图/10000 changes，验证每个对象首触及都是创建且最终全删。
- * 墓碑变化是允许保留的本地效果，不等于服务器执行过这些创建/删除。 */
+ * 本函数不读 ledger 阶段、basePresence、请求或依赖，不独自证明这些操作从未发送/实际基线 absent。
+ * 只做条件变化与生命周期闭合检查，不调用 registry/整图校验；临时片段可无根，最终只保留本地墓碑。 */
 export function proveElision(intents: readonly OperationIntent[], baseTombstones: Readonly<Record<Id, number>>): ElisionProof {
   if (!intents.length || intents.length > 64 || new Set(intents.map(intent => intent.id)).size !== intents.length) throw fault('invalid_elision');
   const created = new Set<Id>(), canvases = new Set<Id>();
@@ -37,6 +38,7 @@ export function proveElision(intents: readonly OperationIntent[], baseTombstones
       }
     }
   }
+  // 起始墓碑只能描述本段确实创建过的元素，不能趁抵消夹带无关 ID 的生命周期水位。
   if (Object.keys(baseTombstones).some(id => !created.has(id))) throw fault('invalid_elision');
   const fragment: Document = { projectId: '', elements: new Map(), canvases: new Map(), tombstones: new Map(Object.entries(baseTombstones)) };
   // 条件执行仍使用真实 applyChanges；before 不匹配不能因最终想删除就被忽略。
@@ -46,10 +48,12 @@ export function proveElision(intents: readonly OperationIntent[], baseTombstones
 }
 
 /** Longest closed prefix before an existing-object write or another unsafe precondition. */
-/** 寻找最长安全闭合前缀；遇 frozen/blocker/外部未解依赖/已有对象首写即停止扩展。
- * preceding 只允许前面已选独立真实段作为依赖屏障，不把它当作已经 applied 的回执。 */
+/** 在传入候选顺序内寻找最长闭合前缀，检查 pending/未绑请求、基线和依赖；不扫描全账本证明中间无漏项。
+ * 全账本连续性还由 ledger.elide/validateElisions 复核；preceding 只给批次边界规划暂时满足前段依赖。
+ * undefined 表示没找到；条件回放失败或闭合证明非法仍会抛错，不统一吞成 undefined。 */
 export function findElision(intents: readonly OperationIntent[], acknowledged: Document, ledger: LedgerSnapshot, preceding: ReadonlySet<Id> = new Set()): ElisionProof | undefined {
   const selected: OperationIntent[] = [], seen = new Set<Id>(), canvases = new Set<Id>(), bases: Record<Id, number> = Object.create(null);
+  // 候选超过 64 直接不寻找，不自动截取前 64；真正闭合后的 changes 上限由 proveElision 检查。
   if (intents.length > 64 || !intents.some(intent => intent.changes.some(change => change.kind !== 'field' && change.after === null))) return undefined;
   // 每次片段归空时保存最佳前缀；后续又创建未删对象，不影响之前已找到的闭合边界。
   let bestLength = 0, bestBases: Record<Id, number> = {};
@@ -57,6 +61,7 @@ export function findElision(intents: readonly OperationIntent[], acknowledged: D
   for (const intent of intents) {
     const record = ledger.operations.get(intent.id);
     if (!record || record.phase !== 'pending' || record.requestId || record.blockers.length || !equal(record.intent, intent) || intent.operationType !== 'document.change' || intent.operationSchemaVersion !== 1) break;
+    // resolved 只表示依赖已被本地解除，不在此区分 applied/elided/retired 的业务理由；preceding 不是远端执行证明。
     if (intent.dependencies.some(id => !selected.some(intent => intent.id === id) && !preceding.has(id) && ledger.operations.get(id)?.phase !== 'resolved')) break;
     let safe = true;
     for (const change of intent.changes) {
@@ -78,7 +83,8 @@ export function findElision(intents: readonly OperationIntent[], acknowledged: D
 }
 
 /** Keep a later closed segment mutable while earlier real edits obtain their own receipt. */
-/** 若后面存在可抵消段，限制前面的真实请求前缀，避免一次冻结把可抵消段也锁死。 */
+/** 若后面存在可抵消候选段，缩短前面的真实请求前缀，避免本次 freeze 锁住后段。
+ * 这里只返回前缀长度，不标 ledger.elided、不证明前段已成功；原前缀可直接抵消时交其它钩子处理。 */
 export function elisionBatchLimit(intents: readonly OperationIntent[], acknowledged: Document, ledger: LedgerSnapshot): number {
   if (!intents.some(intent => intent.changes.some(change => change.kind !== 'field' && change.after === null)) || findElision(intents, acknowledged, ledger)) return intents.length;
   const preceding = new Set<Id>();
@@ -99,7 +105,8 @@ export function assertElisionLineage(proof: ElisionProof, intents: readonly Oper
 
 /** Validate persisted local facts independently of the current (possibly newer) server baseline. */
 /** 恢复时按逻辑顺序复验持久抵消组：成员连续、依赖闭合、anchor 唯一、证明与水位一致。
- * 不依赖当前可能更新过的 ACK 基线来重新猜历史 absent 事实。 */
+ * 不依赖当前可能更新过的 ACK 基线来重新猜历史 absent 事实，而是复核保存的 basePresence/proof。
+ * 它不向服务器查询当年是否接收过请求；此前的持久记录捕获与身份校验仍由恢复边界负责。 */
 export function validateElisions(ledger: Pick<LedgerSnapshot, 'operations'>): void {
   const ordered = [...ledger.operations.values()].sort((a, b) => a.intent.sequence - b.intent.sequence), positions = new Map(ordered.map((record, index) => [record.intent.id, index]));
   const previous = new Map<Id, number>();
@@ -128,7 +135,9 @@ export function validateElisions(ledger: Pick<LedgerSnapshot, 'operations'>): vo
 }
 
 /** Local high-water marks belong to working state, never to the server ACK document. */
-/** 只给 working 候选补本地墓碑最大值，不修改源文档，也不向服务器 ACK 事实表灌入本地证明。 */
+/** 只为候选复制墓碑表并补本地最大值，其余文档表沿用；不改传入文档。
+ * 调用方只能将结果当 working，不应覆写 acknowledged；这里不自动区分两种变量的用途。
+ * 直接读取保存的 elision 字段，不在此复验证据；ledger 应先经可信生成或 validateElisions。 */
 export function withLocalLifecycles(document: Document, ledger: Pick<LedgerSnapshot, 'operations'>): Document {
   const tombstones = new Map(document.tombstones);
   for (const record of ledger.operations.values()) if (record.elision) for (const [id, incarnation] of Object.entries(record.elision.tombstones)) tombstones.set(id, Math.max(tombstones.get(id) ?? 0, incarnation));

src/lib/canvas-runtime/engine.ts

@@ -4,6 +4,8 @@
  * engine 把持久化、网络调度、资源、导入、生成和冲突恢复连接到这个边界。
  * 这里的 Promise/Map/Set 大多是当前进程的任务、租约或索引，不替代可恢复根中的业务事实。
  * 打开项目先取得存储领导权并解码恢复镜像；视图挂载/卸载与项目关闭是不同的生命周期。
+ * 阅读顺序可按“打开/初始根→editor hooks→持久队列→资源清理→请求协调→任务执行→公开能力/关闭”。
+ * 临时上下文只在同步提交期间授予对应 reducer 权限，异步准备不得跨 await 长期占用这些上下文。
  */
 import {dataArray,dataRecord} from '../canvas-core/data-containers.ts';
 import {detachJsonData} from '../canvas-core/json-data.ts';
@@ -58,7 +60,9 @@ const digestFailures=new Set(['digest_capacity','digest_worker_failed','digest_w
 /** 打开项目的依赖注入参数。scope/document 必须属于同一项目；registry 解释模型和恢复数据。
  * storage 是本地可靠保存，persistence 是文档网络协议；assets/runs 为可选外部业务服务。
  * digest/image/display/depot 可共享注入；clock 和 createId 允许宿主或测试控制时间与身份。
- * loading 表示尚未读完的模型，不能把已有前缀当成完整项目。 */
+ * loading 表示尚未读完的模型，不能把已有前缀当成完整项目。
+ * options/端口大多借用而非深复制，宿主须保持配置与 scope 身份稳定；动态认证撤销走 isCurrentIdentity。
+ * 注入共享池的拥有者负责其全局关闭，本项目只释放自己持有的任务、显示租约和存储 leader。 */
 export type EngineOptions = {
   loading?:LoadingState;
   scope: StorageScope; registry: Registry; document: Document; versions: ReadonlyMap<Id, number>;
@@ -84,7 +88,9 @@ export type RecoverySession = {
 };
 
 /** 打开一个项目所有者实例。先独占本地写入，再选择恢复状态或初始服务端状态，
- * 接线 editor 与异步执行器；此工厂是异步入口，普通编辑提交仍在 editor 内同步发布。 */
+ * 接线 editor 与异步执行器；此工厂是异步入口，普通编辑提交仍在 editor 内同步发布。
+ * scope/document 先核项目 ID，loading/versions 在首个 await 前捕获；document/registry/其它 options 仍借用。
+ * 本地 recovered Root 优先于外部初始模型，但传入模型的每张 canvas 仍须带有效 openingVersions。 */
 export async function openProjectEngine(options: EngineOptions) {
   if (options.scope.projectId !== options.document.projectId) throw fault('project_mismatch');
   // 在第一次 await 前捕获加载状态和版本，防止调用方随后修改原容器改变这次打开的基线。
@@ -100,7 +106,8 @@ export async function openProjectEngine(options: EngineOptions) {
     // 渐进读取的在途任务、准入暂停句柄及完成 revision：完成读取后仍要等对应根可靠保存。
     let loadingRead:Promise<Result>|undefined,loadingReadController:AbortController|undefined;
     let acceptingLoading=false,loadingRelease:(()=>void)|undefined,loadingCompletionRevision:number|undefined;
-    // closing 阻止新工作，closed 表示生命周期结束；durableRootRevision 仅由存储回执推进。
+    // closing 阻止新工作，closed 表示生命周期结束；durableRootRevision 从恢复镜像起步，之后只认存储回执。
+    // 新项目设为-1，保证 revision=0 的初始根也必须持久化，不能误当成已保存。
     let closing = false, closed = false, durableRootRevision = image?.rootRevision ?? -1;
     // 项目级摘要中止源，与单次任务 signal 合并；关闭时可撤销仍在处理的字节计算。
     const digestLifecycle=new AbortController();
@@ -110,13 +117,15 @@ export async function openProjectEngine(options: EngineOptions) {
     const report = (error: unknown) => { try { options.onError?.(error); } catch { /* Error reporting cannot alter state. */ } };
     // 持久化订阅与文档订阅分开；缓存同值对象，便于界面按快照身份避免无意义更新。
     const durabilityListeners=new Set<()=>void>();let durabilityError:string|undefined,durabilityCache:Readonly<{rootRevision:number;durableRootRevision:number;closing:boolean;closed:boolean;error?:string}>|undefined;
-    /** 返回当前根/已保存根、关闭阶段和存储错误的稳定只读快照。 */
+    /** 返回当前根/已保存根、关闭阶段和存储错误的稳定只读快照；同字段值复用对象供订阅比较。
+     * 这是本地持久化诊断，不是网络 ACK/服务同步进度；editor 初始化后才允许调用此闭包。 */
     function getDurability(){const rootRevision=editor.getSnapshot().rootRevision;if(!durabilityCache||durabilityCache.rootRevision!==rootRevision||durabilityCache.durableRootRevision!==durableRootRevision||durabilityCache.closing!==closing||durabilityCache.closed!==closed||durabilityCache.error!==durabilityError)durabilityCache=Object.freeze({rootRevision,durableRootRevision,closing,closed,...(durabilityError?{error:durabilityError}:{})});return durabilityCache;}
     /** 拷贝监听集合后逐个通知，订阅过程中增删监听不影响本轮，也不传播监听器异常。 */
     function notifyDurability(){for(const listener of [...durabilityListeners])try{listener();}catch(error){report(error);}}
     // 所有新任务/请求需要独立身份；宿主可注入生成器，默认使用浏览器 UUID。
     const createId = options.createId ?? (() => crypto.randomUUID());
-    // 网络门限制并发为 2，并在准入时核对存储领导权和认证代次。
+    // 网络门限制同时在途为2，在准入时查 leader.active 与当前认证；这里不比较远端数据库 fence。
+    // 本地可靠屏障/任务依赖由 scheduler 另管，network 不自己判断请求是否已经安全落盘。
     const network = createNetworkGate(2,()=>{if(!leader.active)throw fault('storage_leader_lost');if(options.isCurrentIdentity&&!options.isCurrentIdentity())throw fault('identity_changed');});
     // 有共享存储端口时可装配资源仓库；跨项目共享仅限同账户、同工作区。
     const depot=options.assetDepot??(options.storage.assetDepot?createAssetDepot({scope:options.scope,port:options.storage.assetDepot,current:()=>!closing&&!closed&&(!options.isCurrentIdentity||options.isCurrentIdentity()),digest:sourceDigest}):undefined);
@@ -134,7 +143,8 @@ export async function openProjectEngine(options: EngineOptions) {
     const displayOwner = Object.freeze({}), displayCache = options.displays ?? createDisplayCache({ onError: options.onError });
     /** 即使缓存已有显示结果，也先检查项目/身份仍有效，不能跨账户复用旧视图授权。 */
     const assertDisplayIdentity=()=>{if(closing||closed)throw fault('engine_closing');if(options.isCurrentIdentity&&!options.isCurrentIdentity())throw fault('identity_changed');};
-    // 显示租约计数阻止清理；reservation 阻止领用即将删除的文件；durablyPurged 记录已删字节。
+    // displayPins 计数显示/文件借用租约；reservation 在规划 purge 后阻止新领用，直到可靠回执释放。
+    // durablyPurged 是当前 leader 已可靠记录的 purge 身份集合，用来避免重复安排物理删除，并非 Blob 缓存。
     const displayPins=new Map<Id,number>(),collectionReservations=new Set<Id>(),durablyPurged=new Set<Id>([...(recovered?.runtime.resources.values()??[])].filter(resource=>resource.retirement?.purgedAt!==undefined).map(resource=>resource.id));
     /** 清理结果同时报告检查根、当前根和可靠保存根，区分“规划删除”和“字节已删除”。 */
     type CollectionReport={readonly markedIds:readonly Id[];readonly purgedIds:readonly Id[];readonly complete:boolean;readonly checkedRootRevision:number;readonly rootRevision:number;readonly durableRootRevision:number};
@@ -149,9 +159,11 @@ export async function openProjectEngine(options: EngineOptions) {
     // 解码/尺寸补写/摘要等在途索引只用于生命周期等待与去重；恢复事实仍在 runtime 中。
     const imageTasks=new Map<Id,Promise<void>>();
     let sizingTask: Promise<void> | undefined;
-    // 待写 Blob 与根快照分开保存，writePrefix 只把当前快照登记的资源/导入源文件纳入原子提交。
+    // fileWrites 暂存未可靠落盘的 Blob；digestTasks 只去重并等待摘要工作，二者都不是持久任务表。
+    // writePrefix 按某一捕获根的资源/源归属筛选文件，不能把未来编辑的字节提前配给旧根。
     const fileWrites = new Map<Id, Blob>(), digestTasks = new Map<Id, Promise<void>>();
-    // 文件暂存及默认尺寸标记仅覆盖同步编辑事务；事务 reducer 将其写入可恢复资源记录。
+    // staged 与 stagedDefaultSizes 仅是同步编辑事务的授权上下文；reduceRuntime 将其转成根中的资源事实。
+    // 分配/上传/解码不能在 reducer 内启动，失败候选也不能留下第二份已接纳任务。
     let staged: readonly ResourceRecord[] = [];
     const stagedDefaultSizes = new Set<Id>();
     // 将用户提交标为 run.apply 的短暂上下文；不能让一次应用操作泄漏到后续普通编辑。
@@ -168,7 +180,8 @@ export async function openProjectEngine(options: EngineOptions) {
     const importRunners=new Map<Id,ReturnType<typeof createImportRunner>>(),importLoads=new Map<Id,Promise<void>>(),importHolds=new Map<symbol,Map<Id,()=>void>>();
     // 恢复会话存在期间阻止一般写入；会话负责持有/释放调度暂停及中止控制。
     let recovery: { controller: AbortController; release(): void; cancel():Promise<void> } | undefined;
-    /** 复制准备期间保守保护未清除资源，解码期间保护正在读取的图片；供每次保留扫描派生。 */
+    /** 每次派生临时保留清单：任一复制准备仍活跃就保守 pin 全部未 purge 的本地资源，解码按任务 ID pin。
+     * Map 是本次扫描的输入，不发布第二份 resourcePins；任务结束后下次扫描自然不再包含该临时 owner。 */
     const admissionPins=(snapshot:EngineSnapshot)=>{const pins=new Map<Id,readonly Id[]>();if(copyPreparations.size)pins.set('copy-admission',[...snapshot.runtime.resources.values()].filter(resource=>resource.retirement?.purgedAt===undefined).map(resource=>resource.id));if(imageTasks.size)pins.set('image-decode',[...imageTasks.keys()]);return pins;};
     /** 通用写入护栏。complete=false 仅放宽“模型必须完整”，不绕过身份、租约或恢复会话限制。 */
     const assertWritable = (complete=true) => { if(!leader.active)throw fault('storage_leader_lost');if(options.isCurrentIdentity&&!options.isCurrentIdentity())throw fault('identity_changed');if(complete&&editor.getSnapshot().runtime.loading)throw fault('model_loading');if(closing||closed)throw fault('engine_closing');if(recovery)throw fault('recovery_in_progress'); };
@@ -184,7 +197,8 @@ export async function openProjectEngine(options: EngineOptions) {
     // 已领用资源绑定必须能被当前服务 authority 和 URL 解释；换服务不能静默复用旧授权。
     for(const [id,binding]of initial.assetBindings??[])if(!depot||!options.assets?.authority||binding.authority!==options.assets.authority.scope||binding.asset.url!==options.assets.sourceURL(id))throw fault('asset_binding_interpreter_unavailable',[id]);
     if(initial.loading?.version===6&&options.assets)for(const resource of initial.resources.values())if(resource.loadingAdmission?.sourceURL!==options.assets.sourceURL(resource.id))throw fault('asset_source_changed',[resource.id]);
-    // editor 是唯一状态根的发布者，下面的 hooks 在发布前整合 runtime，而非先改文档后补队列。
+    // editor 是唯一状态根的发布者，hooks 在候选发布前整合/检查 runtime，而非先改文档后补队列。
+    // prepareRuntime 是全部发布的保留/所有权边界，reduceRuntime 只处理带 commit 的编辑；二者不做 I/O。
     const editor = createEditor({ registry: options.registry, document: options.document, recovery: recovered, runtime: initial, createId: options.createId, historyLimit: options.historyLimit,queryBudget:options.queryBudget,queryCoverage:loadingQueryCoverage,
       /** 命令入口先检查基础生命周期，再检查渐进加载允许范围，最后应用宿主业务策略。 */
       policy(command, document) { if(!leader.active)return{enabled:false,code:'storage_leader_lost',targets:[]};if(options.isCurrentIdentity&&!options.isCurrentIdentity())return{enabled:false,code:'identity_changed',targets:[]};if (closing || closed || recovery) return { enabled: false, code: closing||closed?'engine_closing':'recovery_in_progress', targets: [] }; if(editor.getSnapshot().runtime.loading){const allowed=loadingCommand(command,document,options.registry,editor.getSnapshot().runtime.loading,editor.getSnapshot().runtime.loadingRead?.document??editor.getSnapshot().runtime.acknowledged,editor.getSnapshot().runtime.loadingRead,assetURLs());if(!allowed.enabled)return allowed;}return options.policy?.(command, document) ?? { enabled: true }; },
@@ -207,6 +221,8 @@ export async function openProjectEngine(options: EngineOptions) {
         for(const id of next.runtime.assetBindings?.keys()??[])if(next.runtime.resources.has(id)||next.runtime.orphanFiles?.has(id)||importFiles(next.runtime.imports).has(id))throw fault('resource_identity_conflict',[id]);
         validateLoadingRuntime(next.runtime,options.registry);
         // 先计算尺寸权限，再依文档/历史/账本/显示引用派生资源保留，最后处理源文件和孤立字节。
+        // 后一步使用前一步返回的候选：先撤销失效尺寸权限，再算资源 pin，再算导入源和孤儿退休状态。
+        // previous/next 只是候选快照，此处抛错交给 editor 拒绝整次发布，不在这里自行修改旧根。
         const sizing=prepareDefaultImageSizing(previous,next);
         const runtime=prepareResourceRetention({...next,runtime:sizing},options.registry,displayPins,collectionReservations,admissionPins(next));
         // 这些引用事实变化会影响“是否仍无人使用”；保留准备函数据此重新检查退休标记。
@@ -216,12 +232,13 @@ export async function openProjectEngine(options: EngineOptions) {
       },
       /** 只把当前应用输出的用户意图转换为 run.apply，保留普通 editor 的命令生成路径。 */
       prepareIntent: intent => applying && intent.origin==='user' ? {...intent,operationType:'run.apply',action:applying} : intent,
-      /** 在现有账本最大序号后分配；预留 staged 上传操作的位置，让上传先于引用它的文档操作。 */
+      /** 取 fallback 与账本最大 sequence+1 的较大值，再为 staged 上传留连续序号。
+       * reduceRuntime 从首个文档操作序号倒推上传起点，保证资源任务排在依赖它的文档意图之前。 */
       nextOperationSequence(runtime, fallback) { let next = fallback; for (const record of runtime.ledger.operations.values()) next = Math.max(next, record.intent.sequence + 1); return next + staged.length; },
       /** 把一次 editor 提交转换为账本、资源及导入作业的同根更新；不在这里发送请求。 */
       reduceRuntime(previous, next, commit) {
         if(previous.loading)assertLoadingChanges(commit.changes,previous.loading.version>=4?editor.getSnapshot().document:previous.acknowledged,options.registry,previous.loading,previous.loadingRead,assetURLs());
-        // 无逻辑操作的提交不创建上传依赖；保留原 runtime 对象。
+        // 没有逻辑 operationIds 就保持原 runtime；资源暂存本身不能脱离文档提交变成上传任务。
         if (!commit.operationIds.length) return previous;
         const ledger = createLedger(previous.ledger), resources = new Map(previous.resources);
         const firstSequence = next.operations.get(commit.operationIds[0])!.sequence - staged.length;
@@ -247,7 +264,8 @@ export async function openProjectEngine(options: EngineOptions) {
               if (grants.some((grant, index) => grant !== resource.sizing!.grants[index])) resources.set(resourceId, freeze({ ...resource, sizing: { version: 1 as const, grants } }));
             }
           }
-          // 所有未决 run.start，以及与本操作足迹冲突的文档/应用操作，都成为先行依赖。
+          // 未决 run.start 全部作为先行依赖；document.change/run.apply 只在对象足迹冲突时加入。
+          // Set 合并原依赖、先前任务和下方资源上传依赖，保留因果关系而不复制第二份调度状态。
           const dependencies = new Set(intent.dependencies);
           for (const record of ledger.getSnapshot().operations.values()) if (record.phase !== 'resolved' && (record.intent.operationType === 'run.start' || ['document.change','run.apply'].includes(record.intent.operationType) && conflictsWith(operationFootprint(record.intent, next.document), footprint))) dependencies.add(record.intent.id);
           // 引用尚未上传完成的资源时，文档同步必须等待该资源的上传操作。
@@ -255,7 +273,8 @@ export async function openProjectEngine(options: EngineOptions) {
             const resource = resources.get(id);
             if (resource && !resource.stored) dependencies.add(resource.operationId);
           }
-          // 合并器需要起始存在性，才能区分本地 create→delete 可消除与已存在对象必须发送删除。
+          // 同一对象首个变化决定 basePresence：element.before 空为 absent，field 默认 exists，后续不覆盖。
+          // 它不是“最后节点对象”；给合并/抵消保留起始事实，是否已发出仍由 ledger/request 证据约束。
           const basePresence: Record<Id, 'absent' | 'exists'> = Object.create(null);
           for (const change of intent.changes) if (change.kind === 'element') basePresence[change.id] ??= change.before ? 'exists' : 'absent'; else if (change.kind === 'field') basePresence[change.target.id] ??= 'exists';
           ledger.add(freeze({ ...intent, dependencies: [...dependencies] }), basePresence);
@@ -278,7 +297,8 @@ export async function openProjectEngine(options: EngineOptions) {
         return Object.freeze({ ...previous, imports:readMap(imports), ...(assetBindings.size?{assetBindings:readMap(assetBindings)}:{}), resources: readMap(resources), ledger: ledger.getSnapshot() });
       },
     });
-    // 待持久化快照按根 revision 递增插入 Map，形成写前缀队列；不会用最新根覆盖未保存旧根。
+    // pending 是 revision→不可变完整根的插入有序 Map，订阅按发布顺序追加；不是只保留最新根的防抖槽。
+    // writePrefix 总取首项，成功后才移除；每项共享不可变子树，但积压仍会占内存，导入背压在后面限制增长。
     const pending = new Map<number, EngineSnapshot>();
     // 新项目的初始根也要保存；恢复镜像已经在磁盘上，不重复当成新提交。
     if (!recovered) pending.set(editor.getSnapshot().rootRevision, editor.getSnapshot());
@@ -288,11 +308,14 @@ export async function openProjectEngine(options: EngineOptions) {
     // 记录由可靠回执确认的 ledger generation；即使派生标记发布失败，也保留这项推进义务。
     let confirmedLedgerGeneration=editor.getSnapshot().runtime.ledger.durableGeneration;
     /** 保存不超过 throughRevision 的已捕获前缀。每份根镜像与对应字节写入/删除同事务提交，
-     * 存储回执核对通过后才移除 pending、释放字节和推进可靠游标。已有写入时共享该 Promise。 */
+     * 存储回执核对通过后才移除 pending、释放字节和推进可靠游标。已有写入时共享该 Promise。
+     * 后来的调用不会扩大当前 throughRevision；persistThrough 在旧写入完成后继续补写所需边界。
+     * pending Map 的插入序由根订阅维护，不在此排序/补洞；存储 adapter 再校验连续 revision。 */
     function writePrefix(throughRevision:number):Promise<void> {
       if (writing) return writing;
       const task = Promise.resolve().then(async () => {
-        /** 把已可靠写入的 generation 发布回 ledger；此更新可能产生新根，不能冒充它也已保存。 */
+        /** 一次前缀结束后把已确认 generation 反映到 ledger；mutate 可能产生新的待保存根。
+         * confirmedLedgerGeneration 在回执后保留推进义务，即使本次派生发布失败，下次也可补办。 */
         const publishDurability=()=>{if(editor.getSnapshot().runtime.ledger.durableGeneration<confirmedLedgerGeneration)mutate(ledger=>ledger.markDurable(confirmedLedgerGeneration));};
         try {
           while (pending.size) {
@@ -304,7 +327,8 @@ export async function openProjectEngine(options: EngineOptions) {
             const deleteFiles=[...[...snapshot.runtime.resources.values()].filter(resource=>resource.retirement?.purgedAt!==undefined&&!durablyPurged.has(resource.id)).map(resource=>resource.id),...[...sourceFiles].filter(([id,entry])=>entry.file.retirement?.purgedAt!==undefined&&!durablyPurged.has(id)).map(([id])=>id),...[...(snapshot.runtime.orphanFiles??[])].filter(([id,file])=>file.retirement?.purgedAt!==undefined&&!durablyPurged.has(id)).map(([id])=>id)];
             // 共享仓库写入和项目 pin 清单也由同一快照准备，避免项目镜像与资源引用各自提交。
             const depot=options.assets?.authority&&options.storage.assetDepot?await prepareDepotCut({snapshot,registry:options.registry,storage:options.storage,leader,authority:options.assets.authority.scope,files:fileWrites,adoptedFiles,displays:displayPins,temporary:admissionPins(snapshot)}):undefined;
-            // 编码可能让出线程；snapshot 保持不可变，不能改用等待后出现的新 working 根。
+            // depot 准备/编码都可能 await，始终使用本轮 snapshot；不能等待后改取 live 根再配旧 revision/files。
+            // storage.commit 必须把 image/本批 Blob/删除/depot 同事务处理；这里只在匹配回执后承认可靠。
             const receipt = await options.storage.commit(leader, { image: await encodeRecoveryAsync(snapshot), files,deleteFiles,...(depot?{depot}:{}) });
             if (receipt.durableRootRevision !== revision) throw fault('invalid_durable_receipt');
             // 回执之后才承认 generation/源 seal 可靠；后续网络准入依赖这些事实。
@@ -319,7 +343,7 @@ export async function openProjectEngine(options: EngineOptions) {
           // 部分前缀成功、后续失败时仍发布成功证据，不能把已可靠写入的操作退回“从未保存”。
           publishDurability();throw error;
         }
-        // One derived publication per captured prefix, not one per receipt.
+        // 一次前缀尽量只发布一次派生 durableGeneration，避免每个回执都再制造一个待保存根。
         publishDurability();
         persistenceFailed = false;durabilityError=undefined;notifyDurability();
       });
@@ -327,18 +351,23 @@ export async function openProjectEngine(options: EngineOptions) {
       writing = task.catch(error => { persistenceFailed = true;const failure=error&&typeof error==='object'?error as {code?:unknown;message?:unknown}:{};durabilityError=typeof failure.code==='string'&&failure.code?failure.code:typeof failure.message==='string'&&failure.message?failure.message:'persistence_failed';notifyDurability(); throw error; }).finally(() => { writing = undefined;if(!persistenceFailed){if(loadingCompletionRevision!==undefined&&durableRootRevision>=loadingCompletionRevision&&!editor.getSnapshot().runtime.loading){const release=loadingRelease;loadingRelease=undefined;loadingCompletionRevision=undefined;release?.();}if(!closing&&!closed)scheduler.refreshAdmission();} });
       return writing;
     }
-    /** 仅保证指定 revision 已可靠保存。若共享的在途写入目标更早，完成后继续写到所需边界。 */
+    /** 捕获 requiredRevision（缺省为调用时根 revision），只保证这一边界已可靠保存。
+     * 共用在途写入可能只到更早根，因此 .then 再查水位并补写；不是保证所有未来编辑都已保存。
+     * 写失败向调用者传播，不在这里无限自动重试；必须由后续显式/自动保存重新触发。 */
     function persistThrough(requiredRevision=editor.getSnapshot().rootRevision):Promise<void> {
       if(durableRootRevision>=requiredRevision)return Promise.resolve();
       return writePrefix(requiredRevision).then(()=>durableRootRevision<requiredRevision?persistThrough(requiredRevision):undefined);
     }
-    /** 排空当前保存义务，包含写回 durableGeneration 派生的新根；不等于网络同步完成。 */
+    /** 循环排空 pending 和 durableGeneration 派生义务，不等于等待网络 ACK/生成/导入任务全部完成。
+     * 与 persistThrough 的固定边界不同，循环期间新增本地根也纳入等待；调用方须先阻止需关闭的生产者。 */
     async function persist():Promise<void> {
       do {await writePrefix(editor.getSnapshot().rootRevision);}
       while(pending.size||writing||confirmedLedgerGeneration>editor.getSnapshot().runtime.ledger.durableGeneration);
     }
     /** 本地上传资源的两阶段清理：先持久化无人引用时间，再于保留期后重新扫描并原子删字节。
-     * 引用覆盖不完整就停止，限制每批文件数，返回标记与真正保存成功的删除结果。 */
+     * 引用覆盖不完整就停止，限制每阶段候选数；先保存现有根，再标记，再复取根/pin 判定删除。
+     * markedIds/purgedIds 只随成功返回报告；中途失败抛错，已保存标记保留供下一轮继续。
+     * maxFiles 分别限制标记/删除，不是全表扫描或总工作量上限；各资源仍需遍历后筛选。 */
     function collectResources(settings:{retentionMs:number;maxFiles?:number}) {
       assertWritable();
       if(options.storage.fileDeletion!=='atomic-v1')throw fault('resource_collection_unavailable');
@@ -347,9 +376,11 @@ export async function openProjectEngine(options: EngineOptions) {
       if(collection)return collection;
       const task=(async()=>{
         await persist();assertWritable();
+        // 一轮使用一个 now；保存后重查引用，但不把等待时间追加进本轮保留期判断。
         const now=runClock.now();if(!Number.isSafeInteger(now)||now<0)throw fault('invalid_resource_collection_clock');
         let root=editor.getSnapshot(),pins=resourceRetentionPins(root,options.registry,displayPins,admissionPins(root));
         const markedIds:Id[]=[],purgedIds:Id[]=[];
+        // complete 只表示引用扫描可解释完整，不表示仓库中所有资源都已 purge。
         const report=()=>Object.freeze({markedIds:Object.freeze(markedIds),purgedIds:Object.freeze(purgedIds),complete:pins.complete,checkedRootRevision:root.rootRevision,rootRevision:editor.getSnapshot().rootRevision,durableRootRevision});
         if(!pins.complete)return report();
         // 待写或摘要处理中资源不参与清理；必须先证明没有文档、历史、任务或显示租约引用。
@@ -362,6 +393,7 @@ export async function openProjectEngine(options: EngineOptions) {
         root=editor.getSnapshot();pins=resourceRetentionPins(root,options.registry,displayPins,admissionPins(root));
         if(!pins.complete)return report();
         // 标记后的 await 期间可能出现新引用，所以重新取根和 pins，再判定到期资源。
+        // retentionMs=0 时本轮新标记也可能直接进入 purge，但前面的标记根已先可靠保存。
         const eligible=[...root.runtime.resources.values()].filter(resource=>resource.retirement&&resource.retirement.purgedAt===undefined&&now-resource.retirement.unreferencedAt>=retentionMs&&!pins.pins.has(resource.id)&&!fileWrites.has(resource.id)&&!digestTasks.has(resource.id)).slice(0,maxFiles);
         if(eligible.length){
           // 先保留删除席位阻止新领用；若根 revision 冲突则撤销保留，不报告已删除。
@@ -376,7 +408,9 @@ export async function openProjectEngine(options: EngineOptions) {
       collection=task.finally(()=>{collection=undefined;});return collection;
     }
     /** 导入源文件的同类两阶段清理；当前源只允许在任务终结且没有载入器时成为候选。
-     * 旧分片/历史源也要经过引用覆盖和保留期，不按任务结束就立即丢弃全部原始字节。 */
+     * 旧分片/历史源也要经过引用覆盖和保留期，不按任务结束就立即丢弃全部原始字节。
+     * single-flight 只覆盖本类 sourceCollection；运行中重复调用共用首次 settings，不另开一轮不同参数扫描。
+     * 与资源回收一样 maxFiles 分阶段限候选，一轮 now 固定，可靠回执后才报告 purgedIds。 */
     function collectImportSources(settings:{retentionMs:number;maxFiles?:number}):Promise<CollectionReport> {
       assertWritable();if(options.storage.fileDeletion!=='atomic-v1')throw fault('resource_collection_unavailable');
       const retentionMs=settings.retentionMs,maxFiles=settings.maxFiles??64;
@@ -410,8 +444,10 @@ export async function openProjectEngine(options: EngineOptions) {
       })();
       sourceCollection=task.finally(()=>{sourceCollection=undefined;});return sourceCollection;
     }
-    /** 为备份/查看借出导入原文件。先加引用 pin 再异步读字节，校验长度及已有 SHA，
-     * 成功返回必须释放的句柄；失败自动释放，关闭期间的迟到结果不再交给调用方。 */
+    /** 为备份/查看借出当前或指定历史源文件。同步选定文件描述并 pin，再从暂存/可靠存储读 Blob。
+     * 校验长度；仅已有 sha256 时重算比对，不因返回 Blob 就推断 integrity-v2 已完成整源封存。
+     * 成功返回 {bytes,release}，调用方必须释放；失败自动释放，关闭期间的迟到结果不交付。
+     * 不调用完整 assertWritable：恢复会话/加载期也可借出文件，远端权限不由此入口重新授权。 */
     async function openImportSource(jobId:Id,fileId?:Id) {
       if(closing||closed)throw fault('engine_closing');const job=getImport(jobId),file=fileId!==undefined?importFiles(new Map([[jobId,job]])).get(fileId)?.file:job.source;if(!file)throw fault('import_source_unavailable');
       if(collectionReservations.has(file.fileId))throw fault('resource_collection_in_progress',[file.fileId]);
@@ -420,7 +456,8 @@ export async function openProjectEngine(options: EngineOptions) {
       /** 幂等归还本次 pin；从 displays 释放表移除，项目关闭不会重复扣除引用计数。 */
       const release=()=>{if(released)return;released=true;displays.delete(release);const count=displayPins.get(file.fileId)??1;if(count<=1)displayPins.delete(file.fileId);else displayPins.set(file.fileId,count-1);};displays.add(release);
       try{
-        // pin 已建立后发布一次 runtime 更新，让保留规则撤销已过时的退休标记。
+        // pin 先建立，空 runtime 更新触发 prepareRuntime 的保留规则，撤掉因无人引用产生的软退休标记。
+        // 只是重新派生引用状态，不更换本次已捕获的文件身份；本函数不等待该更新的持久化回执。
         if(file.retirement){const result=editor.updateRuntime(previous=>Object.freeze({...previous}));if(result.status==='rejected')throw fault(result.code,result.targets);}
         const bytes=fileWrites.get(file.fileId)??await options.storage.readFile(leader,file.fileId);
         if(closing||closed)throw fault('engine_closing');if(!bytes||bytes.size!==file.byteLength)throw fault('import_source_unavailable',[file.fileId]);
@@ -429,7 +466,8 @@ export async function openProjectEngine(options: EngineOptions) {
       }catch(error){release();if(closing||closed)throw fault('engine_closing');throw error;}
     }
     /** 校验存储提供的文件分页：绑定根 revision、ID 严格递增、大小合法、尾游标匹配。
-     * 读取期间根变更则拒绝旧清单，不能把两个时点的所有权证据拼成同一份库存。 */
+     * 不只比较 revision：await 后要求 editor 仍是同一个 root 对象，避免把变更前清单用于当前归属判断。
+     * 这里只验证页结构/顺序，不读 Blob、不哈希，也不证明跨多页调用持有同一个存储快照。 */
     async function scanLocalFiles(root:EngineSnapshot,after:Id|undefined,limit:number){
       if(!options.storage.scanFiles)throw fault('file_inventory_unavailable');
       const page=await options.storage.scanFiles(leader,{expectedRootRevision:root.rootRevision,after,limit});
@@ -440,7 +478,9 @@ export async function openProjectEngine(options: EngineOptions) {
       if(page.nextAfter!==undefined&&(!page.files.length||page.nextAfter!==previous))throw fault('invalid_file_inventory');return page;
     }
     /** 先保存根再读取有界库存，给每个文件附上资源/导入源/孤立文件归属与 pin 依据。
-     * 这是诊断读取；unregistered 只表示未登记，不直接证明该文件可安全删除。 */
+     * 这是诊断读取；unregistered 只表示未登记，不直接证明该文件可安全删除。
+     * ownership 来自当前捕获根，retired 表示 purge 声明，complete 表示引用覆盖；三者不是同一个判定。
+     * 本次只返回一页，页尾 nextAfter 供调用者后续继续，没有自动遍历整仓库。 */
     async function inventoryLocalFiles(settings:{after?:Id;limit?:number}={}){
       assertWritable();const limit=settings.limit??128;if(!Number.isSafeInteger(limit)||limit<1||limit>128||settings.after!==undefined&&(typeof settings.after!=='string'||!settings.after))throw fault('invalid_file_inventory');
       await persist();assertWritable();const root=editor.getSnapshot(),page=await scanLocalFiles(root,settings.after,limit),sources=importFiles(root.runtime.imports),pins=orphanCoverage(root,options.registry,displayPins,admissionPins(root));
@@ -448,7 +488,9 @@ export async function openProjectEngine(options: EngineOptions) {
     }
     /** 分页盘点并清理没有资源/导入源归属的本地文件。
      * 仅对本批核对过长度、MIME 和 SHA 的候选字节安排清理；先记无人引用时间，再经保留期删除。
-     * 文件数与散列字节预算分别限流，nextAfter 指向已处理边界，调用方可继续下一页。 */
+     * 一次只取 pageSize 一页；maxFiles 限实际验证候选数，maxHashBytes 限本页实际散列字节。
+     * 不够预算的候选不推进 nextAfter，调用者需提高预算或换下一次策略，不会悄悄跳过这个文件。
+     * orphanCollection 单飞共用首轮 settings；失败/取消只清执行索引，已保存的退休事实保留供后续继续。 */
     function collectOrphanFiles(settings:{retentionMs:number;maxFiles?:number;after?:Id;pageSize?:number;maxHashBytes?:number;signal?:AbortSignal}){
       assertWritable();if(options.storage.fileDeletion!=='atomic-v1'||!options.storage.scanFiles)throw fault('file_inventory_unavailable');
       const retentionMs=settings.retentionMs,maxFiles=settings.maxFiles??64,pageSize=settings.pageSize??128,maxHashBytes=settings.maxHashBytes??64*1024*1024;
@@ -461,6 +503,7 @@ export async function openProjectEngine(options: EngineOptions) {
       const task=(async()=>{
         await persist();check();const now=runClock.now();if(!Number.isSafeInteger(now)||now<0)throw fault('invalid_resource_collection_clock');
         let root=editor.getSnapshot(),pins=orphanCoverage(root,options.registry,displayPins,admissionPins(root)),scanned=0,nextAfter=settings.after,hashBudgetExhausted=false,scanFinished=false;
+        // verified 只存本轮已实际核对的内容证据；不能仅用此前持久 orphan 元信息授权本轮物理删除。
         const markedIds:Id[]=[],purgedIds:Id[]=[],changedIds:Id[]=[],verified=new Map<Id,OrphanFile>();
         /** 区分引用覆盖完整、扫描到末页与字节预算耗尽；这些状态不能只压成一个 complete。 */
         const result=()=>Object.freeze({markedIds:Object.freeze(markedIds),purgedIds:Object.freeze(purgedIds),changedIds:Object.freeze(changedIds),complete:pins.complete,blockers:pins.blockers,checkedRootRevision:root.rootRevision,scanned,nextAfter,hashBudgetExhausted,scanFinished,durableRootRevision});
@@ -484,7 +527,8 @@ export async function openProjectEngine(options: EngineOptions) {
         // 整页走完才使用存储尾游标；部分处理时保留最后实际检查过的文件 ID。
         if(finished)nextAfter=page.nextAfter;scanFinished=finished&&page.nextAfter===undefined;
         pins=orphanCoverage(root,options.registry,displayPins,admissionPins(root));if(!pins.complete)return result();
-        // 同 ID 字节发生变化时重新起算保留期；旧退休证据不能授权删除一份新内容。
+        // 同 ID 的 digest/长度/MIME 任一变化都重新起算保留期；changedIds 不是自动恢复成原有资源的许可。
+        // now 在本轮开头捕获，重查引用不顺带延长本轮时钟；retentionMs=0 时本轮新标记也可进入删除阶段。
         const updates=new Map<Id,OrphanFile>();
         for(const [id,file]of verified){if(pins.pins.has(id))continue;const old=root.runtime.orphanFiles?.get(id),changed=!!old&&(old.digest!==file.digest||old.byteLength!==file.byteLength||old.mimeType!==file.mimeType);
           if(!old?.retirement||changed){updates.set(id,freeze({...file,retirement:{version:1 as const,unreferencedAt:now}}));markedIds.push(id);if(changed)changedIds.push(id);}
@@ -504,23 +548,29 @@ export async function openProjectEngine(options: EngineOptions) {
       // 成功、失败或取消都撤销单飞索引；不会删除根中的退休记录或伪造 purged 回执。
       orphanCollection=task.finally(()=>{orphanCollection=undefined;if(orphanController===controller)orphanController=undefined;});return orphanCollection;
     }
-    /** 将可变 ledger helper 的一次归约转换为 editor 的同根 runtime 发布；拒绝结果转成领域异常。 */
+    /** 以当前 ledger 快照建立私有 helper，执行同步 reduce，再把其新快照交 editor 一次发布。
+     * 不允许 helper 绕过根发布单独成为事实源；reduce 须保持纯同步，外部副作用不由这里回滚。
+     * Result.rejected 转异常供 scheduler/持久化调用者处理，成功不等于该根已经 durable。 */
     function mutate(reduce: (ledger: ReturnType<typeof createLedger>) => void) {
       const result = editor.updateRuntime(previous => { const ledger = createLedger(previous.ledger); reduce(ledger); return Object.freeze({ ...previous, ledger: ledger.getSnapshot() }); });
       if (result.status === 'rejected') throw fault(result.code, result.targets);
     }
     /** 网络结果的统一协调入口。先记录请求是否生效，再按请求种类解释回执。
      * applied 只证明服务端生效；仍需验证身份/版本并重放本地未决操作，才能发布新的 ACK 和 working。
-     * 协调失败保留原回执与原工作文档，标为“已生效但未协调”，不当作可重新提交的新请求。 */
+     * 协调失败保留原回执与原工作文档，标为“已生效但未协调”，不当作可重新提交的新请求。
+     * 全部协调在同一同步调用内规划/发布；磁盘屏障及请求 generation/身份采纳由外层 scheduler 负责。
+     * 此处 resolved 快速返回检查传入 request 快照，不把任意迟到响应视为可直接采纳的许可。 */
     function complete(request: FrozenRequest, status: OperationStatus): { readonly blocked: true } | void {
       const root = editor.getSnapshot(), previous = root.runtime, ledger = createLedger(previous.ledger);
       if (request.phase === 'resolved') return;
-      // 未生效/未知结果只更新账本和回执；明确未生效的启动、取消动作可终结为无效果。
+      // 非 applied 结果不改 ACK/working，只更新 ledger 与可选回执；not-applied 仍是“确定未生效”，不是传输失败。
+      // run.start/run.cancel 的确定无效果可解决控制依赖；其它重试/阻塞与 writer 占用由 ledger/scheduler 管。
       if (status.outcome !== 'applied') {
         const result=editor.updateRuntime(runtime=>{const ledger=createLedger(runtime.ledger),receipts=new Map(runtime.receipts);ledger.result(request.id,status.outcome,status.error);if(status.outcome==='not-applied'&&['run.start','run.cancel'].includes(request.kind??''))ledger.resolveNoEffect(request.id);if(status.canonical!==undefined)receipts.set(request.id,freeze(status.canonical));return Object.freeze({...runtime,ledger:ledger.getSnapshot(),receipts:readMap(receipts)});},root.rootRevision);
         if(result.status==='rejected')throw fault(result.code,result.targets);return;
       }
-      // 取消是控制结果，不直接用响应替换文档；提高 controlEpoch 使在途旧轮询失效，并继续读尾事件。
+      // run.cancel 没有文档提案：只更新任务事实/回执/ledger，再异步通知 tracker 追尾。
+      // controlEpoch++ 让旧轮询页失效；hasMore=true 继续取取消后的事件，不把“取消受理”当作事件已读完。
       if(request.kind==='run.cancel'){
         const receipts=new Map(previous.receipts);if(status.canonical!==undefined)receipts.set(request.id,freeze(status.canonical));
         try{
@@ -531,7 +581,8 @@ export async function openProjectEngine(options: EngineOptions) {
           queueMicrotask(()=>runTracker.notify([run.id]));return;
         }catch(error){ledger.result(request.id,'applied',(error as Error).message,false);const result=editor.updateRuntime(()=>Object.freeze({...previous,receipts:readMap(receipts),ledger:ledger.getSnapshot()}),root.rootRevision);if(result.status==='rejected')throw fault(result.code,result.targets);report(error);return{blocked:true};}
       }
-      // 上传回执只更新资源已存储事实；资源 ID 和原字节长度必须与冻结请求关联的记录一致。
+      // asset.upload 成功只把 stored 写回资源及解决 ledger，不替换元素数据，不在此删除本地原文件。
+      // 先由 assets.accept 校验协议证据，再核 stored ID/长度；显示 URL、共享仓库提升与回收走各自链路。
       if (request.kind === 'asset.upload') {
         const receipts = new Map(previous.receipts); if (status.canonical !== undefined) receipts.set(request.id, freeze(status.canonical));
         try {
@@ -572,12 +623,14 @@ export async function openProjectEngine(options: EngineOptions) {
           const version = proposal.versions.get(canvas);
           if (!version || version <= request.expectedVersions[canvas] || version < (previous.versions.get(canvas) ?? 0)) throw fault('stale_canonical_version', [canvas]);
         }
-        // A codec cannot roll back an unrelated canvas while reconciling this request.
+        // 不在本次写入集合中的已知 canvas，版本、canvas 记录及直接 owner 成员必须保持 ACK 原值。
+        // 这是参与范围检查，不是以局部响应替换全图的许可；最终重放/发布还会校验候选文档。
         for (const [canvas, version] of previous.versions) if (!writtenCanvases.includes(canvas)) {
           if (proposal.versions.get(canvas) !== version || !equal(proposal.document.canvases.get(canvas), previous.acknowledged.canvases.get(canvas)) || !equal([...proposal.document.elements.values()].filter(element => element.ownerCanvasId === canvas), [...previous.acknowledged.elements.values()].filter(element => element.ownerCanvasId === canvas))) throw fault('canonical_scope_mismatch', [canvas]);
         }
         ledger.result(request.id, 'applied');
-        // 先把回执模型复制为独立 ACK，再只重放仍未解决的本地意图，保留用户随后做出的编辑。
+        // 在私有 ledger 中先解决本次请求，再从回执模型捕获 ACK，重放其它未决意图得到 working。
+        // 本地后续编辑不会因为服务端返回了较早模型而丢失；ACK、working、ledger 直到 reconcile 才一起公开。
         const acknowledged = createDocument(proposal.document.projectId, [...proposal.document.canvases.values()], [...proposal.document.elements.values()], proposal.document.tombstones);
         const document = replayPending(acknowledged, ledger.getSnapshot(), options.registry);
         conflicts.delete(request.id);
@@ -600,14 +653,14 @@ export async function openProjectEngine(options: EngineOptions) {
             if(compact!==status.canonical){const owned=freeze(clone(compact));if(!validJson(owned))throw fault('invalid_receipt_compaction');resolvedReceipts=new Map(receipts);resolvedReceipts.set(request.id,owned);}
           }catch(error){report(error);}
         }
-        // Keep the original map intact for a rejected final publication below.
+        // receipts 原表保留原回执；resolvedReceipts 只供成功候选使用，最终 reconcile 拒绝时仍回到原证据。
         const runtime: RuntimeState = Object.freeze({ ...previous, runs: readMap(runs), ledger: ledger.getSnapshot(), acknowledged, versions: appliedVersions, receipts: readMap(resolvedReceipts), conflicts: readMap(conflicts) });
         // loading v3+ 允许已就绪范围的 ACK 更新；只在这次同步 reconcile 内打开受控发布窗口。
         const oldAccepting=acceptingLoading;acceptingLoading=oldAccepting||(previous.loading?.version??0)>=3;let result:Result;try{result=editor.reconcile(document, runtime, root.rootRevision);}finally{acceptingLoading=oldAccepting;}
         if (result.status === 'rejected') throw fault(result.code, result.targets);
         if(action)queueMicrotask(()=>runTracker.notify([action.runId]));
       } catch (error) {
-        // Preserve both the known receipt and the user's working document. No rollback or lane release.
+        // 失败候选的 ACK/working/runs/压缩回执均不发布，另用旧 runtime 保存 applied-but-unreconciled 及原回执。
         // 从旧账本另起失败分支，避免候选 ledger 中的成功推进泄漏；保留参与画布占用等待恢复。
         const waiting = createLedger(previous.ledger); waiting.result(request.id, 'applied', (error as Error).message, false);
         conflicts.set(request.id, (error as Error).message || 'reconcile_conflict');
@@ -617,10 +670,12 @@ export async function openProjectEngine(options: EngineOptions) {
       }
     }
     // scheduler 只挑选和执行账本事实；注入的 persistThrough 保证请求身份及前置根先可靠保存。
-    // admit 另检查导入 seal、加载覆盖和加载完成保存屏障；v1/2 加载的整体暂停由下方 hold 实现。
+    // admit 另检查导入 seal、加载覆盖和加载完成保存屏障；v1/2 分支返回 true 不代表能发送，整体 hold 在下方。
+    // admit 是额外范围门禁，依赖、冻结/不确定结果、writer 占用及 durableGeneration 仍由 scheduler 自己校验。
     const scheduler = createScheduler({ admit:intent=>{const root=editor.getSnapshot();if(!importsMaySend(root.runtime.imports,durableImportSeals))return false;if(root.runtime.loading&&root.runtime.loading.version<3)return true;if(closing||closed||loadingCompletionRevision!==undefined&&durableRootRevision<loadingCompletionRevision)return false;return (root.runtime.loading?.version===6&&intent.operationType==='asset.upload'||loadingCanSend(root.runtime,operationCanvases(intent,root.document),root.document))&&(!root.runtime.loading||durableRootRevision>=root.rootRevision);},getLedger: () => editor.getSnapshot().runtime.ledger, mutate, persist:persistThrough,
       createId: options.createId ?? (() => crypto.randomUUID()),
-      /** 计算实际写入画布，自动尺寸补写还需验证 historyEffect 的版本与结构。 */
+      /** 沿用非空 intent.canvasIds，否则按变化和当前 working 推导参与画布；尺寸补写先验证 historyEffect。
+       * 这里只计算写入参与者，不分配锁；writer claim 与冻结 expectedVersions 在 scheduler/ledger 中建立。 */
       participants: intent => { if(intent.historyEffect)validateCreationSizeEffect(intent.historyEffect);return operationCanvases(intent, editor.getSnapshot().document); },
       /** 按操作种类生成请求描述。调度器负责随后冻结身份/请求体；这里不发网络请求。 */
       compile(intent, id) {
@@ -643,7 +698,8 @@ export async function openProjectEngine(options: EngineOptions) {
       // 批量编译是端口的显式能力，缺少时不假设协议支持多操作请求。
       compileBatch: options.persistence.compileBatch ? (intents, id) => options.persistence.compileBatch!(intents, id, editor.getSnapshot()) : undefined,
       /** 所有服务共用网络容量；上传先从可靠本地存储取字节并核对冻结长度/摘要。
-       * 不能用 fileWrites 里的尚未保存文件绕过持久化屏障，也不为重试重新生成请求身份。 */
+       * 不能用 fileWrites 里的尚未保存文件绕过持久化屏障，也不为重试重新生成请求身份。
+       * 上传的本地读取/摘要发生在 network.run 之前，不占远端网络槽；只把原字节交给 assets.upload。 */
       async submit(request, signal) {
         if (['run.start','run.cancel','run.apply'].includes(request.kind??'')) return options.runs ? network.run(signal, () => options.runs!.submit(request,signal)) : { outcome: 'unresolved', blocked: true, error: 'run_interpreter_unavailable' };
         if (request.kind !== 'asset.upload') return network.run(signal, () => options.persistence.submit(request, signal));
@@ -661,7 +717,9 @@ export async function openProjectEngine(options: EngineOptions) {
     if(initial.loading&&initial.loading.version<3)loadingRelease=scheduler.hold();
     /** 把完整读取合入渐进模型。fresh 表示新的权威读取；否则是当前来源流的最终补全。
      * 对照来源令牌、版本和所有权证据校验，再合成 ACK 并重放本地意图，一次发布退出 loading。
-     * 这里只记录完成 revision，真正解除发送屏障要等 writePrefix 确认该根可靠保存。 */
+     * 这里只记录完成 revision，真正解除发送屏障要等 writePrefix 确认该根可靠保存。
+     * 完成流读取与 fresh 刷新走不同证据：前者可合并加载期间 ACK，后者须先排除未确定请求。
+     * 函数返回领域 Result；异常可登记 loading 冲突，但不把失败的候选部分合入 working。 */
     function completeLoading(document:Document,versions:ReadonlyMap<Id,number>,settings:{fresh?:boolean;sourceToken?:string}={}):Result{
       try{assertWritable(false);const root=editor.getSnapshot(),previous=root.runtime;if(!previous.loading)throw fault('loading_not_active');
         // 新权威读取不能越过结果未确认的请求，否则无法区分读取包含了哪些本地写入。
@@ -686,7 +744,9 @@ export async function openProjectEngine(options: EngineOptions) {
       if(result.status==='rejected')throw fault(result.code,result.targets);
     }
     /** 协调一页生成事件：校验任务/游标/控制代次，依次采用新的模型事件，最后与游标一起发布。
-     * 有未确认写入或模型冲突时保留 pendingPage 和输出预览，working、ACK 与游标保持原值。 */
+     * 有未确认写入或模型冲突时保留 pendingPage 和输出预览，working、ACK 与游标保持原值。
+     * 依赖 RunPort.poll 保证页协议与事件顺序；此协调器不重复完整解析所有 RunPage 字段。
+     * 页内模型在私有 acknowledged/versions 上依次累积，最后一次 reconcile；不逐事件发布中间文档。 */
     function acceptRunPage(run: RunRecord, page: RunPage) {
       const root=editor.getSnapshot(),previous=root.runtime,current=previous.runs.get(run.id);
       if(!current || current.requestId!==run.requestId)throw fault('run_identity_mismatch');
@@ -704,7 +764,7 @@ export async function openProjectEngine(options: EngineOptions) {
           if(event.seq<=current.cursor || event.type!=='step.applied'&&!(event.type==='step.output'&&event.model&&typeof event.model==='object'&&!Array.isArray(event.model)&&event.model.complete===true))continue;
           const canvas=event.board_id as Id,version=event.canvas_version as number;
           if(!Number.isSafeInteger(version)||version<1)throw fault('invalid_run_response');
-          // A later document receipt already includes this event; never rewind its participant.
+          // 本地 ACK 版本已包含该事件就跳过，避免旧模型倒退；其余事件仍要按本页顺序继续协调。
           if(version<=(versions.get(canvas)??0))continue;
           // 完整上下文可能涉及多画布，所有参与者的未决请求都需先确认，不只检查事件主画布。
           const model=event.model as {[key:string]:Json}|undefined,context=model?.complete===true,participants=context?Object.keys(model.versions as {[key:string]:Json}):[canvas];
@@ -713,7 +773,8 @@ export async function openProjectEngine(options: EngineOptions) {
           // 同页前一个事件已更新 ACK/版本，后一个事件的解释应看到该临时累计结果。
           const snapshot={...root,runtime:{...previous,acknowledged,versions}};
           const proposal=options.runs.canonical(event,snapshot);
-          // 本地尚有几何/路径编辑时，服务端变更元素归属会改变其坐标语义，拒绝盲目重放。
+          // 额外检查未决 field geometry/path 目标的 owner 变化，避免将旧坐标语义重放到新分区。
+          // 此局部检查不宣称涵盖任意复合结构冲突；其它 before/owner/schema 条件仍由 replayPending 校验。
           for(const record of previous.ledger.operations.values())if(record.phase!=='resolved')for(const change of record.intent.changes)if(change.kind==='field'&&(change.field==='geometry'||change.field==='path')){const before=acknowledged.elements.get(change.target.id),after=proposal.document.elements.get(change.target.id);if(before&&after&&before.ownerCanvasId!==after.ownerCanvasId)throw fault('ownership_conflict',[change.target.id]);}
           acknowledged=proposal.document;versions=proposal.versions;
         }
@@ -728,7 +789,8 @@ export async function openProjectEngine(options: EngineOptions) {
       } catch(error) {
         // 等待写入回执属于可自动再试的协调条件；其它错误阻塞任务并登记冲突。
         const code=(error as Error).message;
-        // Save the page as evidence without overwriting local content or advancing the cursor.
+        // 整页保存为 pendingPage，同时保留可预览输出；不采用 try 中的临时 ACK/版本，也不推进 cursor。
+        // 仅 run_waiting_for_receipts 可自动轮询重试，协议/合并等其它错误登记 run 冲突并 blocked。
         const result=editor.updateRuntime(runtime=>{const runs=new Map(runtime.runs);runs.set(run.id,freeze({...current,outputs:page.outputs,outputEvents:[...outputEvents.values()],steps:page.steps,pendingPage:page,error:code,blocked:code!=='run_waiting_for_receipts'}));if(code!=='run_waiting_for_receipts')conflicts.set(`run:${run.id}`,code);return Object.freeze({...runtime,runs:readMap(runs),conflicts:readMap(conflicts)});},root.rootRevision);
         if(result.status==='rejected')throw fault(result.code,result.targets);
         if(code!=='run_waiting_for_receipts')report(error);
@@ -743,7 +805,9 @@ export async function openProjectEngine(options: EngineOptions) {
     const sessions = createSessions(editor);
     // 手势结束后重试默认尺寸补写，避免解码结果在用户拖动/缩放中途抢改几何。
     const unsubscribeSizing = sessions.subscribe(() => { if (!sessions.getSnapshot().gesture) queueDefaultSizes(); });
-    /** 每次成功发布后登记保存义务，再安排后台任务；通知只传现有操作 ID，不另造一份操作状态。 */
+    /** 每次成功发布先把完整 snapshot 按 rootRevision 加入 pending，再安排保存/后台发现微任务。
+     * scheduled 只合并保存触发，不丢中间根；任务通知在监听回调返回后执行，避免在发布栈里发 I/O。
+     * 订阅不创建第二份业务任务：operationIds/runs 均已在本次根中，后续只建立执行索引。 */
     const unsubscribe = editor.subscribe((commit, snapshot) => {
       pending.set(snapshot.rootRevision, snapshot);notifyDurability();
       // 新受理任务在后续微任务启动追尾，让本次根发布和监听通知先完成。
@@ -759,7 +823,9 @@ export async function openProjectEngine(options: EngineOptions) {
     /** 统一摘要入口，继承 sourceDigest 的注入选择与项目生命周期中止。 */
     async function digest(bytes:Blob,signal?:AbortSignal){return sourceDigest(bytes,signal);}
     /** 最多并发两个原文件摘要。只发现 waiting_digest 的上传事实，成功原子写摘要并解除阻塞。
-     * 失败保留可识别原因并退出自动发现条件，等待显式 retry，而非无限计算同一损坏文件。 */
+     * 失败保留可识别原因并退出自动发现条件，等待显式 retry，而非无限计算同一损坏文件。
+     * digestTasks 只是本项目两项并发的索引；共享 digest pool 可能再排队，摘要可先于本地 Blob 落盘完成。
+     * hash 与解除 waiting_digest 同根发布，通知 scheduler 后仍须过保存门禁才能上传。 */
     function prepareDigests() {
       if (closing || closed) return;
       for (const resource of editor.getSnapshot().runtime.resources.values()) {
@@ -782,20 +848,24 @@ export async function openProjectEngine(options: EngineOptions) {
             return Object.freeze({ ...previous, resources: readMap(resources), ledger: ledger.getSnapshot() });
           });
           if (result.status === 'rejected') throw fault(result.code, result.targets);
+          // 这里只通知已有上传操作变得可调度，不直接发送字节或生成新的 requestId。
           scheduler.notify([resource.operationId]);
         }).catch(error => { if (!closing && !closed) { const code=(error as {code?:string}).code;mutate(ledger => ledger.block(resource.operationId, [code&&digestFailures.has(code)?code:'resource_bytes_unavailable'])); report(error); } }).finally(() => { digestTasks.delete(resource.id); prepareDigests(); });
         digestTasks.set(resource.id, task);
       }
     }
     /** 并发两项图片尺寸准备，与上传摘要分别调度。优先解码本地原件，无字节时可用已存服务端尺寸。
-     * image 状态先写成 pending，完成时只更新仍指向同一 image 记录的资源，失败不会覆盖后来重试。 */
+     * image 状态先发布为 pending，完成时核 operationId 与原 image 对象身份，失败也不覆盖后来重试的记录。
+     * 有 options.images 才启动本函数的解码链；其缺省时 stored 尺寸由 prepareDefaultSizes 直接采用。
+     * imageTasks 在 finally 清理并继续发现下一项，任务完成不代表默认几何或上传已经完成。 */
     function prepareImages(){
       queueDefaultSizes();
       if(closing||closed||recovery||!options.images)return;
       for(const resource of editor.getSnapshot().runtime.resources.values()){
         if(imageTasks.size>=2)break;
         if(imageTasks.has(resource.id)||resource.image&&(resource.image.version!==1||resource.image.status!=='pending')||resource.retirement?.purgedAt!==undefined)continue;
-        // 先发布可恢复 pending，再由发布通知进入实际解码，避免隐形在途任务没有状态依据。
+        // 缺 image 时本轮只发布 pending 并返回，由根订阅再次发现任务；不在同一发布栈里启动解码。
+        // “可恢复”表示根中已有任务声明，可靠性仍需后续 persist，不要求解码开始前单独等磁盘回执。
         if(!resource.image){editor.updateRuntime(previous=>{const current=previous.resources.get(resource.id);if(!current||current.image)return previous;const resources=new Map(previous.resources);resources.set(resource.id,freeze({...current,image:{version:1 as const,status:'pending' as const}}));return Object.freeze({...previous,resources:readMap(resources)});});return;}
         const task=(async()=>{
           const bytes=fileWrites.get(resource.id)??await options.storage.readFile(leader,resource.id);
@@ -809,7 +879,8 @@ export async function openProjectEngine(options: EngineOptions) {
         })().catch(error=>{if(closing||closed||recovery)return;const code=(error as{code?:string}).code??'image_decode_failed';editor.updateRuntime(previous=>{const current=previous.resources.get(resource.id);if(!current||current.operationId!==resource.operationId||current.image!==resource.image)return previous;const resources=new Map(previous.resources);resources.set(resource.id,freeze({...current,image:{version:1 as const,status:'failed' as const,code}}));return Object.freeze({...previous,resources:readMap(resources)});});}).finally(()=>{imageTasks.delete(resource.id);prepareImages();});imageTasks.set(resource.id,task);
       }
     }
-    /** 将多个尺寸补写通知合并为一次宏任务；不是网络重试时刻，也不忙等尺寸解码。 */
+    /** 将多个尺寸补写通知合并为一个0ms timer；只要有 pending grant 就可排队，不保证尺寸现在已可用。
+     * 定时器执行前先清 sizingTask，允许本轮发布触发后续 grant 的新检查；Promise 供关闭流程等待。 */
     function queueDefaultSizes() {
       if (sizingTask || closing || closed || recovery || ![...editor.getSnapshot().runtime.resources.values()].some(resource => resource.sizing?.version === 1 && resource.sizing.grants.some(grant => grant.status === 'pending'))) return;
       // A scheduling yield, not a logical retry deadline: avoid a self-extending
@@ -817,7 +888,9 @@ export async function openProjectEngine(options: EngineOptions) {
       sizingTask = new Promise(resolve => { setTimeout(() => { sizingTask = undefined; try { prepareDefaultSizes(); } catch (error) { report(error); } finally { resolve(); } }, 0); });
     }
     /** 一次最多处理一项创建尺寸授权。仅在无手势/无恢复时，把原始比例适配到当前宽度和单位约束。
-     * resolveCreationSize 验证目标代次与创建历史，补写同一历史单元；不能改写任意已编辑对象。 */
+     * resolveCreationSize 验证目标代次与创建历史，补写同一历史单元；不能改写任意已编辑对象。
+     * 尺寸已知且目标为 node 才尝试：保留当前宽度/图片比例，按单位尺度约束双边，再转为接口单位。
+     * 成功的 historyEffect 在 reduceRuntime 中结清 grant；拒绝或无净变化则在下面显式结清，避免反复空转。 */
     function prepareDefaultSizes() {
       if (closing || closed || recovery || sessions.getSnapshot().gesture) return;
       const root = editor.getSnapshot();
@@ -847,11 +920,13 @@ export async function openProjectEngine(options: EngineOptions) {
             });
             if (result.status === 'rejected') report(fault(result.code, result.targets));
           }
-          return; // One publication per pump; its notification schedules further grants.
+          // 每轮只尝试一项可处理 grant；可能还有结清状态的派生发布，后续项由根/手势/任务通知再次触发。
+          return;
         }
       }
     }
-    /** 显式重试把 blocked grant 恢复为 pending，不改已应用项；重新排一次尺寸检查。 */
+    /** 显式重试把 blocked grant 恢复为 pending 并清错误；不复活 revoked，不修改 applied 项。
+     * 只重排尺寸检查，不重新上传/解码文件；入口调用者负责生命周期准入。 */
     function retryDefaultSizes() {
       editor.updateRuntime(previous => {
         const resources = new Map(previous.resources); let changed = false;
@@ -864,7 +939,8 @@ export async function openProjectEngine(options: EngineOptions) {
     }
     /** 将没有文档 changes 的取消/应用动作登记为逻辑操作。调用方先做业务校验，
      * apply 等待所有旧未决操作；cancel 不添加这些依赖，以便及时控制服务端任务。
-     * 只更新账本，返回的 revision 仍是当前文档 revision，发送由后续调度完成。 */
+     * 只更新 ledger/runtime，产生新 rootRevision 而文档 revision 保持原值；返回 applied 表示本地接纳。
+     * id/sequence 只分配一次，依赖冻结在意图里；发送/查询/服务回执由后续 scheduler 使用相同身份处理。 */
     function queueRunAction(operationType:'run.cancel'|'run.apply',action:RunCancelInput|RunApplyInput):Result {
       const root=editor.getSnapshot();let sequence=1;for(const record of root.runtime.ledger.operations.values())sequence=Math.max(sequence,record.intent.sequence+1);
       const id=createId(),intent={id,operationType,action,operationSchemaVersion:1,sequence,origin:'user',canvasIds:operationType==='run.apply'?[(action as RunApplyInput).targetCanvasId]:[],changes:[],dependencies:operationType==='run.cancel'?[]:[...root.runtime.ledger.operations.values()].filter(record=>record.phase!=='resolved').map(record=>record.intent.id)} as OperationIntent;
@@ -876,13 +952,16 @@ export async function openProjectEngine(options: EngineOptions) {
     /** 从唯一根读取当前作业，不以 runner 捕获的旧对象代替可恢复事实。 */
     function getImport(id:Id){const job=editor.getSnapshot().runtime.imports?.get(id);if(!job)throw fault('import_missing',[id]);return job;}
     /** 仅发布作业元数据；generation 乐观校验防止旧异步结果覆盖暂停/取消/替换后的作业。
-     * integrityOwner 只在本次同步更新内允许该 job 推进校验信息，finally 撤销权限。 */
+     * integrityOwner 只在本次同步更新内允许该 job 推进校验信息，finally 撤销权限。
+     * 此内部入口再查宿主 changes.apply 策略，原样采用 job（旧版仅升外层 version）；不是任意外来 job 的完整捕获器。
+     * 不在此 persist 或调整传入 generation，调用方须先构造正确候选并等待所需可靠屏障。 */
     function publishImport(job:ImportJob,expectedGeneration:number){
       assertImportWritable();const permission=options.policy?.({type:'changes.apply',changes:[]},editor.getSnapshot().document);if(permission&&!permission.enabled)throw fault(permission.code,permission.targets);
       integrityOwner=job.id;try{const result=editor.updateRuntime(previous=>{const imports=new Map(previous.imports??[]);if(imports.get(job.id)?.generation!==expectedGeneration)throw fault('stale_import_job');imports.set(job.id,job.version===3?job:freeze({...job,version:3 as const}));return Object.freeze({...previous,imports:readMap(imports)});});if(result.status==='rejected')throw fault(result.code,result.targets);}finally{integrityOwner=undefined;}
     }
     /** 为新建检查点声明各层记录容器的所有权，便于增量恢复编码复用。
-     * dataRecord/dataArray 不代表所有子数据也归这里所有，不跳过后续结构与内容校验。 */
+     * dataRecord/dataArray 不代表所有子数据也归这里所有，不跳过后续结构与内容校验。
+     * 仅重建 job/source/preparation 外壳并标记 allocationIds 容器，嵌套只读值可复用，未进行 JSON 深复制。 */
     function importCheckpoint(job:ImportJob):ImportJob {
       return dataRecord(freeze({...job,
         ...(job.source?{source:dataRecord(freeze({...job.source}))}:{}),
@@ -890,7 +969,8 @@ export async function openProjectEngine(options: EngineOptions) {
       }));
     }
     /** 将当前分块读取证明附入检查点；SHA/校验错误以根中最新值为准，
-     * 防止前台解析的旧 job 覆盖后台全文件验证刚发布的结果。 */
+     * 防止前台解析的旧 job 覆盖后台全文件验证刚发布的结果。
+     * context.reader 提供当前读证明；源 fileId 必须对应该 context，本函数不读字节或自行生成 SHA。 */
     function checkpointImportSource(job:ImportJob):ImportJob{
       if(job.source?.integrityVersion!==2)return job;
       const context=proofReaders.get(job.id),current=editor.getSnapshot().runtime.imports?.get(job.id)?.source;
@@ -899,19 +979,23 @@ export async function openProjectEngine(options: EngineOptions) {
       return importCheckpoint({...job,source:{...source,readProof:context.reader.getProof(),...(current?.sha256?{sha256:current.sha256}:{}),...(current?.integrityError?{integrityError:current.integrityError}:{})}});
     }
     /** 文件校验失败增加 generation，保留已取消/部分完成状态，其余转为暂停。
-     * 错误写入源证据，既有已提交内容保留；短暂 hold 触发 runner 的暂停边界，不持有永久暂停租约。 */
+     * 错误写入 source.integrityError 与 job.error，阻止封存/发送，既有已提交内容不回滚。
+     * 短暂 hold 请求中止 runner 旧 pump 后立即释放；job 已 paused（或保留终态），不会因此自动续跑。 */
     function failImportVerification(job:ImportJob,error:unknown){
       const code=(error as {code?:string}).code??'import_source_verification_failed';
       publishImport(importCheckpoint({...job,generation:job.generation+1,status:['cancelled','partial'].includes(job.status)?job.status:'paused',source:{...job.source!,integrityError:code},error:code}),job.generation);
       const release=importRunners.get(job.id)?.hold();release?.();report(error);
     }
     /** 每 job 单飞的后台完整性校验：先核对已有分块证明，再计算整文件 SHA。
-     * 中止/关闭/全局 hold 时不把取消当损坏；真正失败记录证据，成功保存 seal 后才允许相应同步。 */
+     * 中止/关闭/全局 hold 时不把取消当损坏；真正失败记录证据，成功保存 seal 后才允许相应同步。
+     * 工作基于固定 Blob/reader，采纳时查来源身份而非要求 generation 不变，允许解析进度同期正常前进。
+     * 成功封存沿用当前 job.generation，只替换完整性证据；publish 的授权窗口与 durableImportSeals 保存门仍生效。 */
     function verifyImportSource(id:Id,context:{fileId:Id;bytes:Blob;reader:ReturnType<typeof createImportReadProof>}):Promise<void>{
       // 已中止的旧实例要先结束，再确认上下文仍有效才重建；不能并行验证两个同名来源。
       const active=verificationTasks.get(id);if(active)return active.controller.signal.aborted?active.promise.then(()=>{if(!closing&&!closed&&!importHolds.size&&proofReaders.get(id)===context&&sourceNeedsSeal(getImport(id)))return verifyImportSource(id,context);}):active.promise;
       const admitted=getImport(id),controller=new AbortController(),signal=AbortSignal.any([controller.signal,digestLifecycle.signal]);
-      /** 每次跨 await 后按 fingerprint、fileId、reader 身份复查，不把旧文件结果写给新作业。 */
+      /** 在采纳验证结果/记录错误时复查 fingerprint、fileId、reader 身份及 hold/关闭/取消信号。
+       * 不比较解析 generation；本函数只取当前事实，不自动发布或锁住整个 job。 */
       const current=()=>{signal.throwIfAborted();if(closing||closed||importHolds.size)throw fault('import_aborted');const job=getImport(id);if(job.sourceFingerprint!==admitted.sourceFingerprint||job.source?.fileId!==context.fileId||proofReaders.get(id)!==context)throw fault('import_identity_changed');return job;};
       const promise=(async()=>{
         let sha256:string;
@@ -923,7 +1007,8 @@ export async function openProjectEngine(options: EngineOptions) {
       })().catch(error=>{if(!signal.aborted&&!closing&&!closed)report(error);}).finally(()=>{if(verificationTasks.get(id)?.controller===controller)verificationTasks.delete(id);});
       verificationTasks.set(id,{controller,promise});return promise;
     }
-    /** 重建读取器前先中止并等验证结束、关闭 runner，最后释放分块证明缓存；持久作业不删除。 */
+    /** 重建读取器前先请求中止并等待验证结束，再 close runner，最后释放 reader 缓存。
+     * 删除的是 verification/runner/proof 执行索引，不删持久 job、源 Blob、已加入内容或已存 readProof。 */
     async function resetImportReader(id:Id){
       const active=verificationTasks.get(id);active?.controller.abort();if(active)await active.promise;
       const runner=importRunners.get(id);if(runner){await runner.close();importRunners.delete(id);}
@@ -934,28 +1019,33 @@ export async function openProjectEngine(options: EngineOptions) {
     // 暂停期间被中断、尚未建立 runner 的任务要记下，释放 hold 后才能重新装配。
     const deferredImportLoads=new Set<Id>();
     /** 可嵌套全局导入暂停：中止准备/验证，给已装配 runner 各加一个 hold。
-     * 释放只撤销本 token 的租约，再按根中状态启动需要恢复的任务；不把业务 status 改成 cancelled。 */
+     * 释放只撤销本 token 的租约，再按根中状态启动需要恢复的任务；不把业务 status 改成 cancelled。
+     * hold 本身同步返回，不等待这些任务退出；runner 的 hold 可嵌套，最后一个租约释放后才允许续跑。 */
     function holdImports(){for(const id of importLoads.keys())if(!importRunners.has(id))deferredImportLoads.add(id);const token=Symbol(),releases=new Map<Id,()=>void>();importHolds.set(token,releases);for(const controller of preparationControllers.values())controller.abort();for(const {controller}of verificationTasks.values())controller.abort();for(const[id,runner]of importRunners)releases.set(id,runner.hold());return()=>{if(!importHolds.delete(token))return;for(const release of releases.values())release();if(!closing&&!closed)for(const job of editor.getSnapshot().runtime.imports?.values()??[])if(sourceNeedsSeal(job)||['running','preparing'].includes(job.status)&&!importRunners.has(job.id))void loadImport(job.id);};}
     /** 从固定复制快照恢复规划。规划版本决定生成可流式读取的计划，或旧版 NDJSON 文件。
-     * 期间不断保存 ID 分配/步骤检查点，保证恢复后新元素身份稳定；此阶段还未向画布加入元素。 */
+     * 按检查点保存 ID 分配/步骤，续跑重用已保存的映射；尚未被 checkpoint 持久化的工作仍可重算。
+     * 本阶段只发布 preparing/计划/源文件事实，不创建画布元素；实际内容随后由普通导入 runner 逐批加入。 */
     async function materializeCopy(id:Id,bytes:Blob,controller:AbortController){
       const admitted=getImport(id),preparation=admitted.preparation;
       if(!preparation||admitted.source?.kind!=='duplicate-snapshot')throw fault('invalid_copy_preparation');
-      /** 复制规划只接受原 fingerprint 且仍 preparing 的作业；关闭、hold、取消均使旧结果失效。 */
+      /** 要求同 fingerprint 且仍 preparing，另查 signal/关闭/hold；允许本规划器自己的 generation 前进。
+       * 这不是逐字段验证全部 source 的入口，源文件稳定身份仍由装配与持久任务合同约束。 */
       const check=()=>{const job=getImport(id);if(controller.signal.aborted||closing||closed||importHolds.size||job.status!=='preparing'||job.sourceFingerprint!==admitted.sourceFingerprint)throw fault('copy_aborted');return job;};
       // 先保存快照作业再规划；v2 索引快照可按需读取，旧快照走完整解码。
       await persist();check();const indexed=admitted.source.snapshotVersion===2?await openIndexedCopySnapshot(bytes,options.scope.projectId,options.registry,controller.signal):undefined,document=indexed?.document??await decodeCopySnapshot(bytes,options.scope.projectId,options.registry,controller.signal);
       // 渐进模型还要证明复制快照对应合法来源范围；类型/复制声明变化则拒绝续用旧规划器。
       validateLoadingCopySource(editor.getSnapshot(),admitted,document);
       if(copyRegistrySignature(document,options.registry)!==preparation.registrySignature)throw fault('copy_interpreter_changed');
-      // 新规划器持久化拓扑与稳定 ID，不先展开所有复制数据为另一份 NDJSON。
+      // v3/v4 准备协议产出 lazy emit 计划；v4 可配 format2 索引快照，避免再展开一份完整复制 NDJSON。
+      // checkpoint 回调发布向前的步骤并 persist；最终返回的计划仍需下方另行发布，不能只依赖最后一次回调。
       if(preparation.version===3||preparation.version===4){
         const state=await prepareDuplicateStream(document,options.registry,preparation.selection,{worldOffset:preparation.worldOffset,createId},{sourceToken:admitted.source.sha256!,schemaToken:preparation.registrySignature,checkpoint:preparation.planner,topologyOnly:!!indexed},{signal:controller.signal,checkpointIntervalMs:50,maxStepsPerCheckpoint:8192,checkpoint:async state=>{
           // 只采纳向前推进的 planner 检查点，保存完成后再继续规划，避免恢复丢失已分配身份。
           const job=check(),previous=job.preparation!;if(previous.planner&&state.steps<=previous.steps)return;
           publishImport(importCheckpoint({...job,generation:job.generation+1,preparation:{...previous,steps:state.steps,allocationIds:[...state.elementIds,...state.canvasIds].map(pair=>pair[1]),planner:state}}),job.generation);await persist();check();
         }}),job=check();assertNativeImportTarget(job,editor.getSnapshot().document);
-        // 将旧 ID → 新 ID 和计划一起发布为 running；移除 preparation 后由普通导入 runner 逐批落图。
+        // 以 element:/canvas: 命名空间把旧 ID→新 ID 放进 stableIds，与 emit 计划一起转 running，清 preparation。
+        // 原快照字节继续作读取源，parserVersion 改2表示按计划 ordinal 读取；此发布本身尚不等于已经落盘。
         const stableIds=dataRecord(Object.fromEntries([...state.elementIds.map(([old,id])=>[`element:${old}`,id]),...state.canvasIds.map(([old,id])=>[`canvas:${old}`,id])])),next={...job,generation:job.generation+1,parserVersion:2,status:'running' as const,stableIds,source:{...job.source!,kind:'duplicate-plan' as const,plan:state,copy:dataRecord({sourceRevision:job.source!.copy!.sourceRevision,roots:dataArray(state.roots.map(old=>stableIds[`element:${old}`]))})}};delete next.preparation;delete next.error;
         publishImport(importCheckpoint(next),job.generation);return{job:getImport(id),bytes,document,indexed};
       }
@@ -969,21 +1059,25 @@ export async function openProjectEngine(options: EngineOptions) {
         if(steps<=previous.steps&&allocationIds.length===previous.allocationIds.length)return;
         publishImport(importCheckpoint({...job,generation:job.generation+1,preparation:{...previous,steps:Math.max(previous.steps,steps),allocationIds:[...allocationIds]}}),job.generation);await persist();check();
       }});
-      // 旧解释器若消耗的 ID 数量变了，原分配顺序已不可信，不能静默生成另一份复制结果。
+      // v1 续跑按 allocationIds 消费顺序重放分配；消耗数量不同就拒绝，防旧 checkpoint 被新解释器静默重解释。
+      // 新 createId 分配不做外部回滚，持久化检查点才定义后续重开必须复用的身份集合。
       check();if(preparation.version===1&&cursor!==allocationIds.length)throw fault('copy_interpreter_changed');
       // 旧版计划编码成固定 NDJSON 并算 SHA；异步完成后再次校验目标入口及当前业务策略。
       const encoded=await encodeDuplicateSource(document,options.registry,plan,controller.signal),sha256=await sourceDigest(encoded,controller.signal),job=check();assertImportWritable();assertNativeImportTarget(job,editor.getSnapshot().document);
       const permission=options.policy?.({type:'changes.apply',changes:plan.changes},editor.getSnapshot().document);if(permission&&!permission.enabled)throw fault(permission.code,permission.targets);
       const fileId=createId(),runtime=editor.getSnapshot().runtime;if(!fileId||fileWrites.has(fileId)||runtime.resources.has(fileId)||[...(runtime.imports?.values()??[])].some(job=>job.source?.fileId===fileId))throw fault('import_identity_conflict');
       const stableIds=Object.fromEntries([...Object.entries(plan.elementIds).map(([old,id])=>[`element:${old}`,id]),...Object.entries(plan.canvasIds).map(([old,id])=>[`canvas:${old}`,id])]);
-      // 新源替换旧快照时把原文件保留在 previousFiles，后续清理仍需保留期与引用证明。
+      // 旧路径把复制结果写成新的固定 NDJSON 源，指纹绑定新 fileId/长度；不是原地改写旧快照 Blob。
+      // 原文件进入 previousFiles，引用/保留期证明仍约束后续清理，不能在转换成功时直接删除。
       const next={...job,generation:job.generation+1,status:'running' as const,stableIds,sourceFingerprint:`local-file:${fileId}:${encoded.size}`,source:{...job.source!,previousFiles:[...(job.source!.previousFiles??[]),{fileId:job.source!.fileId,byteLength:job.source!.byteLength,...(job.source!.sha256?{sha256:job.source!.sha256}:{})}],kind:'duplicate-ndjson' as const,fileId,byteLength:encoded.size,sha256,integrityVersion:1 as const,copy:{sourceRevision:job.source!.copy!.sourceRevision,roots:plan.roots}}};delete next.preparation;delete next.error;
       // 先把字节放入待保存集再发布引用它的根，发布失败则撤回本次字节暂存。
       fileWrites.set(fileId,encoded);try{publishImport(importCheckpoint(next),job.generation);}catch(error){fileWrites.delete(fileId);throw error;}
       return{job:getImport(id),bytes:encoded,document:undefined,indexed:undefined};
     }
     /** 按 job 装配或复用导入执行器。验证来源、选择协议解析器、准备依赖与资源，再逐批提交。
-     * importLoads 是装配任务的单飞表，importRunners 是执行器表，两者都从持久 job 派生。 */
+     * importLoads 是装配任务的单飞表，importRunners 是执行器表，两者都从持久 job 派生。
+     * 返回 Promise 等装配/校验前置步骤，不等 runner 消费完整源；runner.start 与后台 seal 可继续执行。
+     * 需要时重开证明读取器，按持久 source.kind/parserVersion 选实现；不把扩展名或当前 UI 选择当协议。 */
     function loadImport(id:Id):Promise<void>{
       // 重复调用共享正在装配的任务；已有 runner 时只补 seal/继续运行，不重复解析和提交。
       if(importLoads.has(id))return importLoads.get(id)!;
@@ -1001,14 +1095,16 @@ export async function openProjectEngine(options: EngineOptions) {
         const latest=getImport(id);if(latest.sourceFingerprint!==job.sourceFingerprint||latest.source?.fileId!==source.fileId||['completed','partial','cancelled'].includes(latest.status)&&(source.integrityVersion!==2||!sourceNeedsSeal(latest)))return;
         if(!bytes)throw fault('import_source_unavailable');if(bytes.size!==source.byteLength)throw fault('import_source_changed');
         let readBytes:ReturnType<typeof createImportReadProof>['port']|undefined;
-        // 分块协议可在按需验证读取的同时做全文件校验；已有 SHA 则先确认整文件匹配再继续。
+        // integrity-v2 先重验已保存 proof，再把 reader.port 注入解析器，后续每次读仍受块证明约束。
+        // 无 SHA 时后台 seal 与解析并行；已有 SHA 时先等 verifying，校验失败会把 job 暂停而不继续加入。
         if(source.integrityVersion===2){
           let context=proofReaders.get(id);if(!context||context.fileId!==source.fileId){context={fileId:source.fileId,bytes,reader:createImportReadProof({bytes,fileId:source.fileId,proof:source.readProof})};proofReaders.set(id,context);}
           // 恢复先重验已保存分块证明；后续解析读口同样经过 reader，不能直接绕过它读取任意字节。
           await context.reader.verify(preparationController.signal);const checking=verifyImportSource(id,context);if(source.sha256)await checking;
           job=getImport(id);source=job.source!;if(preparationController.signal.aborted||['completed','partial','cancelled','paused'].includes(job.status)||importHolds.size)return;readBytes=context.reader.port;
         }else{
-        // 旧完整性协议在开始解析前计算全文件摘要，不用新的分块语义猜测旧格式。
+        // integrity-v1 先全文件 SHA，再装配解析器；缺 SHA 的旧空任务可发布一份新证据并推进 generation。
+        // 这条路径没有 v2 的按块渐进读证明，不能仅因文件相同就交换解释语义。
         if(source.integrityVersion!==1)throw fault('import_source_integrity_unavailable');
         const sha256=await sourceDigest(bytes,preparationController.signal);
         if(closing||closed)return;
@@ -1027,15 +1123,20 @@ export async function openProjectEngine(options: EngineOptions) {
         const importSource=source.kind==='duplicate-plan'?createDuplicatePlanSource(copyDocument??await decodeCopySnapshot(bytes,options.scope.projectId,options.registry,preparationController.signal),options.registry,source.plan!,job.sourceFingerprint,indexed?.readElement):source.kind==='native-document'?await (job.parserVersion===5?openStreamingDocumentImportSource:openDocumentImportSource)({bytes,readBytes,fingerprint:job.sourceFingerprint,signal:preparationController.signal}):source.kind==='native-json-array'?createJsonArrayImportSource({bytes,readBytes,fingerprint:job.sourceFingerprint}):createNdjsonImportSource({bytes,readBytes,fingerprint:job.sourceFingerprint});
         if(closing||closed||preparationController.signal.aborted||getImport(id).generation!==job.generation)return;
         if(importHolds.size){deferredImportLoads.add(id);return;}
-        // beforeCommit 与同步 commit 之间的临时资源授权；不是第二份持久资源表。
+        // authorizedImportAssets 只在一次 beforeCommit→commit 之间借用，下一次准备/中止会清空。
+        // WeakSet 只避免同一 signal 重复装 abort 监听；授权/Blob 缓存不是已发布 assetBindings 或 durable 写入。
         const authorizedImportAssets=new Map<Id,{ref:SharedAsset;bytes:Blob}>(),assetPreparationSignals=new WeakSet<AbortSignal>();
         // 乐观本地模式允许边解析边落图；普通批次最多128项，积压32根或存储失败时施加保存背压。
+        // parsed 阶段只有积压>=32根才等 persist；committed 阶段还会因 persistenceFailed 等保存恢复。
+        // 32是触发背压的当前队列观察值，不是跨所有生产者的严格内存容量；网络仍独立受可靠 seal 门禁限制。
         // SCC 等不可分依赖单元另有限制；128 并不承诺每128项一定让出或一定耗时很短。
         const runner=createImportRunner({maxBatch:128,optimisticLocal:true,checkpointSource:source.integrityVersion===2?checkpointImportSource:undefined,awaitDurabilityBudget:stage=>pending.size>=32||stage!=='parsed'&&persistenceFailed?persist():undefined,source:importSource,getJob:()=>getImport(id),createId,
           // prepare 只生成候选 unit/稳定 ID，实际文档修改由后面的同步事务执行。
           publish:publishImport,prepare:(line,job,reserve)=>['duplicate-ndjson','duplicate-plan'].includes(job.source?.kind??'')?prepareDuplicateImport(line,job,reserve,options.registry):prepareNativeImport(line,job,reserve,editor.getSnapshot().document,options.registry,depot&&options.assets?.authority?options.assets.sourceURL:undefined),persist,onError:report,
-          /** 原生文档格式引用的共享资源先逐项授权、校验 URL、读取字节；批次累计不超过32MiB。
-           * 异步阶段不改业务根，失败清空准备材料；同步 commit 仍须重新核对 job/目标/依赖。 */
+          /** 仅 native-document 对引用资源逐项重新授权、校验 URL 并备好原 Blob；其它源由各自规则处理。
+           * 已有本地资源也先走授权，commit 再核对是否同一身份；不能用热缓存绕过当前远端权限。
+           * 32MiB 按每次 authorize 返回后的 Blob 长度累加，超限拒绝，不是下载过程中的总内存硬限。
+           * 异步阶段不发布业务根，失败清材料；runner 检查 generation 后，同步 commit 再查目标/依赖。 */
           async beforeCommit(units,job,signal){
             // 其它源格式不走该外部资源领用路径；其引用规则由各自 unit 准备/守卫处理。
             authorizedImportAssets.clear();if(job.source?.kind!=='native-document')return{enabled:true};
@@ -1045,14 +1146,16 @@ export async function openProjectEngine(options: EngineOptions) {
             try{for(const id of ids){const authorized=await depot.authorize(leader,{scope:options.assets.authority.scope,resolve:(id,abort)=>network.run(abort,()=>options.assets!.authority!.resolve(id,abort)),read:(id,abort)=>network.run(abort,()=>options.assets!.authority!.read(id,abort))},id,signal);signal.throwIfAborted();assertImportWritable();if(authorized.ref.asset.url!==options.assets.sourceURL(id))throw fault('asset_authorization_mismatch');total+=authorized.bytes.size;if(total>32*1024*1024)throw fault('import_asset_capacity');authorizedImportAssets.set(id,authorized);}return{enabled:true};}catch(error){authorizedImportAssets.clear();return{enabled:false,code:(error as {code?:string}).code??'import_asset_authorization_failed',targets:[]};}
           },
           /** 将一批元素/canvas、授权资源绑定及 next job 检查点放入一次 editor 发布。
-           * 失败回滚的只是本批临时领用材料；此前成功加入并显示的批次保持不变。 */
+           * 事务拒绝不发布本批文档/job，finally 撤回临时领用字节与授权上下文；此前成功批次保持不变。
+           * 允许的 unit 只有 before=null 的 element/canvas 创建；任意字段修改或删除都拒绝。 */
           commit(units,next,expected){
             // 消费一次 beforeCommit 材料，防止后续批次或重入误用上次授权。
             const preparedAssets=new Map(authorizedImportAssets);authorizedImportAssets.clear();
             assertImportWritable();if(importing)throw fault('reentrant_dispatch');const current=getImport(id);if(current.generation!==expected)throw fault('stale_import_job');
             // 等待资源授权期间目标或外部连线端点可能变化，提交前重新检查入口代次和依赖。
             try{assertNativeImportTarget(current,editor.getSnapshot().document);for(const unit of units){assertNativeImportDependencies(current,editor.getSnapshot().document,unit.dependencies);if(['duplicate-ndjson','duplicate-plan'].includes(current.source?.kind??''))assertDuplicateExternal({cursor:0,nextCursor:1,key:unit.key,value:unit.guard},current,editor.getSnapshot().document,options.registry);}}catch(error){return reject(error);}
-            // 临时登记待保存的领用字节，同时保存旧值，保证事务拒绝后可准确恢复原暂存集合。
+            // 已有上传资源须匹配 stored/digest；新领用先占 adoptedFiles 并记旧值，防和孤儿/源/待删文件撞 ID。
+            // 临时 rootRevision=MAX_SAFE_INTEGER 让旧根保存不提前采纳；事务成功后再绑定真实发布 revision。
             const previousFiles=new Map<Id,{readonly bytes:Blob;readonly rootRevision:number}|undefined>();let accepted=false;
             try{for(const [assetId,authorized]of preparedAssets){const runtime=editor.getSnapshot().runtime,own=runtime.resources.get(assetId);if(own){if(!own.stored||own.digest!==authorized.ref.digest||!equal(own.stored,authorized.ref.asset))throw fault('shared_asset_identity_conflict',[assetId]);continue;}if(runtime.orphanFiles?.has(assetId)||importFiles(runtime.imports).has(assetId)||fileWrites.has(assetId)||collectionReservations.has(assetId))throw fault('resource_identity_conflict',[assetId]);previousFiles.set(assetId,adoptedFiles.get(assetId));adoptedFiles.set(assetId,{bytes:authorized.bytes,rootRevision:Number.MAX_SAFE_INTEGER});}importAdoptions=[...preparedAssets].filter(([assetId])=>!editor.getSnapshot().runtime.resources.has(assetId)).map(([,value])=>value.ref);}catch(error){for(const [assetId,previous]of previousFiles)if(previous)adoptedFiles.set(assetId,previous);else adoptedFiles.delete(assetId);authorizedImportAssets.clear();return reject(error);}
             // reducer 在此同步窗口读 importing/importAdoptions，使 job 游标和新增元素同根更新。
@@ -1061,16 +1164,21 @@ export async function openProjectEngine(options: EngineOptions) {
             try{const result=editor.transaction(tx=>{for(const unit of units)for(const change of unit.changes){if(change.kind==='element'&&change.before===null&&change.after)tx.dispatch({type:'element.create',element:change.after});else if(change.kind==='canvas'&&change.before===null&&change.after)tx.dispatch({type:'canvas.create',canvas:change.after});else throw fault('invalid_native_import_unit');}},{label:['duplicate-ndjson','duplicate-plan'].includes(current.source?.kind??'')?'Duplicate selection':'Import canvas content',groupId:`import:${id}`});accepted=result.status==='applied';if(accepted)for(const assetId of previousFiles.keys())adoptedFiles.set(assetId,{bytes:preparedAssets.get(assetId)!.bytes,rootRevision:editor.getSnapshot().rootRevision});return result;}finally{importing=undefined;importAdoptions=[];if(!accepted)for(const [assetId,previous]of previousFiles)if(previous)adoptedFiles.set(assetId,previous);else adoptedFiles.delete(assetId);authorizedImportAssets.clear();}
           },
         });
-        // 装配完成后继承仍有效的全局 holds；业务 status=running 才启动加入画布的工作。
+        // 注册 runner 后继承所有仍有效的全局 hold，避免装配期间新增 hold 被漏掉。
+        // 只有根中 status=running 才启动消费；void start 不延长 loadImport Promise 到导入结束。
         importRunners.set(id,runner);for(const releases of importHolds.values())releases.set(id,runner.hold());
         if(getImport(id).status==='running')void runner.start();
       // 中止不改业务终态；真实读取损坏留下完整性错误，其它装配失败转 paused。
-      // finally 清除执行索引，仅在仍有延迟恢复义务且 job 可运行时重新装配，避免覆盖后来换源的状态。
+      // 失败收尾按最终 expectedFingerprint 判断归属：复制物化合法换源后也只能修改对应来源。
+      // v2 字节错误留 integrityError，其它非终态装配错误转 paused；失败不能清空已加入内容或重置稳定映射。
+      // finally 清执行索引；仅有 deferred 恢复义务、无全局 hold、且仍 running/preparing 时安排重装，不无限重试错误。
       })().catch(error=>{if(preparationController.signal.aborted)return;if(!closing&&!closed){try{const job=getImport(id);if(job.source?.integrityVersion===2&&!importRunners.has(id)&&!verificationTasks.has(id)){proofReaders.get(id)?.reader.close();proofReaders.delete(id);}if(job.sourceFingerprint!==expectedFingerprint)return;if(job.source?.integrityVersion===2&&(isImportByteFailure(error)||(error as {code?:string}).code==='import_source_unavailable')){failImportVerification(job,error);void persist().catch(report);return;}if(['completed','partial','cancelled','paused'].includes(job.status))return;publishImport(importCheckpoint({...job,generation:job.generation+1,status:'paused',error:(error as {code?:string}).code??'import_failed'}),job.generation);}catch{/* Recovery/identity fences retain the original job. */}report(error);}}).finally(()=>{preparationControllers.delete(id);importLoads.delete(id);if(!['running','preparing'].includes(getImport(id).status))deferredImportLoads.delete(id);if(!closing&&!closed&&!importHolds.size&&deferredImportLoads.delete(id)&&!importRunners.has(id)&&['running','preparing'].includes(getImport(id).status))queueMicrotask(()=>{if(!closing&&!closed)void loadImport(id);});});
       importLoads.set(id,task);return task;
     }
     /** 接收本地 Blob 并同步登记一个可恢复作业（源文件上限64MiB），随后后台读取解析。
-     * 文件 ID、源证明和目标入口代次从一开始就写进根，页面可立即观察 running，不等待全文件解析。 */
+     * 文件 ID、空读证明和目标入口代次从一开始写进根，页面可立即观察 running，不等全文件解析。
+     * fileWrites 先暂存源 Blob，登记根被拒绝则撤回；接受仅表示本地任务存在，磁盘保存与 SHA 封存随后完成。
+     * targetEntry 固定子分区入口代次，parserVersion 按显式 format 固定5/3/1，创建时不猜内容格式。 */
     function startNativeImport(bytes:Blob,targetCanvasId:Id,format:'ndjson'|'json-array'|'document'):Id{
         if(!['ndjson','json-array','document'].includes(format))throw fault('import_interpreter_unavailable');
         assertImportWritable();const loadingAdmission=loadingImportAdmission(editor.getSnapshot(),targetCanvasId);const permission=options.policy?.({type:'changes.apply',changes:[]},editor.getSnapshot().document);if(permission&&!permission.enabled)throw fault(permission.code,permission.targets);const canvas=editor.getSnapshot().document.canvases.get(targetCanvasId);if(!canvas)throw fault('canvas_not_loaded',[targetCanvasId]);if(!(bytes instanceof Blob)||bytes.size>64*1024*1024)throw fault('invalid_import_source');
@@ -1098,7 +1206,9 @@ export async function openProjectEngine(options: EngineOptions) {
       startDocument:(bytes:Blob,targetCanvasId:Id)=>startNativeImport(bytes,targetCanvasId,'document'),
       startJsonArray:(bytes:Blob,targetCanvasId:Id)=>startNativeImport(bytes,targetCanvasId,'json-array'),
       /** 捕获当前不可变文档和独立选择/偏移，异步编码索引快照，再登记 preparing 复制任务。
-       * 后续原画布编辑不会改变复制来源；完成编码不代表已创建全部副本。 */
+       * 先编码 captured.document 的完整索引快照，再用 selection 规划复制闭包；不是只序列化选中记录。
+       * Promise 返回的是已登记 preparing 的 job ID，不等待副本创建；快照编码后目标入口仍要在后续提交重查。
+       * 外部 signal 只覆盖本次编码/登记准备句柄，返回后由 imports.pause/cancel 控制作业生命周期。 */
       async duplicate(selection:readonly Target[],settings:{readonly worldOffset?:Point;readonly signal?:AbortSignal;readonly viewCanvasId?:Id}={}):Promise<Id>{
         assertImportWritable();if(collectionReservations.size)throw fault('resource_collection_in_progress',[...collectionReservations]);
         const permission=options.policy?.({type:'changes.apply',changes:[]},editor.getSnapshot().document);if(permission&&!permission.enabled)throw fault(permission.code,permission.targets);
@@ -1129,26 +1239,34 @@ export async function openProjectEngine(options: EngineOptions) {
         // 从编码开始到作业登记结束持有准备任务/pin；所有结束路径清除任务及外部 abort 监听。
         copyPreparations.set(controller,task);void task.finally(()=>{copyPreparations.delete(controller);signal?.removeEventListener('abort',abort);}).catch(()=>{});return task;
       },
-      /** 有 runner 就停在其批次边界；未装配时直接推进 job generation 并保存 paused。
-       * 分块来源的验证仍可能继续补齐已提交前缀的证据，不能把暂停当作删除来源。 */
+      /** 有 runner 则调用其 pause：发布 paused/保存并请求 abort，不额外等待 active 完全退出。
+       * 未装配则推进 generation；v1 请求中止准备，v2 可继续补齐来源证明，但不继续加入内容。
+       * 暂停不删除源文件、已加入内容或稳定映射；需要排空时仍须使用相关 settle/关闭流程。 */
       async pause(id:Id){assertImportWritable();const runner=importRunners.get(id);if(runner)await runner.pause();else{const job=getImport(id);if(['running','preparing'].includes(job.status)){if(job.source?.integrityVersion!==2)preparationControllers.get(id)?.abort();publishImport(importCheckpoint({...job,generation:job.generation+1,status:'paused'}),job.generation);await persist();}}},
-      /** 终态不重启；paused 先等旧装配/runner 结束，必要时重建证明读取器，再保存并恢复调度。
-       * 复制快照回 preparing，其它源回 running，避免跳过尚未完成的复制规划。 */
+      /** completed/partial/cancelled 不重启；已 running/preparing 仅确保 loadImport 装配。
+       * paused 先等旧装配/runner 收尾，v2 重建 reader，再保存现有根并恢复 scheduler，随后重新查状态。
+       * 复制快照回 preparing，其它源回 running；清 job.error 但不擅自清 source.integrityError，重验成功才解封。 */
       async resume(id:Id){assertImportWritable();const job=getImport(id);if(['completed','partial','cancelled'].includes(job.status))return;if(['running','preparing'].includes(job.status)){await loadImport(id);return;}await importLoads.get(id);await importRunners.get(id)?.settle();if(getImport(id).source?.integrityVersion===2)await resetImportReader(id);await persist();await scheduler.resume();assertImportWritable();const current=getImport(id);if(current.status!=='paused')return;const next={...current,generation:current.generation+1,status:current.source?.kind==='duplicate-snapshot'?'preparing' as const:'running' as const};delete next.error;publishImport(importCheckpoint(next),current.generation);await loadImport(id);},
-      /** 取消后续加入，保留已有内容；尚欠 seal 时仍可继续校验，证据完整才中止额外验证。 */
+      /** 取消后续加入并保存取消事实，保留成功内容；无 runner 的 preparing 任务也可在此取消。
+       * v2 若已加入内容但欠 seal，仍保留验证任务；无成功源项的取消任务不欠 seal，可请求中止额外验证。
+       * 不等同于撤销已同步操作、删除源文件或调用后台生成取消接口。 */
       async cancel(id:Id){assertImportWritable();const runner=importRunners.get(id);if(runner)await runner.cancel();else{const job=getImport(id);if(['running','preparing','paused'].includes(job.status)){if(job.source?.integrityVersion!==2)preparationControllers.get(id)?.abort();const next={...job,generation:job.generation+1,status:'cancelled' as const};delete next.error;publishImport(importCheckpoint(next),job.generation);await persist();}}if(!sourceNeedsSeal(getImport(id)))verificationTasks.get(id)?.controller.abort();},
     });
-    // 全部协调回调已接线后启动调度，恢复既有生成轮询和资源任务。
+    // 协调回调与根订阅都装配完才启动执行器；恢复的 run IDs 显式首次 notify，不能只等新发布发现。
+    // 工厂将控制面交回宿主时后台任务可已在运行，并非等所有网络/导入完成才返回。
     scheduler.start(); prepareDigests();prepareImages(); runTracker.notify([...initial.runs.keys()]);
     // 终态作业若仍欠 seal 也装配验证；running/preparing 则恢复尚未完成的内容处理。
     for(const job of initial.imports?.values()??[])if(sourceNeedsSeal(job)||['running','preparing'].includes(job.status))void loadImport(job.id);
     // 对外只暴露冻结的控制面；根快照由 editor 读取，异步执行器和持久化内部表不直接交给界面修改。
     return Object.freeze({
       editor, sessions, imports,
-      /** 渐进加载控制面：accept 合入同一流的前缀，complete 提交完整结果，resume 重新读取权威模型。 */
+      /** 渐进加载控制面：accept 合入同一流前缀，complete 提交完整结果，resume 重新读取权威模型。
+       * getState 返回当前根中的状态引用；accept 同步发布候选，complete/resume 成功路径另等本地保存。 */
       loading:Object.freeze({getState:()=>editor.getSnapshot().runtime.loading,
         /** 同一时间共享一个恢复读取。v3+ 等旧请求确认后先 hold 新发送，再读服务端，
-         * 避免读取期间又发出写入造成模型包含范围不明；finally 释放本次读取的暂停租约。 */
+         * 避免读取期间又发出写入造成模型包含范围不明；finally 释放本次读取的暂停租约。
+         * 等所有 request.phase=resolved，不只等 HTTP 回调；已 applied 但尚未协调的请求仍会阻止刷新。
+         * 不暂停本地编辑，completeLoading 会叠回期间未决意图；此读取不重启导入或替用户解决冲突。 */
         resume():Promise<Result>{
           if(loadingRead)return loadingRead;
           const task=(async()=>{assertWritable(false);if(!editor.getSnapshot().runtime.loading)return{status:'applied' as const,revision:editor.getSnapshot().revision,operationIds:[]};if(!options.persistence.read)throw fault('canonical_reader_unavailable');const controller=new AbortController();loadingReadController=controller;let releaseRead:(()=>void)|undefined;
@@ -1160,7 +1278,8 @@ export async function openProjectEngine(options: EngineOptions) {
           })();loadingRead=task.finally(()=>{if(loadingRead===wrapped)loadingRead=undefined;});const wrapped=loadingRead;return wrapped;
         },
         /** 校验来源前缀只能合法扩展，再合并期间已确认的修改并重放 pending；
-         * 原始读取 nextRead 与 working 分开保存，本地编辑不冒充服务端新增内容。 */
+         * 原始读取 nextRead 与 working 分开保存，本地编辑不冒充服务端新增内容。
+         * acceptingLoading 仅覆盖本次同步 reconcile，finally 撤销；返回 applied 仍须后台保存，并不等待持久回执。 */
         accept(document:Document,versions:ReadonlyMap<Id,number>,state:LoadingState):Result{
           try{assertWritable(false);const root=editor.getSnapshot(),previous=root.runtime;if(!previous.loading)throw fault('loading_not_active');const source=previous.loadingRead;validatePrefixExtension(source?.document??previous.acknowledged,source?.versions??previous.versions,previous.loading,document,versions,state,options.registry);const nextRead=Object.freeze({document:createDocument(document.projectId,[...document.canvases.values()],[...document.elements.values()],document.tombstones),versions:readMap(versions)}),proposal=mergeLoadingRead(previous,nextRead,options.registry),acknowledged=proposal.document,working=replayPending(acknowledged,previous.ledger,options.registry);acceptingLoading=true;return editor.reconcile(working,Object.freeze({...previous,loading:freeze(clone(state)),...(state.version>=3?{loadingRead:nextRead}:{}),versions:readMap(proposal.versions),acknowledged}),root.rootRevision);}catch(error){return reject(error);}finally{acceptingLoading=false;}
         },
@@ -1171,7 +1290,9 @@ export async function openProjectEngine(options: EngineOptions) {
       collectResources,collectImportSources,inventoryLocalFiles,collectOrphanFiles,
       getResourcePins:()=>resourceRetentionPins(editor.getSnapshot(),options.registry,displayPins,admissionPins(editor.getSnapshot())),
       /** 暂停调度/生成轮询/导入，排空在途协调并保存，再读取服务端模型生成审阅会话。
-       * prepare 本身不替用户丢弃编辑或改写原请求；发现冲突只返回诊断，发布发生在 apply/resolve。 */
+       * 不提前发布恢复候选；在途已准入任务仍可先完成并更新当前根，排空后捕获固定底稿。
+       * 暂停、保存、读服务端并验证已生效回执后尝试条件重放；重放冲突以诊断返回会话，不提前改文档。
+       * prepare 期间仍保存原 working/history/request 事实，用户取舍引起的新发布发生在 apply/resolve。 */
       async prepareRecovery(): Promise<RecoverySession> {
         assertWritable(false);
         if(!options.persistence.read)throw fault('canonical_reader_unavailable');
@@ -1191,6 +1312,7 @@ export async function openProjectEngine(options: EngineOptions) {
           await persist();assertCurrent();
           // 从已知 applied 回执推导可采用的候选证据；先保存现有根，不将未验证的候选提前发布。
           const staged=stageAppliedRecovery(editor.getSnapshot(),{persistence:options.persistence,runs:options.runs,assets:options.assets,now:runClock.now()});
+          // staged 只在私有候选中解决已验证 applied 证据；它保持底稿 rootRevision，用于后续乐观发布。
           const root=staged.snapshot,previous=root.runtime;
           // 读取后的根 revision 必须仍一致；后续计划不能建立在与当前状态不同的旧底稿上。
           const loaded=await network.run(controller.signal,()=>options.persistence.read!(controller.signal));assertCurrent();
@@ -1205,21 +1327,24 @@ export async function openProjectEngine(options: EngineOptions) {
           let committed:ConflictPlan|'refresh'|undefined,committedIds:readonly Id[]=[];
           // 只接受本会话实际生成的 plan 对象，拒绝调用方拼接或跨会话重用的方案。
           const plans=new WeakSet<ConflictPlan>();
-          /** 已发布后先过保存屏障，再恢复调度/轮询并释放会话。
-           * 保存失败继续持有暂停；再次调用可重试屏障，不重复发布相同恢复操作。 */
+          /** 发布成功后：persist→scheduler.resume→通知新操作/受影响 run→释放三类 hold。
+           * persist 或 resume 失败都保留已提交标记及会话，可再试 finish 而不重复发布恢复操作。
+           * 返回 applied 表示本地恢复发布/保存完成，不等于替代操作已获服务端 ACK 或生成任务结束。 */
           const finish=async()=>{if(previous.loading&&!editor.getSnapshot().runtime.loading)loadingCompletionRevision=editor.getSnapshot().rootRevision;await persist();assertCurrent();await scheduler.resume();assertCurrent();scheduler.notify(committedIds);runTracker.notify(staged.runIds);active.release();return{status:'applied' as const,revision:editor.getSnapshot().revision,operationIds:committedIds};};
           // 返回会话后，未发布可直接退出；已经发布则必须完成保存，cancel 不等于回滚已发布恢复。
           active.cancel=async()=>{if(recovery!==active)return;if(committed){await finish();return;}active.release();};
           return Object.freeze({baseRootRevision:root.rootRevision,canonical,acknowledgedRequestIds:staged.requestIds,
             pendingOperationIds:Object.freeze([...previous.ledger.operations.values()].filter(record=>record.phase!=='resolved').map(record=>record.intent.id)),
             ...(conflict?{conflict}:{}),
-            /** 在固定根上纯计算明确取舍的恢复方案，分配新操作身份并保存可审计备份。 */
+            /** 在固定底稿上计算恢复候选并分配新操作 ID，生成含审计备份的 plan；不发布/写磁盘。
+             * WeakSet 只登记本会话生成的对象身份，拒绝外部拼造；createId 的分配计数不会因放弃 plan 回滚。 */
             plan(choices:ReadonlyMap<Id,RecoveryChoice>){
               assertCurrent();if(committed)throw fault('recovery_already_committed');if(editor.getSnapshot().rootRevision!==root.rootRevision)throw fault('stale_plan');
               const plan=planConflictRecovery(root,canonical,choices,options.registry,createId,options.historyLimit??100);plans.add(plan);return plan;
             },
             /** 采用本会话方案：重查策略/生成输出适用性，发布文档、历史、账本、审计及资源 pin。
-             * 同一方案已发布时只重试 finish；不能接着换另一方案覆盖第一次发布。 */
+             * 同一方案已发布时只重试 finish；不能接着换另一方案覆盖第一次发布。
+             * 策略拒绝返回 rejected 并保留会话；通过后 reconcile 按原 rootRevision 同时发布 plan 文档/历史/操作和 runtime。 */
             async resolve(plan:ConflictPlan):Promise<Result>{
               assertCurrent();if(!plans.has(plan))throw fault('invalid_recovery_plan');if(committed&&committed!==plan)throw fault('recovery_already_committed');
               if(!committed){
@@ -1245,7 +1370,7 @@ export async function openProjectEngine(options: EngineOptions) {
                 if(result.status==='rejected')return result;
                 committed='refresh';
               }
-              // Persistence failure retains the hold; apply/cancel can retry this barrier without republishing.
+              // 首次发布后记 committed=refresh；保存失败时 apply/cancel 复用 finish，不再发布第二份刷新。
               return finish();
             },
             // 使用更新后的 cancel 语义，已提交会话仍需先完成可靠保存。
@@ -1253,7 +1378,8 @@ export async function openProjectEngine(options: EngineOptions) {
           });
         }catch(error){active.release();throw error;}
       },
-      /** 读取当前项目画布的模型目录，经过共享网络门；不创建生成任务。 */
+      /** 读取当前项目画布的模型目录，经过共享网络门；不创建生成任务或更新 Root。
+       * 只查画布存在/服务可用及网络门身份，不要求无恢复会话或完整模型；目录返回仍由端口解释。 */
       models(boardId: Id, signal: AbortSignal) {
         if(closing||closed||!options.runs)return Promise.reject(fault('run_interpreter_unavailable'));
         if(!editor.getSnapshot().document.canvases.has(boardId))return Promise.reject(fault('canvas_missing'));
@@ -1270,7 +1396,9 @@ export async function openProjectEngine(options: EngineOptions) {
         }catch(error){return reject(error);}
       },
       /** 用户明确采用冲突任务的一份输出。校验目标代次/任务成员/输出身份并防重复，
-       * 通过普通数据编辑取得 history；若内容本已相同，仍登记空 changes 的 run.apply 控制动作。 */
+       * 通过普通数据编辑取得 history；若内容本已相同，仍登记空 changes 的 run.apply 控制动作。
+       * 文本采用 text；图片采用 src/assetId，不把输出复制成新的正在执行任务或重复上传任务。
+       * applied 只表示本地接纳，服务应用回执仍需版本/目标身份核验，appliedOutputIds 在回执协调后更新。 */
       applyRunOutput(runId:Id,target:RunApplyInput['target'],outputId:Id):Result {
         try{
           assertWritable();if(!options.runs)throw fault('run_interpreter_unavailable');if(applying)throw fault('reentrant_dispatch');
@@ -1290,7 +1418,9 @@ export async function openProjectEngine(options: EngineOptions) {
         }catch(error){return reject(error);}finally{applying=undefined;}
       },
       /** 登记生成启动意图，真正受理/执行由服务完成。只允许当前已知的支持类型节点，
-       * 启动依赖所有旧未决操作，保证服务端生成所见输入先包含当前编辑；不在此直接请求模型。 */
+       * 启动依赖所有旧未决操作，保证服务端生成所见输入先包含当前编辑；不在此直接请求模型。
+       * 校验通用输入与目标类型/编辑能力，不在这里刷新模型目录或证明远端模型此刻可用。
+       * 未决 run.start 按目标 ID 保守占用；已有任务用 ID+incarnation/传播目标及 hasMore/pendingPage 判忙。 */
       startRun(input: RunInput): Result {
         try {
           assertWritable();
@@ -1313,7 +1443,8 @@ export async function openProjectEngine(options: EngineOptions) {
         }catch(error){return reject(error);}
       },
       /** 用新的权威模型刷新 ACK，再条件重放本地未决修改；未确认请求存在时拒绝模糊刷新。
-       * 与 prepareRecovery 不同，此入口只尝试安全重放，冲突时保留文档并登记诊断。 */
+       * 与 prepareRecovery 不同，此入口只尝试安全重放，冲突时保留文档并登记诊断。
+       * 不自行读取网络；调用方提供文档/版本。同步 applied 不等待 persist；loading 中转 completeLoading 的同类同步路径。 */
       refresh(document: Document, versions: ReadonlyMap<Id, number>): Result {
         if(editor.getSnapshot().runtime.loading)return completeLoading(document,versions,{fresh:true});
         const root = editor.getSnapshot(), previous = root.runtime;
@@ -1336,7 +1467,9 @@ export async function openProjectEngine(options: EngineOptions) {
       /** 查询图片暂存能力；渐进加载仅 v6 已完整画布开放，真正事务还需经过 editor 策略校验。 */
       canStageFiles(canvasId:Id){try{assertWritable(false);if(!options.assets)throw fault('asset_interpreter_unavailable');const snapshot=editor.getSnapshot();if(!snapshot.document.canvases.has(canvasId))throw fault('canvas_not_loaded',[canvasId]);if(snapshot.runtime.loading&&(snapshot.runtime.loading.version!==6||!loadingQueryCoverage(snapshot).completeCanvasIds.includes(canvasId)))throw fault('loading_scope_incomplete',[canvasId]);const permission=options.policy?.({type:'changes.apply',changes:[]},snapshot.document);if(permission&&!permission.enabled)throw fault(permission.code,permission.targets);return{enabled:true as const};}catch(error){const result=reject(error);return{enabled:false as const,code:result.code,targets:result.targets};}},
       /** 同步图片加入入口：校验字节/身份，暂存 Blob，再由 callback 在同一事务创建资源引用。
-       * reducer 同根建立上传意图和资源记录，后续异步摘要/上传；事务失败清理未被根采用的字节。 */
+       * reducer 同根建立上传意图和资源记录，后续异步摘要/上传；事务失败清理未被根采用的字节。
+       * callback 须同步使用 handles/tx 创建引用，不能 await 后继续提交；这是本地编辑接纳，不等上传完成。
+       * 文件名/MIME/长度在此筛选，实际图片解码与摘要另行验证；空净事务撤回本次待写 Blob。 */
       stageFiles(files: readonly StagedFile[], callback: (resources: readonly ResourceHandle[], transaction: Transaction) => unknown) {
         assertWritable(false);if(editor.getSnapshot().runtime.loading&&editor.getSnapshot().runtime.loading?.version!==6)throw fault('model_loading');
         if (staged.length||adopting) throw fault('reentrant_dispatch');
@@ -1358,7 +1491,9 @@ export async function openProjectEngine(options: EngineOptions) {
         } finally { staged = []; stagedDefaultSizes.clear();for (const resource of resources) if (!editor.getSnapshot().runtime.resources.has(resource.id)) fileWrites.delete(resource.id); }
       },
       /** 复用同工作区已存在的图片：先走服务授权/取字节，再用同步事务建立本项目绑定。
-       * 这条路径不重复创建上传任务；采用失败则还原原来的 adoptedFiles 暂存值。 */
+       * 这条路径不重复创建上传任务；采用失败或无净操作则还原原 adoptedFiles 暂存值。
+       * await 授权后重查写入身份与取消，再设置同步 adopting 上下文；授权成功本身不发布元素/绑定。
+       * Promise 结束于本地事务结果，已接纳字节随后随相应 Root/depot cut 保存，不在此单独等待 durable 回执。 */
       async adoptResource(id:Id,callback:(resource:ResourceHandle&{readonly asset:StoredAsset},transaction:Transaction)=>unknown,settings:{signal?:AbortSignal}={}):Promise<Result>{
         assertWritable(false);if(!depot||!options.assets?.authority||!options.storage.assetDepot)throw fault('asset_depot_unavailable');if(editor.getSnapshot().runtime.loading&&editor.getSnapshot().runtime.loading?.version!==6)throw fault('model_loading');
         if(staged.length||adopting)throw fault('reentrant_dispatch');
@@ -1379,7 +1514,8 @@ export async function openProjectEngine(options: EngineOptions) {
         adoptionTasks.set(controller,task);void task.finally(()=>adoptionTasks.delete(controller)).catch(()=>{});return task;
       },
       /** 借出图片显示句柄：先 pin 防清理，再取得共享显示 lease，调用方用完必须 release。
-       * 外部 signal、项目关闭和失败路径也会释放；Blob URL 由缓存的最后一个使用者撤销。 */
+       * 外部 signal、项目关闭和失败路径也会释放；Blob URL 由缓存的最后一个使用者撤销。
+       * pin 是本项目瞬态计数，不另存到 Root；共享缓存 key 命中可复用 URL，新句柄仍独立检查身份/取消。 */
       async displayResource(id: Id, settings: { signal?: AbortSignal } = {}) {
         assertDisplayIdentity();
         if(collectionReservations.has(id))throw fault('resource_collection_in_progress',[id]);
@@ -1409,7 +1545,8 @@ export async function openProjectEngine(options: EngineOptions) {
           // 缓存键带授权/摘要/操作身份或退休代次，同 ID 换来源不会误用旧 URL。
           const key=JSON.stringify(binding?['shared-asset',id,binding.authority,binding.digest]:retained?['asset',id,retained.operationId,retained.retirement?.purgedAt??null]:orphan?['orphan',id,orphan.digest]:source?['source',id,source.sha256??null]:['unmanaged',id]);
           /** 加载回调先找待保存/本地字节，再尝试共享仓库，最后使用服务端显示 URL。
-           * 孤立文件必须再次核对内容证据；所有 await 后复查项目身份，迟到 URL 不交给旧用户。 */
+           * 孤立文件重算摘要并核长度/MIME；普通资源/导入源不在这条显示路径统一重新哈希。
+           * 在字节采纳及最终句柄交付前检查身份/取消；depot.read 不是新的跨项目 adoption 授权。 */
           lease=displayCache.acquire(displayOwner,key,async signal=>{
             let bytes=adoptedFiles.get(id)?.bytes??fileWrites.get(id)??await options.storage.readFile(leader,id);
             if(!bytes&&binding&&depot)bytes=await depot.read(leader,binding,signal);
@@ -1430,7 +1567,9 @@ export async function openProjectEngine(options: EngineOptions) {
         }catch(error){release();assertDisplayIdentity();if(settings.signal?.aborted)throw fault('display_aborted');throw error;}
       },
       /** 用户主动按原始图片比例调整大小，形成独立编辑事务；与创建时默认尺寸补写区别在历史语义。
-       * 要求资源确属目标、代次未变且无手势，事务后核对实际几何，策略约束不满足则整次拒绝。 */
+       * 要求资源确属目标、代次未变且无手势，在事务草稿中核对实际几何，约束不满足则整次拒绝。
+       * 只从本项目 resources 的已解码/服务尺寸取比例，不对共享 binding 自动发起解码或下载。
+       * 和默认 grant 补写不同，这次是用户显式几何编辑，由普通 transaction 形成独立历史语义。 */
       fitImage(target:Target,resourceId:Id):Result{
         try{assertWritable();if(sessions.getSnapshot().gesture)throw fault('gesture_in_progress');const root=editor.getSnapshot(),element=root.document.elements.get(target.id),resource=root.runtime.resources.get(resourceId),size=resource?.image?.version===1&&resource.image.status==='ready'?resource.image:resource?.stored;
           if(!element||element.incarnation!==target.incarnation||element.structure!=='node'||options.registry.resolve(element)!=='known'||!options.registry.components.get(element.componentId)?.resourceFields?.includes('assetId')||element.data.assetId!==resourceId)throw fault('target_changed');if(!size||!validImageDimensions(size))throw fault('image_dimensions_unavailable');
@@ -1446,10 +1585,13 @@ export async function openProjectEngine(options: EngineOptions) {
       /** 订阅本地耐久性变化，返回取消订阅；已关闭时不再登记监听。 */
       subscribeDurability(listener:()=>void){if(closed)return()=>{};durabilityListeners.add(listener);return()=>{durabilityListeners.delete(listener);};},
       /** 显式重试先解决恢复会话和保存屏障，再重置可重试摘要/解码/尺寸授权及来源验证。
-       * 最后恢复调度与生成追尾；复用原逻辑事实和冻结请求，不把失败重试变成重复创建。 */
+       * 最后恢复调度与生成追尾；复用原逻辑事实和冻结请求，不把失败重试变成重复创建。
+       * 只重置约定的可重试状态：不复活 revoked grant、不重启所有已终结导入，也不等待未来服务任务结束。 */
       retry: async () => { if(recovery)await recovery.cancel();assertWritable(false);await persist();retryDefaultSizes();const runtime=editor.getSnapshot().runtime,ids=[...runtime.resources.values()].filter(resource=>!resource.digest&&runtime.ledger.operations.get(resource.operationId)?.blockers.some(code=>digestFailures.has(code))).map(resource=>resource.operationId);if(ids.length){mutate(ledger=>{for(const id of ids)ledger.block(id,['waiting_digest']);});prepareDigests();}if(options.images){editor.updateRuntime(previous=>{const resources=new Map(previous.resources);let changed=false;for(const [id,resource]of resources)if(resource.image?.version===1&&resource.image.status==='failed'){resources.set(id,freeze({...resource,image:{version:1 as const,status:'pending' as const}}));changed=true;}return changed?Object.freeze({...previous,resources:readMap(resources)}):previous;});prepareImages();}for(const job of editor.getSnapshot().runtime.imports?.values()??[])if(sourceNeedsSeal(job)){await importLoads.get(job.id);await resetImportReader(job.id);await loadImport(job.id);}await scheduler.resume();await runTracker.retry(); },
       /** 排空当前执行链及其派生保存，根变化时再次检查直到稳定。
-       * 不等待未来轮询时刻或服务端生成终结；暂停任务和未到期重试也不等于已经同步成功。 */
+       * 不等待未来轮询时刻或服务端生成终结；暂停任务和未到期重试也不等于已经同步成功。
+       * 不主动取得 hold：期间新增本地根/任务可延长等待；以根 revision、pending 和任务表重新检查稳定性。
+       * adoption/copy 的拒绝用 allSettled 等收尾，其它链路仍可能抛错，settle 不是所有领域错误的汇总报告。 */
       async settle() {
         let revision:number;
         do {
@@ -1459,21 +1601,26 @@ export async function openProjectEngine(options: EngineOptions) {
           await scheduler.settle();await runTracker.settle();await persist();await scheduler.settle();await persist();
         } while(revision!==editor.getSnapshot().rootRevision||pending.size||writing||adoptionTasks.size||copyPreparations.size||importLoads.size||verificationTasks.size||digestTasks.size||imageTasks.size||sizingTask);
       },
-      /** 关闭项目所有者：先阻止新准入，中止并排空执行器，再归还显示资源，最后可靠保存与释放领导权。
-       * 保存失败时保留 leader/根与字节材料，允许再次 close 重试；视图 detach 不应调用本方法。 */
+      /** 关闭项目所有者：先 closing、请求中止后台工作，等待列出的本地任务，再释放显示/保存根/归还 leader。
+       * scheduler/runTracker.stop 仅请求 abort 并阻止迟到采纳，这里未另外 await 它们的传输 Promise 全部结束。
+       * 末尾 persist 失败时保留 leader/根/待写字节与 closing 状态，后续 close 可重试；不是把实例恢复可编辑。
+       * 只有 closed 后重复调用立即返回，没有额外 close 单飞 Promise；宿主负责串行关闭，视图 detach 不应调用。 */
       async close() {
         if (closed) return;
         // 关闭标志先发布，再逐类取消/等待；共享 display/depot 只有本项目自己创建时才负责关闭整个实例。
         closing = true;notifyDurability();loadingReadController?.abort();await loadingRead?.catch(()=>{});unsubscribeSizing();orphanController?.abort();await Promise.allSettled([collection,sourceCollection,orphanCollection].filter(Boolean));digestLifecycle.abort();for(const {controller}of verificationTasks.values())controller.abort();for(const controller of preparationControllers.values())controller.abort();for(const controller of copyPreparations.keys())controller.abort();await Promise.allSettled([...copyPreparations.values()]);for(const controller of adoptionTasks.keys())controller.abort();await Promise.allSettled([...adoptionTasks.values()]); sessions.dispose(); scheduler.stop(); runTracker.stop();
-        // runner close 保留已提交前缀；等所有载入/校验/摘要/解码结束后才能释放读取器和底层存储。
+        // 先等 runner.close、装配/验证，再关闭 proof reader，接着等摘要/解码及尺寸 timer。
+        // runner 关闭保留已经提交内容；上述步骤完成才进入最后根保存，不等待服务器生成任务本身终结。
         await Promise.all([...importRunners.values()].map(runner=>runner.close()));while(importLoads.size)await Promise.all([...importLoads.values()]);while(verificationTasks.size)await Promise.allSettled([...verificationTasks.values()].map(task=>task.promise));for(const {reader}of proofReaders.values())reader.close();proofReaders.clear();while(digestTasks.size)await Promise.allSettled([...digestTasks.values()]);while(imageTasks.size)await Promise.allSettled([...imageTasks.values()]);while(sizingTask)await sizingTask;
         recovery?.controller.abort();recovery?.release();
         // 释放本项目所有显示句柄和 cache owner；其它项目仍可继续使用注入的共享缓存。
         for (const release of [...displays]) release();displayCache.releaseOwner(displayOwner);if(!options.displays)displayCache.close();
-        // Failure keeps the leader/recovery material available for an explicit retry of close.
+        // 只有 persist 成功才取消根订阅、dispose editor、释放自建 depot 和 leader，再标 closed。
+        // 注入的 storage 连接及共享池由宿主/Workspace 管，engine 不在这里调用 storage.close。
         await persist(); unsubscribe(); editor.dispose();if(!options.assetDepot)depot?.close();adoptedFiles.clear(); await leader.release(); closed = true;notifyDurability();durabilityListeners.clear();
       },
     });
-  // 工厂打开失败时释放已取得的领导权；成功返回后的关闭责任交给实例 close。
+  // 工厂 try 内失败至少归还已取得的 leader，并传播异常；不是已返回实例 close 的完整清理路径。
+  // 成功返回后由宿主调用实例 close 管理项目所有权，视图挂载/卸载不重建这个 leader。
   } catch (error) { await leader.release(); throw error; }
 }

src/lib/canvas-runtime/history-event-source.ts

@@ -15,17 +15,24 @@ export type HistorySourceEvent={readonly record:OperationRecord|undefined;readon
 /** 事件序列与可选 owning adoption 证据；count 标识虚拟事件前缀长度。 */
 export type HistoryEventSource={readonly events:readonly HistorySourceEvent[];readonly adoption?:{readonly count:number;readonly replay:HistoryReplay;readonly transition:HistoryTransition}};
 /** Resolve either a native interval or the owning adoption's proved virtual events, followed by later native events. */
-/** 找最早有文档效果的 pending 所属事件源；缺失/歧义/陈旧审计不能猜，直接拒绝。 */
+/** 从 pending 中有 changes 的最早 sequence 选择事件源；全为空则返回空列表，不读取其它证据。
+ * 无 owning adoption 时取原生区间；有时先取其虚拟 replay.events，再接 revision 之后的原生事件。
+ * 这里只解析形状/解释器/先后关系，不反向执行历史或核验事件文档效果；resolution 由消费规划器继续检查。
+ * pending 应来自同一已验证账本；ID 顺序检查不等于逐字段比对传入 intent 与 ledger 对象。
+ * 返回数组/envelope 未冻结，record/transition 沿用快照引用，调用方按不可变证据使用。 */
 export function historyEventSource(snapshot:EngineSnapshot,pending:readonly OperationIntent[]):HistoryEventSource{
   const content=pending.filter(intent=>intent.changes.length).sort((a,b)=>a.sequence-b.sequence),first=content[0];if(!first)return{events:[]};
   const records=snapshot.runtime.ledger.operations,audits=[...snapshot.runtime.recoveries.values()],owners=audits.filter(audit=>audit.decisions.some(decision=>decision.replacementId===first.id));
   if(owners.length>1)throw fault('recovery_history_adoption_ambiguous',[first.id]);
- /** 确认操作/尺寸效果解释器存在，未来数据保留不等于允许当前代码解释执行。 */
+ /** 要求 operationSchemaVersion=1，存在尺寸效果时验其解释器形状；不在此执行尺寸计划或校验操作类别。
+  * 未来数据可被上层保留，不表示此路径能据它恢复历史。 */
   const interpreter=(record:OperationRecord)=>{if(record.intent.operationSchemaVersion!==1)throw fault('operation_interpreter_unavailable',[record.intent.id]);if(record.intent.historyEffect)validateCreationSizeEffect(record.intent.historyEffect);};
   const pendingIds=new Set(content.map(intent=>intent.id));
- /** 校验事件不重复，且 pending 子序列与逻辑 sequence 精确一致，不能遗漏或交换。 */
+ /** 带 record 的所有事件 ID 不重复，抽出的 pending 子序列须与按 sequence 排序的 content 完全对应。
+  * adjustment 无 operation ID 不参与此计数；不要求所有账本 sequence 数值连续，也不检查服务执行顺序。 */
   const order=(events:readonly HistorySourceEvent[])=>{const seen=new Set<string>(),active:string[]=[];for(const event of events)if(event.record){const id=event.record.intent.id;if(seen.has(id))throw fault('recovery_history_event_order',[id]);seen.add(id);if(pendingIds.has(id))active.push(id);}if(active.length!==content.length||active.some((id,index)=>id!==content[index].id))throw fault('recovery_history_event_order');};
- /** 从操作提取已验证的原生历史 transition，缺证据不构造推测事件。 */
+ /** 提取原生 transition 并验结构；未传领域 checkChanges，也不在这里重放其 before/after 元数据。
+  * 缺失证据直接拒绝，完整可回放性由 createHistoryJournalRecovery 的反向条件执行验证。 */
   const native=(record:OperationRecord):HistorySourceEvent=>{interpreter(record);const transition=record.intent.historyTransition;if(!transition)throw fault('recovery_history_transition_missing',[record.intent.id]);validateHistoryTransition(transition);return{record,transition};};
   // 无 owning adoption 时用原生区间；区间内还有 adoption 就不能越过其边界盲目回放。
   if(!owners.length){
@@ -33,7 +40,8 @@ export function historyEventSource(snapshot:EngineSnapshot,pending:readonly Oper
     const start=events[0]?.transition.rootRevision??Infinity;if(audits.some(audit=>(audit.historyTransition?.rootRevision??audit.baseRootRevision+1)>=start))throw fault('recovery_history_adoption_replay_required');
     for(let i=1;i<events.length;i++)if(events[i].transition.rootRevision<=events[i-1].transition.rootRevision)throw fault('recovery_history_event_order');order(events);return{events};
   }
-  // 有 adoption 时要求其 replay/transition 齐全且没有更晚审计覆盖；先重建虚拟历史事实。
+  // owning audit 必须有 replay/transition，replay 绑定 baseRootRevision+1，且不允许其它更晚审计遮盖。
+  // 此处只组织虚拟事件，anchor 与整体 historyTransition 是否真的一致，留给日志规划器反向验证。
   const audit=owners[0],revision=audit.baseRootRevision+1,replay=audit.historyReplay;
   if(!replay||!audit.historyTransition)throw fault('recovery_history_adoption_evidence_missing',[audit.id]);validateHistoryReplay(replay,revision);validateHistoryTransition(audit.historyTransition);
   if(audits.some(other=>other.baseRootRevision+1>revision))throw fault('recovery_history_adoption_stale',[audit.id]);
@@ -42,7 +50,8 @@ export function historyEventSource(snapshot:EngineSnapshot,pending:readonly Oper
     if(event.kind==='adjustment')return{record:undefined,transition:event.transition};const record=records.get(event.operationId);if(!record?.intent.changes.length)throw fault('history_replay_operation_missing',[event.operationId]);interpreter(record);witnessed.add(event.operationId);return{record,transition:event.transition};
   });
   for(const intent of content)if(!witnessed.has(intent.id)&&!(intent.historyTransition&&intent.historyTransition.rootRevision>revision))throw fault('recovery_history_transition_missing',[intent.id]);
-  // 只接 adoption revision 之后的原生事件，再核对 revision 单调与 pending 完整顺序。
+  // 后续原生事件按逻辑 sequence 排序，再要求 rootRevision 严格递增，不以网络回执顺序拼接。
+  // 本层不按 phase/resolution 过滤；消费端仍须拒绝非 pending 但结果未明确的历史贡献。
   const later=[...records.values()].filter(record=>record.intent.changes.length&&record.intent.historyTransition&&record.intent.historyTransition.rootRevision>revision).sort((a,b)=>a.intent.sequence-b.intent.sequence).map(native);
   let previous=revision;for(const event of later){if(event.transition.rootRevision<=previous)throw fault('recovery_history_event_order');previous=event.transition.rootRevision;}
   order([...events,...later]);return{events:[...events,...later],adoption:{count:events.length,replay,transition:audit.historyTransition}};

src/lib/canvas-runtime/history-journal-recovery.ts

@@ -15,7 +15,11 @@ import type { EngineSnapshot } from './contracts.ts';
 import { planCreationSize, validateCreationSizeEffect } from '../canvas-core/creation-size-plan.ts';
 
 /** Native history events are reconstructed from evidence; all cursors remain private until the recovery root is accepted. */
-/** 创建一次恢复会话，要求有效 history 容量和完整事件证据；返回 project→accept→finish/evidence 协作接口。 */
+/** 一次同步恢复规划会话：从已验证 snapshot/pending 取事件，逆向条件回放历史元数据得到 baseline。
+ * 不逆向执行文档 changes 或访问服务；document 的 fresh 重规划由 project/rebaseIntent 处理。
+ * 调用方按事件顺序为每项 project→分配替代操作→accept，最后 finish→evidence，并同一个恢复 Root 采纳。
+ * snapshot/registry 沿用不可变输入；方法会改变私有游标/history，失败不自动回滚或封闭会话，应丢弃本次规划对象。
+ * limit 约束重建 user 贡献时的 undo 容量，不代表所有外部事件证据都可截断；无异步预算/网络/持久化。 */
 export function createHistoryJournalRecovery(snapshot:EngineSnapshot,pending:readonly OperationIntent[],registry:Registry,limit:number){
   if(!Number.isSafeInteger(limit)||limit<1)throw fault('invalid_history_limit');
   // historyEventSource 可能提供 adoption 虚拟事件；给每项补私有 before/after 以便核对后续取舍。
@@ -31,15 +35,19 @@ export function createHistoryJournalRecovery(snapshot:EngineSnapshot,pending:rea
   const baseline=history,replayEvents:HistoryReplayEvent[]=[],adoptionRevision=snapshot.rootRevision+1;
   /** 记录私有 history 的一次真实变化；关联操作即使 no-op 也留证据，调整事件不造 operation。 */
   function recordStep(before:HistoryState,entryId:Id|undefined,operationId?:Id){const transition=describeHistoryTransition(before,history,adoptionRevision,entryId,!!operationId);if(transition)replayEvents.push(operationId?freeze({kind:'operation' as const,operationId,transition}):freeze({kind:'adjustment' as const,transition}));}
-  // next 是严格事件游标；touched 区分本轮已审阅项，retired 解释被清redo/容量淘汰或无效果移除的项。
+  // events 保存证据中的原始 before/after，history 是随取舍变化的新候选，不能混成同一份状态。
+  // next 指下个事件；touched 标本轮审阅项，retired 解释清 redo/容量淘汰/无效果删除；remap/sizeHistory 仅服务当前 project→accept。
   let next=0;const touched=new Set<Id>(),retired=new Set<Id>();let remap:((change:Change)=>Change)|undefined;
   let sizeHistory: HistoryState | undefined;
   /** 捕获双栈数组和 entry 表成员为新只读 history，不暴露私有可变容器。 */
   const state=(undo:readonly Id[],redo:readonly Id[],entries:ReadonlyMap<Id,HistoryEntry>)=>Object.freeze({undo:freeze([...undo]),redo:freeze([...redo]),entries:readMap(entries)});
-  /** 当前处理的 intent 必须恰好位于 next；不能按网络返回先后跳过或交换历史。 */
+  /** 只按下个 record 的 intent.id 检查位置，不逐字段比对外来 intent；协调器须传同快照中受信意图。
+   * 不能按网络返回顺序跳过/交换，adjustment 和已结算事件由 advance 先消费。 */
   const eventFor=(intent:OperationIntent)=>{const event=events[next];if(!event||event.record?.intent.id!==intent.id)throw fault('recovery_history_event_order',[intent.id]);return event;};
-  /** 处理一个已有分组项的确认前缀：纯字段仅保留 fresh 仍含其最终效果的字段链。
-   * 几何/path 要求 owner 未变；结构性前缀必须可完整逆向执行，否则拒绝猜测部分历史。 */
+  /** 审阅已有分组项：纯字段按 target ID/代次/field 的最后 after 判断 fresh 是否还保留该贡献。
+   * 最终值/存在性匹配才保留该字段的原整条链，不将每条都压成一次最后值；不匹配就移除此字段贡献。
+   * geometry/path 的 owner 还须与原 ACK 一致；含 owner/端点或整记录的前缀必须可完整逆向规划。
+   * 只返回 changes，不移动文档；不在这里恢复被远端覆盖的旧字段值。 */
   function reviewPrefix(entry:HistoryEntry,document:Document):readonly Change[]{
     const prefix=entry.changes;
     if(prefix.every(change=>change.kind==='field'&&!['ownerCanvasId','source','target'].includes(change.field))){
@@ -50,14 +58,17 @@ export function createHistoryJournalRecovery(snapshot:EngineSnapshot,pending:rea
     }
     try{planHistoryChanges(document,invert(prefix),registry);}catch{throw fault('recovery_history_prefix_conflict',[entry.id]);}return prefix;
   }
-  /** 丢弃一个未保留的 user 贡献时，仍审查同 entry 中已确认的旧前缀，不能连旧贡献一起删除。 */
+  /** 无 replacement 的 user 贡献不追加新 changes；首次触及且还在 undo 的旧项才审阅原前缀。
+   * 空前缀退休并从两栈移除，非空则保留；无 entryId（history=false）、已 touched 或不在 undo 时不重复处理。 */
   function skipUser(intent:OperationIntent,document:Document){
     const event=eventFor(intent),id=event.transition.entryId;if(!id)return;const entry=history.entries.get(id);
     if(!entry){retired.add(id);return;}
     if(touched.has(id)||!history.undo.includes(id))return;
     const changes=reviewPrefix(entry,document),entries=new Map(history.entries);if(changes.length)entries.set(id,freeze({...entry,changes}));else{entries.delete(id);retired.add(id);}history=state(history.undo.filter(key=>entries.has(key)),history.redo.filter(key=>entries.has(key)),entries);
   }
-  /** 加入保留/已确认的 user 贡献，沿用原 entry 元数据并维护分组顺序、清redo和容量淘汰。 */
+  /** 以原事件 after 的 label/group 等元数据加入贡献，append 必须与原有分组/栈顶关系相容。
+   * 先清 redo 并标 retired；pending 首次触及旧项才审阅 fresh 前缀，随后追加本轮 changes/operationId。
+   * 新项压 undo，超过 limit 从栈底淘汰；已退休原组可按证据重新建立，不借旧 ID 静默改写任意已有项。 */
   function addUser(intent:OperationIntent,changes:readonly Change[],operationId:Id,pending:boolean,document?:Document){
     const event=eventFor(intent),id=event.transition.entryId;if(!id)return;
     const original=event.after!.entries.get(id);if(!original)throw fault('recovery_history_transition_conflict',[id]);
@@ -77,7 +88,9 @@ export function createHistoryJournalRecovery(snapshot:EngineSnapshot,pending:rea
     for(const patch of event.transition.entries){const current=entries.get(patch.id),original=before.entries.get(patch.id),desired=after.entries.get(patch.id);if(equal(current,desired))continue;if(!original||!equal(current,original))throw fault('recovery_history_adjustment_conflict',[patch.id]);if(desired)entries.set(patch.id,desired);else{entries.delete(patch.id);retired.add(patch.id);}}
     history=state(history.undo.filter(id=>entries.has(id)),history.redo.filter(id=>entries.has(id)),entries);
   }
-  /** 先消费下一个待审阅意图之前的已确认/调整事件；碰到另一 pending 不能越过它自动处理。 */
+  /** 消费目标 pending 之前（或 finish 时剩余）的 adjustment 与已有结果事件，逐个 recordStep/推进 next。
+   * 带 record 者不得是另一个 pending，resolution 只接受 applied/elided；不在此独立校验 phase/服务回执真实性。
+   * 默认尺寸、user、undo/redo 分别走专用逻辑，其它 origin 明确拒绝；不会重发这些已结算操作。 */
   function advance(intent?:OperationIntent){
     while(next<events.length&&(!intent||events[next].record?.intent.id!==intent.id)){
       const event=events[next],record=event.record,before=history;
@@ -90,7 +103,9 @@ export function createHistoryJournalRecovery(snapshot:EngineSnapshot,pending:rea
       recordStep(before,event.transition.entryId,record?.intent.id);next++;
     }
   }
-  /** 对应已验证前后 entry 的变化位置提取代次映射，供其它历史目标跟随显式 restore。 */
+  /** 按原/新 entry changes 的对应索引提取同 ID 的 old incarnation→new incarnation Map。
+   * 不是任意两组 changes 的通用差异算法，依赖证据保证对应位置语义一致；不按资源/正文字符串猜身份。
+   * 返回纯 change 改写函数供其它历史目标跟随 restore，未映射代次保留原值。 */
   function incarnationRemap(before:HistoryEntry,after:HistoryEntry){
     const maps=new Map<Id,Map<number,number>>();
     /** 仅同 ID 且代次确实改变时登记，不能把两个不同元素意外映为同一生命周期。 */
@@ -99,7 +114,8 @@ export function createHistoryJournalRecovery(snapshot:EngineSnapshot,pending:rea
     /** 仅重写 field target 与整元素 before/after 代次，不修改 canvas 记录或冻结服务请求。 */
     return(change:Change):Change=>{const record=<T extends {id:Id;incarnation:number}>(value:T|null)=>value?{...value,incarnation:maps.get(value.id)?.get(value.incarnation)??value.incarnation}:null;if(change.kind==='field')return freeze({...change,target:record(change.target)!});if(change.kind==='element')return freeze({...change,before:record(change.before),after:record(change.after)});return change;};
   }
-  /** 已 applied 的 undo/redo 是事实：只有当前审阅前缀仍表示完全相同效果才允许移动栈。 */
+  /** 已有 applied/elided 结果的遍历必须命中当前栈顶，且原事件前后变化与审阅后的正向效果精确对应。
+   * 只重建历史移动/关联并为其它项重映代次，不执行已结算文档变化，也不改旧 operation/request。 */
   function addConfirmedTraversal(intent:OperationIntent){
     const event=eventFor(intent),id=event.transition.entryId,undo=[...history.undo],redo=[...history.redo],source=intent.origin==='undo'?undo:redo,destination=intent.origin==='undo'?redo:undo;
     if(!id||source.at(-1)!==id)throw fault('recovery_history_traversal_order',id?[id]:[]);
@@ -110,7 +126,8 @@ export function createHistoryJournalRecovery(snapshot:EngineSnapshot,pending:rea
     const entries=new Map(history.entries),map=incarnationRemap(before,after);for(const[otherId,other]of entries)if(otherId!==id)entries.set(otherId,freeze({...other,changes:other.changes.map(map)}));
     entries.set(id,freeze({...entry,changes,operationIds:[...entry.operationIds,intent.id]}));source.pop();destination.push(id);history=state(undo,redo,entries);
   }
-  /** 已确认默认尺寸效果只修原 entry/后续条件，不移动双栈；当前历史必须仍匹配原前置证据。 */
+  /** 已结算默认尺寸使用原 transition 的 entry changes 修正，要求该事件两栈不动、当前 changes/label/group 仍匹配。
+   * 不再次运行尺寸文档命令；只给所属创建项追加逻辑操作关联，其它被修正项保留各自关联。 */
   function addConfirmedSize(intent: OperationIntent) {
     validateCreationSizeEffect(intent.historyEffect);
     const event = eventFor(intent), entries = new Map(history.entries);
@@ -123,7 +140,10 @@ export function createHistoryJournalRecovery(snapshot:EngineSnapshot,pending:rea
     history = state(history.undo, history.redo, entries);
   }
   return{
-    /** 为当前 intent 计算文档候选，不立即移动对应新历史；accept 在替代操作身份确定后接续。 */
+    /** 先 advance 结算前置事件，再为当前 pending 返回 fresh 文档候选；自身对应的历史贡献等 accept。
+     * 尺寸专用 planner 暂存 sizeHistory；touched 遍历按审阅后的 entry 重新规划，其它 keep 意图走 rebaseIntent。
+     * 丢弃返回零文档变化但仍可能校验原遍历可行性；空 changes 直接返回，不消费事件游标。
+     * 此调用可能已经改变前置私有 history，不能当无状态 query，也不能并发交错不同项的 project/accept。 */
     project(document:Document,intent:OperationIntent,context:IntentContext,keep:boolean){
       if(!intent.changes.length)return{document,changes:[] as readonly Change[]};advance(intent);const event=eventFor(intent),id=event.transition.entryId;remap=undefined;sizeHistory=undefined;
       // 尺寸效果通过专用 planner 重算 history；keep=false 不发布旧自动尺寸。
@@ -150,7 +170,10 @@ export function createHistoryJournalRecovery(snapshot:EngineSnapshot,pending:rea
       // 普通保留意图经显式审阅后重新规划；丢弃返回零文档变化，不自行伪造成功回执。
       return keep?rebaseIntent(document,intent,context,registry):{document,changes:[] as readonly Change[]};
     },
-    /** 接受 project 的取舍/替代操作，更新私有双栈并记 replay；每项完成后 next 单调前进。 */
+    /** 在协调器确定 replacement 后，按当前 project 结果更新私有历史、记 replay 并将 next 加一。
+     * replacement/keep/before/after 须与此前 project 配对；接口不独立比对该语义或自动生成新 ID/账本记录。
+     * user 按贡献维护组，尺寸采用暂存计划，keep 遍历有剩余效果才移到另一栈，否则退休该项。
+     * 不发布 Root、不持久化审计；调用失败后不要继续使用可能已部分推进的同一规划会话。 */
     accept(intent:OperationIntent,replacement:OperationIntent|undefined,keep:boolean,before:Document,after:Document){
       if(!intent.changes.length)return;const previous=history,event=eventFor(intent),id=event.transition.entryId;
       if (intent.historyEffect) {
@@ -174,9 +197,12 @@ export function createHistoryJournalRecovery(snapshot:EngineSnapshot,pending:rea
       }
       recordStep(previous,id,replacement?.id);next++;
     },
-    /** 消费剩余已确认事件后返回最终候选 history；未审阅 pending 仍会被 advance 拒绝。 */
+    /** 消费剩余已结算/调整事件并返回候选 history；未处理 pending 会拒绝，不静默跳过。
+     * 不设置 finished 锁或自动保存，协调器仍需整体校验并原子采纳文档/历史/账本。 */
     finish(){advance();return history;},
-    /** 输出原 history→baseline 的 anchor 及有序增量，和本次 adoption 一起持久化以支持再次重开。 */
+    /** 完成 finish 后作为最后步骤输出证据：原 history→baseline 的 anchor，加本次有序元数据增量。
+     * 所有 transition 绑定 snapshot.rootRevision+1，不表示多次服务写入或已持久化成功。
+     * freeze 直接包含 replayEvents 数组，会冻结该会话的事件缓冲；提前调用后不能再向它追加规划事件。 */
     evidence():HistoryReplay{return freeze({version:1 as const,anchor:describeHistoryTransition(snapshot.history,baseline,adoptionRevision,undefined,true)!,events:replayEvents});},
   };
 }

src/lib/canvas-runtime/history-replay.ts

@@ -11,13 +11,16 @@ export type HistoryReplayEvent={readonly kind:'operation';readonly operationId:I
 /** version=1 的 anchor+有序事件；所有 transition 绑定同一次 adoption Root revision。 */
 export type HistoryReplay={readonly version:1;readonly anchor:HistoryTransition;readonly events:readonly HistoryReplayEvent[]};
 /** Local evidence only. The anchor and event deltas explain one atomic adoption, not new service writes. */
-/** 检查证据版本/JSON、anchor无entry、事件 revision 一致和 operation ID 唯一；未知版本拒绝解释。 */
+/** 检查证据版本/JSON、anchor 无 entry、事件 revision 一致及 operation ID 唯一；未知版本拒绝解释。
+ * revision 由调用方提供；不查询真实发布日志，checkChanges 缺省时不完整解释各条领域 Change。 */
 export function validateHistoryReplay(value:unknown,revision:number,checkChanges?:(value:unknown)=>unknown):asserts value is HistoryReplay{
   if(!value||typeof value!=='object'||Array.isArray(value))throw fault('invalid_history_replay');const raw=value as Record<string,unknown>;
   if(raw.version!==1)throw fault('history_replay_interpreter_unavailable');if(!validJson(value))throw fault('invalid_history_replay');validateHistoryTransition(raw.anchor,checkChanges);if(raw.anchor.rootRevision!==revision||raw.anchor.entryId!==undefined||!Array.isArray(raw.events))throw fault('invalid_history_replay');const ids=new Set<Id>();
   for(const value of raw.events){if(!value||typeof value!=='object'||Array.isArray(value))throw fault('invalid_history_replay');const event=value as Record<string,unknown>;validateHistoryTransition(event.transition,checkChanges);if(event.transition.rootRevision!==revision)throw fault('invalid_history_replay');if(event.kind==='operation'){if(typeof event.operationId!=='string'||!event.operationId||ids.has(event.operationId))throw fault('invalid_history_replay');ids.add(event.operationId);}else if(event.kind!=='adjustment'||event.operationId!==undefined)throw fault('invalid_history_replay');}
 }
-/** 纯条件回放 anchor/events；可选校验逻辑 ID 存在，带 entry 的事件必须在该项关联同 operation。 */
+/** 条件回放历史元数据：先正向 anchor，再按 events 顺序更新两栈/entries，不执行文档 changes 或网络。
+ * 用 anchor 自身 revision 调结构校验，不独自核对外部 adoption 的 Root；调用方另需绑定那次发布。
+ * hasOperation 可选检查 ID 存在，带 entry 的操作事件需关联同 ID；不在此比较逻辑意图内容与 transition 是否语义等价。 */
 export function replayHistoryEvidence(before:HistoryState,replay:HistoryReplay,hasOperation?:(id:Id)=>boolean):HistoryState{
   validateHistoryReplay(replay,replay.anchor.rootRevision);let history=applyHistoryTransition(before,replay.anchor,'forward');
   for(const event of replay.events){if(event.kind==='operation'&&hasOperation&&!hasOperation(event.operationId))throw fault('history_replay_operation_missing',[event.operationId]);history=applyHistoryTransition(history,event.transition,'forward');if(event.kind==='operation'&&event.transition.entryId&&!history.entries.get(event.transition.entryId)?.operationIds.includes(event.operationId))throw fault('history_replay_operation_mismatch',[event.operationId]);}
@@ -25,5 +28,6 @@ export function replayHistoryEvidence(before:HistoryState,replay:HistoryReplay,h
 }
 /** 比较两栈和全部 entry；entry 表按 ID 排序，避免 Map 插入顺序差异被误认作历史不一致。 */
 export function sameHistory(left:HistoryState,right:HistoryState):boolean{
+  // 仅规范化 entries 表的顺序；undo/redo 数组顺序仍按栈语义精确比较，不能排序后当集合。
   const value=(history:HistoryState)=>({undo:history.undo,redo:history.redo,entries:[...history.entries].sort(([a],[b])=>a.localeCompare(b))});return equal(value(left),value(right));
 }

src/lib/canvas-runtime/host.ts

@@ -11,7 +11,10 @@ import { createScopedLoader, type LoadPort, type ScopedLoader } from './loader.t
 import type { CanonicalReadUpdate } from './contracts.ts';
 
 /** Host lifetime matches the signed-in application, independently of navigation. */
-/** 宿主注入 workspace/loader 工厂；current 闭包绑定精确账号与 epoch，作为异步结果准入围栏。 */
+/** 一个应用级宿主：workspaces/readers 按当前账号下的 workspaceId 复用，retired 单独保留待关闭实例。
+ * registry 由注入方按不可变定义合同共享，本函数不冻结或复制它；也不保存 token/密码等认证凭证。
+ * current 闭包绑定账号+authEpoch，拒绝旧身份结果；业务/存储实际副作用仍需 adapters 自行遵守该围栏。
+ * 后台退休关闭可与新身份运行并行；Host 不为 closeRetired 建单飞锁，workspace.close 应支持重复/并发调用。 */
 export function createRuntimeHost(options: { registry: Registry; workspace(accountId: Id, workspaceId: Id, authEpoch: number, current: () => boolean): WorkspaceRuntime; modelLoader?(accountId:Id,workspaceId:Id,authEpoch:number,current:()=>boolean):LoadPort<CanonicalReadUpdate>; onError?: (error: unknown) => void; onObserverError?: (error: unknown) => void }) {
   let accountId: Id | null = null, authEpoch = 0, disposed = false;
   // active 表只含当前身份，retired 持有尚未成功关闭的旧 runtime，不能因换账号就丢掉待保存内容。
@@ -25,7 +28,8 @@ export function createRuntimeHost(options: { registry: Registry; workspace(accou
   };
   /** 同步撤销当前身份：先换 epoch，再关闭读取句柄/移走 workspace；实际存储收尾另行等待。 */
   function retire() { authEpoch++; accountId = null; for (const reader of readers.values()) reader.close();readers.clear();for (const runtime of workspaces.values()) retired.add(runtime); workspaces.clear(); }
-  /** 账号变化才退休旧作用域；后台关闭错误走 onError，报告失败不能改变新账号的身份事实。 */
+  /** 相同账号复用 epoch，换账号先 retire 再同步启用新账号，不等待旧 workspace 关闭。
+   * 旧关闭失败通过 onError 报告且保留 retired，后续身份退休/close 可重试；异常报告也被隔离。 */
   function activate(account: Id) {
     if (disposed) throw fault('host_disposed');
     if (accountId !== account) {
@@ -42,7 +46,10 @@ export function createRuntimeHost(options: { registry: Registry; workspace(accou
     identity: () => Object.freeze({ accountId, authEpoch }),
     /** 返回当前 workspace 表的安全只读快照，外部不能手动增删运行实例。 */
     getWorkspaces: () => readMap(workspaces),
-    /** 通过共享 scoped loader 读 canonical 源；增量可产生只读预览，terminal 完整后才返回最终模型。 */
+    /** 只读加载不创建 workspace engine/storage；每 workspace 复用 scoped loader、每订阅维护独立 preview/seen。
+     * 导航代次属于订阅者，授权 epoch 才参与共享身份；已完成读取不作长期缓存（maxCacheEntries=0）。
+     * ready 后核对身份与终结完整标志，再返回 ready 模型或其它终态；不是在 Host 再做全量 Document/schema 校验。
+     * preview/observer 出错只停止此订阅预览并上报 onObserverError，不取消其它订阅或替换共享读取事实。 */
     async loadModel(account:Id,workspace:Id,canvas:Id,settings:{signal?:AbortSignal;navigationGeneration?:number;onPreview?:(preview:LiveModelPreview)=>void}={}) {
       activate(account);
       const readEpoch=authEpoch;
@@ -60,7 +67,8 @@ export function createRuntimeHost(options: { registry: Registry; workspace(accou
       };
       // key 纳入账号、workspace、格式、查询与 authEpoch；view 导航代次不替代授权代次。
       const handle=reader.acquire({accountId:account,workspaceId:workspace,projectId:null,canvasId:canvas,viewKey:'canonical-project',format:'canonical-model-v1',queryFingerprint:'full-project',source:'foundry',authEpoch,navigationGeneration:settings.navigationGeneration??0},{signal:settings.signal,onUpdate});
-      // ready 后再查身份和 terminal/complete；finally 始终释放本订阅，不能泄漏 reader 引用。
+      // handle 成功取得后，ready 成功/拒绝都在 finally 释放订阅并 close preview；不关闭共享 reader/其它订阅。
+      // 端口返回模型的领域合法性仍由 canonical adapter/预览解释器和后续 engine 准入负责。
       try{const snapshot=await handle.ready;if(disposed||accountId!==account||authEpoch!==readEpoch)throw fault('identity_changed');const last=snapshot.chunks.at(-1);if(!last||!last.complete||last.value.status==='receiving')throw fault('incomplete_load');return last.value.status==='ready'?Object.freeze({...last.value,sourceToken:last.snapshotToken}):last.value;}finally{handle.release();preview?.close();}
     },
     /** 按当前账号激活并懒创建 workspace；导航到同工作区不会重新创建资源池或项目。 */
@@ -74,9 +82,11 @@ export function createRuntimeHost(options: { registry: Registry; workspace(accou
       }
       return runtime;
     },
-    /** 退出身份但保留 host 可再次绑定；返回旧 runtime 收尾 Promise，让宿主处理未保存错误。 */
+    /** 同步清账号并递增 epoch，关闭读句柄，再等待退休 runtime；不永久 disposed，之后可重新绑定。
+     * 不等待 close 成功也已使旧 current 失效；失败不会恢复旧身份或删除退休实例。 */
     retireIdentity() { retire(); return closeRetired(); },
-    /** 永久关闭 host 并退休全部作用域；失败仍可再次调用 close 重试退休集合。 */
+    /** 永久 disposed 后再退休/等待关闭，后续 workspace/bind/load 准入拒绝。
+     * 失败可再次 close 重试；每次都会再次 retire/推进 epoch，返回值不是共享的单飞关闭 Promise。 */
     close() { disposed = true; retire(); return closeRetired(); },
   });
 }

src/lib/canvas-runtime/image-decoder.ts

@@ -15,17 +15,25 @@ export type ImageDecoderPort={decode(bytes:Blob,signal?:AbortSignal):Promise<Ima
 /** 这里只验证正安全整数和乘积可安全表示，不等同于已应用产品的像素预算。 */
 export function validImageDimensions(value:unknown):value is ImageDimensions{const size=value as ImageDimensions;return !!size&&Number.isSafeInteger(size.width)&&size.width>0&&Number.isSafeInteger(size.height)&&size.height>0&&Number.isSafeInteger(size.width*size.height);}
 /** Bounded read-only compute. Cancellation rejects the caller; a slot remains occupied until execution settles. */
-/** 默认2并发/64等待，最多8并发；取消结果与执行容量分开，防止无视 abort 的任务挤爆池。 */
+/** 默认 2 并发/64 等待，最多 8 并发；waiting/active 各用按插入顺序的 Map，不是持久任务队列。
+ * maxQueued 只限制尚未进入 active 的任务；active 包括已取消但执行器仍未退出的任务。
+ * 池只检查 Blob 的 image/ MIME 前缀和尺寸数值，不限制文件字节/实际像素预算，也不缓存解码结果。 */
 export function createImageDecodePool(options:{execute:(bytes:Blob,signal:AbortSignal)=>Promise<ImageDimensions>;concurrency?:number;maxQueued?:number}):ImageDecoderPort{
  const concurrency=options.concurrency??2,maxQueued=options.maxQueued??64;
  if(!Number.isSafeInteger(concurrency)||concurrency<1||concurrency>8||!Number.isSafeInteger(maxQueued)||maxQueued<1)throw fault('invalid_image_decode_budget');
  /** 每个解码请求独立控制器/完成标记；cleanup 解除外部取消监听，迟到执行结果不再采纳。 */
  type Task={id:number;bytes:Blob;controller:AbortController;resolve:(size:ImageDimensions)=>void;reject:(error:unknown)=>void;done:boolean;cleanup():void};
  const waiting=new Map<number,Task>(),active=new Map<number,Task>();let next=0,closed=false;
- /** 幂等 settle 调用者，成功捕获冻结尺寸；不提前归还仍在执行的 active 槽。 */
+ /** 幂等 settle 调用者并清理等待项；成功浅复制/冻结执行器结果，扩展属性不会被过滤。
+  * error 用真值区分成败，执行器应以 Error 等真值拒绝；falsy rejection 不保证按失败解释。
+  * 不删除 active，取消后的名额仍要等 execute 链的 finally 才归还。 */
  function finish(task:Task,error?:unknown,size?:ImageDimensions){if(task.done)return;task.done=true;task.cleanup();waiting.delete(task.id);if(error)task.reject(error);else task.resolve(freeze({...size!}));}
- /** FIFO 取任务并在微任务执行，校验返回尺寸，最后 finally 删除 active 再继续泵；异常不毒化后续队列。 */
+ /** 取 waiting 首项立即占 active，再在微任务调用 execute；启动前复查内部 abort。
+  * 成功尺寸先校验再 finish；正常错误交 finish，finally 负责释放 active 并继续 FIFO。
+  * execute 若不响应取消且永不 settle，名额会持续占用；池没有超时或强制终止通用执行器的能力。 */
  function pump(){while(!closed&&active.size<concurrency&&waiting.size){const task=waiting.values().next().value!;waiting.delete(task.id);active.set(task.id,task);void Promise.resolve().then(()=>{if(task.controller.signal.aborted)throw fault('image_decode_aborted');return options.execute(task.bytes,task.controller.signal);}).then(size=>{if(!validImageDimensions(size))throw fault('invalid_image_dimensions');finish(task,undefined,size);}).catch(error=>finish(task,error)).finally(()=>{active.delete(task.id);pump();});}}
- /** decode 校验图片 MIME/容量并建立任务；close 取消所有调用结果，active 实际结束仍由 finally 收尾。 */
+ /** decode 拒绝关闭/预先取消/非图片 Blob/等待容量已满，随后创建任务、绑定外部 abort 并入 waiting。
+  * abort 转发给内部 controller，立即拒绝调用者并移除 waiting；运行中的 active 留待 finally。
+  * close 幂等取消全部调用结果并禁止继续泵，不返回 drain Promise，也不证明所有 execute 已停止。 */
  return Object.freeze({decode(bytes:Blob,signal?:AbortSignal){if(closed)return Promise.reject(fault('image_decoder_closed'));if(signal?.aborted)return Promise.reject(fault('image_decode_aborted'));if(!(bytes instanceof Blob)||!bytes.type.startsWith('image/'))return Promise.reject(fault('invalid_image_input'));if(active.size>=concurrency&&waiting.size>=maxQueued)return Promise.reject(fault('image_decode_capacity'));return new Promise<ImageDimensions>((resolve,reject)=>{const abort=()=>{task.controller.abort();finish(task,fault('image_decode_aborted'));pump();},task:Task={id:++next,bytes,controller:new AbortController(),resolve,reject,done:false,cleanup:()=>signal?.removeEventListener('abort',abort)};signal?.addEventListener('abort',abort,{once:true});waiting.set(task.id,task);pump();});},close(){if(closed)return;closed=true;for(const task of [...waiting.values(),...active.values()]){task.controller.abort();finish(task,fault('image_decode_aborted'));}}});
 }

src/lib/canvas-runtime/image.worker.ts

@@ -4,11 +4,14 @@
  */
 /** 仅声明本入口需要的 Worker 消息能力，不导入 renderer 或 DOM 状态。 */
 const worker=globalThis as unknown as{onmessage:((event:MessageEvent)=>void)|null;postMessage(value:unknown):void};
-/** 接受正确版本/id/Blob，按 from-image 选项解码；失败回稳定 image_decode_failed。 */
+/** 仅接收 version=1、安全整数 id、Blob；非法请求直接忽略，不回错误消息。
+ * 不在此限制 id 为正数、MIME、字节或像素预算；单任务 Worker 的创建/并发/取消由宿主控制。
+ * 异步 handler 本身不排队，重复消息可并行解码；正常宿主每 Worker 只发一个请求。 */
 worker.onmessage=async event=>{
  const {version,id,bytes}=event.data??{};if(version!==1||!Number.isSafeInteger(id)||!(bytes instanceof Blob))return;
  // bitmap 是临时原生资源，尺寸读取即使抛错也由 finally close；成功只发送 width/height 和输入长度。
  try{const bitmap=await createImageBitmap(bytes,{imageOrientation:'from-image'});let width:number,height:number;try{width=bitmap.width;height=bitmap.height;}finally{bitmap.close();}worker.postMessage({version:1,id,byteLength:bytes.size,width,height});}
+ // 解码/读取尺寸/close/成功回信失败均尝试发送稳定错误；若通信本身不可用，宿主仍需取消/错误事件收尾。
  catch{worker.postMessage({version:1,id,byteLength:bytes.size,error:'image_decode_failed'});}
 };
 // 标记为独立 TypeScript 模块，避免 Worker 全局声明与其它源码脚本命名空间合并。

src/lib/canvas-runtime/import-batches.ts

@@ -4,7 +4,9 @@
  */
 /** Runner-owned feedback, not persisted job state. Probe bounded batches to
  * distinguish fixed publication cost from the marginal cost of another unit. */
-/** budget/max由runner给出，用实际已提交units和耗时更新下一批软上限。 */
+/** runner 提供已验证的正 budget/max，并在尝试后反馈 units/elapsed；本函数不自行读取时钟或发布内容。
+ * 闭包只保留 limit 和 observed，重启 runner 会重新从 1 探测，不用持久化这些性能估计。
+ * 参数/样本未在此验证，调用方需传有限且合理的耗时/单位；它不是容量或源完整性校验器。 */
 export function createImportBatches(budget:number,max:number){
  // 初始未观测时保守为1；observed只表示收到反馈，不是源校验或导入已完成。
  let limit=1,observed=false;
@@ -13,7 +15,9 @@ export function createImportBatches(budget:number,max:number){
   get limit(){return limit;},
   /** 是否已有至少一次发布成本样本，用于runner的调度决策。 */
   get observed(){return observed;},
-  /** 超时按比例减小并至少降一档；不足当前limit的尾批不能证明更大批也便宜。 */
+  /** 首次反馈即 observed=true；elapsed > budget 按比例缩小，且尽量至少减 1，最低保留 1。
+   * 未超时且 units ≥ limit 才按约 1.5 倍增长并封顶 max；等于 budget 也算此分支。
+   * 不足当前 limit 的尾批不增长，避免将少量记录的固定发布成本误当成更大批仍便宜。 */
   record(units:number,elapsed:number){
    observed=true;
    if(elapsed>budget){limit=Math.max(1,Math.min(limit-1,Math.floor(units*budget/elapsed)));return;}

src/lib/canvas-runtime/import-budget.ts

@@ -13,7 +13,10 @@ export type ImportScheduling = {
 
 /** A soft time slice with a work threshold, even when the clock is coarse.
  * The caller bounds each indivisible parse/decode operation separately. */
-/** 默认6ms软目标；step 不一定产生 Promise，调用方须在返回等待值时真正 await/yield。 */
+/** 默认 6ms 软目标，闭包保存本时间片 started/work/unchecked 三个计数，不存任务或文档。
+ * step 可能同步返回 undefined；只有返回 Promise 且调用方 await 时才形成有效背压，应串行使用同一预算。
+ * 自定义 yieldTask 决定让出到微任务还是后续任务；预算不保证浏览器一定在该点完成一帧绘制。
+ * 构造只校验 frameBudgetMs，不预先检查 signal；units 应由调用者提供非负有限工作量。 */
 export function createImportBudget(signal: AbortSignal, options: ImportScheduling = {}) {
   const budget = options.frameBudgetMs ?? 6;
   if (!Number.isFinite(budget) || budget <= 0) throw fault('invalid_import_budget');
@@ -22,7 +25,10 @@ export function createImportBudget(signal: AbortSignal, options: ImportSchedulin
   // 每128工作单位才读一次时钟，减少高频开销；总量16384强制让出，不能因时间测不准而无限执行。
   let started = now(), work = 0, unchecked = 0;
   return {
-    /** 记工作量并按阈值检查取消/时间；达到预算或时间异常时让出，回来再验取消并重置时间片。 */
+    /** 累加 units；未满 128 个未检查单位且总量未满 16384 时直接返回，连 signal 也尚未检查。
+     * 阈值到达才读时钟；未超时保留 work 累计，超时/时间倒退或非有限值/工作量封顶则 await yieldTask。
+     * yield 后复查取消，成功才重设 started/work；读取时钟或 yield 抛错直接传播，不隐式重试。
+     * units 无运行时校验，负数/NaN 会破坏计数假设；本函数不测量单次实际 CPU 成本或字节数。 */
     step(units = 1): Promise<void> | undefined {
       work += units;
       unchecked += units;

src/lib/canvas-runtime/import-byte-reader.ts

@@ -6,13 +6,17 @@ import {fault} from '../canvas-core/values.ts';
 
 /** 会破坏整个源读取可信性的错误集合，供上层区分单记录失败与源级暂停/失败。 */
 const failures=new Set(['import_source_changed','invalid_import_byte_range','import_read_capacity','import_source_closed','import_source_read_failed','invalid_import_read_proof','import_read_proof_interpreter_unavailable']);
-/** 仅按稳定领域错误码分类，不依赖展示 message 或错误文本包含某个词。 */
+/** 只按 code 是否在固定集合分类，不校验错误对象的来源；其它码（含一般 import_aborted）不在集合内。
+ * 取消是否应优先由读取调用方看 signal；本分类器不是所有源错误/取消的通用判定器。 */
 export const isImportByteFailure=(error:unknown)=>failures.has((error as {code?:string}|undefined)?.code??'');
 
 /** Optional immutable-source port. Implementations return exactly the requested bytes. */
 /** 可选只读端口声明完整长度，必须返回所请求区间的精确字节，不能截断或换源。 */
 export type ImportByteReader={readonly byteLength:number;read(start:number,end:number,signal:AbortSignal):Promise<Uint8Array>};
-/** 校验安全整数范围，end 可截至EOF；读取前后查取消，外来 reader 结果额外复制以隔离缓冲复用。 */
+/** 校验安全整数范围，允许 end 超出 EOF 并截到 bytes.size；start 超出 EOF 则拒绝。
+ * reader 长度须等于 Blob 长度，但本函数不逐字节比较 Blob/reader，也不证明同长度源未被替换。
+ * 外来 Uint8Array 结果复制为自有缓冲，默认 Blob 路径返回此次新读缓冲；不缓存结果或做并发合并。
+ * 空范围仍会调用 reader/Blob 读取，是否优化零 I/O 由端口决定；bytes 依赖调用方已验证的 Blob 合同。 */
 export async function readImportRange(bytes:Blob,reader:ImportByteReader|undefined,start:number,end:number,signal:AbortSignal):Promise<Uint8Array<ArrayBuffer>>{
  if(signal.aborted)throw fault('import_aborted');
  if(!Number.isSafeInteger(start)||!Number.isSafeInteger(end)||start<0||end<start||start>bytes.size||reader&&reader.byteLength!==bytes.size)throw fault('invalid_import_byte_range');

src/lib/canvas-runtime/import-document-stream.ts

@@ -22,8 +22,10 @@ const allowed=new Set(['documentFormatVersion','projectId','canvases','elements'
 /** JSON语法空白字节，不用于处理字符串内容。 */
 const whitespace=(byte:number)=>byte===9||byte===10||byte===13||byte===32;
 
-/** Each scan owns its cursor. An aborted scan cannot advance the resumable source. */
-/** 每次扫描从指定位置建立私有cursor，完成边界后外层才更新可恢复源进度。 */
+/** Each scan owns a private byte cursor; shared progress records completed boundaries. */
+/** 从指定字节位置建立私有 cursor；仅外层 scanNext 将完整结构边界写回源级进度。
+ * 取消不发布业务结果，但已定位的完整 ranges 可保留用于重试，不承诺整次 read 的缓存/边界都回滚。
+ * options/缓存沿用内部引用；scanner 负责定位/单值解码，不验证完整文档引用关系。 */
 function scanner(options:Options,signal:AbortSignal,start=0,cache:ScanCache={start:-1,bytes:new Uint8Array()}){
  const {bytes}=options,budget=createImportBudget(signal,options);
  let cursor=start;
@@ -41,7 +43,9 @@ function scanner(options:Options,signal:AbortSignal,start=0,cache:ScanCache={sta
  async function spaces(){while(whitespace(await peek()))await step();}
  /** 严格匹配一个结构字节，不修补缺逗号/冒号等源损坏。 */
  async function take(byte:number){await spaces();if(await peek()!==byte)throw fault('invalid_document_import');await step();}
- /** 引号/转义/栈配对扫描一个完整值range，限制嵌套深度，避免把字符串里的分隔符当边界。 */
+ /** 用 quoted/escaped/显式 stack 定位一个值范围，最多 256 层；不收集 payload 字节。
+  * 此步只找词法/括号边界，primitive 或字符串内容仍可能是非法 JSON，稍后 decode 才完整解析。
+  * 超大值也要扫描完才得到范围，maxRecordBytes 仅约束后续解码分配，不限制扫描总工作量。 */
  async function value():Promise<Range>{
   await spaces();const start=cursor,stack:number[]=[];let quoted=false,escaped=false;
   while(true){
@@ -57,7 +61,9 @@ function scanner(options:Options,signal:AbortSignal,start=0,cache:ScanCache={sta
   }
   if(cursor===start)throw fault('invalid_document_import');return{start,end:cursor};
  }
- /** 对单range校验大小、fatal UTF8、JSON语法和值域，返回原值，不修改业务ID。 */
+ /** 读取单 range，按指定上限控制分配，再 fatal UTF-8/JSON.parse/validJson；不重写业务 ID。
+  * 默认 payload 256KiB，header 调用可传独立上限；合法 JSON 不等同元素 schema 或引用关系合法。
+  * JSON.parse 本身为同步工作，扫描预算不抢占这一步；字节端口异常保持源级错误，不转成坏记录。 */
  async function decode(range:Range,limit=options.maxRecordBytes??256*1024):Promise<any>{
   check();if(range.end-range.start>limit)throw fault('record_too_large');
   const data=await readImportRange(bytes,options.readBytes,range.start,range.end,signal);let text:string;
@@ -75,7 +81,11 @@ function tombstones(value:unknown){
 /** Parser 5: canonical headers open before scanning the elements tail.
  * Out-of-order headers require the indexed interpreter to establish ownership first.
  * Ordinals remain stable; ranges are retained only as records are requested. */
-/** 打开standard header后即可返回源；真正elements/tail结构检查跟随read进行，未扫描尾部不冒称合法。 */
+/** 浅捕获 options 后打开标准头：源最多 64MiB，单个元数据值上限 4MiB，字段名上限 1KiB。
+ * 先解析整份 canvases 并验证单根/父链，再返回 canvas-first 的 ordinal 接口；此时元素/尾部可尚未读取。
+ * 头顺序不满足拥有树前提时委托索引解释器，仍暴露 parserVersion=5，不能据版本推断一定渐进扫描。
+ * 指纹只是上层传入身份；源字节证明/完整 SHA 与最终元素/入口校验由读取端口和导入准备层负责。
+ * options.signal 用于打开阶段，返回后的每次 read 使用自己的 readSignal，不自动合并原 signal。 */
 export async function openStreamingDocumentImportSource(input:Options):Promise<ImportSource>{
  const options:Options=Object.freeze({...input});
  const {bytes,signal}=options,max=options.maxRecordBytes??256*1024;
@@ -120,7 +130,9 @@ export async function openStreamingDocumentImportSource(input:Options):Promise<I
   for(const id of path){rooted.add(id);await budget.step();}
  }
  const children=canvases.filter(canvas=>canvas.id!==rootId),ranges:Range[]=[];
- // 源级进度只记录完整range边界/phase，serial只串行化延伸；failure最多输出一条终结错误。
+ // ranges 随请求积累元素字节范围，children 是已捕获子 canvas；ordinal 与原文件 byte offset 不同。
+ // 重开源需重建这些内存范围，持久 runner 保存的是稳定 ordinal/源身份，不是这里的 Promise 链。
+ // serial 只串行化范围延伸，failure 最多输出一条终结错误；请求很远的 ordinal 仍会扫描此前全部未定位项。
  let cursor=header.position(),phase:'elements'|'tail'|'done'='elements',first=true,failure:string|undefined,serial=Promise.resolve();
  /** 延伸一个element range，或验证剩余envelope与EOF；只在结构边界确认后更新cursor/phase。 */
  async function scanNext(readSignal:AbortSignal){
@@ -146,7 +158,10 @@ export async function openStreamingDocumentImportSource(input:Options):Promise<I
   await scan.take(125);await scan.spaces();if(scan.position()!==bytes.size)throw fault('invalid_document_import');
   cursor=scan.position();phase='done';
  }
- /** ordinal read：子canvas直接返回，元素按需scan定位；已定位范围逐记录解码，后续恢复可重读。 */
+ /** ordinal read：先 children，后 ranges 中元素；源根只作为 sourceRootId 别名，不作为导入子项输出。
+  * 子 canvas 可直接返回，元素定位后按独立 range 重读/解码；一个 payload 错误不抹掉其它已定位项。
+  * 结构错误记终结 failure；取消/已知字节证明错误只拒绝本次，允许同 ordinal 重试。
+  * EOF 仅在有效末序号返回 null，越过末尾仍拒绝，不能把任意大序号当作已完成。 */
  async function read(position:number,readSignal:AbortSignal):Promise<ImportLine|null>{
   if(readSignal.aborted)throw fault('import_aborted');
   if(!Number.isSafeInteger(position)||position<0)throw fault('invalid_import_cursor');

src/lib/canvas-runtime/import-document.ts

@@ -11,7 +11,11 @@ import {fault,validJson} from '../canvas-core/values.ts';
 type Range={start:number;end:number};
 /** Index the envelope without decoding element payloads. Original bytes remain the source.
  * Preparation scans O(bytes) and retains O(records) ranges; this is not constant memory. */
-/** 在64MiB源上索引envelope/记录范围，验证头与树后返回可按ordinal重读的ImportSource。 */
+/** 在最多 64MiB 源上完整扫描 envelope/元素 ranges，验证元数据与父链后才返回 parser 4。
+ * 字段名解码上限 1KiB、单元数据值 4MiB，元素默认 256KiB 且逐次 read 解码；坏 envelope 尾部会拒绝打开。
+ * bytes/signal/max 为入口局部值，readBytes 和返回 fingerprint 仍取原 options，调用方须保持选项稳定。
+ * 不生成完整源 SHA/读取证明或业务 ID；注入端口负责源字节一致性，runner 负责业务发布/恢复。
+ * 完整扫描至少访问全部源字节；父链校验另有树遍历成本，不能将全部准备工作都算作 O(bytes)。 */
 export async function openDocumentImportSource(options:{bytes:Blob;fingerprint:string;readBytes?:ImportByteReader;signal:AbortSignal;maxRecordBytes?:number}&ImportScheduling):Promise<ImportSource>{
  const {bytes,signal}=options,max=options.maxRecordBytes??256*1024;
  if(!(bytes instanceof Blob)||bytes.size>64*1024*1024||!options.fingerprint||!Number.isSafeInteger(max)||max<1)throw fault('invalid_import_source');
@@ -35,7 +39,8 @@ export async function openDocumentImportSource(options:{bytes:Blob;fingerprint:s
  }
  /** 对限定range执行fatal UTF8和JSON值域校验；key/元数据/记录可使用不同字节上限。 */
  async function decode(range:Range,limit=max,readSignal=signal){if(range.end-range.start>limit)throw fault('record_too_large');const data=await readImportRange(bytes,options.readBytes,range.start,range.end,readSignal);let text:string;try{text=new TextDecoder('utf-8',{fatal:true}).decode(data);}catch{throw fault('invalid_utf8');}try{const result=JSON.parse(text);if(!validJson(result))throw Error();return result;}catch{throw fault('invalid_json');}}
- // envelope字段名去重；elements仅保留ranges，其它字段按有限metadata大小解码。
+ // fields 用 Map 去重/保存元数据，elements 数组保存 [start,end)；扫描 payload 时不缓存其完整 JSON 对象。
+ // 范围定位只检查括号/分隔，元素内部的 JSON/UTF-8 内容错误仍可能直到 read 才发现。
  const fields=new Map<string,unknown>(),elements:Range[]=[];
  await take(123);await spaces();if(await peek()===125)throw fault('invalid_document_import');
  while(true){const key=await decode(await value(),1024);if(typeof key!=='string'||fields.has(key))throw fault('invalid_document_import');await take(58);
@@ -48,7 +53,8 @@ export async function openDocumentImportSource(options:{bytes:Blob;fingerprint:s
  const canvases=fields.get('canvases') as {id:string;parent:null|{canvasId:string;entryElementId:string}}[],ids=new Set<string>();
  for(const canvas of canvases){if(!canvas||typeof canvas.id!=='string'||!canvas.id||ids.has(canvas.id)||canvas.parent!==null&&(!canvas.parent||typeof canvas.parent.canvasId!=='string'||typeof canvas.parent.entryElementId!=='string'))throw fault('invalid_document_import');ids.add(canvas.id);}
  const roots=canvases.filter(canvas=>canvas.parent===null);if(roots.length!==1)throw fault('invalid_document_import');const rootId=roots[0].id;
- // parent链必须存在且无环；入口实际节点/引用闭合仍由后续原生转换与文档校验完成。
+ // 对每个 canvas 从头跟父链，用本路径 seen 检测环；不复用其它路径结果，深树可能反复遍历共同祖先。
+ // 这里只证明 canvas 单根/父链连通，不核对入口节点是否存在、组件引用是否闭合或 projectId 是否等于根 ID。
  const byId=new Map(canvases.map(canvas=>[canvas.id,canvas]));
  for(const canvas of canvases){const seen=new Set<string>();let current=canvas;while(current.parent){if(seen.has(current.id))throw fault('invalid_document_import');seen.add(current.id);await budget.step();const parent=byId.get(current.parent.canvasId);if(!parent)throw fault('invalid_document_import');current=parent;}}
  const tombstones=fields.get('tombstones');if(tombstones!==undefined&&(!tombstones||typeof tombstones!=='object'||Array.isArray(tombstones)||Object.values(tombstones).some(n=>!Number.isSafeInteger(n)||(n as number)<1)))throw fault('invalid_document_import');
@@ -57,7 +63,9 @@ export async function openDocumentImportSource(options:{bytes:Blob;fingerprint:s
  return Object.freeze({fingerprint:options.fingerprint,parserVersion:4,async read(position:number,readSignal:AbortSignal):Promise<ImportLine|null>{
   if(readSignal.aborted)throw fault('import_aborted');if(!Number.isSafeInteger(position)||position<0||position>count)throw fault('invalid_import_cursor');if(position===count)return null;
   const base={cursor:position,nextCursor:position+1,key:`record:${position}`};let record:any,kind:string;
-  // 单记录payload失败返回error/next ordinal，保留后续合法记录；源级字节失败和取消仍抛出。
+  // children 返回已解析的元数据记录引用，元素则每次按 range 重读/新解析；消费者不应修改共享 children。
+  // 已完成索引的读取无需再移动扫描 cursor；本次 readSignal 独立于打开阶段 signal。
+  // 单记录 payload 失败返回 error/next ordinal，不影响其它项；源级字节错误/取消仍抛出，供同序号重试。
   try{if(position<children.length){kind='canvas';record=children[position];}else{kind='element';record=await decode(elements[position-children.length],max,readSignal);}if(readSignal.aborted)throw fault('import_aborted');if(!record||typeof record!=='object'||Array.isArray(record)||typeof record.id!=='string'||!record.id)throw fault('invalid_native_import_record');return{...base,value:{kind,key:record.id,record,sourceRootId:rootId}};}catch(error){if(readSignal.aborted)throw fault('import_aborted');if(isImportByteFailure(error))throw error;return{...base,error:(error as {code?:string}).code??'invalid_document_import'};}
  }});
 }

src/lib/canvas-runtime/import-duplicate.ts

@@ -20,7 +20,10 @@ type ExternalCanvas = {id: Id; parent: CanvasRecord['parent']; entryIncarnation?
 type CopyLine = {key: string; change: Exclude<Change,{kind:'field'}>; dependencies: string[]; externalElements: ExternalElement[]; externalCanvases: ExternalCanvas[]};
 
 /** Internal source: already mapped records, with explicit guards for every retained external reference. */
-/** 兼容完整计划路径：逐change生成有限记录NDJSON，单条≤256KiB、全源≤64MiB；仍返回完整Blob。 */
+/** 完整计划兼容路径：先同步建立新 ID→源 key Map，再逐 change 编码 NDJSON，保留所有字符串直到生成 Blob。
+ * 单条含换行的 UTF-8 字节须 ≤256KiB，全源 ≤64MiB；这些是编码成本限制，不是进程峰值内存保证。
+ * 每条完成后按约每 KiB 一个工作单位调用 copy budget；单次映射建表/JSON.stringify 不被抢占。
+ * 成功前复查取消，不输出部分 Blob；不验证整个 plan 的 ID 唯一性/图合法性或计算源摘要。 */
 export async function encodeDuplicateSource(document: Document, registry: Registry, plan: DuplicatePlan, signal: AbortSignal, scheduling:ImportScheduling={}): Promise<Blob> {
   const keys = new Map<Id,string>(),parts: BlobPart[] = [];
   for (const [id,mapped] of Object.entries(plan.elementIds)) keys.set(mapped,`element:${id}`);
@@ -36,11 +39,15 @@ export async function encodeDuplicateSource(document: Document, registry: Regist
   if(signal.aborted)throw fault('copy_aborted');return new Blob(parts,{type:'application/x-ndjson'});
 }
 
-/** 共享逐记录转换器：将新映射ID关联到source key，收集owner/端点/声明引用的必要外部闭包。 */
+/** 将一条已映射创建变化封装成 CopyLine：keys 区分副本内部依赖与仍引用原图的外部身份。
+ * 收集 owner/端点/声明数据引用及外部 canvas 父链入口，去掉自身依赖；不重新映射字段或分配 ID。
+ * 返回的 change 沿用输入引用，数组/guard 未整体冻结；输入文档/映射须来自已验证的不可变计划。
+ * 这里只收集已知 copy.references，不独立调用 resolve 验组件版本，也不替代最终整图校验。 */
 export function duplicateImportLine(document:Document,registry:Registry,change:Exclude<Change,{kind:'field'}>,keys:ReadonlyMap<Id,string>):CopyLine {
   if(!change.after||change.before!==null)throw fault('invalid_duplicate_plan');
   const dependencies=new Set<string>(),elements=new Map<Id,ExternalElement>(),canvases=new Map<Id,ExternalCanvas>();
-  /** 内部canvas转成依赖；外部canvas沿父链收集guard和入口节点身份，不猜其数据字段。 */
+  /** keys 命中即登记内部依赖；否则沿原 canvas 父链收集 parent 与存在的入口代次。
+   * canvases Map 同时去重/止循环，不在这里证明父链无环或每个入口都存在，依赖合法源文档合同。 */
   const canvas=(id:Id)=>{
     const key=keys.get(id);if(key){dependencies.add(key);return;}
     let next:Id|undefined=id;
@@ -65,7 +72,9 @@ export function duplicateImportLine(document:Document,registry:Registry,change:E
   return {key,change,dependencies:[...dependencies],externalElements:[...elements.values()],externalCanvases:[...canvases.values()]};
 }
 
-/** 校验旧durable预映射行与当前job.stableIds一致，元素新incarnation必须为1，不重新分配ID。 */
+/** 旧持久源的基础封装校验：允许源种类、JSON 值域、数组形状、创建 ID 与 stableIds/key 前缀对应。
+ * element 还要求 incarnation=1；不逐字段验证 guard/dependency schema，也不证明外部 guard 集合完整。
+ * 返回原行引用，不捕获/修复源，不重新分配 ID；完整源绑定、变化及图校验仍由 runner/发布边界承担。 */
 function copyLine(line:ImportLine,job:ImportJob):CopyLine {
   const value=line.value as unknown as CopyLine;
   if(!['duplicate-ndjson','duplicate-plan'].includes(job.source?.kind??'')||!value||!validJson(value)||typeof value.key!=='string'||!Array.isArray(value.dependencies)||!Array.isArray(value.externalElements)||!Array.isArray(value.externalCanvases)||!value.change||value.change.kind!=='element'&&value.change.kind!=='canvas'||value.change.before!==null||!value.change.after||!Object.hasOwn(job.stableIds,value.key)||job.stableIds[value.key]!==value.change.id||value.change.after.id!==value.change.id||!value.key.startsWith(`${value.change.kind}:`))throw fault('invalid_duplicate_source');
@@ -73,7 +82,9 @@ function copyLine(line:ImportLine,job:ImportJob):CopyLine {
   return value;
 }
 /** Re-check the current reference contract when decoding old durable prepared sources. */
-/** 对当前复制schema重验引用：内部映射须声明依赖，外部引用须explicit preserve且有对应guard。 */
+/** 对 element 的当前 copy.references 重验：内部映射（自引用除外）须列依赖，外部须 preserve 且列 guard ID。
+ * 每个引用线性扫描 stableIds 找对应命名空间；这里只查声明数据引用，不重建 owner/端点的完整 guard 闭包。
+ * canvas 直接跳过；此步骤不是全部 CopyLine schema 校验或外部对象当前生命周期校验。 */
 function assertCopyReferences(value:CopyLine,job:ImportJob,registry:Registry){
   if(value.change.kind!=='element')return;
   const record=value.change.after!,schema=registry.components.get(record.componentId)?.copy;
@@ -84,14 +95,18 @@ function assertCopyReferences(value:CopyLine,job:ImportJob,registry:Registry){
     else if(ref.external!=='preserve'||!(ref.target==='element'?value.externalElements:value.externalCanvases).some(guard=>guard.id===id))throw fault('copy_external_reference',[record.id,id]);
   }
 }
-/** 形成runner的纯ImportUnit并保留原行作为guard，reserve只核对已有映射，不修改原图。 */
+/** 先校验预映射行/声明引用，再用 reserve 核对自身 ID，要求依赖键都在 job.stableIds 中。
+ * reserve 由调用方提供，本函数不回滚它的副作用；合法已准备源应命中现有映射而非再分配身份。
+ * dependencies/change 沿用原行引用，guard 用 JSON 克隆捕获；不检查依赖已提交，也不发布/持久化内容。 */
 export function prepareDuplicateImport(line:ImportLine,job:ImportJob,reserve:(key:string)=>Id,registry:Registry):ImportUnit {
   const value=copyLine(line,job);assertCopyReferences(value,job,registry);if(reserve(value.key)!==value.change.id)throw fault('invalid_duplicate_source');
   for(const key of value.dependencies)if(!Object.hasOwn(job.stableIds,key))throw fault('invalid_duplicate_source');
   return{key:value.key,dependencies:value.dependencies,changes:[value.change],guard:clone(line.value!)};
 }
 /** Check at the synchronous commit boundary, never only when the source was first parsed. */
-/** 提交前按当前文档核对外部节点代次/owner、canvas parent/入口代次；不符即拒绝这一单元/组。 */
+/** 同步提交前重新解释行与声明引用，再逐个核对提供的外部 element 代次/owner、canvas parent/入口代次。
+ * 内容/样式可变化而通过；组件版本等未在此额外比较，guard 是否完整依赖受信源生成与恢复校验。
+ * 不锁住对象或发布 changes；应与真正提交处于同一同步边界，中间 await 会让该检查过期。 */
 export function assertDuplicateExternal(line:ImportLine,job:ImportJob,document:Document,registry:Registry){
   const value=copyLine(line,job);assertCopyReferences(value,job,registry);
   for(const guard of value.externalElements){const record=document.elements.get(guard.id);if(!record||record.incarnation!==guard.incarnation||record.ownerCanvasId!==guard.ownerCanvasId)throw fault('copy_external_changed',[guard.id]);}

src/lib/canvas-runtime/import-file-retention.ts

@@ -15,12 +15,15 @@ export type PreviousImportFile={readonly fileId:Id;readonly byteLength:number;re
 export type ImportFile={readonly jobId:Id;readonly current:boolean;readonly file:PreviousImportFile};
 /** completed/partial/cancelled是本任务终态；paused/preparing不代表源已经不再需要。 */
 export const terminalImport=(status:ImportJob['status'])=>['completed','partial','cancelled'].includes(status);
-/** 检查退休协议与安全时间值；只是结构合法，不证明引用扫描已完整。 */
+/** 检查版本及非负安全整数时间，purgedAt 不得早于 unreferencedAt。
+ * 不与当前时钟比较，也不证明保留期已满、引用已清空或删除已提交；这些由收集器/存储边界保证。 */
 export function validFileRetirement(value:unknown):value is FileRetirement {
  const marker=value as FileRetirement;
  return !!marker&&marker.version===1&&Number.isSafeInteger(marker.unreferencedAt)&&marker.unreferencedAt>=0&&(marker.purgedAt===undefined||Number.isSafeInteger(marker.purgedAt)&&marker.purgedAt>=marker.unreferencedAt);
 }
-/** 汇总全部当前/旧源，验证job键与ID一致且同fileId不跨job重复，供原子回收检查使用。 */
+/** 从有 source 的 job 汇总当前/previous 文件，检查 job 键与 ID 及全表 fileId 唯一性。
+ * 重复包括同 job 的 current/previous 重复；无 source 的 job 不贡献文件。
+ * 只派生索引，不完整校验文件元数据；返回实际可变 Map（类型只读），值中的 file 沿用输入引用。 */
 export function importFiles(jobs:ReadonlyMap<Id,ImportJob>|undefined):ReadonlyMap<Id,ImportFile> {
  const files=new Map<Id,ImportFile>();
  for(const [jobId,job]of jobs??[]){
@@ -32,18 +35,22 @@ export function importFiles(jobs:ReadonlyMap<Id,ImportJob>|undefined):ReadonlyMa
  }
  return files;
 }
-/** 当前源仅终态可退休；旧源可独立退休，且同job文件ID互异、元数据和摘要合法。 */
+/** 当前源带任何退休标记时都要求终态；previous 文件可独立退休，逐项检查 ID/长度/可选摘要/标记。
+ * 最后检查 current+previous ID 互异；当前源自身的 fileId/长度/摘要等仍由导入源完整校验负责。 */
 export function validateImportFileRetention(source:NativeImportSource,status:ImportJob['status']) {
  if(source.retirement!==undefined&&(!validFileRetirement(source.retirement)||!terminalImport(status)))throw fault('invalid_import_file_retirement');
  if(source.previousFiles!==undefined&&(!Array.isArray(source.previousFiles)||source.previousFiles.some(file=>!file||typeof file.fileId!=='string'||!file.fileId||!Number.isSafeInteger(file.byteLength)||file.byteLength<0||file.sha256!==undefined&&!/^[a-f0-9]{64}$/.test(file.sha256)||file.retirement!==undefined&&!validFileRetirement(file.retirement))))throw fault('invalid_import_file_retirement');
  const ids=[source.fileId,...(source.previousFiles??[]).map(file=>file.fileId)];if(new Set(ids).size!==ids.length)throw fault('import_file_identity_conflict');
 }
-/** 只改退休标记并保留文件身份；相同标记复用原对象，清标记不删除文件记录。 */
+/** 仅替换/移除 retirement；相等时沿用原对象，否则返回冻结记录。
+ * 不验证新标记或任务终态，也不删除文件；调用方仍需经过发布/源结构校验。 */
 function mark<T extends PreviousImportFile>(file:T,retirement:FileRetirement|undefined):T {
  if(equal(file.retirement,retirement))return file;
  const {retirement:_,...rest}=file;return freeze(retirement?{...rest,retirement}:rest) as T;
 }
-/** 按fileId批量更新当前/旧源标记，必要时copy-on-write并推进job.generation；不直接删字节。 */
+/** 按 fileId 更新 current/previous 标记，首次修改才复制 imports，每个变化 job 的 generation 只加一次。
+ * 未命中任何文件的 marker 忽略，重复同值无变化时复用 runtime；这里只改元数据，不校验退休资格或删字节。
+ * 新 generation 溢出则拒绝，不能生成无法可靠恢复的任务版本。 */
 export function markImportFiles(runtime:RuntimeState,markers:ReadonlyMap<Id,FileRetirement|undefined>):RuntimeState {
  let imports=runtime.imports;
  for(const [id,job]of runtime.imports??[]){
@@ -56,7 +63,10 @@ export function markImportFiles(runtime:RuntimeState,markers:ReadonlyMap<Id,File
  return imports===runtime.imports?runtime:Object.freeze({...runtime,imports:readMap(imports!)});
 }
 /** A source file cannot disappear from its owning job, become an asset or regain execution after purge. */
-/** 每次Root发布前校验源身份单调性并取消不安全软退休；已purge仍被pin明确拒绝。 */
+/** 发布前校验文件归属/长度/已有摘要单调性，并清掉重 pin 或覆盖不完整的软退休。
+ * 已 purge 的 retirement 不得改写且不能再 pin；当前源若带标记回到非终态也会被结构校验拒绝。
+ * reserved 只让此函数绕过快路，不逐 ID 检查占用；统一 reservation 屏障由外围资源保留钩子执行。
+ * referencesChanged 默认 true；传 false 的调用方须确保引用变化已准确反映，不能仅凭 Map 相等猜完整性。 */
 export function prepareImportFileRetention(previous:RuntimeState,next:RuntimeState,pins:()=>{complete:boolean;pins:ReadonlyMap<Id,{has(owner:string):boolean}>},reserved:ReadonlySet<Id>,referencesChanged=true):RuntimeState {
  const hasSoft=[...(next.imports?.values()??[])].some(job=>job.source&&[job.source,...(job.source.previousFiles??[])].some(file=>file.retirement&&file.retirement.purgedAt===undefined));
  if(previous.imports===next.imports&&previous.resources===next.resources&&previous.resourcePins===next.resourcePins&&!reserved.size&&!hasSoft&&!referencesChanged)return next;
@@ -69,8 +79,10 @@ export function prepareImportFileRetention(previous:RuntimeState,next:RuntimeSta
   if(!entry||entry.jobId!==old.jobId||entry.file.byteLength!==old.file.byteLength||old.file.sha256!==undefined&&entry.file.sha256!==old.file.sha256||!old.current&&entry.current)throw fault('import_file_identity_conflict',[id]);
   if(old.file.retirement?.purgedAt!==undefined&&!equal(old.file.retirement,entry.file.retirement))throw fault('import_source_retired',[id]);
  }
+ // 无软标记、reservation 或 purge 记录时不调用 pins；身份校验已完成，不等于执行了完整引用扫描。
  if(!hasSoft&&!reserved.size&&![...after.values()].some(entry=>entry.file.retirement?.purgedAt!==undefined))return next;
  // 覆盖未知或重新引用都清软标记，下一次无引用须重新计保留期，不沿用旧时钟直接删除。
+ // 新摘要可在旧值缺失时补齐，但已有摘要不能替换；清标记通过 markImportFiles 同步推进 job generation。
  const coverage=pins(),clear=new Map<Id,undefined>();
  for(const [id,entry]of after){
   if(entry.file.retirement?.purgedAt!==undefined){if(coverage.pins.has(id))throw fault('import_source_retired',[id]);continue;}

src/lib/canvas-runtime/import-groups.ts

@@ -5,10 +5,15 @@
 import type { ImportLocator } from './imports.ts';
 import { fault } from '../canvas-core/values.ts';
 
-/** Ready SCCs are indivisible. Ordinary records retain source-order FIFO selection. */
-/** pending按源顺序输入；返回有序原子组，不实际提交，缺依赖的组继续等待而非直接丢失。 */
+/** Ready SCCs are indivisible; source order guides each readiness scan. */
+/** pending 由调用方按源顺序提供且 key 唯一；先找 SCC，再按组内/组间最早源索引扫描。
+ * 缺外部依赖的组会跳过，可选择其后的已就绪组；同轮后面补齐依赖也不回头重扫，留给下一次调用。
+ * 不修改 committed/pending，不读取源或实际提交；输出数组可变且 row 沿用输入引用。
+ * limits 与 locator 成本须先校验；本函数不核对真实编码字节/changes，也没有中途取消或异步让出。 */
 export function selectImportGroups(pending: readonly ImportLocator[], committed: ReadonlySet<string>, limits: {units: number; bytes: number; changes: number}): readonly (readonly ImportLocator[])[] {
-  // 正向边仅含当前pending内依赖，反向表用于第二次DFS；原index保留稳定源顺序。
+  // byKey 用 key→原记录/源索引，edges 是依赖邻接表，reverse 是依赖→引用者表。
+  // 建图只含 pending 内边；外部 key 暂不入图，稍后用 committed 判定是否满足。
+  // 全段建图与排序同步完成，runner 应先限制 pending 大小，不能靠返回组数限制本次计算成本。
   const byKey = new Map(pending.map((row, index) => [row.key, {row, index}])), edges = new Map<string, string[]>(), reverse = new Map<string, string[]>();
   for (const row of pending) {
     const dependencies = row.dependencies.filter(key => byKey.has(key)); edges.set(row.key, dependencies);
@@ -39,11 +44,13 @@ export function selectImportGroups(pending: readonly ImportLocator[], committed:
   for (const group of components) {
     const internal = new Set(group.map(row => row.key));
     if (!group.every(row => row.dependencies.every(key => available.has(key) || internal.has(key)))) continue;
-    // SCC不可拆：单组字节/changes超安全上限必须报错，不能分批提交半个循环引用。
+    // 只有依赖就绪的组才检查硬成本；超限直接抛错，即使前面已选了组也不会返回部分结果。
+    // SCC 不可拆，依赖未就绪的超限组仍先等待，不能用拆组绕过循环引用完整性。
     const size = group.reduce((sum, row) => sum + row.byteLength, 0), count = group.reduce((sum, row) => sum + row.changeCount, 0);
     if (size > limits.bytes || count > limits.changes) throw fault('import_dependency_group_capacity');
     // The frame's adaptive unit budget is soft for one SCC, byte/change safety limits are hard.
-    // 第一组可超过units软预算以闭合环；后续组和字节/changes总预算仍保守限制。
+    // 第一组可超过 units 软预算以闭合环，字节/changes 总量始终不得超限。
+    // 后续组放不下就继续找后面的较小可用组，不以 break 阻止其它独立组；available 只加入实际 chosen 的键。
     if (units && units + group.length > limits.units || bytes + size > limits.bytes || changes + count > limits.changes) continue;
     chosen.push(group); units += group.length; bytes += size; changes += count; for (const row of group) available.add(row.key);
   }

src/lib/canvas-runtime/import-identities.ts

@@ -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;}}));
 }

src/lib/canvas-runtime/import-integrity.ts

@@ -5,13 +5,17 @@
 import { fault } from '../canvas-core/values.ts';
 import {createSha256} from './sha256.ts';
 /** Complete-source SHA-256, with bounded chunk memory and cooperative fallback scheduling. */
-/** 默认64KiB分块（配置上限4MiB），每块读前/读后检查取消，并在块间合作让出。 */
+/** 顺序 slice 读取完整 Blob，默认 64KiB 分块（配置上限 4MiB），空文件也返回合法摘要。
+ * 每块读前/读后及 yield 后检查取消；原生 arrayBuffer/yield 本身不被信号强制终止。
+ * 默认块间 setTimeout(0) 让出，只有仍有下一块才 yield；自定义 yieldTask 决定实际调度公平性。
+ * 块内 hash.update 为同步 CPU 工作，不会中途取消；读/让出错误直接传播，不返回部分摘要。 */
 export async function importSourceDigest(bytes:Blob,signal?:AbortSignal,options:{chunkBytes?:number;yieldTask?:()=>Promise<void>}={}):Promise<string>{
   const chunk=options.chunkBytes??64*1024,yieldTask=options.yieldTask??(()=>new Promise<void>(resolve=>setTimeout(resolve,0)));
   if(!(bytes instanceof Blob)||!Number.isSafeInteger(chunk)||chunk<1||chunk>4*1024*1024)throw fault('invalid_digest_input');
   /** 读/计算/让出边界统一检查 signal；异步读取即使无法中止，迟到字节也不再参与有效结果。 */
   const check=()=>{if(signal?.aborted)throw fault('import_aborted');};check();const hash=createSha256();
-  // 更新增量状态后释放对本块的局部引用；空文件直接 hex 得到标准空输入摘要。
+  // 只顺序持有当前块，hash 自身不累计输入；part 在本次迭代/yield 期间仍可存在，实际释放时机由 GC 决定。
+  // 空文件跳过读取/让出，最后 check 后直接 hex；有界分块不是整个应用进程的内存硬上限。
   for(let cursor=0;cursor<bytes.size;cursor+=chunk){check();const part=await bytes.slice(cursor,cursor+chunk).arrayBuffer();check();hash.update(new Uint8Array(part));if(cursor+chunk<bytes.size){await yieldTask();check();}}
   check();return hash.hex();
 }

src/lib/canvas-runtime/import-json-array.ts

@@ -9,7 +9,10 @@ import type {ImportSource,ImportLine} from './imports.ts';
 import {fault,validJson} from '../canvas-core/values.ts';
 /** Seekable JSON array reader. Cursors are byte offsets after '[' or a record comma.
  * Structure errors end the source; previously published records remain explicit. */
-/** 捕获Blob/指纹与读取预算，缓存一块源字节；本解析器不分配业务ID、不发布history或发送请求。 */
+/** 捕获 Blob/max/chunk 与返回指纹标量，按字节 offset 每次返回一条记录，缓存一个读取块。
+ * readBytes 与调度选项仍从原 options 读取，调用方应保持它们稳定；这里不建立源摘要/读取证明。
+ * 默认单条 256KiB/块 16KiB，未给 maxRecordBytes 设置总上限，也不限制源文件总长。
+ * 不分配业务 ID、不发布 history 或发送请求；缓存不是持久进度，合法边界由 runner 保存。 */
 export function createJsonArrayImportSource(options:{bytes:Blob;fingerprint:string;readBytes?:ImportByteReader;maxRecordBytes?:number;chunkBytes?:number}&ImportScheduling):ImportSource{
  const bytes=options.bytes,max=options.maxRecordBytes??256*1024,chunk=options.chunkBytes??16384;
  if(!(bytes instanceof Blob)||!options.fingerprint||!Number.isSafeInteger(max)||max<1||!Number.isSafeInteger(chunk)||chunk<1||chunk>max)throw fault('invalid_import_source');
@@ -18,6 +21,7 @@ export function createJsonArrayImportSource(options:{bytes:Blob;fingerprint:stri
  /** read每次返回一个ImportLine及nextCursor；EOF返回null，源级I/O失败仍抛出而不伪装坏记录。 */
  return Object.freeze({fingerprint:options.fingerprint,parserVersion:3,async read(start:number,signal:AbortSignal):Promise<ImportLine|null>{
   if(!Number.isSafeInteger(start)||start<0||start>bytes.size)throw fault('invalid_import_cursor');
+  // EOF offset 直接返回 null，不重扫先前数组结构；任意范围内 seek 也不证明是合法记录起点。
   if(start>0&&start===bytes.size){if(signal.aborted)throw fault('import_aborted');return null;}
   if(bytes.size===0)throw fault('invalid_json_array');
   let cursor=start;const budget=createImportBudget(signal,options);
@@ -32,7 +36,8 @@ export function createJsonArrayImportSource(options:{bytes:Blob;fingerprint:stri
   await spaces();if(start===0){if(await peek()!==91)return failure('invalid_json_array');await advance();await spaces();}
   if(await peek()===93){await advance();await spaces();if(cursor!==bytes.size)return failure('invalid_json_array');if(start!==0){/* Empty tail is valid only after a record, not a trailing comma. */return failure('invalid_json_array');}return null;}
   if(await peek()===-1)return failure('incomplete_json_array');
-  // quoted/escaped隔离字符串分隔符，stack配对{}与[]；超大小后仍扫描至合法边界但不再保留字节。
+  // parts 是至多 max 个字节数值的普通数组（内存成本不等于 max 字节），stack 至多保留 256 层括号。
+  // quoted/escaped 只定位边界，不完整校验 JSON；超大小后仍扫描但不再收集，坏结构仍可能终结整个源。
   const recordStart=cursor,parts:number[]=[],stack:number[]=[];let quoted=false,escaped=false,oversized=false;
   while(true){const byte=await peek();if(byte===-1)return failure('incomplete_json_array');
    if(!quoted&&stack.length===0&&(byte===44||byte===93))break;
@@ -41,13 +46,15 @@ export function createJsonArrayImportSource(options:{bytes:Blob;fingerprint:stri
    else if(byte===34)quoted=true;else if(byte===123||byte===91){stack.push(byte);if(stack.length>256)return failure('json_nesting_limit');}else if(byte===125||byte===93){if(stack.pop()!==(byte===125?123:91))return failure('invalid_json_array');}
    await advance();
   }
-  // 消费外层逗号或]并检查尾部/尾逗号；内嵌数组的]已由stack处理，不会截断记录。
+  // 先确认记录后的外层分隔与尾部，再返回此记录；若尾逗号/垃圾在此处发现，本记录也返回结构失败。
+  // 数组内嵌 ] 已由 stack 处理；nextCursor 消费分隔和后续空白，最后一项则推进到真实 EOF。
   const delimiter=await peek();await advance();
   if(delimiter===93){await spaces();if(cursor!==bytes.size)return failure('invalid_json_array');}
   else {await spaces();if(await peek()===93||await peek()===-1)return failure('invalid_json_array');}
   const base={cursor:start,nextCursor:cursor,key:`byte:${start}`};
   if(oversized)return{...base,error:'record_too_large'};
-  // 只解码这一记录：fatal UTF8防替换字符掩盖损坏，再JSON.parse/validJson校验值域。
+  // fatal UTF-8 与 JSON.parse 在边界已确定后处理，失败可随 nextCursor 继续下一项；不做元素业务 schema 校验。
+  // JSON.parse 同步完成且无中途取消，记录扫描的预算不抢占解码/解析；调用方仍需在采纳结果前校验生命周期。
   let text:string;try{text=new TextDecoder('utf-8',{fatal:true}).decode(new Uint8Array(parts));}catch{return{...base,error:'invalid_utf8'};}
   try{const value=JSON.parse(text);return validJson(value)?{...base,value}:{...base,error:'invalid_json_value'};}catch{return{...base,error:'invalid_json'};}
  }});

src/lib/canvas-runtime/import-native.ts

@@ -1,6 +1,7 @@
 /**
  * 原生导入记录到纯ImportUnit的转换：源ID经reserve映射为新身份，依赖保留为source key等待闭合。
- * $target或文档源根映射到显式选定的现有canvas；副本incarnation从1开始，不继承旧墓碑/任务执行。
+ * $target或文档源根映射到显式选定的现有canvas；副本incarnation从1开始，不继承旧墓碑。
+ * 任务字段只按组件copy.omit声明去除；转换不创建/启动生成任务，不能据此假定所有未知执行字段都已过滤。
  * 本模块只规划changes，不写文档、不上传/授权；资源地址和授权事实由宿主/engine另行提供与校验。
  */
 import type { Document, ElementRecord, Id, Json, Registry } from '../canvas-core/types.ts';
@@ -9,14 +10,18 @@ import { remapCopyData } from '../canvas-core/duplicate.ts';
 import { clone, fault } from '../canvas-core/values.ts';
 import type { ImportJob, ImportLine, ImportUnit } from './imports.ts';
 
-/** 校验目标canvas仍存在且入口ID/代次或根身份未变，防旧任务把尾批导入后来替换的分区。 */
+/** 按 source.targetCanvasId 定位当前 canvas；有 targetEntry 时核对入口 ID 与元素代次，否则要求根。
+ * 不比较整个祖先链/父 canvas、入口组件或 job.projectId；同入口移动后的目标仍可通过此局部身份检查。
+ * 返回原 source 引用，不生成新任务或锁住目标，后续提交前还需再检查当前文档。 */
 export function assertNativeImportTarget(job:ImportJob,document:Document){
   const source=job.source,canvas=source?document.canvases.get(source.targetCanvasId):undefined;
   if(!source||!canvas)throw fault('import_target_missing');
   if(source.targetEntry?(canvas.parent?.entryElementId!==source.targetEntry.id||document.elements.get(source.targetEntry.id)?.incarnation!==source.targetEntry.incarnation):canvas.parent!==null)throw fault('import_target_changed');
   return source;
 }
-/** 已committed依赖必须仍是原绑定生命周期；用户删后重建同ID不能被后续导入误认领。 */
+/** 仅检查已在 committedSourceKeys 的依赖：stableIds 定位目标，再以 job.bindings 核对生命周期。
+ * element 检查代次，canvas 检查仍存在、入口 ID 及已记录入口代次；不比较正文、几何、组件或全部 owner 链。
+ * 未提交/SCC 内部依赖不在这里猜成存在，留给分组选取与原子创建后的文档校验；本函数不改变绑定。 */
 export function assertNativeImportDependencies(job:ImportJob,document:Document,dependencies:readonly string[]){
   for(const key of dependencies)if(job.committedSourceKeys.includes(key)){
     const id=job.stableIds[key],binding=job.bindings?.[id];
@@ -27,7 +32,11 @@ export function assertNativeImportDependencies(job:ImportJob,document:Document,d
 }
 
 /** Native NDJSON records use source IDs; $target names the explicitly chosen existing canvas. */
-/** 校验记录封装/源ID，预留自身与引用ID，生成一条创建变化及去除自引用后的依赖列表。 */
+/** 校验封装/源 ID 后克隆 record，reserve 自身与引用键，生成一条 before=null 的创建变化和依赖列表。
+ * reserve 可能先于后续类型校验调用；本函数不回滚自定义 reserve 的副作用，runner 应使用私有捕获上下文。
+ * registry.resolve 只确认已知类型/版本与 copy 声明，不等同完整数据/几何/引用校验；最终提交仍需验证文档。
+ * 原几何/其它字段按记录携带，不在此统一转换世界坐标，也不检查所有目标 ID 的文档/墓碑冲突。
+ * 返回的 ImportUnit/changes envelope 未整体冻结，交 runner 捕获、计成本、持久化和发布。 */
 export function prepareNativeImport(line:ImportLine,job:ImportJob,reserve:(key:string)=>Id,document:Document,registry:Registry,resourceURL?:(id:Id)=>string):ImportUnit {
   const source=assertNativeImportTarget(job,document);
   const raw=line.value as Record<string,Json>|undefined;
@@ -39,7 +48,8 @@ export function prepareNativeImport(line:ImportLine,job:ImportJob,reserve:(key:s
   /** 根/$target直接重定向目标，子canvas则分配稳定新ID并登记canvas依赖。 */
   const owner=(id:Json):Id=>{if(id==='$target'||source.kind==='native-document'&&id===raw.sourceRootId){canvasIds.set(id as string,source.targetCanvasId);return source.targetCanvasId;}if(typeof id!=='string'||!id)throw fault('invalid_import_reference');const key=`canvas:${id}`;dependencies.add(key);const mapped=reserve(key);canvasIds.set(id,mapped);return mapped;};
   const key=`${raw.kind}:${raw.key}`,id=reserve(key);
-  // 不把源根作为第二个根插入；这里只处理有parent的子canvas，parent与入口都使用新映射。
+  // 只接受带 parent 的子 canvas；源根由读取器排除，再通过 sourceRootId/$target alias 接到现有目标。
+  // parent/record 其它属性沿用克隆数据，额外 schema/树约束不会在此分支自动补齐。
   if(raw.kind==='canvas'){
     const parent=record.parent as Record<string,Json>|null;
     if(!parent||typeof parent!=='object'||Array.isArray(parent))throw fault('invalid_import_canvas');
@@ -49,7 +59,8 @@ export function prepareNativeImport(line:ImportLine,job:ImportJob,reserve:(key:s
   // record是脱离源的副本，original是其类型视图；未知组件/缺复制声明不猜字段含义。
   const original=record as unknown as ElementRecord,definition=registry.components.get(original.componentId);
   if(registry.resolve(original)!=='known'||!definition?.copy||!original.data||typeof original.data!=='object'||Array.isArray(original.data))throw fault('import_component_unavailable');
-  // 文档图片需宿主提供规范资源URL；仅重建引用不代表完成授权，授权由运行时后续门禁证明。
+  // native-document 的非空资源字段要求宿主 resourceURL：值须为非空 ID，assetId 还重建 data.src。
+  // callback 只是地址提供者，此处不读取字节/校验权限；其它资源字段不自动改名，NDJSON 也不走此文档专用分支。
   if(source.kind==='native-document')for(const key of definition.resourceFields??[]){const value=original.data[key];if(value===undefined||value===null)continue;if(!resourceURL)throw fault('import_resource_authorization_required');if(typeof value!=='string'||!value)throw fault('invalid_import_reference');if(key==='assetId')record.data={...original.data,src:resourceURL(value)};}
   record.data=original.data;
   // 只遍历schema声明引用，避免重写普通文字里的ID；omit字段由共享remapCopyData处理。
@@ -60,5 +71,7 @@ export function prepareNativeImport(line:ImportLine,job:ImportJob,reserve:(key:s
     if(!original.source||!original.target)throw fault('invalid_import_endpoint');
     Object.assign(after,{source:{...original.source,elementId:element(original.source.elementId)},target:{...original.target,elementId:element(original.target.elementId)}});
   }else if(original.structure!=='node')throw fault('invalid_import_structure');
+  // Set 保留引用首次遇到的顺序并去重；删除自身依赖避免单节点自引用被误当外部等待。
+  // 尚未出现的定义仍有稳定 reserve ID/依赖键，缺失定义由 runner 后续报告，不直接连回源项目。
   dependencies.delete(key);return{key,dependencies:[...dependencies],changes:[{kind:'element',id,before:null,after:after as ElementRecord}]};
 }

src/lib/canvas-runtime/import-read-proof.ts

@@ -15,7 +15,9 @@ const MAX_SOURCE_BYTES=64*1024*1024;
 /** version=1是块证明DTO版本，与source.integrityVersion=2的业务封存协议不是同一版本域。 */
 export type ImportReadProof={readonly version:1;readonly fileId:string;readonly byteLength:number;readonly blockBytes:16384;readonly blocks:readonly {readonly index:number;readonly sha256:string}[]};
 /** This binds only read blocks. It is not a whole-source digest or permission to send mutations. */
-/** 校验fileId/长度/固定块大小、严格递增的合法块索引及摘要；可表示只读过部分非连续块。 */
+/** 校验源身份/长度、固定块宽、严格递增的合法块索引、摘要格式及允许字段，再捕获冻结 DTO。
+ * 可包含不连续的部分块，不要求完整前缀；这里不读 Blob 或验证摘要真实性，也不是整源 SHA。
+ * 缺记录/非法 JSON/未知版本报解释器不可用，其它身份/结构错误报 invalid_import_read_proof。 */
 export function validateImportReadProof(value:unknown,fileId:string,byteLength:number):ImportReadProof{
  if(typeof fileId!=='string'||!fileId||!Number.isSafeInteger(byteLength)||byteLength<0||byteLength>MAX_SOURCE_BYTES)throw fault('invalid_import_read_proof');
  const proof=value as ImportReadProof;
@@ -29,7 +31,10 @@ export function validateImportReadProof(value:unknown,fileId:string,byteLength:n
 
 /** Bounded, seekable verified reads for parsers; checkpoints contain hashes, never byte buffers.
  * Restored evidence must be checked with verify() before a runner resumes business changes. */
-/** 创建可seek的验证reader；初始证明与源绑定，port.read成功后才把新块追加到本地证明。 */
+/** 建立 seek reader：hashes 保存期望摘要，resident 是按 Map 顺序淘汰的 LRU，pending 合并同块在途读取。
+ * 初始 proof 仅结构校验即进入 hashes/getProof；没有 verified 标志，调用方须在恢复业务前主动 verify。
+ * 最多 4 个活跃非空 range、4 个不同块的原生读取；驻留默认 4 块（最多 64），单 range 默认/最多 4MiB。
+ * range 输出、在途块和 Blob 本身另占内存，residentLimit 不是整体内存硬上限；本实例不持久化证明。 */
 export function createImportReadProof(input:{bytes:Blob;fileId:string;proof?:ImportReadProof;maxResidentBlocks?:number;maxReadBytes?:number}&ImportScheduling){
  const options=Object.freeze({...input});
  const {bytes,fileId}=options,residentLimit=options.maxResidentBlocks??4,readLimit=options.maxReadBytes??4*1024*1024;
@@ -40,13 +45,17 @@ export function createImportReadProof(input:{bytes:Blob;fileId:string;proof?:Imp
  type Block={index:number;sha256:string;data:Uint8Array};
  const resident=new Map<number,Block>(),pending=new Map<number,Promise<Block>>(),lifecycle=new AbortController();
  let closed=false,activeReads=0,proof:ImportReadProof=initial;
- /** 每次等待前后检查生命周期/取消；close是源关闭，调用者abort是停止此订阅采纳。 */
+ /** 入口/成功采纳时检查 closed 与 signal，关闭优先报 import_source_closed，其次报 import_aborted。
+  * 单个订阅取消只停止等待，不终止共享原生块读取；已拒绝的底层 Promise 仍可能保留自己的原始错误。 */
  const check=(signal:AbortSignal)=>{if(closed)throw fault('import_source_closed');if(signal.aborted)throw fault('import_aborted');};
  /** 单调用可取消等待共享块Promise，不强制取消可能正被其它range复用的只读底层读取。 */
  function wait<T>(task:Promise<T>,signal:AbortSignal):Promise<T>{
   check(signal);return new Promise((resolve,reject)=>{const abort=()=>{try{check(signal);}catch(error){reject(error);}};signal.addEventListener('abort',abort,{once:true});task.then(value=>{signal.removeEventListener('abort',abort);try{check(signal);resolve(value);}catch(error){reject(error);}},error=>{signal.removeEventListener('abort',abort);reject(error);});});
  }
- /** 先命中LRU或共享pending，再读块并对旧摘要；新原图与已证明块不符即源改变。 */
+ /** 命中 resident 时移动到 Map 尾部作为最近使用，命中 pending 时复用同一 Promise。
+  * 缺块就读完整对齐 16KiB（最后块截 EOF）并计算 SHA，可能覆盖请求 range 之外的相邻字节。
+  * 比对 hashes 中旧期望后放 resident，但不在此新增持久候选 proof；range 失败也可留下可复用缓存。
+  * 缓存命中不重新读 Blob/算摘要，依赖 Blob 不可变合同；淘汰只丢字节，不丢已提交的期望摘要。 */
  function block(index:number):Promise<Block>{
   const cached=resident.get(index);if(cached){resident.delete(index);resident.set(index,cached);return Promise.resolve(cached);}
   const active=pending.get(index);if(active)return active;
@@ -61,7 +70,10 @@ export function createImportReadProof(input:{bytes:Blob;fileId:string;proof?:Imp
   })();
   pending.set(index,task);void task.finally(()=>{if(pending.get(index)===task)pending.delete(index);}).catch(()=>{});return task;
  }
- /** 精确range端口：只分配所需输出，逐块拼接并按软预算让出，最后成功才提交used块证明。 */
+ /** 精确 range 端口：要求 end ≤ EOF，不自行截断；空范围在容量检查前返回，不读块/新增证明。
+  * 非空范围分配独立输出并逐块拼接，每块向预算记 128 单位，最后检查取消与并发摘要一致性。
+  * 只有整次范围成功才将 used 中新块加入 hashes/proof；取消/失败不提交本次部分块，也不回退其它成功读取的证明。
+  * activeReads 随等待退出而归还，真实不可取消 I/O 仍占 pending 容量，不能用大量取消绕过底层上限。 */
  const port:ImportByteReader=Object.freeze({byteLength:bytes.size,async read(start:number,end:number,signal:AbortSignal){
   const combined=AbortSignal.any([signal,lifecycle.signal]);check(combined);
   if(!Number.isSafeInteger(start)||!Number.isSafeInteger(end)||start<0||end<start||end>bytes.size||end-start>readLimit)throw fault('invalid_import_byte_range');
@@ -81,9 +93,12 @@ export function createImportReadProof(input:{bytes:Blob;fileId:string;proof?:Imp
   }finally{activeReads--;}
  }});
  return Object.freeze({port,getProof:()=>proof,
-  /** 重开后验证所有已保存块；不扫描尚未读到的尾部，故不能代替完整SHA或已durable封存。 */
+  /** 对调用开始时 hashes 中的索引逐块核对，不增加新证明块、不产生完整源摘要或自动持久化。
+   * 重开实例缓存为空时实际重读旧块；同实例调用可命中 resident，不强制绕过缓存重新读物理字节。
+   * 不核对尚未证明的尾部，也不锁住并发 range；是否已安全恢复、何时封存由引擎决定。 */
   async verify(signal:AbortSignal){const combined=AbortSignal.any([signal,lifecycle.signal]),budget=createImportBudget(combined,options);check(combined);for(const index of [...hashes.keys()]){await wait(block(index),combined);await budget.step(128);}check(combined);},
-  /** 幂等关闭，清驻留字节并取消等待者；已开始的只读Blob读取可能迟到，由closed检查拒绝采纳。 */
+  /** 幂等关闭并清 resident/取消等待者，不清 hashes/proof，getProof 仍可读取最后不可变快照。
+   * 不等待原生 Blob 读取退出；pending 由各 Promise finally 清理，迟到读取经 closed 检查拒绝进入缓存。 */
   close(){if(closed)return;closed=true;resident.clear();lifecycle.abort();},
   /** 只读诊断：驻留/活range/pending块/证明块分别计数，不当作导入完成百分比。 */
   stats:()=>Object.freeze({residentBlocks:resident.size,activeReads,pendingBlocks:pending.size,proofBlocks:hashes.size,closed}),

src/lib/canvas-runtime/import-verification.ts

@@ -8,20 +8,28 @@ import {importNeedsSeal,validateImportJob,type ImportJob} from './imports.ts';
 import {validateImportReadProof} from './import-read-proof.ts';
 
 /** A derived durable-cut index, never an in-memory permission boolean. */
-/** 从给定job表派生fileId→SHA索引；调用者须传已可靠保存的cut，本函数不执行落盘。 */
+/** 从 integrity-v2、带 SHA 且无 integrityError 的 job 派生 fileId→SHA Map，不扫描字节或读取存储。
+ * 调用方必须传已持久 cut；函数不证明其来源可靠，也不独立调用 validateImportJob 验摘要。
+ * 返回实际可变 Map，若重复 fileId 后项覆盖前项；文件身份唯一性由外围约束保证。 */
 export function importSeals(jobs:ReadonlyMap<Id,ImportJob>|undefined){
  const seals=new Map<Id,string>();for(const job of jobs?.values()??[])if(job.source?.integrityVersion===2&&job.source.sha256&&!job.source.integrityError)seals.set(job.source.fileId,job.source.sha256);return seals;
 }
-/** integrity-v2任务需自身已完整验证且durable seals匹配；取消且零已提交前缀的任务可不阻塞。 */
+/** 整个 job 表的发送闸门：每个非豁免 integrity-v2 源都须无需 seal 且与 seals 中 SHA 相等。
+ * 取消且 committedSourceKeys 为空者豁免；不按本次请求挑选 job，也不重验块证明/实际存储事务。
+ * 其它 integrityVersion 在此跳过，是否支持/合法由 job 解释器先校验，不能把 true 当所有源都已验证。 */
 export function importsMaySend(jobs:ReadonlyMap<Id,ImportJob>|undefined,seals:ReadonlyMap<Id,string>){
  for(const job of jobs?.values()??[])if(job.source?.integrityVersion===2&&!(job.status==='cancelled'&&!job.committedSourceKeys.length)&&(importNeedsSeal(job)||seals.get(job.source.fileId)!==job.source.sha256))return false;return true;
 }
 /** Only engine-owned publication paths may advance read evidence or source verification. */
-/** 发布前保护引擎拥有的readProof/SHA/执行进度，未持owner任务ID的路径不能伪造或删除它们。 */
+/** 比较前后 job 表保护 integrity-v2 证据，owner 是引擎传入的当前任务 ID，不是外部权限令牌。
+ * 同一表引用直接返回，依赖不可变状态合同；v2 job 不得删除或降级，即使 owner 匹配也不例外。
+ * 每个 next v2 job 验结构且要求 proof 索引为从 0 开始的连续前缀，比通用 seek reader 更严格。
+ * owner 可推进证据/执行事实，仍不能改 fileId/长度/已有 SHA 或丢改旧块；此处不重算字节或检查持久水位。 */
 export function assertImportEvidence(previous:ReadonlyMap<Id,ImportJob>|undefined,next:ReadonlyMap<Id,ImportJob>|undefined,owner:Id|undefined){
  if(previous===next)return;
  for(const[id,job]of previous??[])if(job.source?.integrityVersion===2&&!next?.has(id))throw fault('import_integrity_owned',[id]);
- /** 对比执行事实时剔除generation和源retirement生命周期字段；其它进度/身份仍要求合法owner。 */
+ /** 比较执行事实时仅剔除 job.generation 和当前 source.retirement；previousFiles 等内容仍参与比较。
+  * 允许普通保留流程调整这些排除字段，不在这里证明 generation/退休时钟单调，交其它发布校验处理。 */
  const execution=(job:ImportJob|undefined)=>{if(!job)return job;const{generation:_,source,...body}=job;if(!source)return body;const{retirement:__,...identity}=source;return {...body,source:identity};};
  for(const[id,job]of next??[]){const source=job.source,old=previous?.get(id)?.source;if(source?.integrityVersion!==2){if(old?.integrityVersion===2)throw fault('import_integrity_owned',[id]);continue;}
   validateImportJob(job);const proof=validateImportReadProof(source.readProof,source.fileId,source.byteLength);

src/lib/canvas-runtime/imports.ts

@@ -1,7 +1,8 @@
 /**
  * 渐进导入的持久job合同、NDJSON解释器和合作式runner。解析得到稳定ID/locator，依赖闭合后原子加入文档，
  * job进度与文档同Root发布；暂停/取消保留已提交内容，失败逐记录或按不可分依赖组报告partial。
- * runner不拥有第二份持久job store：ports.getJob是事实源，所有await后的业务采纳受generation/身份检查。
+ * runner不拥有第二份持久job store：ports.getJob是事实源，关键异步结果采纳前重查generation/身份。
+ * 本地加入、可靠保存与后端发送分属不同边界；此模块不调用网络写入，也不把 EOF 当成整源已封存。
  */
 import {dataArray,dataRecord} from '../canvas-core/data-containers.ts';
 import {createImportBatches} from './import-batches.ts';
@@ -31,7 +32,9 @@ export type LoadingImportAdmission={readonly version:1;readonly sourceToken:stri
 export type NativeImportSource = { readonly loadingAdmission?:LoadingImportAdmission; readonly kind: 'native-document' | 'native-json-array' | 'native-ndjson' | 'duplicate-ndjson' | 'duplicate-snapshot' | 'duplicate-plan'; readonly retirement?:FileRetirement;readonly previousFiles?:readonly PreviousImportFile[];readonly snapshotVersion?:2;readonly plan?:DuplicateCheckpoint; readonly copy?: {readonly sourceRevision:number; readonly roots:readonly Id[]}; readonly integrityVersion?:1|2;readonly readProof?:ImportReadProof;readonly integrityError?:string;readonly sha256?:string; readonly name?:string; readonly fileId: Id; readonly byteLength: number; readonly targetCanvasId: Id; readonly targetEntry?: {readonly id:Id;readonly incarnation:number} };
 /** 已加入新ID的生命周期绑定；canvas还绑定入口，防用户删除/恢复后被后续尾批误认。 */
 export type ImportBinding = {readonly kind:'element';readonly incarnation:number}|{readonly kind:'canvas';readonly entryElementId?:Id};
-/** 唯一持久任务记录；preparation是准备阶段游标，cursor/eof是解析进度，committed才是已加入前缀。 */
+/** 根状态中的唯一任务事实；可靠性仍取决于包含它的 Root 已 persist。
+ * preparation 是复制准备进度，cursor/eof 是解析进度，committedSourceKeys 是成功源项集合。
+ * 依赖调度可跳过尚未闭合的项，因此成功集合不必是文件顺序的连续前缀；pending 留待重读/协调。 */
 export type ImportJob = {
   readonly version: 1 | 2 | 3; readonly id: Id; readonly projectId: Id; readonly sourceFingerprint: string; readonly parserVersion: number;
   readonly source?: NativeImportSource;
@@ -42,14 +45,19 @@ export type ImportJob = {
   /** 稳定分配跨重开复用；pending可重读，committed不会因后续失败/取消被重新创建。 */
   readonly stableIds: Readonly<Record<string, Id>>; readonly pending: readonly ImportLocator[]; readonly committedSourceKeys: readonly string[]; readonly failures: readonly ImportFailure[]; readonly error?: string;
 };
-/** integrity-v2除零前缀取消外，缺完整SHA或有完整性错误都继续阻止发送；解析EOF不等于源已封存。 */
+/** integrity-v2 除无成功源项的取消任务外，缺完整 SHA 或有完整性错误都仍需封存。
+ * 这里只按记录字段判定，不验证 SHA/readProof、不调度验证任务；网络发送门禁由调用方采用此结论。 */
 export const importNeedsSeal=(job:ImportJob)=>job.source?.integrityVersion===2&&!(job.status==='cancelled'&&!job.committedSourceKeys.length)&&(!job.source.sha256||!!job.source.integrityError);
-/** 验证基本身份并创建v3 paused空任务；source旧调用缺省integrityVersion=1，不自动伪造摘要证明。 */
+/** 验证基本身份并创建v3 paused空任务；source旧调用缺省integrityVersion=1，不自动伪造摘要证明。
+ * source 经 JSON 往返捕获并冻结，但这里不做完整源/任务校验；接纳/恢复仍需 validateImportJob。
+ * 工厂不预留 ID、不读取文件，也不写根状态或磁盘。 */
 export function createImportJob(input: Pick<ImportJob, 'id' | 'projectId' | 'sourceFingerprint' | 'parserVersion' | 'source'>): ImportJob {
   if (![input.id,input.projectId,input.sourceFingerprint].every(value=>typeof value==='string'&&!!value) || !Number.isSafeInteger(input.parserVersion) || input.parserVersion<1) throw fault('invalid_import_job');
   return freeze({ id: input.id, projectId: input.projectId, sourceFingerprint: input.sourceFingerprint, parserVersion: input.parserVersion, ...(input.source?{source:{...clone(input.source),integrityVersion:input.source.integrityVersion??1}}:{}), version: 3, generation: 0, status: 'paused', cursor: 0, eof: false, bindings: {}, stableIds: {}, pending: [], committedSourceKeys: [], failures: [] });
 }
-/** 校验job及独立解释器、准备/加入状态、源证明、映射/绑定/pending/failure间的一致性。 */
+/** 校验job及独立解释器、准备/加入状态、源证明、映射/绑定/pending/failure间的一致性。
+ * 只检查记录内声明，不读取源文件/当前文档，不重算单元 digest 或校验绑定对象仍存活。
+ * 本函数不迁移/发布 job；旧版本合同允许部分字段缺省，不能仅凭校验通过就跳过端口及完整性门禁。 */
 export function validateImportJob(job: ImportJob): void {
   if(!job||typeof job!=='object'||!validJson(job)||!job.stableIds||typeof job.stableIds!=='object'||Array.isArray(job.stableIds)||![job.pending,job.committedSourceKeys,job.failures].every(Array.isArray)||job.error!==undefined&&typeof job.error!=='string')throw fault('invalid_import_job');
   if (job.version !== 1 && job.version !== 2 && job.version !== 3) throw fault('import_interpreter_unavailable');
@@ -90,6 +98,7 @@ export function validateImportJob(job: ImportJob): void {
     const ids=Object.fromEntries([...plan.elementIds.map(([id,mapped])=>[`element:${id}`,mapped]),...plan.canvasIds.map(([id,mapped])=>[`canvas:${id}`,mapped])]);
     if(job.parserVersion!==2||plan.projectId!==job.projectId||plan.sourceToken!==job.source.sha256||plan.phase!=='emit'||plan.emitted||plan.emittedEdges||!equal(ids,job.stableIds)||!equal(plan.roots.map(id=>ids[`element:${id}`]),job.source.copy!.roots)||job.cursor>plan.order.length+plan.edges.length)throw fault('invalid_copy_stream_checkpoint');
   }else if(job.source?.plan!==undefined)throw fault('invalid_copy_stream_checkpoint');
+  // bindings 的键是目标 ID，不是 source key；有 source 的已提交项还须能从 stableIds 找到对应绑定。
   for(const[id,binding]of Object.entries(job.bindings??{}))if(!id||!binding||!stableIdSet.has(id)||!['element','canvas'].includes(binding.kind)||binding.kind==='element'&&(!Number.isSafeInteger(binding.incarnation)||binding.incarnation<1)||binding.kind==='canvas'&&binding.entryElementId!==undefined&&typeof binding.entryElementId!=='string')throw fault('invalid_import_job');
   for(const key of job.committedSourceKeys){if(!key||keys.has(key))throw fault('invalid_import_job');keys.add(key);}
   if(job.source)for(const key of job.committedSourceKeys){const id=job.stableIds[key],binding=job.bindings?.[id];if(!Object.hasOwn(job.stableIds,key)||!binding||!key.startsWith(`${binding.kind}:`)||binding.kind==='canvas'&&(!binding.entryElementId||job.bindings?.[binding.entryElementId]?.kind!=='element'))throw fault('invalid_import_job');}
@@ -103,14 +112,18 @@ export function validateImportJob(job: ImportJob): void {
 const yieldTask=()=>new Promise<void>(resolve=>setTimeout(resolve,0));
 
 /** Seekable bounded NDJSON parser. Fingerprint must identify the host's immutable, durable byte source. */
-/** parser1按换行边界返回一条记录，最大记录与读取chunk分开约束，空白行skip但仍推进cursor。 */
+/** parser1按 LF/EOF 返回一条记录，cursor 为字节偏移；key 使用起始字节位置，空白行 skip 也推进游标。
+ * 捕获 Blob 与 max/chunk 标量，但 readBytes/调度配置仍从 options 读取，宿主须保持源与配置稳定。
+ * 不校验 cursor 是否真是行边界，不限制整个 Blob 总长，也不在这里证明 fingerprint 对应持久字节。 */
 export function createNdjsonImportSource(options:{bytes:Blob;fingerprint:string;readBytes?:ImportByteReader;maxRecordBytes?:number;chunkBytes?:number}&ImportScheduling):ImportSource {
   const max=options.maxRecordBytes??256*1024,chunk=options.chunkBytes??16*1024;
   if(!(options.bytes instanceof Blob)||!options.fingerprint||!Number.isSafeInteger(max)||max<1||!Number.isSafeInteger(chunk)||chunk<1||chunk>max)throw fault('invalid_import_source');
   const sourceBytes=options.bytes;
   let cache={offset:-1,bytes:new Uint8Array()};
   return Object.freeze({fingerprint:options.fingerprint,parserVersion:1,
-    /** 从已保存byte游标扫描到LF/EOF，超大行丢缓存但继续定位下一行；坏UTF8/JSON返回单项error。 */
+    /** 从游标扫描到 LF/EOF；单行上限不计 LF（CRLF 的 CR 仍计入），无最后换行的记录也接受。
+     * 超大行丢累积 parts 后继续扫描至下一边界，保留读块缓存；坏 UTF8/JSON 返回单项 error。
+     * readBytes/取消/调度失败会抛出，不伪装坏记录；同步解码/JSON.parse 只能在整行读取后执行。 */
     async read(cursor:number,signal:AbortSignal):Promise<ImportLine|null>{
       if(!Number.isSafeInteger(cursor)||cursor<0||cursor>sourceBytes.size)throw fault('invalid_import_cursor');
       if(signal.aborted)throw fault('import_aborted');if(cursor===sourceBytes.size)return null;
@@ -125,6 +138,7 @@ export function createNdjsonImportSource(options:{bytes:Blob;fingerprint:string;
         cursor=cache.offset+end+(newline<0?0:1);await budget.step(end-begin);
         if(newline>=0||cursor===sourceBytes.size)break;
       }
+      // 只有定位到完整行尾才形成可推进游标；一次 read 不直接修改 ImportJob。
       const base={cursor:start,nextCursor:cursor,key:`byte:${start}`};
       if(oversized)return{...base,error:'record_too_large'};
       const bytes=new Uint8Array(total);let offset=0;for(const part of parts){bytes.set(part,offset);offset+=part.length;}
@@ -157,7 +171,9 @@ export type ImportRunnerPorts={
 };
 
 /** Cooperative producer/consumer. Pending work stores seekable locators, not unbounded decoded payloads. */
-/** 创建单job执行器；先校验源解释器与完整性能力，duplicate-snapshot准备任务走另一专用路径。 */
+/** 创建单job执行器；先校验源解释器与完整性能力，duplicate-snapshot准备任务走另一专用路径。
+ * 构造只读初始事实，不自动 start。ports 的同步比较发布/原子提交/错误形状是宿主合同，runner 不实现数据库事务。
+ * 预算限制 pending 定位表、热解码表及一次提交，不保证源图、稳定映射、累计成功/失败记录的总内存恒定。 */
 export function createImportRunner(ports:ImportRunnerPorts){
   const initial=ports.getJob(),identity={id:initial.id,projectId:initial.projectId,sourceFingerprint:initial.sourceFingerprint,parserVersion:initial.parserVersion},budget=ports.frameBudgetMs??6,maxPending=ports.maxPending??4096,maxBytes=ports.maxPendingBytes??1024*1024,maxBatch=ports.maxBatch??32,now=ports.now??(()=>performance.now());
   validateImportJob(initial);
@@ -171,7 +187,8 @@ export function createImportRunner(ports:ImportRunnerPorts){
   let active:Promise<void>|undefined,controller:AbortController|undefined,closed=false,restart=false;const holds=new Set<symbol>();
   /** 错误上报异常隔离，不让日志失败改变已加入内容或已持久游标。 */
   const report=(error:unknown)=>{try{ports.onError(error);}catch{/* Reporting cannot change imported content. */}};
-  /** 每次读事实都检查job/project/fingerprint/parser身份，旧runner不能采纳新任务的同名状态。 */
+  /** 每次读事实检查固定的 job/project/fingerprint/parser 身份；generation 由各采纳点另行检查。
+   * 不深比较 source 的 fileId/目标/全部字段，也不重新完整验证 job；宿主须维持同身份记录的生命周期约束。 */
   function current(){const job=ports.getJob();if(job.id!==identity.id||job.projectId!==identity.projectId||job.sourceFingerprint!==identity.sourceFingerprint||job.parserVersion!==identity.parserVersion)throw fault('import_identity_changed');return job;}
   /** 只允许checkpointSource补readProof/SHA/integrityError；其它source身份和整个job主体都不可偷偷改变。 */
   function checkpointEvidence(job:ImportJob):ImportJob{
@@ -184,11 +201,14 @@ export function createImportRunner(ports:ImportRunnerPorts){
     else if(!equal(job.source,value.source))throw fault('invalid_import_checkpoint');
     return value;
   }
-  /** 合成下一代候选job并捕获源证明；不在这里写私有任务store。 */
+  /** 合成 generation+1 的 v3 候选并捕获源证明；error=undefined 时删键以保持 JSON 合同。
+   * 仅规划，不调用 publish/persist；校验钩子也须纯同步，字段比对不能回滚外部副作用。 */
   function next(job:ImportJob,patch:Partial<ImportJob>):ImportJob{const value={...job,...patch,version:3 as const,generation:job.generation+1};if(value.error===undefined)delete value.error;const checked=checkpointEvidence(value);return checked===value?dataRecord(freeze(value)):freeze(checked);}
   /** 以expectedGeneration compare-and-publish，再核对getJob确实返回该候选，防宿主半接受/丢字段。 */
   function publish(job:ImportJob,patch:Partial<ImportJob>){const value=next(job,patch);ports.publish(value,job.generation);if(!equal(current(),value))throw fault('invalid_import_publish');return value;}
-  /** 用stableIds解码单元，校验纯JSON/非空changes/依赖/成本，新创建ID必须来自reserve分配集合。 */
+  /** 用stableIds解码单元，校验纯JSON/非空changes/依赖/成本，新创建ID必须来自reserve分配集合。
+   * 成功后捕获整个 unit 和映射；这里不校验每条 Change 的领域语义/最终文档，guard 交给宿主提交准备。
+   * prepare 失败时不发布本次映射，但 createId 已发生的分配不会回退；端口不得在解码中产生外部业务效果。 */
   function prepare(line:ImportLine,job:ImportJob){
     const ids=identities(job.stableIds,allocateIdentity);
     const unit=ports.prepare(line,job,ids.reserve);
@@ -197,17 +217,21 @@ export function createImportRunner(ports:ImportRunnerPorts){
     if(new TextEncoder().encode(JSON.stringify(unit)).byteLength>maxBytes)throw fault('import_unit_capacity');
     return{unit:freeze(clone(unit)),ids:ids.finish()};
   }
-  /** optimisticLocal可按宿主背压延后磁盘，但网络仍须过durable门；默认每次直接等待persist。 */
+  /** optimisticLocal 且提供 awaitDurabilityBudget 时按宿主背压等待，否则直接 persist。
+   * 返回不一定代表刚才每个 Root 已落盘；网络仍须由宿主单独确保不可越过相同 Root 的 durable 屏障。 */
   const checkpoint=async(stage:'parsed'|'committed'='committed')=>{if(ports.optimisticLocal&&ports.awaitDurabilityBudget)await ports.awaitDurabilityBudget(stage);else await ports.persist();};
   /** 对含guard的完整ImportUnit取SHA，恢复重读时校验转换结果而不只比较源key。 */
   const digest=async(unit:ImportUnit)=>[...new Uint8Array(await crypto.subtle.digest('SHA-256',new TextEncoder().encode(JSON.stringify(unit))))].map(value=>value.toString(16).padStart(2,'0')).join('');
-  /** 为成功创建记录保存代次/入口绑定，并把source key追加committed，同时移除对应pending。 */
+  /** 规划成功后的 job：新建元素记 incarnation，新建 canvas 记入口，追加成功 source key 并采用过滤后 pending。
+   * 这里尚未执行提交；失败不应发布此候选。字段修改/删除不新建绑定，旧绑定留给宿主生命周期校验。 */
   function completed(job:ImportJob,units:readonly ImportUnit[],pending:readonly ImportLocator[]){
     const bindings:Record<Id,ImportBinding>=Object.assign(Object.create(null),job.bindings??{});
     for(const unit of units)for(const change of unit.changes)if(change.kind==='element'&&change.before===null&&change.after)bindings[change.id]={kind:'element',incarnation:change.after.incarnation};else if(change.kind==='canvas'&&change.before===null&&change.after)bindings[change.id]={kind:'canvas',...(change.after.parent?{entryElementId:change.after.parent.entryElementId}:{})};
     return next(job,{pending:dataArray(freeze(pending)),committedSourceKeys:dataArray(freeze([...job.committedSourceKeys,...units.map(unit=>unit.key)])),bindings:dataRecord(freeze({...bindings}))});
   }
-  /** 同步提交前再查generation，提交后核对job与Result一致；只有applied样本用于batch成本反馈。 */
+  /** 同步提交前再查 generation，提交后核对 applied 已发布候选、rejected 保持原 job。
+   * 只比 job，不在此审计全部文档变化；原子发布是 ports.commit 合同，后置核对失败不能自动回滚宿主副作用。
+   * 成本反馈只计同步 ports.commit 耗时，不含 beforeCommit、解析、SHA 或磁盘保存。 */
   function commit(units:readonly ImportUnit[],job:ImportJob,value:ImportJob){const base=current();if(base.generation!==job.generation)throw fault('stale_import_job');value=freeze(checkpointEvidence(value));const start=now(),result=ports.commit(units,value,job.generation),elapsed=Math.max(0,now()-start);if(!['applied','rejected'].includes(result?.status)||!equal(current(),result.status==='applied'?value:base))throw fault('invalid_import_commit');if(result.status==='applied')batches.record(units.length,elapsed);return result;}
   /** 合作式生产/消费循环：先消化闭合pending，再按有界slice解析新记录，EOF最后确认partial/completed。 */
   async function pump(signal:AbortSignal){
@@ -223,13 +247,16 @@ export function createImportRunner(ports:ImportRunnerPorts){
     /** 预读将异常转成结果以便接住迟到拒绝，不让并行准备出现未处理Promise。 */
     type ReadResult={kind:'line';line:ImportLine|null}|{kind:'error';error:unknown};
     let reading:{cursor:number;result:Promise<ReadResult>}|undefined;
-    // 仅内存有界热缓存：按maxBatch和maxBytes淘汰，pending持久状态始终是locators而非这些payload。
+    // 每次 pump 独立的热缓存按插入/替换顺序淘汰，读取命中不刷新顺序；不是另一份持久 job。
+    // maxBytes 计 unit 序列化成本，不等于 JS 堆占用，且不包括当前 units、源缓存和暂存解析切片。
     const decoded=new Map<string,{unit:ImportUnit;digest:string;bytes:number}>();let decodedBytes=0;
     /** 更新热单元/字节水位，超任一预算淘汰最旧项；淘汰后可按locator重读，不丢业务事实。 */
     function cache(key:string,value:{unit:ImportUnit;digest:string;bytes:number}){const previous=decoded.get(key);if(previous)decodedBytes-=previous.bytes;decoded.delete(key);decoded.set(key,value);decodedBytes+=value.bytes;while(decoded.size>maxBatch||decodedBytes>maxBytes){const[key,value]=decoded.entries().next().value!;decoded.delete(key);decodedBytes-=value.bytes;}}
     /** 提交/失败处理后及时丢热payload，避免已加入内容继续占runner缓存。 */
     function forget(key:string){const value=decoded.get(key);if(value){decodedBytes-=value.bytes;decoded.delete(key);}}
-    /** 同一游标共享一次预读；已有普通ready项时与0ms timer竞速，可先flush显示而不等慢尾部。 */
+    /** 同一游标共享一次预读；已有普通 ready 项时与0ms timer竞速，慢读取保留以便先 flush。
+     * flush 不取消该读取，下一轮仍复用同一 Promise；不同时对源发第二条 read。
+     * 这里只识别全部依赖已 committed 的单项，不替代后面的 SCC 闭合选择。 */
     async function read(cursor:number,flushReady:boolean):Promise<ReadResult|{kind:'flush'}>{
       if(reading&&reading.cursor!==cursor)throw fault('invalid_import_cursor');
       reading??={cursor,result:Promise.resolve().then(()=>ports.source.read(cursor,signal)).then(line=>({kind:'line' as const,line}),error=>({kind:'error' as const,error}))};
@@ -245,7 +272,8 @@ export function createImportRunner(ports:ImportRunnerPorts){
       didWork=true;
       const committed=new Set(job.committedSourceKeys);
       const batchLimit=batches.limit;
-      // 组选择把循环引用SCC视为不可拆单元；chosen源顺序与依赖可用性共同约束原子提交。
+      // 先消费已闭合 pending：SCC 将循环引用视为不可拆单元，单个闭合组可一起创建互相依赖的记录。
+      // 组选择受单位数/字节/变化数限制；没有可提交组才继续解析或检查 EOF/容量。
       const groups=selectImportGroups(job.pending,committed,{units:batchLimit,bytes:maxBytes,changes:10000}),chosen=groups.flat();
       if(chosen.length){
         const units:ImportUnit[]=[];
@@ -253,7 +281,7 @@ export function createImportRunner(ports:ImportRunnerPorts){
           const cached=decoded.get(locator.key);
           // 热缓存命中须与持久digest相同；否则seek重读并核对nextCursor/依赖/映射/成本及完整unit摘要。
           if(cached&&cached.digest===locator.digest){units.push(cached.unit);continue;}
-          // A source need not support concurrent reads. Finish any speculative read before seeking.
+          // 源不要求支持并发 read；先等旧预读结束再 seek，不丢 reading 句柄，返回顺序读取时仍可复用。
           if(reading)await reading.result;
           const line=await ports.source.read(locator.cursor,signal);
           if(closed||signal.aborted||current().generation!==job.generation)return;
@@ -289,11 +317,13 @@ export function createImportRunner(ports:ImportRunnerPorts){
         const unresolved=job.pending.filter(unit=>!job.failures.some(failure=>failure.key===unit.key&&failure.code==='unresolved_dependency')).map(unit=>({key:unit.key,cursor:unit.cursor,code:'unresolved_dependency',dependencies:unit.dependencies.filter(key=>!committed.has(key))}));
         publish(job,{status:job.failures.length||unresolved.length?'partial':'completed',failures:[...job.failures,...unresolved]});await ports.persist();return;
       }
-      // 等待依赖超容量是可恢复paused，不继续无限解析并在内存里堆积整个文件。
+      // 没有可提交组且 pending 达阈值就暂停；统计定位表的 JSON 成本，不把 unit 热缓存大小混用。
+      // 检查发生在加入下一项之前，单次追加可跨过阈值；它不是全任务严格字节硬上限。
       if(job.pending.length>=maxPending||new TextEncoder().encode(JSON.stringify(job.pending)).byteLength>=maxBytes){publish(job,{status:'paused',error:'dependency_capacity'});await ports.persist();return;}
       // Stage a bounded parser slice, then publish its cursor/IDs/locators once. This is
       // unpublished transaction preparation, never another durable task state store.
-      // staged是一次未发布的解析slice，不是第二份任务事实；最终cursor/ID/locator一起发布。
+      // staged 是基于 base.generation 的私有解析 slice，最终 cursor/稳定映射/locator/失败一次发布。
+      // 当前 doc 不随纯解析改变；真正可见内容仍由上面的 commit 发布，保存可按 optimistic 背压稍后跟进。
       const base=job;let staged=job,records=0;
       while(!staged.eof&&records<maxBatch&&staged.pending.length<maxPending&&new TextEncoder().encode(JSON.stringify(staged.pending)).byteLength<maxBytes){
         const ready=staged.pending.some(unit=>unit.dependencies.every(key=>committed.has(key)));
@@ -322,14 +352,17 @@ export function createImportRunner(ports:ImportRunnerPorts){
         }catch(error){patch={cursor:line.nextCursor,failures:[...staged.failures,{key:line.key,cursor:line.cursor,code:(error as {code?:string}).code??'import_decode_failed'}]};}
         if(closed||signal.aborted||current().generation!==base.generation)return;
         staged={...staged,...patch};records++;
-        // First ready record displays immediately; subsequent slices amortize publication.
+        // 首次观察到可提交项便尽快结束解析 slice，随后 commit 才能显示；不宣称此处已渲染或落盘。
+        // 之后依 batch 反馈和帧耗时摊销发布；单条 prepare/JSON 计算仍同步，SHA 则 await 其异步结果。
         if(!batches.observed&&staged.pending.some(unit=>unit.dependencies.every(key=>committed.has(key)))||now()-frame>=budget)break;
       }
       if(staged!==base){const{generation,...patch}=staged;publish(base,patch);const ready=staged.pending.some(unit=>unit.dependencies.every(key=>committed.has(key)));if(ports.awaitDurabilityBudget||!ports.optimisticLocal||!ready)await checkpoint(ready?'parsed':'committed');}
 
     }
   }
-  /** 单执行句柄：异常把仍属于自己的运行任务暂停并尽量保存；finally清索引并按restart条件继续。 */
+  /** active 共享同一 pump Promise；重复 launch 只记 restart，当前轮收尾后按状态决定是否再起一轮。
+   * 非取消异常尽量把同固定身份的 running/completed/partial 改 paused 并保存，已加入内容不回滚。
+   * 该异常兜底不另比原 generation；宿主仍须防同身份的非法替换。finally 清稳定 ID 临时索引及执行句柄。 */
   function launch(){
     if(closed||holds.size)return Promise.resolve();if(active){restart=true;return active;}
     restart=false;controller=new AbortController();
@@ -343,11 +376,14 @@ export function createImportRunner(ports:ImportRunnerPorts){
   return Object.freeze({
     /** paused可显式启动，completed/partial/cancelled不会自动续跑；新一轮清job.error但不清历史内容。 */
     start(){if(closed)throw fault('import_runner_closed');const job=current();if(['completed','partial','cancelled'].includes(job.status))return Promise.resolve();if(job.status!=='running')publish(job,{status:'running',error:undefined});return launch();},
-    /** 临时叠加冻结并abort旧pump，释放最后hold后仅在job仍running时续跑，不制造新的任务身份。 */
+    /** 临时叠加 hold 并 abort 当前 pump，释放最后 token 后仅 job 仍 running 才续跑；不改持久 status。
+     * 与 run tracker 的 hold 不同，这里请求中止在途源读取（实际响应由端口决定）；已提交内容不会回滚。 */
     hold(){const token=Symbol();holds.add(token);controller?.abort();return()=>{if(!holds.delete(token)||holds.size||closed)return;if(current().status==='running')void launch();};},
-    /** running→paused并持久化，保留cursor/映射/pending/已加入前缀；迟到结果由代次检查挡住。 */
+    /** 仅 running→paused 并 persist，保留 cursor/映射/pending/成功项；不等待 active 完全退出。
+     * publish 推进 generation，加上 abort 挡住迟到采纳；如需排空另外 await settle。 */
     async pause(){const job=current();if(job.status==='running'){controller?.abort();publish(job,{status:'paused'});await ports.persist();}},
-    /** running/paused→cancelled，保留成功前缀与失败报告，不执行默认整批回滚。 */
+    /** 仅 running/paused→cancelled 并 persist，保留成功内容与失败报告，不撤销已提交操作。
+     * 不负责取消 preparing 复制计划、删除源文件或退回后台请求；这些生命周期由 engine 协调。 */
     async cancel(){const job=current();if(['running','paused'].includes(job.status)){controller?.abort();publish(job,{status:'cancelled',error:undefined});await ports.persist();}},
     /** 等当前pump（及其已触发重启）收尾，不代表未来任务/网络同步都已完成。 */
     async settle(){while(active)await active;},

src/lib/canvas-runtime/journal-delta.ts

@@ -10,7 +10,9 @@ type Path = readonly (string | number)[];
 /** set 替换子树，splice 修改数组尾/区间；不提供任意执行代码或隐式创建路径。 */
 export type JournalPatch = {op:'set';path:Path;value:Json}|{op:'splice';path:Path;start:number;deleteCount:number;items:Json[]};
 /** Exact JSON property order is retained because recovery checksums cover serialized bytes. */
-/** 生成至多10000项差分；超限返回 null，让存储层选择完整图像，不返回被截断的补丁。 */
+/** 生成至多10000项差分；超限返回 null，让存储层选择完整图像，不返回被截断的补丁。
+ * 输入应是已捕获的 JSON 树：本函数不校验深度/循环、不 clone/freeze，set 与 splice.items 的子值可借用 after。
+ * 10000 限制补丁数而非遍历量/编码字节；共同前缀仍逐项检查，没有时间预算或异步让出。 */
 export function diffJournal(before:Json,after:Json):JournalPatch[]|null {
   const patches:JournalPatch[]=[];
   /** 相同身份立即跳过；数组递归共同前缀并 splice 长度差，对象仅同键同序时逐字段递归。 */
@@ -24,6 +26,7 @@ export function diffJournal(before:Json,after:Json):JournalPatch[]|null {
       }
       if(a.length!==b.length)patches.push({op:'splice',path,start:common,deleteCount:a.length-common,items:b.slice(common)});
     }else if(a&&b&&typeof a==='object'&&typeof b==='object'&&!Array.isArray(a)&&!Array.isArray(b)){
+      // 增删键或键序变化时替换整个对象，避免逐字段重建改变精确序列化顺序。
       const left=Object.keys(a),right=Object.keys(b);
       if(left.length===right.length&&left.every((key,i)=>key===right[i]))for(const key of right){
         const previous=a[key],next=b[key];if(previous!==next)visit(previous,next,[...path,key]);
@@ -34,15 +37,20 @@ export function diffJournal(before:Json,after:Json):JournalPatch[]|null {
   visit(before,after,[]);return patches.length>10000?null:patches;
 }
 /** Copy only changed ancestors; never mutate the preceding checkpoint or another patch's input. */
-/** 逐补丁重放到私有结果，每次仅复制受影响祖先；原 checkpoint 和其它已持有值不被改动。 */
+/** 逐补丁重放到私有结果，每次仅复制受影响祖先；原 checkpoint 和其它已持有值不被改动。
+ * 不检查 before 整树，不验证前像/摘要/业务身份；可信恢复链和最终 Root 校验由调用方完成。
+ * set 直接采用 patch.value，splice 只新建数组外壳，未改子树也共享；输出不自动冻结或深隔离。
+ * 后续补丁失败会抛错且不返回中间结果，但外来 getter 副作用不在此处回滚。 */
 export function applyJournal(before:Json,patches:readonly JournalPatch[]):Json {
   if(!Array.isArray(patches)||patches.length>10000)throw fault('corrupt_recovery_delta');
   let result=before;
   for(const patch of patches){
     if(!patch||!['set','splice'].includes(patch.op)||!Array.isArray(patch.path)||patch.path.length>64||patch.path.some((key:unknown)=>typeof key!=='string'&&(typeof key!=='number'||!Number.isSafeInteger(key)||key<0)))throw fault('corrupt_recovery_delta');
+    // validJson 限定值域；它不是稠密数组/描述符捕获器，恢复字节的 JSON.parse 边界仍很关键。
     if(patch.op==='set'?!validJson(patch.value):!Array.isArray(patch.items)||!validJson(patch.items))throw fault('corrupt_recovery_delta');
     /** 验证路径自有属性/数组下标后递归替换，set/splice 终点另外校验 JSON 与区间边界。 */
     function replace(value:Json,depth:number):Json {
+      // 空路径直接替换根或对根数组 splice；非空路径只允许已有自有属性，不隐式创建中间对象。
       if(depth===patch.path.length){
         if(patch.op==='set')return patch.value;
         if(!Array.isArray(value)||!Number.isSafeInteger(patch.start)||!Number.isSafeInteger(patch.deleteCount)||patch.start<0||patch.deleteCount<0||patch.start>value.length||patch.deleteCount>value.length-patch.start)throw fault('corrupt_recovery_delta');

src/lib/canvas-runtime/loader.ts

@@ -19,7 +19,8 @@ export type LoadChunk<T> = {
   readonly sequence: number; readonly coverage: readonly string[]; readonly complete: boolean;
   readonly byteLength: number; readonly value: T;
 };
-/** 加载状态及已收到块；initial-ready/partial 只说明有内容，ready Promise 要到 terminal+EOF 才完成。 */
+/** 加载状态及已收到块；initial-ready 表示收到首个合法块，可能只是空模型头，并不证明画面已有元素。
+ * partial 继续累积前缀；ready Promise 要等 terminal+EOF，失败前缀仍保留在 failed-with-partial 快照中。 */
 export type LoadSnapshot<T> = {
   readonly scope: LoadScope; readonly generation: number;
   readonly cacheStatus: 'bypassed' | 'miss' | 'invalid' | 'hit';
@@ -44,7 +45,10 @@ export function loadQueryKey(scope: LoadScope): string {
 /** Read copies only. This coordinator never publishes a document or a server ACK.
  * Adapters validate payloads and declare their measured byte cost before yielding.
  */
-/** 装配有界加载池；默认缓存年龄0不保留空闲结果，启用缓存也要求宿主 acceptCached 明确同意。 */
+/** 建立共享 query 调度器：inflight 去重、queue 按 generation FIFO、active 计真实未退出源，cache 按 Map LRU。
+ * 默认并发 4/等待 128、单响应声明 64MiB/4096 块；上限依赖 adapter 准确测量 byteLength，不测 T 或内存峰值。
+ * 默认缓存年龄 0 不插入终态缓存；启用后仍须订阅 allow-validated 且 acceptCached 同意，不把缓存当授权事实。
+ * 不重试、无读取超时，不深克隆/解释 T；current 应表达共享查询的授权生命周期，导航取消由各订阅管理。 */
 export function createScopedLoader<T>(options: {
   load: LoadPort<T>; current(scope: LoadScope): boolean; concurrency?: number; maxQueued?: number;
   maxResponseBytes?: number; maxChunks?: number; maxCacheEntries?: number; maxCacheBytes?: number;
@@ -54,7 +58,8 @@ export function createScopedLoader<T>(options: {
 }) {
   /** 订阅自己的 scope/取消/通知状态，不把旧导航的取消写成整个 job 失败。 */
   type Subscriber = { readonly scope: LoadScope; active: boolean; cancelled?: LoadSnapshot<T>; lastState?: LoadSnapshot<T>; snapshot?: LoadSnapshot<T>;resolve(value: LoadSnapshot<T>): void; reject(error: unknown): void; cleanup(): void; notify?(snapshot: LoadSnapshot<T>): void };
-  /** 共享 query 的执行句柄；generation 防重开混淆，controller 只在最后订阅释放时 abort。 */
+  /** 共享执行句柄，scope 来自首个订阅；view 会将导航信息换成各订阅自己的 scope。
+   * generation 区分重开，controller 在 retire（最后释放或 close）时 abort，不以订阅数为持久任务事实。 */
   type Job = { readonly key: string; readonly scope: LoadScope; readonly generation: number; readonly controller: AbortController; readonly subscribers: Set<Subscriber>; state: LoadSnapshot<T>; retired: boolean };
   const concurrency = options.concurrency ?? 4, maxQueued = options.maxQueued ?? 128, maxBytes = options.maxResponseBytes ?? 64 * 1024 * 1024, maxChunks = options.maxChunks ?? 4096;
   const maxCacheEntries = options.maxCacheEntries ?? 16, maxCacheBytes = options.maxCacheBytes ?? 16 * 1024 * 1024, cacheMaxAge = options.cacheMaxAgeMs ?? 0;
@@ -74,7 +79,8 @@ export function createScopedLoader<T>(options: {
   const notify = (job: Job) => { for (const subscriber of [...job.subscribers]) notifyOne(job, subscriber); };
   /** 淘汰同时扣除字节计数，避免缓存键删了但容量永远不归还。 */
   const removeCache = (key: string) => { const entry = cache.get(key); if (entry) { cacheBytes -= entry.state.byteLength; cache.delete(key); } };
-  /** 幂等废弃 job：abort/出等待队列，仅当 inflight 仍指向自己时删除，旧任务不能删新代次。 */
+  /** 幂等 retire：abort、移除排队/仍指向自己的 inflight，不删除缓存、不清前缀或提早扣 active。
+   * 成功/失败后仍保留的句柄可独立 release；本函数不把已兑现的 ready Promise 改成拒绝。 */
   function retire(job: Job) {
     if (job.retired) return; job.retired = true; job.controller.abort(); queue.delete(job.generation);
     if (inflight.get(job.key) === job) inflight.delete(job.key);
@@ -88,7 +94,9 @@ export function createScopedLoader<T>(options: {
       void (async () => {
         try {
           current(job.scope); let terminal = false, projectId: Id | undefined, token: string | undefined, versions: Readonly<Record<Id, number>> | undefined;
-          // 每块重新检查身份并核对连续序号、稳定 token/项目/版本向量、权限代次和声明预算。
+          // 端口可收到已取消信号（例如 loading 通知期间最后订阅释放）；它仍须在实际 I/O 前检查 signal。
+          // 每块重新检查身份，核对连续序号、稳定 token/项目/版本、权限代次和声明预算；coverage 只是合法字符串集合。
+          // complete/coverage 的领域含义、实际请求范围和 T 的 schema 由 adapter 负责，本层不从它们推断文档闭合。
           for await (const chunk of options.load(job.scope, job.controller.signal)) {
             if (job.retired) return; current(job.scope);
             if (!chunk || terminal || chunk.queryKey !== job.key || chunk.permissionEpoch !== job.scope.authEpoch || typeof chunk.projectId !== 'string' || !chunk.projectId
@@ -103,7 +111,8 @@ export function createScopedLoader<T>(options: {
             if (projectId !== undefined && (chunk.projectId !== projectId || chunk.snapshotToken !== token || !equal(orderedVersions, versions))) throw fault('load_snapshot_changed');
             if (job.state.chunks.length >= maxChunks || chunk.byteLength > maxBytes - job.state.byteLength) throw fault('load_response_budget');
             projectId = chunk.projectId; token = chunk.snapshotToken; versions = orderedVersions; terminal = chunk.complete;
-            // Own metadata; the adapter supplies an immutable/owned payload value.
+            // 捕获标准元数据表/coverage，value 与其它嵌套扩展字段仍沿用端口引用，不在此深冻结任意 T。
+            // adapter 应在 yield 前完成 payload 校验并交出不可变值；外层 Object.freeze 不证明内部所有权。
             const owned = Object.freeze({ ...chunk, serverVersions: freeze(orderedVersions), coverage: freeze([...chunk.coverage]) });
             // 只追加合法块并通知可显示前缀；即使当前块 complete=true，也要等源 EOF 才能成功 ready。
             job.state = Object.freeze({ ...job.state, status: job.state.chunks.length ? 'partial' : 'initial-ready', chunks: Object.freeze([...job.state.chunks, owned]),
@@ -116,6 +125,8 @@ export function createScopedLoader<T>(options: {
             removeCache(job.key); cache.set(job.key, { state: job.state, at: now() }); cacheBytes += job.state.byteLength;
             while (cache.size > maxCacheEntries || cacheBytes > maxCacheBytes) removeCache(cache.keys().next().value!);
           }
+          // 成功清理外部 abort 监听并兑现 ready，但不自动 release 句柄；后续 signal.abort 不再改变其快照。
+          // subscriber 仍持有共享状态，调用方应在不再使用时显式 release；已发出的快照继续描述原切点。
           notify(job); for (const subscriber of job.subscribers) if (subscriber.active) { subscriber.cleanup(); subscriber.resolve(view(job, subscriber)); }
         } catch (error) {
           if (job.retired) return;
@@ -132,7 +143,10 @@ export function createScopedLoader<T>(options: {
     }
   }
   return Object.freeze({
-    /** 捕获 scope→检查缓存→共享/新建 job→建立独立订阅；本调用不直接打开/关闭 ProjectEngine。 */
+    /** 捕获声明 scope 字段，校验身份/取消，再检查缓存并共享或新建 job；不打开 ProjectEngine。
+     * fresh 会淘汰该 key 的旧缓存，但仍共享已有 inflight，并不保证为每次调用发新请求。
+     * 缓存验证/时钟/容量等错误可同步抛出，成功才返回 ready/getSnapshot/release 句柄。
+     * cacheStatus 属于共享 job 建立时的读取事实，复用在途 job 不会按新订阅的缓存偏好重写它。 */
     acquire(scopeInput: LoadScope, settings: { signal?: AbortSignal; onUpdate?: (snapshot: LoadSnapshot<T>) => void; cache?: 'fresh' | 'allow-validated' } = {}): LoadHandle<T> {
       if(!scopeInput)throw fault('invalid_load_scope');
       const scope:LoadScope=Object.freeze({accountId:scopeInput.accountId,workspaceId:scopeInput.workspaceId,projectId:scopeInput.projectId,canvasId:scopeInput.canvasId,viewKey:scopeInput.viewKey,format:scopeInput.format,queryFingerprint:scopeInput.queryFingerprint,source:scopeInput.source,authEpoch:scopeInput.authEpoch,navigationGeneration:scopeInput.navigationGeneration});
@@ -158,13 +172,19 @@ export function createScopedLoader<T>(options: {
       }
       const shared = job; let subscriber: Subscriber;
       const ready = new Promise<LoadSnapshot<T>>((resolve, reject) => { subscriber = { scope, active: true, resolve, reject, notify: settings.onUpdate, cleanup: () => settings.signal?.removeEventListener('abort', release) }; });
-      /** 冻结本订阅 cancelled 视图、清监听并拒绝等待；只有最后借用者离开才 retire 共享源。 */
+      /** 为本订阅记录 cancelled 快照、移除监听/借用，尝试以 load_aborted 拒绝尚未兑现的 ready。
+       * ready 已成功/失败时 Promise 结果不变；getSnapshot 则改读此 cancelled 切点，保留已有 chunks。
+       * 最后借用者才 retire 共享源；取消一个订阅不会撤回其它订阅的前缀或删除成功缓存。 */
       const release = () => { if (!subscriber.active) return; subscriber.cancelled=Object.freeze({...view(shared,subscriber),status:'cancelled'});subscriber.active = false; subscriber.cleanup(); shared.subscribers.delete(subscriber); subscriber.reject(fault('load_aborted')); if (!shared.subscribers.size) retire(shared); };
       shared.subscribers.add(subscriber!); settings.signal?.addEventListener('abort', release, { once: true });
+      // 缓存命中的句柄不登记进 inflight，ready 立即兑现，外部 abort 监听仍保留到 release。
+      // 因此 close 负责清共享缓存，却不追溯取消这种已返回句柄；调用方仍拥有其只读快照。
       if (cached) { subscriber!.resolve(view(shared, subscriber!)); notifyOne(shared, subscriber!); } else { notifyOne(shared, subscriber!); pump(); }
       return Object.freeze({ ready, getSnapshot: () => subscriber.cancelled??view(shared,subscriber), release });
     },
-    /** 永久关闭并拒绝所有活订阅，清等待/缓存；底层迟到结果由 retired/current 围栏拒绝采纳。 */
+    /** 永久关闭：只对当前 inflight 的订阅记录 cancelled 并以 loader_closed 拒绝，随后清 queue/cache。
+     * 不追溯修改已从 inflight 退出的终态句柄或缓存命中句柄；其旧快照仍可读，显式 release 仍可调用。
+     * 不等待底层迭代器退出，active 在各 finally 才归还；无视 abort 的源仍可能占着资源，但迟到块不被采纳。 */
     close() {
       if (closed) return; closed = true;
       for (const job of [...inflight.values()]) { retire(job); for (const subscriber of job.subscribers) if (subscriber.active) { subscriber.cancelled=Object.freeze({...view(job,subscriber),status:'cancelled'});subscriber.active = false; subscriber.cleanup(); subscriber.reject(fault('loader_closed')); } job.subscribers.clear(); }

src/lib/canvas-runtime/loading-assets.ts

@@ -11,7 +11,10 @@ import {referencedResources,type LoadingAssetAdmission} from './resources.ts';
 /** Proven local upload identities; never infer authorization from an arbitrary URL. */
 // source身份+各proof身份一致时复用资源URL表；不因浏览器缓存有URL就授予准入。
 const namespaces=new WeakMap<object,{proofs:Map<Id,LoadingAssetAdmission>;urls:ReadonlyMap<Id,string>}>();
-/** 从已记录loadingAdmission派生resource→规范来源URL，只在v6和保留源存在时提供。 */
+/** v6 且 loadingRead 存在时提取 resource/binding 的 admission.sourceURL，不执行认证或完整 proof 校验。
+ * 以源对象与各 proof 引用身份缓存；依赖 runtime/proof 不可变合同，准入校验应由外围先完成。
+ * 返回实际可变 Map（类型只读），命中时沿用同一表，内部调用方不得修改；否则会污染后续复用。
+ * 同 ID 若两表均有 proof 后者覆盖，资源命名空间无冲突由其它运行时校验保证。 */
 export function loadingAssetURLs(runtime:RuntimeState):ReadonlyMap<Id,string>{
  const source=runtime.loadingRead;if(!source||runtime.loading?.version!==6)return new Map();
  const proofs=new Map<Id,LoadingAssetAdmission>();for(const resource of runtime.resources.values())if(resource.loadingAdmission)proofs.set(resource.id,resource.loadingAdmission);
@@ -19,10 +22,14 @@ export function loadingAssetURLs(runtime:RuntimeState):ReadonlyMap<Id,string>{
  const previous=namespaces.get(source);if(previous&&previous.proofs.size===proofs.size&&[...proofs].every(([id,proof])=>previous.proofs.get(id)===proof))return previous.urls;
  const urls=new Map([...proofs].map(([id,proof])=>[id,proof.sourceURL]));namespaces.set(source,{proofs,urls});return urls;
 }
-/** 联合验证上传/采纳与源范围、操作顺序、引用和stored证明；最后核对冻结上传协议字段。 */
+/** 仅 v6 校验全部本地 resource/binding 的准入：token/范围、逻辑因果与冻结上传 body 一致性。
+ * 要求外围已验证 loadingRead/ledger/资源结构；这里不下载字节、重算摘要、请求授权或核验真实服务回执。
+ * referencedResources 是声明字段的保守引用集（含变化前后），顺序检查不单独证明某条记录当前仍可显示。
+ * sourceURL 对 upload 只查非空/长度，对 adoption 要与 binding.asset.url 相等，规范来源由受信端口提供。 */
 export function validateLoadingAssetAdmissions(runtime:RuntimeState,registry:Registry):void{
  const loading=runtime.loading;if(loading?.version!==6)return;
- // upload先分配资源，后续document.change才能引用；早于/同于upload的引用不具备可靠身份因果。
+ // 每个 upload resource 都要有对应上传意图；stored 存在时 resolution 必须 applied。
+ // 至少有一个后续 document.change 引用且不允许早于/等于上传序号的引用；不按 ledger phase 过滤。
  for(const resource of runtime.resources.values()){
   const proof=resource.loadingAdmission,record=runtime.ledger.operations.get(resource.operationId);
   if(!proof||proof.version!==1||proof.sourceToken!==loading.sourceToken||typeof proof.sourceURL!=='string'||!proof.sourceURL||proof.sourceURL.length>8192||!Array.isArray(proof.canvasIds)||!proof.canvasIds.length||new Set(proof.canvasIds).size!==proof.canvasIds.length||proof.canvasIds.some(id=>typeof id!=='string'||!structuralRequestScope(runtime,runtime.loadingRead!,id))||record?.intent.operationType!=='asset.upload'||record.intent.resourceId!==resource.id||resource.stored&&record.resolution!=='applied')throw fault('invalid_loading_asset',[resource.id]);
@@ -35,7 +42,8 @@ export function validateLoadingAssetAdmissions(runtime:RuntimeState,registry:Reg
   if(!proof||proof.version!==1||proof.operationId!==binding.operationId||proof.sourceToken!==loading.sourceToken||proof.sourceURL!==binding.asset.url||!Array.isArray(proof.canvasIds)||!proof.canvasIds.length||new Set(proof.canvasIds).size!==proof.canvasIds.length||proof.canvasIds.some(owner=>!structuralRequestScope(runtime,runtime.loadingRead!,owner))||record?.intent.operationType!=='document.change'||!referencedResources(record.intent.changes,registry).has(id))throw fault('invalid_loading_asset',[id]);
   if([...runtime.ledger.operations.values()].some(candidate=>candidate.intent.operationType==='document.change'&&candidate.intent.sequence<record.intent.sequence&&referencedResources(candidate.intent.changes,registry).has(id)))throw fault('invalid_loading_asset',[id]);
  }
- // 冻结请求必须是原资源/operation/digest/长度/MIME，且不伪造canvas版本参与者。
+ // 每个 asset.upload 冻结请求必须只对应一个资源意图，协议 2 且 canvas/expectedVersions 为空。
+ // JSON body 与原 request/resource/operation/digest/长度/名称/MIME 精确匹配；不在此重新编译或修改冻结请求。
  for(const request of runtime.ledger.requests.values())if(request.kind==='asset.upload'){
   const intent=request.operationIds.length===1?runtime.ledger.operations.get(request.operationIds[0])?.intent:undefined,resource=intent?.operationType==='asset.upload'?runtime.resources.get(intent.resourceId):undefined;
   if(!resource?.digest||request.protocolVersion!==2||request.canvasIds.length||Object.keys(request.expectedVersions).length)throw fault('invalid_loading_request');
@@ -46,7 +54,10 @@ export function validateLoadingAssetAdmissions(runtime:RuntimeState,registry:Reg
 
 // 每registry+文档身份缓存资源的实际owner集合，完整比较首用范围时避免重复全表扫描。
 const ownership=new WeakMap<Registry,WeakMap<Document,Map<Id,readonly Id[]>>>();
-/** 资源首次出现在逻辑回放中时，实际owner集合须精确匹配准入范围；seen只在本次验证中去重。 */
+/** 外围应先将本 intent 应用到逻辑候选 document，再在首次遇有 admission 的资源时比较实际 owner 集合。
+ * registry+document 身份缓存全表资源→owner 索引，复用依赖不可变文档/定义；统计内容引用，不使用 DOM 可见性。
+ * 无 proof 或已 seen 的资源跳过，后续意图不重复做首次范围比较；一般资源合法性由其它门禁负责。
+ * seen 在比较前更新，失败后应丢弃本轮 Set，不能将失败结果当作已验证缓存继续使用。 */
 export function validateLoadingAssetUse(intent:OperationIntent,document:Document,runtime:RuntimeState,registry:Registry,seen:Set<Id>):void{
  if(runtime.loading?.version!==6)return;
  for(const id of referencedResources(intent.changes,registry)){

src/lib/canvas-runtime/loading-import.ts

@@ -16,7 +16,10 @@ const relations=new WeakMap<Document,{members:Map<Id,Id[]>;children:Map<Id,Id[]>
 /** 构造直接成员和entry→子canvas映射，供选区DFS扩张使用，不从节点可见性推断拥有范围。 */
 function index(document:Document){let value=relations.get(document);if(!value){const members=new Map<Id,Id[]>(),children=new Map<Id,Id[]>();for(const element of document.elements.values()){const ids=members.get(element.ownerCanvasId)??[];ids.push(element.id);members.set(element.ownerCanvasId,ids);}for(const canvas of document.canvases.values())if(canvas.parent){const ids=children.get(canvas.parent.entryElementId)??[];ids.push(canvas.id);children.set(canvas.parent.entryElementId,ids);}value={members,children};relations.set(document,value);}return value;}
 /** The caller captures this proof with the same document that becomes source bytes. */
-/** target先闭合；复制还要求全部选中后代/必要祖先/上级入边owner完整，然后冻结准入范围与sequence。 */
+/** 无 loading 返回 undefined；只有 v5/v6+loadingRead 能生成准入，target 必须 ownerReady。
+ * selection 存在时以数组栈+copied Set 深扩张，补入头部声明却未发布的 child，避免误将未读分区当叶子。
+ * captured 元素还检查必要祖先；上级入边的 owner 也纳入 required，最终冻结去重排序范围与账本最大 sequence。
+ * 只派生证据，不复制字节/分配 ID/验证 policy；没有 selection 表示普通目标导入，不检查复制子树。 */
 export function loadingImportAdmission(snapshot:EngineSnapshot,target:Id,selection?:readonly Target[]):LoadingImportAdmission|undefined {
  const state=snapshot.runtime.loading;if(!state)return;
  if((state.version!==5&&state.version!==6)||!snapshot.runtime.loadingRead)throw fault('model_loading');
@@ -42,7 +45,9 @@ export function loadingImportAdmission(snapshot:EngineSnapshot,target:Id,selecti
  let operationSequence=0;for(const record of snapshot.runtime.ledger.operations.values())operationSequence=Math.max(operationSequence,record.intent.sequence);
  return freeze({version:1 as const,sourceToken:state.sourceToken,operationSequence,requiredCanvasIds:[...required].sort()});
 }
-/** 恢复时job须同项目/同token，证明sequence不超账本，target与全部必要canvas仍是可证明范围。 */
+/** v5/v6 恢复/发布时逐个 validateImportJob，再核对项目、token、sequence 上界、target 包含与各范围准入。
+ * 只检查保存的 requiredCanvasIds，不在此重新展开 selection 或读取源字节；复制源重建由下一函数负责。
+ * 依赖外围已建立 loadingRead/账本身份，本函数不证明原 checkpoint 已落盘或获得当前服务器权限。 */
 export function validateLoadingImportAdmissions(runtime:EngineSnapshot['runtime']):void {
  const state=runtime.loading;if(!state||(state.version!==5&&state.version!==6))return;
  let maxSequence=0;for(const record of runtime.ledger.operations.values())maxSequence=Math.max(maxSequence,record.intent.sequence);
@@ -51,7 +56,10 @@ export function validateLoadingImportAdmissions(runtime:EngineSnapshot['runtime'
 
 /** Revalidate the frozen copy topology before planning or resuming its source.
  * Later source chunks may add unrelated owners, so compare only the closed cut. */
-/** 恢复规划前按准入sequence重建预期源，只比较原闭合cut的topology，不要求后到无关owner保持不增长。 */
+/** 从原捕获源重放 sequence≤准入时点的全部意图 changes（不按 phase 过滤，conditional=false）重建旧逻辑切点。
+ * 用 preparation/plan 中 selection 重算 required 范围并逐 owner 比较 canvas 与 copyTopology，忽略无关后到范围。
+ * copyTopology 保留身份/owner/端点/几何及表现尺度，省略正文等组件内容和边 path；这不是完整 payload 一致性证明。
+ * 不计算 SHA、不执行完整文档/权限校验，也不发布重建文档；源字节完整性由快照/导入证据链负责。 */
 export function validateLoadingCopySource(snapshot:EngineSnapshot,job:ImportJob,document:Document):void {
  const state=snapshot.runtime.loading,proof=job.source?.loadingAdmission;if(!state||(state.version!==5&&state.version!==6)||!proof)return;
  const source=snapshot.runtime.loadingRead!;let expected=source.document;

src/lib/canvas-runtime/loading-structure.ts

@@ -17,11 +17,16 @@ const counts=new WeakMap<Document,ReadonlyMap<Id,number>>();
 function membership(document:Document){let result=counts.get(document);if(!result){const next=new Map<Id,number>();for(const element of document.elements.values())next.set(element.ownerCanvasId,(next.get(element.ownerCanvasId)??0)+1);result=next;counts.set(document,result);}return result;}
 /** 全部声明元素/canvas 均到齐才算源闭合；这里只做数量闭合判断，领域合法性由其它校验共同保证。 */
 export function sourceClosed(state:LoadingState,source:Capture){return source.document.elements.size===state.totalElements&&source.document.canvases.size===state.declaredCanvasIds.length;}
-/** working中owner存在，且是明确新canvas或源成员数已达头部证明，才能作为闭合操作范围。 */
+/** working 中 canvas 必须存在；source.versions 不含它时按本地新 scope 处理，否则需 v2+ 直属源计数齐。
+ * 依赖 source/state 事先验证的完整声明，不以 working 乐观新增数补齐；也不单独证明全部后代/引用闭合。 */
 export function ownerReady(state:LoadingState,source:Capture,document:Document,id:Id){return document.canvases.has(id)&&(!source.versions.has(id)||state.version!==1&&(membership(source.document).get(id)??0)===state.canvasElementCounts[id]);}
-/** 只有v4+完整ID命名空间才能证明一个ID不属于原捕获；“当前还没看到”本身不够。 */
+/** 仅 v4/v5/v6 用完整 elementOwners 的缺席判定不属于捕获，不能只看当前 prefix 未出现。
+ * 这里不查元素是否真的新建、墓碑或 ID 冲突；born 是命名空间分类，具体创建条件在其它分支核对。 */
 function born(state:LoadingState,id:Id){return (state.version===4||state.version===5||state.version===6)&&!Object.hasOwn(state.elementOwners,id);}
-/** 禁止凭早期payload引入新任务状态或任意资源URL；新资源须有准入表，已有资源须能在已知数据证明。 */
+/** 数据门禁要求 copy 声明：ai/taskId/runId 的非空值只能与 prior 相等，允许清空而不允许改成新任务值。
+ * src/assetId/声明资源字段若非空，须命中受控 assets 表，或与 working/source 已知组件的同字段值一致。
+ * 这是可解释来源检查，不发授权请求、不验证 URL 协议，也不代替数据 schema/任务服务校验。
+ * 比对可扫描当前与源的元素表，不能把此函数当作常数成本字段检查。 */
 function safeData(data:ElementRecord['data'],registry:Registry,component:Id,document:Document,source?:Document,prior?:ElementRecord['data'],assets?:ReadonlyMap<Id,string>){
  const definition=registry.components.get(component);if(!definition?.copy)return false;
  for(const key of ['ai','taskId','runId'])if(data[key]!==undefined&&data[key]!==null&&!equal(data[key],prior?.[key]))return false;
@@ -38,7 +43,10 @@ function assetPatch(patch:ElementRecord['data'],registry:Registry,component:Id){
  const definition=registry.components.get(component),fields=['src','assetId',...(definition?.resourceFields??[])],keys=Object.keys(patch);
  return keys.some(key=>fields.includes(key))&&keys.every(key=>fields.includes(key)||!['presentation','ports','ai','taskId','runId'].includes(key)&&!definition?.copy?.references.some(ref=>ref.path[0]===key||ref.path[0]==='*'));
 }
-/** 返回结构命令的预检结果，undefined交普通字段门；准入仍需后续核心policy/schema与实际changes检查。 */
+/** v4+ 对结构/受控数据命令返回 enabled/deny；未处理命令或不满足专用数据入口时返回 undefined。
+ * undefined 留给普通字段门，不表示允许；enabled 也不证明目标代次、能力、handler 副作用与最终文档都合法。
+ * 原捕获对象的删除/重挂等要求源闭合，本地 born 对象可在 ready owner 操作；解散仍要求整个源到齐。
+ * 函数只预检，不锁范围、不生成 changes；调用方仍需核心 policy/schema 和 assertStructuralChanges。 */
 export function structuralCommand(command:Command,document:Document,registry:Registry,state:LoadingState,source:Capture,assets?:ReadonlyMap<Id,string>):Availability|undefined {
  if(state.version<4)return;
  const deny:Availability={enabled:false,code:'model_loading',targets:[]},yes:Availability={enabled:true};
@@ -52,7 +60,10 @@ export function structuralCommand(command:Command,document:Document,registry:Reg
  if(command.type==='element.data'&&(born(state,command.target.id)||sourceClosed(state,source)||state.version===6&&assetPatch(command.patch,registry,document.elements.get(command.target.id)?.componentId??'')&&ownerReady(state,source,document,document.elements.get(command.target.id)?.ownerCanvasId??''))){const element=document.elements.get(command.target.id);return element&&registry.resolve(element)==='known'&&safeData({...element.data,...command.patch},registry,element.componentId,document,source.document,element.data,assets)?yes:deny;}
 }
 /** Actual changes, not a command name, establish the mutation's required closure. */
-/** 逐条在私有cursor验证实际变化的必要闭合范围/数据，并检查最终声明引用，防handler副作用绕过。 */
+/** 将每条实际 change 按顺序作用到私有 cursor，逐项核对 owner/生命周期分类/数据门禁，最终检查声明引用。
+ * geometry 的局部门只要求已知 node，path/端点还要求 ready owner；owner 迁移则检查新旧两侧与 captured 分类。
+ * applyChanges 检查 before 条件，但这里不调用完整 validateDocument，也不执行 capability/policy/服务器授权校验。
+ * 返回是通过加载门禁的候选，非已发布 Root；任何抛错都不返回半份候选，原文档按不可变输入合同复用。 */
 export function assertStructuralChanges(changes:readonly Change[],document:Document,registry:Registry,state:LoadingState,source:Capture,assets?:ReadonlyMap<Id,string>):Document {
  if(state.version<4)throw fault('model_loading');
  // 按变化顺序推进，同批先创建owner/端点可满足后续依赖，但原源命名空间不会因此被改写。
@@ -84,10 +95,13 @@ export function assertStructuralChanges(changes:readonly Change[],document:Docum
  // 即使命令名字获准，最终仍不能产生悬空声明引用；整批失败不给调用方半份合法结果。
  references(cursor,registry);return cursor;
 }
-/** Protocol-2 receipts contain exactly these applied logical changes. */
+/** The caller's validated protocol-2 ledger supplies the applied logical effects. */
 // 缓存同一源上的已确认结构投影，只在applied意图前缀身份未变时从缓存后缀继续。
 const projectionCache=new WeakMap<Capture,{intents:readonly OperationIntent[];document:Document}>();
-/** 将resolved/applied意图按sequence叠到读取候选，并按精确协议2的参与者版本推进；不混入pending。 */
+/** 按 sequence 对 resolved+resolution=applied 意图叠原 changes，conditional=false，不加入 pending/elided 效果。
+ * 不按 operationType 额外过滤，也不再次核验协议/回执或调用 validateDocument；依赖外围已验证账本与精确协议 2 合同。
+ * 文档缓存仅在同 source 与 intent 引用前缀一致时续算；参与者版本另按每个 applied request 的 expected+1 取最大值。
+ * 返回新的投影 document/versions，不修改 runtime ACK；最终合法性由加载合并/验证入口继续检查。 */
 export function appliedSource(runtime:RuntimeState,source:Capture):Capture {
  let document=source.document;const versions=new Map(source.versions);
  const applied=[...runtime.ledger.operations.values()].filter(record=>record.phase==='resolved'&&record.resolution==='applied').sort((a,b)=>a.intent.sequence-b.intent.sequence);
@@ -98,9 +112,11 @@ export function appliedSource(runtime:RuntimeState,source:Capture):Capture {
  return{document,versions};
 }
 
-// source/registry/intent/before/assets全身份绑定校验缓存，不能把另一捕获或不同资源授权的结果拿来复用。
+// 缓存键为 source/registry/intent 引用，再比较 before/assets 引用；不按内容 hash 或 LoadingState 单独建键。
 const intentProofs=new WeakMap<Capture,WeakMap<Registry,WeakMap<OperationIntent,{before:Document;after:Document;assets?:ReadonlyMap<Id,string>}>>>();
-/** 对同一候选上下文复用已验证结构结果，否则重新assert全部实际changes；不是跳过当前源范围验证。 */
+/** 命中同一 source/registry/intent/before/assets 上下文时直接复用候选，否则重新检查 changes 并缓存。
+ * LoadingState 不在独立缓存键内，调用方须保证其与同源上下文一致，所有参与引用均按不可变合同使用。
+ * 缓存只证明这次加载结构门禁曾通过，不证明任意后来的 state/权限变化也可沿用结果。 */
 export function validateStructuralIntent(intent:OperationIntent,document:Document,registry:Registry,state:LoadingState,source:Capture,assets?:ReadonlyMap<Id,string>):Document {
  let registries=intentProofs.get(source);if(!registries){registries=new WeakMap();intentProofs.set(source,registries);}let intents=registries.get(registry);if(!intents){intents=new WeakMap();registries.set(registry,intents);}const previous=intents.get(intent);if(previous?.before===document&&previous.assets===assets)return previous.after;
  const after=assertStructuralChanges(intent.changes,document,registry,state,source,assets);intents.set(intent,{before:document,after,assets});return after;

src/lib/canvas-runtime/loading.ts

@@ -16,9 +16,13 @@ import type {CanonicalProposal,RuntimeState} from './contracts.ts';
  * version 3 admits certified scopes with a retained read baseline. No HTTP cursor. */
 /** 当前捕获的稳定 token、声明 canvas 范围及接收数量；不保存或伪造可续传 HTTP 字节游标。 */
 type LoadingBase={readonly sourceToken:string;readonly declaredCanvasIds:readonly Id[];readonly receivedElements:number;readonly totalElements:number};
-/** 版本化范围证据：counts/owners/sourceCanvases 能力逐级增加，缺字段不能当有证明。 */
+/** 版本化范围证据：v1 无计数，v2/3 加直属计数，v4 加全 ID→owner，v5/6 再加完整源树。
+ * 版本表示允许解释的协议能力，不表示收到全部 payload 或已可发送；loading 清除前项目仍标记未完整。 */
 export type LoadingState=LoadingBase&({readonly version:1;readonly canvasElementCounts?:never;readonly elementOwners?:never;readonly sourceCanvases?:never}|{readonly version:2|3;readonly canvasElementCounts:CanvasElementCounts;readonly elementOwners?:never;readonly sourceCanvases?:never}|{readonly version:4;readonly canvasElementCounts:CanvasElementCounts;readonly elementOwners:ElementOwners;readonly sourceCanvases?:never}|{readonly version:5|6;readonly canvasElementCounts:CanvasElementCounts;readonly elementOwners:ElementOwners;readonly sourceCanvases:readonly CanvasRecord[]});
-/** 验证前缀与捕获头一致：版本、树/ID命名空间、总数、直属计数和源版本向量；不是只比较已加载数量。 */
+/** 校验声明版本/token/范围/接收数及版本值，再按版本核对 counts、owners、源树和当前前缀成员。
+ * document.elements.size 可以少于 receivedElements，允许已收但因依赖尚未发布的记录；两者都不能超过总量。
+ * 不调用 validateDocument、不捕获/冻结输入或检验 HTTP 身份；外围须提供合法模型/源与不可变声明。
+ * 旧版本不允许偷带新证据字段，但不是通用严格 JSON DTO/所有扩展字段过滤器。 */
 export function validateLoadingState(value:LoadingState,document:Document,versions:ReadonlyMap<Id,number>):void{
  if(!value||![1,2,3,4,5,6].includes(value.version))throw fault('loading_interpreter_unavailable');
  for(const [id,version]of versions)if(!Number.isSafeInteger(version)||version<1)throw fault('invalid_canonical_version',[id]);
@@ -42,7 +46,9 @@ function pathAllowed(id:Id,document:Document,registry:Registry,loading?:LoadingS
  const element=document.elements.get(id);if((!loading||loading.version===1)||element?.structure!=='connection'||registry.resolve(element)!=='known')return false;
  return (directCounts(base).get(element.ownerCanvasId)??0)===loading.canvasElementCounts[element.ownerCanvasId];
 }
-/** partial 模式的命令预检；新结构证明可处理特定命令，否则仅已有节点几何/安全内容等受限编辑。 */
+/** 部分加载策略入口：v4+ 先问结构门，undefined 才落回已知 node 几何/安全普通内容/可证完整边路径。
+ * enabled 仅表示加载策略允许，核心目标代次、capability、业务 policy 和提交校验仍需执行。
+ * 本 helper 不是无 loading 时的通用命令放行器；调用方应只在 partial 模式将它作为额外约束。 */
 export function loadingCommand(command:Command,document:Document,registry:Registry,loading?:LoadingState,base=document,source?:CanonicalProposal,assets?:ReadonlyMap<Id,string>):Availability{
  if(loading&&(loading.version===4||loading.version===5||loading.version===6)&&source){const scoped=structuralCommand(command,document,registry,loading,source,assets);if(scoped)return scoped;}
  if(command.type==='connection.path')return pathAllowed(command.target.id,document,registry,loading,base)?{enabled:true}:denied;
@@ -53,7 +59,9 @@ export function loadingCommand(command:Command,document:Document,registry:Regist
 }
 /** Check actual changes too: a feature handler cannot evade command admission by
  * modifying a protected reference field as a side effect of an allowed edit. */
-/** 再核对 handler 实际输出，防止表面是编辑 title，却顺带修改受保护引用字段；v4+走结构闭合校验。 */
+/** 对 handler 实际 changes 再做加载策略检查；v4+ 以结构候选验证，返回结果在此不发布。
+ * 旧分支只允许字段类并逐项针对传入 document 检查，不按顺序执行 changes、不校验 before 或完整 schema。
+ * 因此通过不表示变更可直接采用，后续事务执行/文档校验仍负责条件与最终合法性。 */
 export function assertLoadingChanges(changes:readonly Change[],document:Document,registry:Registry,loading?:LoadingState,source?:CanonicalProposal,assets?:ReadonlyMap<Id,string>):void{
  if(loading&&(loading.version===4||loading.version===5||loading.version===6)&&source){assertStructuralChanges(changes,document,registry,loading,source,assets);return;}
  for(const change of changes){
@@ -62,7 +70,10 @@ export function assertLoadingChanges(changes:readonly Change[],document:Document
   if(!element||element.incarnation!==change.target.incarnation||registry.resolve(element)!=='known'||!(change.field==='path'&&pathAllowed(change.target.id,document,registry,loading)||change.field==='geometry'&&element.structure==='node'||change.field.startsWith('data.')&&dataKeyAllowed(element.componentId,change.field.slice(5),registry)))throw fault('model_loading',[change.target.id]);
  }
 }
-/** 恢复/发布时联合校验 loading/source/ACK/意图/资源/导入，不让单表合法但整体证据矛盾的 Root 通过。 */
+/** 校验部分加载 Root 的组合证据：原源/ACK 对应、各版本禁止的任务类别、资源/导入准入和逻辑回放。
+ * 无 loading 时只禁止孤立 loadingRead 即返回，并不在此验证所有普通运行时字段；通用校验由恢复/引擎负责。
+ * v4+ 按 sequence 回放所有文档意图而非只 pending，v6 允许合规 asset.upload 并在文档步骤后查首次资源范围。
+ * 本函数只验证/构造私有候选，不提交 Root、写存储或放行网络，不能替代持久/身份围栏。 */
 export function validateLoadingRuntime(runtime:RuntimeState,registry:Registry):void{
  if(!runtime.loading){if(runtime.loadingRead)throw fault('invalid_loading_state');return;}
  // v3+必须保留独立 loadingRead，旧版本不可偷带该字段；源校验不使用已经推进的 ACK 代替。
@@ -82,15 +93,19 @@ export function validateLoadingRuntime(runtime:RuntimeState,registry:Registry):v
   validateLoadingAssetUse(record.intent,logical,runtime,registry,assetUses);
  }
 }
-/** 同一读取的前缀扩展只能追加：token/版本/范围证据/墓碑固定，旧记录不得在后块被修改或移除。 */
+/** 验证 next 文档/声明后，与已验证 previous 比较：同项目/token/证据版本/头部/版本向量/墓碑不变。
+ * received 单调，旧 canvas/element 记录逐个保留且相等，允许新闭合记录追加；不是用较新 ACK 覆盖旧源来比较。
+ * 不发布/冻结 next，也不证明其传输来源；调用方完成捕获后再合并 ACK、重放 pending 并同 Root 采纳。 */
 export function validatePrefixExtension(previous:Document,previousVersions:ReadonlyMap<Id,number>,state:LoadingState,next:Document,versions:ReadonlyMap<Id,number>,nextState:LoadingState,registry:Registry):void{
  validateDocument(next,registry);validateLoadingState(nextState,next,versions);
  if(next.projectId!==previous.projectId||state.sourceToken!==nextState.sourceToken||state.version!==nextState.version||!equal(state.canvasElementCounts,nextState.canvasElementCounts)||!equal(state.elementOwners,nextState.elementOwners)||!equal(state.sourceCanvases,nextState.sourceCanvases)||state.totalElements!==nextState.totalElements||nextState.receivedElements<state.receivedElements||!equal(state.declaredCanvasIds,nextState.declaredCanvasIds)||!equal(Object.fromEntries(previousVersions),Object.fromEntries(versions))||!equal(Object.fromEntries(previous.tombstones),Object.fromEntries(next.tombstones))||[...previous.canvases].some(([id,record])=>!equal(record,next.canvases.get(id)))||[...previous.elements].some(([id,record])=>!equal(record,next.elements.get(id))))throw fault('loading_source_mismatch');
 }
 /** Full fresh reads may include new records in an unchanged-version scope. Known
  * records still cannot change without an owner version advancing. */
-/** 校验终结或 fresh read：已知版本不倒退，同版本已知记录不变，墓碑不倒退。
- * 原捕获补完要求相同 token/向量/总量；fresh read 可新增此前未收到项，v4+按新完整捕获协调。 */
+/** 校验完整 next：合法文档/活 canvas 版本、已知版本和墓碑不倒退，同 owner 版本的已知记录不得改变。
+ * fresh=false 还要求原 token/向量，按原声明总量/范围/直属计数补完；此处不会自动叠本地已确认编辑。
+ * fresh=true 可采用新的完整捕获，v4+ 即使版本向量相同也不强套旧总量/范围计数，但已知记录/生命周期约束仍在。
+ * 旧版本 fresh 在向量相同时仍受原总量/计数约束；是否移除 loading/合并 working 由引擎决定。 */
 export function validateLoadingCompletion(previous:Document,previousVersions:ReadonlyMap<Id,number>,state:LoadingState,next:Document,versions:ReadonlyMap<Id,number>,registry:Registry,fresh=false,sourceToken?:string):void{
  validateDocument(next,registry);if(previous.projectId!==next.projectId)throw fault('project_mismatch');
  for(const [id,version]of versions)if(!Number.isSafeInteger(version)||version<1)throw fault('invalid_canonical_version',[id]);
@@ -117,7 +132,10 @@ const namespaceSets=new WeakMap<ElementOwners,import('../canvas-core/types.ts').
 function namespace(owners:ElementOwners){let value=namespaceSets.get(owners);if(!value){value=readSet(Object.keys(owners));namespaceSets.set(owners,value);}return value;}
 /** 计算并缓存单文档 owner 的直属数量，节点/边都计入，不递归累计子树。 */
 function directCounts(document:Document):ReadonlyMap<Id,number>{let counts=membershipCounts.get(document);if(!counts){const next=new Map<Id,number>();for(const element of document.elements.values())next.set(element.ownerCanvasId,(next.get(element.ownerCanvasId)??0)+1);counts=next;membershipCounts.set(document,counts);}return counts;}
-/** 给 query 同次发布的完整性：整个项目未完仍可有已认证完整 owner；born canvas 另按结构证明处理。 */
+/** 派生查询覆盖状态：无 loading 时标全项目/拓扑完整，有 loading 时 projectComplete 固定 false。
+ * v4+ 同时给全源 elementIds 与合法源前缀 loadedElementIds，后者不是传输 received 数；born scope 依 ownerReady 判定。
+ * 拓扑完整只按合法前缀 canvas 与声明范围数量判断，成员完整另用源直属计数，不能相互替代。
+ * WeakMap 索引依赖 document/owners 不可变；这里不改变 document 或验证网络捕获身份。 */
 export function loadingQueryCoverage(snapshot:import('./contracts.ts').EngineSnapshot):import('../canvas-core/queries.ts').QueryCoverage {
  const loading=snapshot.runtime.loading,base=snapshot.runtime.loadingRead?.document??snapshot.runtime.acknowledged;
  if(!loading)return{projectComplete:true,topologyComplete:true,completeCanvasIds:[...snapshot.document.canvases.keys()]};
@@ -146,7 +164,9 @@ function validateLoadingRead(runtime:RuntimeState,registry:Registry):void {
  for(const request of runtime.ledger.requests.values())if(request.kind!==undefined&&request.kind!=='document.change'||!request.canvasIds.length||new Set(request.canvasIds).size!==request.canvasIds.length||Object.keys(request.expectedVersions).length!==request.canvasIds.length||request.canvasIds.some(id=>!ready.has(id)||!Number.isSafeInteger(request.expectedVersions[id])||request.expectedVersions[id]<(source.versions.get(id)??Infinity)||request.expectedVersions[id]>(runtime.versions.get(id)??-1)))throw fault('invalid_loading_request');
 }
 /** Overlay only scopes whose ACK version advanced since this immutable capture. */
-/** 在新源前缀上只叠已推进 ACK 的效果，不叠未确认 pending；pending 由后续条件重放重建。 */
+/** 无 v3+ 保留源时直接返回 read；v4+ 用 appliedSource 叠已确认逻辑效果并验文档。
+ * v3 只将版本已超过原捕获的 owner 成员整组换成 ACK，保留新 read 其它 owner、树与墓碑，再更新对应版本。
+ * 不叠 pending、不修改 runtime.loadingRead/ACK；引擎随后重放未决意图并发布同一 Root。 */
 export function mergeLoadingRead(runtime:RuntimeState,read:CanonicalProposal,registry:Registry):CanonicalProposal {
  const source=runtime.loadingRead;if((!runtime.loading||runtime.loading.version<3)||!source)return read;
  if(runtime.loading.version>=4){const projected=appliedSource(runtime,read);validateDocument(projected.document,registry);return projected;}
@@ -159,13 +179,17 @@ export function mergeLoadingRead(runtime:RuntimeState,read:CanonicalProposal,reg
 }
 /** 以指定元素列表重建源文档，保留同一项目/canvas/墓碑，创建标准只读表而非返回可变拼接对象。 */
 function importDocument(document:Document,elements:readonly import('../canvas-core/types.ts').ElementRecord[]):Document{return createDocument(document.projectId,[...document.canvases.values()],elements,document.tombstones);}
-/** 发送门：v1/v2不发，v3要求全部参与owner闭合，v4+要求每项符合结构范围；无loading正常放行。 */
+/** 加载范围发送门：无 loading 返回 true，v1/2 返回 false，v3+ 要求非空且全部参与范围有证明。
+ * 不检查实际 operation/请求 body、身份/政策、依赖、导入 seal 或磁盘水位；scheduler/engine 还须叠加那些门禁。
+ * v6 asset.upload 的空文档参与者由引擎专门准入，不因这里对空数组返回 false 就一概禁止资源上传。 */
 export function loadingCanSend(runtime:RuntimeState,canvasIds:readonly Id[],document=runtime.acknowledged):boolean {
  if(!runtime.loading)return true;if(runtime.loading.version<3)return false;if(runtime.loading.version>=4)return canvasIds.length>0&&canvasIds.every(id=>structuralRequestScope(runtime,runtime.loadingRead!,id));
  const ready=new Set(loadingQueryCoverage({runtime,document} as import('./contracts.ts').EngineSnapshot).completeCanvasIds);return canvasIds.length>0&&canvasIds.every(id=>ready.has(id));
 }
 
-/** source+已applied changes 必须精确等于 ACK 和版本向量，拒绝旧tail抹去确认后的创建/删除/重挂。 */
+/** 用原 source+applied 意图重建期望，逐表/版本与 ACK 比较，再 validateDocument(ACK)。
+ * 请求需符合协议 2/非空参与者/结构范围及版本区间；v6 上传请求例外留给资源专用校验。
+ * 原回执是否真实、ledger 内部状态是否合法仍由外围校验保证，此步骤不查询服务器或修复不一致。 */
 function validateStructuralRead(runtime:RuntimeState,registry:Registry){
  const source=runtime.loadingRead!,expected=appliedSource(runtime,source),ack=runtime.acknowledged;
  if(expected.document.projectId!==ack.projectId||!equal(Object.fromEntries(expected.document.canvases),Object.fromEntries(ack.canvases))||!equal(Object.fromEntries(expected.document.elements),Object.fromEntries(ack.elements))||!equal(Object.fromEntries(expected.document.tombstones),Object.fromEntries(ack.tombstones))||!equal(Object.fromEntries(expected.versions),Object.fromEntries(runtime.versions)))throw fault('invalid_loading_read');
@@ -173,7 +197,9 @@ function validateStructuralRead(runtime:RuntimeState,registry:Registry){
  for(const request of runtime.ledger.requests.values())if(!(runtime.loading?.version===6&&request.kind==='asset.upload')&&(request.protocolVersion!==2||!request.canvasIds.length||Object.keys(request.expectedVersions).length!==request.canvasIds.length||request.canvasIds.some(id=>!structuralRequestScope(runtime,source,id)||!Number.isSafeInteger(request.expectedVersions[id])||request.expectedVersions[id]<(source.versions.get(id)??0)||request.expectedVersions[id]>(runtime.versions.get(id)??0))))throw fault('invalid_loading_request');
 }
 
-/** 原源owner须完整；不在源版本表的新canvas须有明确创建意图，不能凭任意ID绕过范围门。 */
+/** 源版本表中的 owner 按原捕获成员数量判完整；不在源表的 ID 须在某条意图中明确创建过 canvas。
+ * 新 canvas 分支不按 ledger phase/resolution 过滤，也不单独检查它当前仍存在；实际 changes/请求验证还要继续。
+ * 这是范围来源判定，不是任意 canvas 的权限或完整生命周期证明。 */
 export function structuralRequestScope(runtime:RuntimeState,source:CanonicalProposal,id:Id):boolean {
  if(source.versions.has(id))return ownerReady(runtime.loading!,source,source.document,id);
  return [...runtime.ledger.operations.values()].some(record=>record.intent.changes.some(change=>change.kind==='canvas'&&change.id===id&&!change.before&&!!change.after));

src/lib/canvas-runtime/model-preview.ts

@@ -16,7 +16,10 @@ export type LiveModelPreview=ModelPreview&{readonly loading:import('./loading.ts
 export type ModelPreview = { readonly canvasElementCounts?:CanvasElementCounts;readonly elementOwners?:ElementOwners;readonly sourceCanvases?:readonly CanvasRecord[]; readonly document:Document;readonly receivedElements:number;readonly totalElements:number;readonly waitingElements:number;readonly complete:false };
 /** An ephemeral read projection. It owns neither a working document nor ACKs,
  * history, operations, file bytes or a durable recovery cut. */
-/** 建立单捕获投影器；一旦失败/终结就关闭，避免后续块继续污染合法旧预览。 */
+/** 一个流捕获的临时解释器：canvases 保存全源树，records 保存已收未发布元素，known 保存已发布命名空间键。
+ * published/snapshot 是最后合法前缀，received/ownerCounts 统计接收量，二者不等同可见/可编辑范围。
+ * 更新为同步建图/校验，无独立预算/取消或等待表容量上限；源规模与调用节奏由 loader/宿主约束。
+ * 任一更新失败后禁止继续，公开旧 snapshot 不变，但不保证所有内部计数/临时表事务回滚。 */
 export function createModelPreview(registry:Registry){
  let elementOwners:ElementOwners|undefined;let canvasElementCounts:CanvasElementCounts|undefined;const ownerCounts=new Map<Id,number>();
  let header=false,finished=false,projectId='',expected=0,received=0;
@@ -26,10 +29,14 @@ export function createModelPreview(registry:Registry){
  const key=(kind:'canvas'|'element',id:Id)=>JSON.stringify([kind,id]);
  // known 只存已经进入合法 published 前缀的键；records 暂存已收到但还未闭合的元素。
  const known=new Set<string>();
- /** 接收 header/增量/terminal；每批先校验所有记录，再计算新的最大闭合候选集合。 */
+ /** 接收单次 canonical update，先校验批，再按依赖排除求最大可发布候选并验证整份前缀。
+  * 不比较 sourceToken/serverVersions 或网络 scope；这些捕获身份由外层 LoadChunk/loader 管理。
+  * 只有 receiving 更新会生成 ModelPreview；终态仅封闭解释器并返回旧 snapshot，complete 仍为 false。 */
  function update(value:CanonicalReadUpdate):ModelPreview|undefined{
   if(finished)throw fault('model_preview_closed');
-  // terminal 必须含相同项目/树/墓碑和全部已收到记录，不能用另一份 fresh read 假装补完当前源。
+  // 已有 header 时，terminal 必须 ready 且项目/全树/墓碑/接收总数与所有已收记录精确相符。
+  // 这里不再次 validateDocument(terminal) 或要求 waiting=0；合法完整终态由 adapter/engine 另验。
+  // 无 header 就先遇非 receiving 时直接结束并返回 undefined，不据此生成一个完整预览。
   if(value.status!=='receiving'){
    if(header&&(value.status!=='ready'||value.document.projectId!==projectId||received!==expected||value.document.canvases.size!==canvases.size||[...canvases].some(([id,canvas])=>!equal(value.document.canvases.get(id),canvas))||!equal(Object.fromEntries(value.document.tombstones),Object.fromEntries(tombstones))||value.document.elements.size!==expected||[...(published?.elements??[]),...records].some(([id,record])=>!equal(value.document.elements.get(id),record))))throw fault('model_preview_changed');
    finished=true;return snapshot;
@@ -56,6 +63,7 @@ export function createModelPreview(registry:Registry){
   for(const record of value.elements){if(records.has(record.id)||known.has(key('element',record.id))||incoming.has(record.id)||!canvases.has(record.ownerCanvasId))throw fault('invalid_model_preview');validateElementRecord(record,registry,tombstones);if(elementOwners&&(!Object.hasOwn(elementOwners,record.id)||elementOwners[record.id]!==record.ownerCanvasId))throw fault('invalid_model_identity');incoming.add(record.id);}
   for(const record of value.elements){const count=(ownerCounts.get(record.ownerCanvasId)??0)+1;if(canvasElementCounts&&count>canvasElementCounts[record.ownerCanvasId])throw fault('invalid_model_coverage');ownerCounts.set(record.ownerCanvasId,count);}
   for(const record of value.elements)records.set(record.id,freeze(clone(record)));received=value.receivedElements;
+  // 已知组件只按 copy.references 加数据引用依赖，unknown 组件保持 opaque，不猜其私有 ID。
   // Greatest closed subset: removing an unavailable dependency also removes its
   // dependants. Fully received cycles survive and publish in one legal prefix.
   // 候选图包含尚未发布的 canvas/记录，依赖为父/入口/owner/端点及组件明确声明引用。
@@ -68,17 +76,20 @@ export function createModelPreview(registry:Registry){
    for(const ref of definition?.copy?.references??[])for(const id of copyReferenceIds(element.data,ref))deps.add(key(ref.target,id));
    candidates.set(key('element',element.id),{element,deps});
   }
-  // 从“缺少且未收到的依赖”向反向依赖传播排除；完全收到的环可保留并在同一合法前缀发布。
+  // dependants 是依赖键→使用者集合；queue 数组+游标作 FIFO，将缺失依赖的影响向引用者传播。
+  // 非拓扑逐项插入：完整收到的环不会因没有入度零节点被丢弃，仍需通过最终文档校验才可发布。
   const dependants=new Map<string,Set<string>>(),blocked=new Set<string>(),queue:string[]=[];
   for(const [id,item]of candidates)for(const dependency of item.deps){let users=dependants.get(dependency);if(!users){users=new Set();dependants.set(dependency,users);}users.add(id);if(!known.has(dependency)&&!candidates.has(dependency)&&!blocked.has(id)){blocked.add(id);queue.push(id);}}
   for(let index=0;index<queue.length;index++)for(const id of dependants.get(queue[index])??[])if(!blocked.has(id)){blocked.add(id);queue.push(id);}
-  // 在已发布前缀上加全部未阻塞候选，整份文档校验后才更新 published/known。
+  // 先在旧 published 上加全部未阻塞候选，create/validate 成功后才更新 published/known 并移除 records。
+  // 无新增候选时复用原 document，但接收计数仍能生成新 snapshot；等待中不意味着已丢弃该记录。
   const nextCanvases=[...(published?.canvases.values()??[])],nextElements=[...(published?.elements.values()??[])],accepted:string[]=[];
   for(const [id,item]of candidates)if(!blocked.has(id)){if(item.canvas)nextCanvases.push(item.canvas);if(item.element)nextElements.push(item.element);accepted.push(id);}
   if(!published||accepted.length){const next=createDocument(projectId,nextCanvases,nextElements,tombstones);validateDocument(next,registry);published=next;for(const id of accepted){known.add(id);const item=candidates.get(id);if(item?.element)records.delete(item.element.id);}}
   // 预览计数始终来自同捕获；v5/v6使用的 sourceCanvases 保留完整源拓扑，不由当前可见树猜。
   snapshot=Object.freeze({...(elementOwners?{elementOwners,sourceCanvases:freeze([...canvases.values()])}:{}),...(canvasElementCounts?{canvasElementCounts}:{}),document:published,receivedElements:received,totalElements:expected,waitingElements:received-published.elements.size,complete:false});return snapshot;
  }
- /** 对外 update 失败即封闭解释器；getSnapshot 只读旧合法前缀，close 清临时表而不删除业务文档。 */
+ /** update 失败即封闭且保留最后合法 snapshot 供诊断；getSnapshot 初始/显式 close 后为 undefined。
+  * close 清内部表和快照引用，不修改调用方已持有的不可变前缀，也不删除/撤销业务 engine 内容。 */
  return Object.freeze({update(value:CanonicalReadUpdate){try{return update(value);}catch(error){finished=true;throw error;}},getSnapshot:()=>snapshot,close(){finished=true;records.clear();canvases.clear();known.clear();published=undefined;snapshot=undefined;}});
 }

src/lib/canvas-runtime/network.ts

@@ -7,7 +7,9 @@ import { fault } from '../canvas-core/values.ts';
 import { createDeque } from './structures.ts';
 
 /** Shared bounded transport capacity for writes, uploads and run reads. */
-/** 建立正整数容量的 gate，beforeRun 在实际执行 callback 前检查宿主身份等条件。 */
+/** 建立正整数容量的 gate，beforeRun 在实际执行 callback 前同步检查宿主身份等条件。
+ * 每个实例独立计数，等待 FIFO 无长度上限；这里没有跨实例锁、重试或持久任务记录。
+ * beforeRun 是同步钩子；异步身份校验应由 callback 自己 await，不能依赖 void 钩子等待。 */
 export function createNetworkGate(limit = 2, beforeRun?:()=>void) {
   if(!Number.isSafeInteger(limit)||limit<1)throw fault('invalid_concurrency');
   let active = 0;
@@ -15,6 +17,7 @@ export function createNetworkGate(limit = 2, beforeRun?:()=>void) {
   /** 有空位直接占用，否则等待 grant；已取消的等待项标记保留，释放时惰性跳过。 */
   async function enter(signal: AbortSignal) {
     signal.throwIfAborted();
+    // enter 自己推进 active，或等 release 直接转交名额；等待者获准时不再重复 active++。
     if (active < limit) { active++; return; }
     await new Promise<void>((resolve,reject) => {
       // grant 解除 abort 监听再唤醒；被唤醒后 run 还会再次检查 signal，避免取消竞态执行请求。
@@ -29,7 +32,9 @@ export function createNetworkGate(limit = 2, beforeRun?:()=>void) {
     let item=waiting.pop();while(item?.cancelled)item=waiting.pop();
     if(item)item.grant();else active--;
   }
-  /** 统一入口：enter 后即使 signal/beforeRun/callback 抛错，finally 也会归还名额。 */
+  /** enter 成功后即使 signal/beforeRun/callback 抛错，finally 也会归还名额。
+   * 排队取消会拒绝 enter；执行中取消不自动结束 callback 或提早释放，仍等其 Promise 结束。
+   * 身份只在准入时检查一次；任务运行中的失效/响应采纳校验由 callback 和上层协调。 */
   return Object.freeze({ async run<T>(signal: AbortSignal, callback: () => Promise<T>): Promise<T> {
     await enter(signal);
     try { signal.throwIfAborted();beforeRun?.();return await callback(); } finally { release(); }

src/lib/canvas-runtime/orphan-files.ts

@@ -10,12 +10,15 @@ import {resourceRetentionPins} from './resource-retention.ts';
 
 /** 盘点确认的文件身份/摘要与退休状态，不是上传资源元数据，也不是 DOM 图片缓存。 */
 export type OrphanFile={readonly version:1;readonly id:Id;readonly byteLength:number;readonly mimeType:string;readonly digest:string;readonly retirement?:FileRetirement};
-/** 检查 ID、字节数、MIME、SHA256 和退休解释器；失败不默默忽略损坏文件记录。 */
+/** 检查记录版本、键与 ID 相同、安全字节数、MIME 字符串、64 位小写十六进制摘要和退休标记。
+ * 不读取 Blob 或重算 SHA；MIME 只要求字符串，不在此证明真实内容类型或元数据来自可信盘点。 */
 export function validateOrphanFile(value:unknown,id:Id):asserts value is OrphanFile {
  const file=value as OrphanFile;
  if(!file||file.version!==1||file.id!==id||!id||!Number.isSafeInteger(file.byteLength)||file.byteLength<0||typeof file.mimeType!=='string'||typeof file.digest!=='string'||!/^[a-f0-9]{64}$/.test(file.digest)||file.retirement!==undefined&&!validFileRetirement(file.retirement))throw fault('invalid_orphan_file');
 }
-/** 结合 pin 与所有未解释任务/审计证据给出回收阻碍；blockers 非空即 complete=false。 */
+/** 在 resourceRetentionPins 上叠加孤立文件专用阻碍，返回已知 pins 与 blockers。
+ * 任意 run/recovery、非终态导入、copy-admission 或未解决的其它动作都阻止孤儿回收。
+ * complete 只表示本函数列出的引用/生产者条件通过；不代表盘点到末页、文件散列完成或删除已持久化。 */
 export function orphanCoverage(snapshot:EngineSnapshot,registry:Registry,displays:ReadonlyMap<Id,number>,temporary:ReadonlyMap<Id,readonly Id[]>) {
  const pins=resourceRetentionPins(snapshot,registry,displays,temporary),blockers:string[]=[];
  if(!pins.complete)blockers.push('opaque_references');
@@ -27,7 +30,10 @@ export function orphanCoverage(snapshot:EngineSnapshot,registry:Registry,display
  return Object.freeze({...pins,complete:blockers.length===0,blockers:Object.freeze(blockers)});
 }
 /** Registered orphan identities survive repinning. Purged identities cannot be forgotten or reassigned. */
-/** 在发布前维护孤儿事实与回收 reservations：身份不得与资源/导入源冲突，已 purge 不得改写。 */
+/** 在发布前维护孤儿记录：禁止与资源/源文件重名，旧记录不得消失，已 purge 记录必须完整相等。
+ * 未 purge 记录允许盘点方更新摘要/长度等事实，本函数不读取字节来证明这种更新。
+ * referencesChanged 和 Map 引用用于快路判断；调用方须准确报告文档/历史/账本等引用变化。
+ * reservation 仅检查 next.orphanFiles 中对应 ID；跨文件类别的统一阻拦由外围发布钩子负责。 */
 export function prepareOrphanFiles(previous:RuntimeState,next:RuntimeState,coverage:()=>{complete:boolean;pins:ReadonlyMap<Id,unknown>},reserved:ReadonlySet<Id>,referencesChanged:boolean):RuntimeState {
  if(!previous.orphanFiles?.size&&!next.orphanFiles?.size)return next;
  const hasSoft=[...(next.orphanFiles?.values()??[])].some(file=>file.retirement&&file.retirement.purgedAt===undefined);
@@ -37,6 +43,7 @@ export function prepareOrphanFiles(previous:RuntimeState,next:RuntimeState,cover
  for(const [id,file]of next.orphanFiles??[]){validateOrphanFile(file,id);if(next.resources.has(id)||sources.has(id))throw fault('local_file_identity_conflict',[id]);}
  for(const [id,file]of previous.orphanFiles??[]){const after=next.orphanFiles?.get(id);if(!after||file.retirement?.purgedAt!==undefined&&!equal(file,after))throw fault('local_file_retired',[id]);}
  // 覆盖不足/重 pin 取消软退休；永久删除后重 pin 明确拒绝，不能让模型引用失去字节的 ID。
+ // 需要慢路才调用覆盖回调；即使引用覆盖未知，已 purge 项也仅在有明确 pin 时拒绝。
  const pins=coverage(),clear:Id[]=[];
  for(const [id,file]of next.orphanFiles??[]){
    if(reserved.has(id)&&(!pins.complete||pins.pins.has(id)))throw fault('resource_collection_in_progress',[id]);
@@ -48,7 +55,9 @@ export function prepareOrphanFiles(previous:RuntimeState,next:RuntimeState,cover
 }
 
 /** Read-only I/O may finish late; cancellation detaches its result without publishing it. */
-/** 取消只让调用者停止采纳读取结果，不保证底层只读 I/O 被终止；迟到成功/失败均已接住。 */
+/** 包装已启动的 Promise：取消以 file_inventory_aborted 拒绝，不沿用 signal.reason。
+ * 不终止底层只读 I/O；仍安装成功/失败处理器接住迟到结果，并在完成/取消时移除监听。
+ * 不持有 Root，也不校验结果是否过期；盘点调用方还需在 await 后核对当前快照身份。 */
 export function abortableFileRead<T>(task:Promise<T>,signal:AbortSignal):Promise<T>{
  return new Promise((resolve,reject)=>{const abort=()=>{signal.removeEventListener('abort',abort);reject(fault('file_inventory_aborted'));};signal.addEventListener('abort',abort,{once:true});if(signal.aborted)abort();task.then(value=>{signal.removeEventListener('abort',abort);if(!signal.aborted)resolve(value);},error=>{signal.removeEventListener('abort',abort);if(!signal.aborted)reject(error);});});
 }

src/lib/canvas-runtime/reconcile.ts

@@ -12,11 +12,13 @@ import type { LedgerSnapshot } from './ledger.ts';
 
 /** A complete read cannot rewind known scopes or change an unchanged-version canvas. */
 /** 校验完整 fresh read：同项目、合法文档、活 canvas 版本齐全、已知版本和墓碑均不可倒退。
- * 某 canvas 版本没变时，其记录/直属元素必须相同；全向量没变时墓碑集合也不能偷偷改变。 */
+ * 某 canvas 版本没变时，其记录/直属元素必须相同；全向量没变时墓碑集合也不能偷偷改变。
+ * 只校验模型一致性/单调性，不证明响应身份或读取来自何服务；传输认证与实际完整覆盖由端口保证。 */
 export function validateCanonicalRead(previous: Document, previousVersions: ReadonlyMap<Id,number>, next: Document, versions: ReadonlyMap<Id,number>, registry: Registry) {
   if(next.projectId!==previous.projectId)throw fault('project_mismatch');
   validateDocument(next,registry);
   for(const [id,version]of versions)if(!Number.isSafeInteger(version)||version<1)throw fault('invalid_canonical_version',[id]);
+  // 活 canvas 必须有版本，但不要求版本表只含活项；已移除 scope 的已知水位也可继续保留。
   for(const canvas of next.canvases.keys())if(!versions.has(canvas))throw fault('missing_server_version',[canvas]);
   // 记录服务声明“版本未变”的 owner，随后双向检查元素，既防遗漏删除也防夹带新增。
   const unchanged=new Set<Id>();
@@ -34,10 +36,12 @@ export function validateCanonicalRead(previous: Document, previousVersions: Read
 }
 
 /** The footprint follows ownership; geometry does not decide which canvas owns an object. */
-/** 计算跨 canvas 操作 footprint：有已冻结意图范围时沿用，否则收集新旧 owner/父级/端点归属。
- * 上传和 run.cancel 不占文档参与者；空间位置或画框相交不决定 owner。 */
+/** 计算跨 canvas footprint：声明了非空 intent.canvasIds 就直接沿用，不以是否已冻结为条件。
+ * 否则从变化收集新旧 owner/父级/端点归属；上传和 run.cancel 总是返回空文档参与者。
+ * 不根据画框相交或 run 的 boardId/action 自动猜参与者；ID 有效性与编译覆盖另由边界核对。 */
 export function operationCanvases(intent: OperationIntent, document: Document, after:Document=document): readonly Id[] {
   if(intent.operationType==='asset.upload'||intent.operationType==='run.cancel')return[];
+  // 已声明范围按原引用/顺序返回，不在此排序去重；仅下方推导路径用 Set 并排序。
   if (intent.canvasIds?.length) return intent.canvasIds;
   // 字段变化不能只查 after；重挂/改端点时旧 owner 也参与版本条件和占用。
   const ids = new Set<Id>();
@@ -64,18 +68,21 @@ export function operationCanvases(intent: OperationIntent, document: Document, a
 
 /** Replay once, by logical sequence. A receipt can already contain a desired field value. */
 /** 将本地生命周期水位叠到 ACK 副本，再按 sequence 回放 document.change/run.apply。
- * 只有已满足的 after 可安全跳过，条件冲突仍拒绝；不会自动改写原意图或冻结请求。 */
+ * 底层按同 incarnation/字段存在性判断已满足 after，并检查 field owner 范围；条件冲突仍拒绝。
+ * 不改写意图/冻结请求，不移动 history；historyEffect 只在此验证形状，不重新执行尺寸历史规划。 */
 export function replayPending(base: Document, ledger: LedgerSnapshot, registry: Registry): Document {
   /** 已 resolved 项不重放；未冻结、冻结或 blocked 的未解决文档意图仍按原事实参与重建。 */
   function* pending(){
     for(const record of [...ledger.operations.values()].sort((a,b)=>a.intent.sequence-b.intent.sequence)){
       if(record.phase==='resolved'||!['document.change','run.apply'].includes(record.intent.operationType))continue;
+      // 只筛 document.change/run.apply 的变化；上传、run.start/cancel 不因存在 changes 字段就在这里执行。
       if(record.intent.historyEffect)validateCreationSizeEffect(record.intent.historyEffect);
       yield {changes:record.intent.changes,canvasIds:record.intent.canvasIds};
     }
   }
   // 本地抵消可能从未进入服务器，水位只加到 working 候选，不能冒充服务器已确认墓碑。
   const document=replayChanges(withLocalLifecycles(base,ledger),pending());
+  // 全部回放成功后检查最终工作文档；任何异常让调用者丢弃这份候选，不在此处理冲突 UI 或覆盖 ACK。
   validateDocument(document,registry);
   return document;
 }

src/lib/canvas-runtime/recovery-encoding.ts

@@ -12,7 +12,8 @@ import type { RecoveryImage } from './storage-port.ts';
 
 /** 归一后的值、子树高度、可复用证明和精确 JSON UTF-8 字节数；undefined 表示 JSON 省略值。 */
 type Encoded = {value:Json|undefined;height:number;reusable:boolean;bytes:number};
-// WeakMap 仅按被证明安全的源身份缓存；sealed/imageSizes 是本 codec 的来源事实，外部 freeze 不能伪造。
+// immutable: 源对象→归一值/高度/字节；encodedSizes: 输出子树→字节；sealed/imageSizes: 本 codec 图像身份/总字节。
+// 都是进程内弱来源事实，不持久化、不检查权限/schema；JSON 克隆/重开对象不会继承 sealed 品牌。
 const immutable=new WeakMap<object,Encoded>(),sealed=new WeakSet<object>(),encodedSizes=new WeakMap<object,number>(),imageSizes=new WeakMap<object,number>();
 /** 计算 UTF-8 字节数（代理对计4字节）；调用时多为 JSON.stringify 后的已转义字符串。 */
 function utf8Length(text:string){let bytes=0;for(let i=0;i<text.length;i++){const c=text.charCodeAt(i);if(c<128)bytes++;else if(c<2048)bytes+=2;else if(c>=0xd800&&c<=0xdbff&&i+1<text.length&&text.charCodeAt(i+1)>=0xdc00&&text.charCodeAt(i+1)<=0xdfff){bytes+=4;i++;}else bytes+=3;}return bytes;}
@@ -20,7 +21,9 @@ function utf8Length(text:string){let bytes=0;for(let i=0;i<text.length;i++){cons
 const scalarBytes=(value:unknown)=>utf8Length(JSON.stringify(value));
 
 /** JSON value semantics, with reuse only for transitively frozen plain data properties. */
-/** 创建一次编码的递归访问器，visiting 检测当前路径循环；共享不可变节点可从全局弱缓存复用。 */
+/** 一次同步访问器拥有 visiting 路径 Set，共用模块 immutable 弱缓存；共享节点不等同循环，退出路径即移除。
+ * 普通数据逐属性捕获，toJSON/装箱/自定义原型退回原生 JSON 语义；此 codec 不是一般保身份深克隆工具。
+ * 会求值外部 getter/toJSON，也可能传播原生 JSON 异常；不修改业务 Root，但不能回滚用户回调副作用。 */
 function createEncoder() {
   const visiting=new Set<object>();
   /** 按原 JSON 语义捕获值并检查最大深度64，返回携带不可变性/大小证明的 Encoded。 */
@@ -28,7 +31,8 @@ function createEncoder() {
     if(value===null||typeof value==='string'||typeof value==='boolean'){if(depth>64)throw fault('invalid_recovery_payload');return{value,height:0,reusable:true,bytes:scalarBytes(value)};}
     if(typeof value==='number'){if(depth>64)throw fault('invalid_recovery_payload');const normalized=Number.isFinite(value)?(Object.is(value,-0)?0:value):null;return{value:normalized,height:0,reusable:true,bytes:scalarBytes(normalized)};}
     if(value===undefined||typeof value==='symbol')return{value:undefined,height:0,reusable:true,bytes:0};
-    /** 对 toJSON/装箱值/自定义原型使用原生 JSON 兼容路径，每次重新求值，不缓存隐藏可变行为。 */
+    /** 用 {[key]:value} 包裹保留原生 toJSON 的属性 key 上下文，stringify/parse 后再检查 JSON 深度并冻结结果。
+     * undefined 省略、BigInt/循环/用户回调错误保持该原生路径行为；返回 reusable=false，避免缓存隐藏可变状态。 */
     const fallback=()=>{
       // Preserve the previous JSON codec for toJSON, boxed values and custom prototypes.
       // These can depend on hidden mutable state and are deliberately never cached.
@@ -40,6 +44,7 @@ function createEncoder() {
     if(typeof value==='bigint'||typeof value==='function')return fallback();
     if(typeof value!=='object')throw fault('invalid_recovery_payload');
     const object=value as object,cached=immutable.get(object);
+    // 命中先前完整证明可跳过重读，但仍以当前位置+子树高度检查深度；它不是重新验证任意原型行为的入口。
     if(cached){if(depth+cached.height>64)throw fault('invalid_recovery_payload');return cached;}
     const prototype=Object.getPrototypeOf(object);
     // A callable toJSON getter must also be evaluated afresh on every encode.
@@ -59,7 +64,8 @@ function createEncoder() {
         }
         const encoded={value:Object.freeze(result) as unknown as Json,height,reusable,bytes};encodedSizes.set(result,bytes);if(reusable)immutable.set(object,encoded);return encoded;
       }
-      // 对象只遍历可枚举自有字符串键；defineProperty 安全写入特殊键，并保留原属性次序。
+      // 对象只遍历可枚举自有字符串键；省略值不计输出属性/高度，数组同类槽则归一成 null 并受深度上限约束。
+      // defineProperty 将 __proto__ 等保留为普通自有数据键，字节累计包含名字/冒号/逗号，不改变属性次序。
       const result:Record<string,Json>={};let properties=0;
       for(const name of Object.keys(object)){
         const descriptor=Object.getOwnPropertyDescriptor(object,name);if(!descriptor||!Object.hasOwn(descriptor,'value'))reusable=false;
@@ -82,7 +88,9 @@ type ImageVersion = RecoveryImage['formatVersion'];
 function validateHeader(formatVersion:ImageVersion,rootRevision:number,localRevision:number){
   if(![1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17].includes(formatVersion)||!Number.isSafeInteger(rootRevision)||rootRevision<0||!Number.isSafeInteger(localRevision)||localRevision<0||localRevision>rootRevision)throw fault('corrupt_recovery_image');
 }
-/** 组装本 codec 拥有的不可变信封，并登记精确字节成本；只登记真正由本模块构造的对象。 */
+/** 对已归一 payload 组装冻结图像并登记私有 sealed/大小；公开入口在此前验证 header。
+ * header 仅数字/ASCII 字段，以 payload:null 信封长度减 4 再加 payload UTF-8 成本；无子树事实时用原生计算。
+ * sealed 只表示 codec 捕获完成，不证明业务 schema、存储完成或服务端已确认。 */
 function finishImage(formatVersion:ImageVersion,rootRevision:number,localRevision:number,encoded:Json):RecoveryImage {
   const image=Object.freeze({formatVersion,rootRevision,localRevision,payload:encoded});sealed.add(image);imageSizes.set(image,JSON.stringify({...image,payload:null}).length-4+(encoded&&typeof encoded==='object'?encodedSizes.get(encoded)??scalarBytes(encoded):scalarBytes(encoded)));return image;
 }
@@ -100,11 +108,14 @@ type Prepared = Scalar | Encoded | {source:object;depth:number;children?:Prepare
 // Read unknown objects synchronously, before the first suspension. Shape-owned
 // containers can include external values; each such occurrence is captured now.
 // Detached JSON can also defer after checking its prototype environment.
-/** 在第一次让出前固定不安全输入；shape-owned 外壳仍逐个捕获外部子值，不能只信 Object.freeze。 */
+/** 同步准备 Prepared 树：原子值可延后，已证明 Encoded 可复用，陌生子树按出现次数立即规范化。
+ * shape-owned 容器只证明外壳，仍逐个捕获外部子值；detached JSON 在原型环境允许时可整棵延后。
+ * 此准备阶段本身可遍历大量结构/运行回调，未必常数时间；不是 async 后才首次读取所有输入。 */
 function prepareEncoding(input:unknown) {
   const normalize=createEncoder(),visiting=new Set<object>();
   let plainEnvironment:boolean|undefined;
-  /** 同步规范化陌生对象；任何用户行为可能改原型环境，结束即使失败也使环境缓存失效。 */
+  /** 同步规范化陌生值；回调可能改全局原型，finally 只清 plainEnvironment 检查缓存，失败也清。
+   * 不清模块已有 immutable 编码事实，也不撤销用户环境修改；后续 detached 准入需重新读描述符。 */
   const capture=(value:unknown,depth:number,key:string)=>{
     try{return normalize(value,depth,key);}finally{plainEnvironment=undefined;}
   };
@@ -151,15 +162,20 @@ function prepareEncoding(input:unknown) {
 /** Capture external data immediately; cooperatively encode stable owned tables.
  * Time slicing is soft: synchronous capture of an unknown subtree remains indivisible.
  * The returned image has exactly the synchronous codec's wire representation. */
-/** 异步入口：先同步固定输入，再按预算遍历安全部分；结果表示与同步 codec 相同。
- * 同步 capture、单个原生操作仍不可抢占，不能由 async 名称推导整个编码无长任务。 */
+/** 验 header 并同步 prepare 后，驱动编码生成器按 ImportBudget 合作让出，最终才 finishImage。
+ * 默认优先 scheduler.yield，否则 timer；无 signal/check 参数，宿主需通过 yieldTask 或外层采纳围栏处理生命周期。
+ * 逐子项计工作，原子归一化/字符串转义/UTF-8 计量及未知子树捕获仍为同步步骤，不保证每项都不超时间片。
+ * 失败不返回部分图像/授予可用 sealed 结果，但已建的不可变子树缓存与回调副作用不会整体回滚。
+ * 结果沿用同步 codec 的规范 JSON 表示，不包含文件 Blob 或恢复业务状态的执行动作。 */
 export async function sealRecoveryImageAsync(formatVersion:ImageVersion,rootRevision:number,localRevision:number,payload:unknown,options:ImportScheduling={}):Promise<RecoveryImage> {
   validateHeader(formatVersion,rootRevision,localRevision);
   const {plan,normalize}=prepareEncoding(payload);
   const scheduler=(globalThis as typeof globalThis & {scheduler?:{yield?:()=>Promise<void>}}).scheduler;
   // 默认使用可用 scheduler.yield；没有时由预算适配器回退，所有语义仍由同一个 normalize 决定。
   const budget=createImportBudget(new AbortController().signal,{...options,yieldTask:options.yieldTask??(typeof scheduler?.yield==='function'?()=>scheduler.yield!():undefined)});
-  /** 生成器只在预算要求时 yield Promise；逐项累加深度/字节并冻结结果，尚未完成的图像不外发。 */
+  /** Prepared 的判别：原子值走 normalize，带 height 是已捕获 Encoded，其余为结构计划。
+   * 有 children 就用准备阶段捕获值；无 children 只允许已准入 detached 源的不可变数据属性延后读取。
+   * 每个输出子项完成后才 budget.step/yield；组装容器时累计高度/精确字节并登记弱缓存，不外发半成品。 */
   function* encode(plan:Prepared,depth=0,key=''):Generator<Promise<void>,Encoded,void>{
     if(plan===null||typeof plan!=='object')return normalize(plan,depth,key);
     if('height' in plan)return plan;
@@ -198,7 +214,7 @@ export async function sealRecoveryImageAsync(formatVersion:ImageVersion,rootRevi
   if(step.value.value===undefined)throw fault('invalid_recovery_payload');
   return finishImage(formatVersion,rootRevision,localRevision,step.value.value);
 }
-/** 查询私有 sealed 来源，供存储跳过重复防御复制；不接受外部伪造品牌字段。 */
+/** 仅查询本进程私有 WeakSet 身份，不重新验 header/payload/持久性；外部同形对象或反序列化副本不命中。 */
 export function isSealedRecoveryImage(image:RecoveryImage):boolean{return sealed.has(image);}
 
 /** Exact UTF-8 JSON size, available only for codec-owned immutable images. */
@@ -206,5 +222,6 @@ export function isSealedRecoveryImage(image:RecoveryImage):boolean{return sealed
 export function sealedRecoveryByteLength(image:RecoveryImage){return imageSizes.get(image);}
 
 /** Internal codec ownership/size fact, never inferred from external Object.freeze. */
-/** 已编码 JSON 子树的精确大小事实，供 serializer 选择小子树原生 stringify 快路径。 */
+/** 查询本 codec 输出子树的大小事实，未知身份返回 undefined，不能用外部 freeze/自报长度冒充。
+ * 只提供 serializer 的成本依据，不证明任何加载/上传任务已完成。 */
 export function encodedRecoveryByteLength(value:object){return encodedSizes.get(value);}

src/lib/canvas-runtime/recovery-json.ts

@@ -8,7 +8,9 @@ import {isSealedRecoveryImage,sealedRecoveryByteLength,encodedRecoveryByteLength
 import {createImportBudget,type ImportScheduling} from './import-budget.ts';
 import {fault} from '../canvas-core/values.ts';
 
-/** 长字符串每段至多4096 UTF-16单元；避免截断代理对，再分别转义并拼接为一个合法 JSON 字符串。 */
+/** 按最多 4096 UTF-16 单元切原字符串，跨边界代理对一起留到下段；孤立代理由原生 JSON 转义。
+ * 长串只输出一对外层引号，各段去掉 stringify 引号后拼接，保持完整字符串的转义/字节语义。
+ * 段上限不是转义后字符/UTF-8 字节上限，单段 stringify 仍是同步工作。 */
 function* stringTokens(value:string):Generator<string>{
  if(value.length<=4096){yield JSON.stringify(value);return;}
  yield '"';
@@ -16,7 +18,9 @@ function* stringTokens(value:string):Generator<string>{
  yield '"';
 }
 /** Only traverse codec-owned normalized JSON. Small owned subtrees use native stringify. */
-/** 保留数组/对象原顺序，显式输出分隔符；≤16KiB 已知子树直接 stringify，降低 token 分配开销。 */
+/** 只遍历已封存的规范 JSON：数组按索引、对象按 Object.keys 顺序输出，显式生成分隔符。
+ * codec 有精确 UTF-8 大小事实且 ≤16KiB 的对象/数组直接原生 stringify；没有大小事实不猜其成本。
+ * 不自行解释 toJSON/getter、稀疏/undefined 或执行深度校验；这些应在封存捕获阶段已规范化/约束。 */
 function* tokens(value:unknown):Generator<string>{
  if(value&&typeof value==='object'){
   const size=encodedRecoveryByteLength(value);if(size!==undefined&&size<=16384){yield JSON.stringify(value);return;}
@@ -26,12 +30,17 @@ function* tokens(value:unknown):Generator<string>{
  if(typeof value==='string')yield* stringTokens(value);else yield JSON.stringify(value);
 }
 /** Preserve exact JSON.stringify bytes; scheduling never exposes a partial recovery image. */
-/** 输出完成的 Blob；check 在工作/await 边界复查 leader/生命周期，失败不返回半成品。 */
+/** 返回完整 application/json Blob，不发布 Root、不写存储或持续产出可消费的字节流。
+ * 私有 sealed 品牌才走 token 分片并核对精确字节；外部 image 同步原生 stringify，不因 Object.freeze 获得快速路径。
+ * check 由宿主实现 leader/身份围栏，在入口、聚合片段及 await 前后/末尾调用；内部 signal 从不主动 abort。
+ * 所有 BlobPart 累积到结束，合作调度只限制部分同步工作，不是全文件零缓冲或整体内存硬预算。
+ * 任一错误不返回部分 Blob；此处不再 validate RecoveryImage/schema，输入有效性由 codec/存储边界保证。 */
 export async function serializeRecoveryImage(image:RecoveryImage,options:ImportScheduling&{check?:()=>void}={}):Promise<Blob>{
  options.check?.();
  // 外部输入不信任所有权/尺寸缓存，继续走原生同步 stringify，不能冒称这一路也全部可分片。
  if(!isSealedRecoveryImage(image)){const bytes=new Blob([JSON.stringify(image)],{type:'application/json'});options.check?.();return bytes;}
- // 小 token 先聚合成约8K字符的片段，控制 BlobPart 数量；不是每个标点都创建独立 Blob。
+ // token 先聚合到至少 8192 个输出字符串 UTF-16 单元再 flush，单 token 可使片段超过目标；不是 8KiB 字节上限。
+ // 每次 flush 给预算记 128 单位，粗时钟也能按累积工作让出；不对每个标点单独创建 BlobPart/读取时钟。
  const budget=createImportBudget(new AbortController().signal,options),parts:BlobPart[]=[];let pending:string[]=[],length=0;
  for(const token of tokens(image)){
   pending.push(token);length+=token.length;

src/lib/canvas-runtime/recovery.ts

@@ -3,6 +3,7 @@
  * 不把它们分别恢复成可互相漂移的 store；Blob 字节走 DurableBatch.files，不放进 JSON payload。
  * 编码按所需特性选择格式，解码校验表/跨表身份、依赖、请求、历史、资源与任务证据后才返回候选 Root。
  * 解码不发 HTTP、不重启外部副作用，最终恢复准入和可靠存储仍由 engine/adapter 负责。
+ * 领域解码同步执行；存储字节/校验摘要、当前账号权限、外部文件可读性均不在本模块证明范围内。
  */
 import {referencedResources} from './resources.ts';
 import {validateSharedAsset,type SharedAssetBinding} from './asset-depot.ts';
@@ -35,7 +36,8 @@ import type { RecoveryImage } from './storage-port.ts';
 const entryViews=new WeakMap<object,readonly (readonly [unknown,unknown])[]>();
 /** 可选表缺省的共享空数组，只表示没有表成员，不表示其数据已完成业务校验。 */
 const noEntries=dataArray([]);
-/** 把 Map 编成有序元组数组；自有读视图可复用外壳，其 value 是否可复用由 codec 另查。 */
+/** 把 Map 编成按迭代顺序排列的元组数组；自有 readMap 视图可缓存成员外壳，WeakMap 不额外保活源视图。
+ * 未知来源表每次重新枚举，value 仍借用原引用；codec 后续捕获值，不以稳定成员表推断值已不可变。 */
 function mapValue<K,V>(map?:ReadonlyMap<K,V>):readonly (readonly [K,V])[]{
   if(!map)return noEntries;
   if(!isOwnedMapView(map))return [...map];
@@ -52,7 +54,8 @@ function encodeDocumentValue(document:Document){
 }
 // 缓存工厂信封的序列化外壳，不缓存/跳过组件数据校验，也不将该外壳视为发布文档。
 const documentViews=new WeakMap<Document,ReturnType<typeof encodeDocumentValue>>();
-/** 工厂文档可复用成员外壳；未知来源文档重新枚举，防止冻结外壳掩盖可变 Map 成员。 */
+/** 工厂文档可复用成员外壳；未知来源文档重新枚举，防止冻结外壳掩盖可变 Map 成员。
+ * documentViews 只缓存 documentValue 的表示，不缓存“该文档已经通过完整 schema/图校验”的结论。 */
 function documentValue(document:Document){
   if(!isFactoryDocument(document))return encodeDocumentValue(document);
   let value=documentViews.get(document);if(!value){value=encodeDocumentValue(document);documentViews.set(document,value);}return value;
@@ -61,7 +64,10 @@ function documentValue(document:Document){
  * stored asset URL 和 sourceURL 属于已选协议数据，会按原值保存；不应把本函数当成任意数据的脱敏器。 */
 /** 从同一 snapshot 选择文档/双栈/意图及所有运行事实，按当前特性选择兼容 envelope 格式。
  * 格式优先级覆盖读完整性、原生文档、数组、共享binding、partial loading、尺寸/文件退休等；
- * 与 parserVersion、component dataVersion、IDB/journalVersion 无关，不能互相代替。 */
+ * 与 parserVersion、component dataVersion、IDB/journalVersion 无关，不能互相代替。
+ * 三元条件按优先级挑一个格式：17读证明 >16流式文档 >15文档 >14数组 >13采纳 >7–12加载 >6尺寸/历史效果，
+ * 再到5孤儿/4导入退休/3资源退休/2导入/1基础；不是逐项独立版本取最大值，兼容组合仍由解码检查。
+ * 只投影字段，不在此调用 decode 的完整校验；snapshot 各域必须由宿主作为同一稳定根提供。 */
 function recoveryInput(snapshot: EngineSnapshot) {
   const payload = dataRecord({
     document: documentValue(snapshot.document),
@@ -71,17 +77,19 @@ function recoveryInput(snapshot: EngineSnapshot) {
   });
   return [[...(snapshot.runtime.imports?.values()??[])].some(job=>job.source?.integrityVersion===2)?17:[...(snapshot.runtime.imports?.values()??[])].some(job=>job.source?.kind==='native-document'&&job.parserVersion===5)?16:[...(snapshot.runtime.imports?.values()??[])].some(job=>job.source?.kind==='native-document')?15:[...(snapshot.runtime.imports?.values()??[])].some(job=>job.source?.kind==='native-json-array')?14:snapshot.runtime.assetBindings?.size?13:snapshot.runtime.loading?(snapshot.runtime.loading.version===6?12:snapshot.runtime.loading.version===5?11:snapshot.runtime.loading.version===4?10:snapshot.runtime.loading.version===3?9:snapshot.runtime.loading.version===2?8:7):[...snapshot.operations.values()].some(intent=>intent.historyEffect)||[...snapshot.runtime.resources.values()].some(resource=>resource.sizing)?6:snapshot.runtime.orphanFiles?.size?5:[...(snapshot.runtime.imports?.values()??[])].some(job=>job.source?.retirement||job.source?.previousFiles?.length)?4:[...snapshot.runtime.resources.values()].some(resource=>resource.retirement)?3:snapshot.runtime.imports?.size ? 2 : 1,snapshot.rootRevision,snapshot.revision,payload] as const;
 }
-/** 同步编码完整 Root，返回 sealed 不可变图像；编码成功尚不代表已 durable。 */
+/** 同步投影并捕获 Root，返回 sealed 不可变 JSON 图像；编码成功尚不代表领域校验通过或已 durable。
+ * sealed 是 codec 内部来源/字节成本标记，不是数据库提交回执或恢复准入证明。 */
 export function encodeRecovery(snapshot:EngineSnapshot):RecoveryImage {
   return sealRecoveryImage(...recoveryInput(snapshot));
 }
-/** 相同输入合同的分片编码入口，预算与外部数据捕获边界由 recovery-encoding 明确处理。 */
+/** 相同输入合同的分片编码入口，预算与外部数据捕获边界由 recovery-encoding 明确处理。
+ * recoveryInput 的表枚举/格式选择先同步完成；不是异步遍历 live editor，也不返回部分可用 Root。 */
 export function encodeRecoveryAsync(snapshot:EngineSnapshot,options:ImportScheduling={}):Promise<RecoveryImage> {
   return sealRecoveryImageAsync(...recoveryInput(snapshot),options);
 }
 /** 解码边界的未验证对象字段表，后续每个字段仍需具体校验。 */
 type ObjectValue = Record<string, unknown>;
-/** 要求非 null 的非数组对象，否则统一报告图像损坏。 */
+/** 要求非 null 的非数组对象；仅是字段读取辅助器，不在这里证明普通原型或全部属性合法。 */
 function object(value: unknown): ObjectValue { if (!value || Array.isArray(value) || typeof value !== 'object') throw fault('corrupt_recovery_image'); return value as ObjectValue; }
 /** 要求数组；不能把缺失字段或对象静默转成空数组。 */
 function array(value: unknown): unknown[] { if (!Array.isArray(value)) throw fault('corrupt_recovery_image'); return value; }
@@ -91,7 +99,8 @@ function string(value: unknown): string { if (typeof value !== 'string' || !valu
 function integer(value: unknown, min = 0): number { if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < min) throw fault('corrupt_recovery_image'); return value; }
 /** 验证非空字符串数组；是否允许重复由具体持久字段/关联约束决定。 */
 function strings(value: unknown): string[] { return array(value).map(string); }
-/** 解码二元组表，拒绝重复 ID 与非二元组；完成后返回运行时安全只读 Map。 */
+/** 顺序解码二元组表，拒绝重复非空 ID 与非二元组，返回隐藏 set/delete 的 readMap 视图。
+ * 每行 decode 决定 value 的校验与冻结；表外壳本身不递归捕获任意值，任一行抛错就不返回该表。 */
 function table<T>(value: unknown, decode: (entry: unknown, id: Id) => T): ReadonlyMap<Id, T> {
   const result = new Map<Id, T>();
   for (const item of array(value)) { const pair = array(item), id = string(pair[0]); if (pair.length !== 2 || result.has(id)) throw fault('corrupt_recovery_image'); result.set(id, decode(pair[1], id)); }
@@ -104,7 +113,9 @@ function readDocument(value: unknown, registry: Registry): Document {
   const document = createDocument(string(raw.projectId), array(raw.canvases) as never, array(raw.elements) as never, tombstones);
   validateDocument(document, registry); return document;
 }
-/** 校验持久 Change 的基础形状/目标/字段白名单/存在性；不在恢复解码时执行历史修改。 */
+/** 校验持久 Change 的基础形状、目标代次、字段白名单及 before/after 自有字段存在性。
+ * 不按当前文档执行 before 条件，不逐一验证整元素前后像的全部领域语义；历史回放另有验证入口。
+ * 输入已经过顶层 JSON 捕获，这里冻结同一份捕获数组，不 clone 第二份 changes。 */
 function changes(value: unknown): readonly Change[] {
   for (const item of array(value)) {
     const change = object(item);
@@ -124,7 +135,8 @@ function changes(value: unknown): readonly Change[] {
 /** 已知版本校验历史增量，未来版本原样保留；真正回放前必须另查解释器，不能自动重写。 */
 function historyTransition(value:unknown){
   const raw=object(value);integer(raw.version,1);
-  // Preserve future evidence with its original bytes. Its interpreter must be checked before any replay.
+  // 未知正版本保留捕获后的 JSON 值，不按 v1 重写字段；不保证输入原始序列化字节未变。
+  // 真正回放前仍须查对应解释器；“能留存”不等于当前实现能执行该证据。
   if(raw.version===1){try{validateHistoryTransition(value,changes);}catch{throw fault('corrupt_recovery_image');}}
 }
 /** 校验意图身份与已知 upload/run 字段约束，保留 schema version；可恢复不等于可直接执行。 */
@@ -145,14 +157,18 @@ function intent(value: unknown, id: Id): OperationIntent {
   strings(raw.canvasIds); strings(raw.dependencies); changes(raw.changes);
   return freeze(value as OperationIntent);
 }
-/** 双栈 ID 必须唯一且精确覆盖 entries；每个 entry 关联的 operation 必须存在，不从网络队列推断历史。 */
+/** undo/redo 合起来必须无重复且精确覆盖 entries；栈顺序原样保留，不从网络队列重新推断。
+ * entry.operationIds 要在 core operations 存在，但此处不尝试撤销/重做或证明当前每个栈项都可执行。 */
 function readHistory(history:ObjectValue,operations:ReadonlyMap<Id,OperationIntent>):HistoryState {
   const entries=table<HistoryEntry>(history.entries,(value,id)=>{const raw=object(value);if(string(raw.id)!==id||typeof raw.label!=='string')throw fault('corrupt_recovery_image');changes(raw.changes);for(const operationId of strings(raw.operationIds))if(!operations.has(operationId))throw fault('corrupt_recovery_image');if(raw.groupId!==undefined)string(raw.groupId);return freeze(value as HistoryEntry);});
   const undo=strings(history.undo),redo=strings(history.redo),ids=[...undo,...redo];
   if(new Set(ids).size!==ids.length||ids.length!==entries.size||ids.some(id=>!entries.has(id)))throw fault('corrupt_recovery_image');
   return Object.freeze({undo:freeze(undo),redo:freeze(redo),entries});
 }
-/** 防御恢复入口：捕获 JSON 后逐域校验，所有通过才返回冻结 Root；不部分发布合法前缀。 */
+/** 防御恢复入口：同步捕获 payload 后逐域校验，所有通过才返回候选冻结 Root；不部分发布合法前缀。
+ * 先读 working/history/ledger，再核依赖和请求，再读 ACK/资源/审计/任务，最后联合检查 loading 与 pin。
+ * 不读取 IDB/Blob/服务端，不对快照做自动修复；失败直接抛出（子校验器可保留自己的错误码）。
+ * JSON 往返隔离调用者记录，但 getter/toJSON 可能在捕获时执行，其外部副作用不会被撤销。 */
 export function decodeRecovery(image: RecoveryImage, registry: Registry): CoreSnapshot & { readonly rootRevision: number; readonly runtime: RuntimeState } {
   if (![1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17].includes(image.formatVersion)) throw fault('unsupported_recovery_version');
   integer(image.rootRevision); integer(image.localRevision);
@@ -166,7 +182,8 @@ export function decodeRecovery(image: RecoveryImage, registry: Registry): CoreSn
   if(image.formatVersion<6&&[...operations.values()].some(intent=>intent.historyEffect))throw fault('unsupported_recovery_version');
   for(const operation of operations.values())if(operation.historyTransition?.version===1&&(operation.historyTransition.rootRevision<1||operation.historyTransition.rootRevision>image.rootRevision))throw fault('corrupt_recovery_image');
   if(image.formatVersion===1&&array(runtime.imports??[]).length)throw fault('unsupported_recovery_version');
-  // core operations 与 ledger 的文档意图/历史证据互相核对；上传/无文档效果的控制动作另有归属。
+  // core operations 保存文档意图；ledger 还含上传/控制任务，因此不是两个表逐项一对一同大小。
+  // 文档效果项必须能关联 core 意图，并核对 historyTransition/historyEffect；这一步不比较所有 intent 字段。
   const records = table<OperationRecord>(ledger.operations, (value, id) => {
     const raw = object(value); intent(raw.intent, id); strings(raw.blockers); object(raw.basePresence);
     if (((object(raw.intent).operationType === 'document.change'||object(raw.intent).operationType==='run.apply'&&array(object(raw.intent).changes).length>0) && !operations.has(id)) || !['pending', 'frozen', 'resolved', 'blocked'].includes(string(raw.phase))) throw fault('corrupt_recovery_image');
@@ -178,6 +195,8 @@ export function decodeRecovery(image: RecoveryImage, registry: Registry): CoreSn
   if (operations.size !== [...records.values()].filter(record => (record.intent.operationType === 'document.change'||record.intent.operationType==='run.apply'&&record.intent.changes.length>0)).length) throw fault('corrupt_recovery_image');
   // Validate the dependency DAG iteratively, including missing dependencies, without recursion overflow.
   // 用 Kahn 迭代检查整个依赖 DAG，避免深链递归溢出；缺依赖/重复依赖/环均拒绝。
+  // counts 是未消解入度，dependents 是反向邻接表，ready 用数组+递增下标作 FIFO，不用反复 shift。
+  // 所有顶点出队才证明无环；这个次序只供校验，不重排持久 operation.sequence 或执行任何操作。
   const counts = new Map<Id, number>(), dependents = new Map<Id, Id[]>(), ready: Id[] = [];
   for (const [id, record] of records) {
     const dependencies = record.intent.dependencies;
@@ -187,7 +206,8 @@ export function decodeRecovery(image: RecoveryImage, registry: Registry): CoreSn
   }
   for (let index = 0; index < ready.length; index++) for (const id of dependents.get(ready[index]) ?? []) { counts.set(id, counts.get(id)! - 1); if (!counts.get(id)) ready.push(id); }
   if (ready.length !== records.size) throw fault('corrupt_recovery_image');
-  // 恢复原 body 字符串，不 parse 后重新 stringify 以免改变冻结字节；仅为身份核验读取已知协议字段。
+  // FrozenRequest.body 保留捕获后的字符串内容，不 parse 后重新 stringify 替换请求体。
+  // 只对已识别 run 协议另 parse 核身份；普通文档/未知协议不在此编译或发请求，执行前仍须解释器准入。
   const requests = table<FrozenRequest>(ledger.requests, (value, id) => {
     const raw = object(value);
     if (string(raw.id) !== id || typeof raw.body !== 'string') throw fault('corrupt_recovery_image');
@@ -217,7 +237,8 @@ export function decodeRecovery(image: RecoveryImage, registry: Registry): CoreSn
     if (raw.retryAction !== undefined && !['submit', 'query'].includes(string(raw.retryAction))) throw fault('corrupt_recovery_image');
     return freeze(value as FrozenRequest);
   });
-  // 请求→操作和操作→请求双向校验，冻结状态不能缺少原请求身份。
+  // 请求列出的操作必须反指该请求；操作声明的 requestId 必须存在，frozen 操作不能缺 requestId。
+  // 这是这里实现的关联检查，并不单独证明所有服务执行结果或整份冻结请求语义。
   for (const record of records.values()) if (record.requestId && !requests.has(record.requestId) || record.phase === 'frozen' && !record.requestId) throw fault('corrupt_recovery_image');
   try {
     // 本地零效果证明也要独立复验，working 墓碑必须已经含其水位，不能因服务未见过而复用身份。
@@ -236,7 +257,8 @@ export function decodeRecovery(image: RecoveryImage, registry: Registry): CoreSn
   }
   const generation = integer(ledger.generation), durableGeneration = integer(ledger.durableGeneration);
   if (durableGeneration > generation) throw fault('corrupt_recovery_image');
-  // ACK 与 working 同项目，但保持两份不同意义的文档；服务版本要求覆盖 ACK 的全部活 canvas。
+  // ACK 是服务端已确认基线，working 是含本地编辑的当前模型；分别完整校验，并要求属于同一项目。
+  // versions 必须覆盖 ACK 全部活 canvas，允许仍带其它版本项；这里不把 ACK 覆盖到 working。
   const acknowledged = readDocument(runtime.acknowledged, registry);
   if (acknowledged.projectId !== document.projectId) throw fault('project_mismatch');
   const versions = table(runtime.versions, value => integer(value, 1));
@@ -267,6 +289,7 @@ export function decodeRecovery(image: RecoveryImage, registry: Registry): CoreSn
   });
   if(image.formatVersion===13&&!assetBindings.size||assetBindings.size&&runtime.loading!==undefined&&object(runtime.loading).version!==6)throw fault('unsupported_recovery_version');
   // 显式 owner→资源 ID 清单与恢复 audit 互证；完整反向 pin 集仍由保留扫描派生。
+  // 这些都是逻辑引用，不能证明原文件字节仍存在、摘要已重新计算或当前还有远端读权限。
   const resourcePins = table(runtime.resourcePins ?? [], strings);
   const replacementOwners=new Set<Id>();
   // 审计备份、选择、原/替代操作和 history replay 是一个闭合证明，不能只保留一句 keep-local 标签。
@@ -275,6 +298,8 @@ export function decodeRecovery(image: RecoveryImage, registry: Registry): CoreSn
     const working=readDocument(backup.document,registry),base=readDocument(backup.acknowledged,registry),versions=table(backup.versions,value=>integer(value,1));
     if(working.projectId!==document.projectId||base.projectId!==document.projectId||[...base.canvases.keys()].some(id=>!versions.has(id)))throw fault('corrupt_recovery_image');
     readHistory(object(backup.history),operations);if(!equal(strings(backup.resourceIds),resourcePins.get(`recovery:${id}`)))throw fault('corrupt_recovery_image');
+    // 每次审计内去重原操作，全局 replacementOwners 防同一替代操作被两次审计重复认领。
+    // keep-local 可 superseded/satisfied，discard-local 必须 discarded；替代意图的 sequence 必须更晚。
     const localReplacements:Id[]=[],ids=new Set<Id>();for(const value of array(raw.decisions)){const decision=object(value),operationId=string(decision.operationId),record=records.get(operationId),request=record?.requestId?requests.get(record.requestId):undefined;
       if(ids.has(operationId)||!record||record.phase!=='resolved'||record.recoveryId!==id||record.resolution!==decision.resolution||record.replacementId!==decision.replacementId||record.intent.operationType==='asset.upload'||record.requestId&&(!request||request.phase!=='resolved'||request.outcome!=='not-applied'))throw fault('corrupt_recovery_image');ids.add(operationId);
       if(!['keep-local','discard-local'].includes(string(decision.choice))||(decision.choice==='discard-local')!==(decision.resolution==='discarded'))throw fault('corrupt_recovery_image');
@@ -308,7 +333,8 @@ export function decodeRecovery(image: RecoveryImage, registry: Registry): CoreSn
     if(['superseded','discarded','satisfied'].includes(record.resolution??'')){const audit=record.recoveryId?recoveries.get(record.recoveryId):undefined;if(!audit||!audit.decisions.some(decision=>decision.operationId===record.intent.id))throw fault('corrupt_recovery_image');}
     else if(record.recoveryId!==undefined||record.replacementId!==undefined)throw fault('corrupt_recovery_image');
   }
-  // run 必须由已 applied 的原受理请求产生，轮询游标、待合并页和 output 事件均有身份/顺序约束。
+  // run 关联原 run.start 操作和 outcome=applied 请求；不向服务查询任务现在是否仍存在/已经完成。
+  // pendingPage 从当前 cursor 连续编号到 next，outputEvents 按 step 唯一且 seq 不得超出已知页尾。
   const runs=table<RunRecord>(runtime.runs ?? [],(value,id)=>{
     const raw=object(value),operation=records.get(string(raw.operationId)),request=requests.get(string(raw.requestId)),target=object(raw.target);
     if(string(raw.id)!==id||operation?.intent.operationType!=='run.start'||operation.requestId!==raw.requestId||request?.kind!=='run.start'||request.outcome!=='applied'||operation.intent.run.boardId!==string(raw.boardId)||operation.intent.run.target.id!==string(target.id)||operation.intent.run.target.incarnation!==integer(target.incarnation,1))throw fault('corrupt_recovery_image');
@@ -325,6 +351,7 @@ export function decodeRecovery(image: RecoveryImage, registry: Registry): CoreSn
     return freeze({...value as RunRecord,outputEvents:array(raw.outputEvents ?? []) as never});
   });
   // 导入 job 有独立 validator；source/parser/read-proof 特性与 envelope 版本必须互相匹配。
+  // 只验证已存任务声明与项目归属，不重读源文件或启动 runner；恢复执行由 engine 后续装配。
   const imports=table<ImportJob>(runtime.imports??[],(value,id)=>{const job=value as ImportJob;validateImportJob(job);if(job.id!==id||job.projectId!==document.projectId)throw fault('corrupt_recovery_image');return freeze(job);});
   const hasJsonArrays=[...imports.values()].some(job=>job.source?.kind==='native-json-array');if(hasJsonArrays&&image.formatVersion<14||image.formatVersion===14&&!hasJsonArrays)throw fault('unsupported_recovery_version');
   const hasReadProof=[...imports.values()].some(job=>job.source?.integrityVersion===2);if(hasReadProof!==(image.formatVersion===17))throw fault('unsupported_recovery_version');
@@ -333,12 +360,14 @@ export function decodeRecovery(image: RecoveryImage, registry: Registry): CoreSn
   // 上传资源、采纳binding、导入源和孤儿文件共享本地文件身份空间，任何交叉冲突均拒绝。
   const orphanFiles=table<OrphanFile>(runtime.orphanFiles??[],(file,id)=>{validateOrphanFile(file,id);return freeze(file);});
   if(orphanFiles.size&&image.formatVersion<5)throw fault('unsupported_recovery_version');for(const id of orphanFiles.keys())if(resources.has(id)||assetBindings.has(id)||importFiles(imports).has(id))throw fault('local_file_identity_conflict',[id]);
-  // 直到所有分表校验完成才组装一个候选 Root；不在这里启动 scheduler 或创建 view。
+  // 分表及关联检查完成后组装候选 Root，保留 localRevision/rootRevision 和 ledger 两种水位。
+  // readMap/冻结外壳让已捕获事实只读；不在这里推进 durableGeneration、启动 scheduler 或创建 view。
   const restoredLedger: LedgerSnapshot = Object.freeze({ generation, durableGeneration, operations: records, requests });
   const snapshot=Object.freeze({ revision: image.localRevision, rootRevision: image.rootRevision, document, history:restoredHistory, operations,
     runtime: Object.freeze({ ...(runtime.loadingRead!==undefined?{loadingRead:Object.freeze({document:readDocument(object(runtime.loadingRead).document,registry),versions:table(object(runtime.loadingRead).versions,(value)=>integer(value,1))})}:{}), ...(runtime.loading!==undefined?{loading:freeze(runtime.loading as LoadingState)}:{}), orphanFiles, imports, recoveries, runs, resources, ...(assetBindings.size?{assetBindings}:{}), resourcePins, ledger: restoredLedger, acknowledged, versions, receipts, conflicts: table(runtime.conflicts, string) }),
   });
-  // 永久清理的本地独有字节仍被 pin 是损坏状态，不能恢复成看似可用的图片引用。
+  // 对已有 purge 声明的本地独有资源/孤儿再查保留引用：仍被 pin 则拒绝，而非静默删除引用。
+  // 有 stored 的资源不走此“本地唯一字节”拒绝分支，后续能否再取原图仍由资源端口决定。
   if([...resources.values()].some(resource=>resource.retirement?.purgedAt!==undefined&&!resource.stored)){
     const pins=resourceRetentionPins(snapshot,registry);for(const [id,resource]of resources)if(resource.retirement?.purgedAt!==undefined&&!resource.stored&&pins.pins.has(id))throw fault('corrupt_recovery_image');
   }

src/lib/canvas-runtime/resource-retention.ts

@@ -10,7 +10,10 @@ import type {EngineSnapshot,RuntimeState} from './contracts.ts';
 import {createResourcePinScan} from './resources.ts';
 
 /** Complete local-byte protection for one project scope; no DOM/viewport filtering. */
-/** 同时扫描 working 与 acknowledged；ACK 只额外取元素引用，避免把历史重复当另一套业务事实。 */
+/** 派生 resource ID → 保留理由 Set，同时扫描 working 与 acknowledged。
+ * 复用同一 history/ledger 解释器，但 ACK 只额外合入 element: 理由；两次扫描完整性仍都参与结果。
+ * displays 是资源 ID→租用数，temporary/resourcePins 是 owner→资源 ID 列表，不是同方向的表。
+ * 返回捕获的只读表/集合；不写 runtime、不增减持久引用计数，也不盘点文件是否实际存在。 */
 export function resourceRetentionPins(snapshot:EngineSnapshot,registry:Registry,displays:ReadonlyMap<Id,number>=new Map(),temporary:ReadonlyMap<Id,readonly Id[]>=new Map()) {
   const {runtime}=snapshot;
   const scan=createResourcePinScan(snapshot.history,runtime.ledger,registry);
@@ -26,20 +29,26 @@ export function resourceRetentionPins(snapshot:EngineSnapshot,registry:Registry,
   // 未结束/未封存导入和 opaque run 保留已知资源仓库，不假设尚未解释的 envelope 没有引用。
   for(const job of runtime.imports?.values()??[])if(!['completed','partial','cancelled'].includes(job.status)||importNeedsSeal(job)){if(job.source)add(job.source.fileId,`import-source:${job.id}`);for(const [id,resource]of runtime.resources)if(resource.retirement?.purgedAt===undefined)add(id,`import:${job.id}`);}
   for(const run of runtime.runs.values())for(const [id,resource]of runtime.resources)if(resource.retirement?.purgedAt===undefined)add(id,`run:${run.id}`);
+  // imports 只在非终态或仍需 seal 时 pin，runs 则不按 status 过滤；它们保留已知且未 purge 的资源。
+  // 这种保守 pin 不会自行把 complete 改为 false，也无法列出未知仓库 ID；全局/孤儿回收还需更强覆盖门槛。
   // 等待解码或没有解释器的状态也 pin；显示 URL 租用数与临时任务另外合并。
   for(const resource of runtime.resources.values())if(resource.image&&(resource.image.version!==1||resource.image.status==='pending'))add(resource.id,resource.image.version!==1?'image-decoder-unavailable':'image-decode');
   for(const [owner,ids]of temporary)for(const id of ids)add(id,owner);
   for(const [id,count]of displays)if(count>0)add(id,'display');
+  // sizing 未知版本也降低覆盖完整性，即使本轮没有形成额外 pin；complete 不是文件可读/可删证明。
   return Object.freeze({complete:current.complete&&base.complete&&![...runtime.resources.values()].some(resource=>resource.image&&resource.image.version!==1||resource.sizing&&resource.sizing.version!==1),pins:readMap(new Map([...pins].map(([id,owners])=>[id,readSet(owners)])))});
 }
 
 /** Runs inside the editor's single publication boundary, including reconcile and metadata commits. */
-/** 所有 Root 发布路径共同检查回收：reserved 正在原子删除时，不允许新 pin 或不完整覆盖闯入。 */
+/** 由 engine 的 Root 发布钩子调用：检查全局 reserved 集合，清除失效的软退休标记。
+ * reserved 非空时，任一保留 ID 相交或扫描不完整都会拒绝发布；它本身不获取/释放 reservation。
+ * 只按 next 检查保留状态，不比较 previous 来证明退休时钟单调，也不执行磁盘删除或等待保留期。 */
 export function prepareResourceRetention(next:EngineSnapshot,registry:Registry,displays:ReadonlyMap<Id,number>,reserved:ReadonlySet<Id>,temporary:ReadonlyMap<Id,readonly Id[]>=new Map()):RuntimeState {
   // 没有待回收工作/软标记时快速复用 runtime，避免每次普通编辑重扫整个资源集合。
   if(!reserved.size&&![...next.runtime.resources.values()].some(resource=>resource.retirement&&(resource.retirement.purgedAt===undefined||!resource.stored)))return next.runtime;
   const pins=resourceRetentionPins(next,registry,displays,temporary);
   if(reserved.size&&(!pins.complete||[...reserved].some(id=>pins.pins.has(id))))throw fault('resource_collection_in_progress',[...reserved]);
+  // 没有标记需清除时沿用 runtime；首次真正修改才复制 resources 表，其余资源记录继续共享。
   let resources=next.runtime.resources;
   for(const [id,resource]of next.runtime.resources){
     if(!resource.retirement)continue;

src/lib/canvas-runtime/resources.ts

@@ -42,7 +42,9 @@ export type ResourceHandle = { readonly id: Id; readonly src: string };
 /** 单资源 20 MiB 上限，与解码像素预算是不同约束。 */
 export const maxResourceBytes = 20 * 1024 * 1024;
 
-/** 从 changes 收集可能依赖的资源；这里不返回完整性证明，不能直接作为安全回收扫描。 */
+/** 从变化两侧收集字符串资源值：整记录按 component.resourceFields，字段变化按所有已安装字段名的并集。
+ * 不调用 registry.resolve 检查版本、不校验资源值域或字节存在性，空字符串也会进入 Set；输入合法性由上层保证。
+ * 不解释 canvas/隐藏引用，也不返回 complete，适合保守依赖收集而非证明无引用或直接删除文件。 */
 export function referencedResources(changes: readonly Change[], registry: Registry): Set<Id> {
   const result = new Set<Id>(), fields = new Set([...registry.components.values()].flatMap(component => component.resourceFields ?? []));
   /** 整记录按组件声明 resourceFields 收集；字段变化另用已安装字段名的保守并集。 */
@@ -61,7 +63,10 @@ export function referencedResources(changes: readonly Change[], registry: Regist
 }
 
 /** Read/write dependencies use object identities, rather than blocking every edit behind a pending image. */
-/** 构造对象级 read/write 集，避免独立文本编辑被未完成图片上传全局阻塞。 */
+/** 构造临时对象读写 Set：canvas:/element:/resource: 分命名空间，同一元素各字段/代次共用 element ID 键。
+ * owner 读取含祖先，边读取端点，上传仅写 resource 键；资源内容引用的上传依赖由 engine 另外收集。
+ * 不读取 intent.dependencies 或 run.action，也不获取锁/检查权限、服务版本或 before 条件；不是完整可并发证明。
+ * 返回可变集合供依赖规划，不保存成第二份 ledger 或持久调度状态。 */
 export function operationFootprint(intent: OperationIntent, document: Document) {
   const reads = new Set<string>(), writes = new Set<string>();
   if (intent.operationType === 'asset.upload') { writes.add(`resource:${intent.resourceId}`); return { reads, writes }; }
@@ -92,25 +97,29 @@ export function operationFootprint(intent: OperationIntent, document: Document)
   }
   return { reads, writes };
 }
-/** 写/写、写/读或读/写相交才冲突，纯读/读可并行。 */
+/** 只判给定足迹的写/写、写/读、读/写交集，纯读/读不构成该规则下的冲突。
+ * 不自行调度/等待；结果准确性依赖足迹覆盖所需对象，不能代替 canvas writer claim 或服务端条件提交。 */
 export function conflictsWith(prior: ReturnType<typeof operationFootprint>, next: ReturnType<typeof operationFootprint>) {
   return [...prior.writes].some(id => next.writes.has(id) || next.reads.has(id)) || [...prior.reads].some(id => next.writes.has(id));
 }
 
-/** One synchronous retention pass shares history interpretation across working/ACK.
- * No snapshot or mutable reference-count state is retained after the caller returns. */
-/** 一次保留扫描的解释器，预处理 history/ledger 可复用到 working 与 ACK；不缓存新的业务快照。 */
+/** Reuse one immutable history/ledger interpretation across synchronous document scans. */
+/** 预处理历史/账本后返回扫描闭包，可复用于 working 与 ACK；闭包仍持有这些输入及派生 schema/transition 引用。
+ * 输入需保持不可变，扫描结束不代表这些引用已释放；没有模块级新业务快照或独立可变引用计数 store。
+ * 每次调用重新生成 pins/complete；未知解释器降低完整性，已知 transition 形状损坏仍可能直接抛错。
+ * 这里只解释文档/历史/操作/explicit，ACK、显示租约、导入/run 等额外保留由 resourceRetentionPins 叠加。 */
 export function createResourcePinScan(history:HistoryState,ledger:LedgerSnapshot,registry:Registry){
  const transitions=new Map<OperationRecord,readonly Change[]>(),fieldTargets=new Set<Id>();
  /** 先记需要解释 data 字段变化的目标，再从历史整记录补齐它可能使用过的组件 schema。 */
  const rememberTargets=(values:readonly Change[])=>{for(const change of values)if(change.kind==='field'&&change.field.startsWith('data.'))fieldTargets.add(change.target.id);};
- // 最早未解决 sequence 决定还需保留哪些历史 transition 证据；不能只扫描当前非空 undo 栈。
+ // 所有 history.entries 都扫描，不只 undo/redo 栈顶；最早未解决 sequence（含上传等）确定相关 transition 前沿。
+ // 无未决项时 earliest=Infinity，不再将已结算 transition 增量当作待保留证据区间。
  const pending=[...ledger.operations.values()].filter(record=>record.phase!=='resolved'),earliest=pending.reduce((value,record)=>Math.min(value,record.intent.sequence),Infinity);
  for(const entry of history.entries.values())rememberTargets(entry.changes);
  let interpreted=true;
  for(const record of ledger.operations.values()){
-  // Obtain validated ranges for every understood transition, including resolved
-  // evidence. The core may reuse only proven immutable transition data.
+  // 所有 v1 transition 都经 helper 验结构/提取变化区间两侧，非完整历史展开；即使已 resolved 也可供 schema 索引。
+  // 未知 historyEffect 版本会降低完整性；未知 transition 仅在相关前沿内降低完整性，不能一概当空内容。
   if(record.intent.historyTransition?.version===1)transitions.set(record,historyTransitionChanges(record.intent.historyTransition));
   if(record.phase!=='resolved')rememberTargets(record.intent.changes);
   if(record.intent.historyEffect&&record.intent.historyEffect.version!==1)interpreted=false;
@@ -118,7 +127,8 @@ export function createResourcePinScan(history:HistoryState,ledger:LedgerSnapshot
  }
  // 同一 ID 的历史可能跨组件/版本，不只套用当前元素的 resourceFields。
  const schemas=new Map<Id,ElementRecord[]>();
- /** 每种 component/version 保留一个历史样本，只为需要解释字段变化的目标建立索引。 */
+ /** 对需解释字段变化的目标 ID，每种 component/version 留一个样本，跨 incarnation 保守复用历史 schema。
+  * 样本用于解释哪些键可能是资源，不证明当前目标仍是同一生命周期，也不复制全部历史 payload。 */
  const remember=(record:ElementRecord|null)=>{if(record&&fieldTargets.has(record.id)){const list=schemas.get(record.id)??[];if(!list.some(item=>item.componentId===record.componentId&&item.dataVersion===record.dataVersion))list.push(record);schemas.set(record.id,list);}};
  /** 从整记录变化的 before/after 补历史 schema，删除后的资源仍可由 history 保留。 */
  const rememberChanges=(values:readonly Change[])=>{for(const change of values)if(change.kind==='element'){remember(change.before);remember(change.after);}};
@@ -127,12 +137,15 @@ export function createResourcePinScan(history:HistoryState,ledger:LedgerSnapshot
   for(const record of ledger.operations.values()){rememberChanges(record.intent.changes);const changes=transitions.get(record);if(changes)rememberChanges(changes);}
  }
  const fields=new Set([...registry.components.values()].flatMap(component=>component.resourceFields??[]));
- /** 为指定 document 生成 resource ID→owner 集；explicit 输入相反，是 owner→资源 ID 列表。 */
+ /** 每个 document 新建资源→理由 Set；explicit 输入方向相反，为 owner→资源 ID 列表。
+  * complete 只表示本扫描器相关引用可解释，不证明本地字节可读、上传成功、其它 producer 无引用或允许立即回收。
+  * 输出 readMap/readSet 捕获成员，重复扫描之间不共享可变计数；扫描本身无异步让出/取消。 */
  return(document:Document,explicit:ReadonlyMap<Id,readonly Id[]>=new Map())=>{
   const pins=new Map<Id,Set<string>>();let complete=interpreted;
   /** 同一 owner 只计一份保留理由；调用者得到集合，不拥有第二套可变引用计数。 */
   const pin=(id:Id,owner:string)=>{const set=pins.get(id)??new Set<string>();set.add(owner);pins.set(id,set);};
-  /** 已知组件逐资源字段收集，字段格式或 schema 不可解释时降低完整性，不能默认为空。 */
+  /** 未知组件/版本或未声明 resourceFields 都令 complete=false；显式 [] 才可表示该定义无资源字段。
+   * 声明字段字符串作为 pin，undefined/null 视为空，非字符串非空值使解释不完整；不重算任何文件摘要。 */
   const element=(record:ElementRecord|null,owner:string)=>{
    if(!record)return;const component=registry.components.get(record.componentId);
    if(registry.resolve(record)!=='known'||component?.resourceFields===undefined){complete=false;return;}
@@ -151,7 +164,8 @@ export function createResourcePinScan(history:HistoryState,ledger:LedgerSnapshot
      }
     }
    }
-   // Keep the conservative cross-schema fallback and its original insertion order.
+   // 再用所有已安装资源字段的并集做保守兜底，保留可能的 before/after 字符串及原插入顺序。
+   // 即使当前/历史 schema 缺失已将 complete 降为 false，仍尽可能留下已知资源理由，而非只返回一个空失败表。
    const refs=new Set<Id>(),collect=(record:ElementRecord|null)=>{if(record)for(const field of registry.components.get(record.componentId)?.resourceFields??[])if(typeof record.data[field]==='string')refs.add(record.data[field] as string);};
    for(const change of values)if(change.kind==='element'){collect(change.before);collect(change.after);}else if(change.kind==='field'&&change.field.startsWith('data.')&&fields.has(change.field.slice(5))){if(typeof change.before==='string')refs.add(change.before);if(typeof change.after==='string')refs.add(change.after);}
    for(const id of refs)pin(id,owner);

src/lib/canvas-runtime/runs.ts

@@ -3,6 +3,7 @@
  * 任务受理和生成完成是两件事：RunPort 解释服务端回执及事件，RunRecord 保存任务事实，
  * tracker 只负责何时读取下一页；它不直接创建元素，也不自行把输出写进文档。
  * nextPollAt/cursor 等随根状态持久化；堆、去重 token、定时器和 AbortController 都可重建。
+ * tracker 不提交生成请求：受理与控制操作由 ledger/scheduler 处理，poll 只读取已受理任务。
  */
 import type { Id, Json, OperationIntent, Target, RunInput } from '../canvas-core/types.ts';
 import type { AppliedModelProof, CanonicalProposal, EngineSnapshot } from './contracts.ts';
@@ -12,7 +13,8 @@ import { fault, validJson } from '../canvas-core/values.ts';
 import { createMinHeap } from './structures.ts';
 
 /** 校验生成意图的基本形状和大小：提示词按 Unicode 码点计数，参数按 JSON 的 UTF-8 字节计数。
- * 此处不判断模型是否可用或目标是否仍存在，这些属于目录、编辑器和服务适配器的校验。 */
+ * 只检查形状，不捕获/冻结输入，也不查询模型目录、目标存活、board 归属或服务权限。
+ * JSON 校验/计长可能读取 getter，不能将此检查当成外来可变对象已经隔离的证明。 */
 export function validateRunInput(input: RunInput) {
   if (!input || typeof input.boardId!=='string' || !input.boardId || typeof input.target?.id!=='string' || !input.target.id || !Number.isSafeInteger(input.target.incarnation) || input.target.incarnation<1 || typeof input.modelId!=='string' || !input.modelId || typeof input.prompt!=='string' || !input.prompt.trim() || [...input.prompt].length>16000 || typeof input.propagate!=='boolean' || !input.parameters || Array.isArray(input.parameters) || typeof input.parameters!=='object' || !validJson(input.parameters) || new TextEncoder().encode(JSON.stringify(input.parameters)).length>16384) throw fault('invalid_ai_request');
 }
@@ -29,7 +31,8 @@ export type RunEvent = { readonly seq: number; readonly run_id: Id; readonly typ
 export type RunPage = { readonly status: RunStatus; readonly events: readonly RunEvent[]; readonly next: number; readonly hasMore: boolean; readonly outputs: readonly Json[]; readonly steps: readonly Json[]; readonly error?: string };
 /** 可恢复的任务事实：关联受理操作/请求、目标代次、计划、事件游标与输出。
  * controlEpoch 区分控制操作前后的读取；pendingPage 保留尚待协调的页，避免贸然越过游标。
- * attempt/nextPollAt 记录重试安排，blocked 要求显式恢复，而不是不断自动重试。 */
+ * attempt/nextPollAt 记录重试安排，blocked 要求显式恢复，而不是不断自动重试。
+ * 此类型不执行运行时校验；pendingPage 的保存及模型/游标同根协调由 engine.accept 实现。 */
 export type RunRecord = {
   readonly id: Id; readonly operationId: Id; readonly requestId: Id; readonly boardId: Id; readonly target: Target;
   readonly plan: Json; readonly status: RunStatus; readonly cursor: number; readonly hasMore: boolean;
@@ -38,7 +41,8 @@ export type RunRecord = {
 };
 /** 外部生成服务的适配协议。compile 产生请求描述，submit/query 处理请求是否生效，
  * accept/acceptAction 验证并转换受理/控制回执；poll 追踪执行，canonical 提取事件中的权威文档。
- * verifyApplied 可提供已应用结果的验证证据，不能把任意响应直接当成本地文档覆盖。 */
+ * verifyApplied 可提供已应用结果的验证证据，不能把任意响应直接当成本地文档覆盖。
+ * 回执/事件的 schema、版本及游标校验是端口与协调器的实现合同；tracker 不重复验证 RunPage。 */
 export type RunPort = {
   verifyApplied?: (request:FrozenRequest,receipt:Json)=>{readonly model:AppliedModelProof;readonly admission?:RunRecord;readonly action?:{readonly runId:Id;readonly runStatus?:RunStatus;readonly outputId?:Id}};
   catalog(boardId: Id, signal: AbortSignal): Promise<RunCatalog>;
@@ -51,7 +55,8 @@ export type RunPort = {
   canonical(event: RunEvent, snapshot: EngineSnapshot): CanonicalProposal;
 };
 /** 按 ID + incarnation 查目标：既检查入口目标，也检查计划 steps 中的传播目标。
- * 同 ID 重建后的元素不是旧任务的目标；无法识别的计划不推测它包含哪些节点。 */
+ * 同 ID 重建后的元素不是旧任务的目标；只认识 plan.steps 的 node_id/target_incarnation。
+ * 不递归搜索任意 JSON、不检查文档中目标是否存活，也不计算所有间接资源依赖。 */
 export function runContainsTarget(run: RunRecord, target: Target) {
   if(run.target.id===target.id && run.target.incarnation===target.incarnation)return true;
   const plan=run.plan;
@@ -59,11 +64,14 @@ export function runContainsTarget(run: RunRecord, target: Target) {
   return plan.steps.some(step=>!!step&&typeof step==='object'&&!Array.isArray(step)&&step.node_id===target.id&&step.target_incarnation===target.incarnation);
 }
 
-/** 除排队/执行中外均视为终态；是否还有事件要结合 hasMore 判断。 */
+/** 在 RunStatus 合同内，除 queued/running 外均视为终态；是否还有事件要结合 hasMore。
+ * 这里只做两个字符串比较，不是验证任意服务状态值的解析器。 */
 export const runTerminal = (status: RunStatus) => status !== 'queued' && status !== 'running';
 
 /** 创建串行轮询器：最多一个在途读取，以截止时间小顶堆选下个任务，同刻按入堆顺序。
- * 所有状态修改通过 update/accept 注入，持久化通过 persist 注入，因此调度器不另存业务事实。 */
+ * 所有状态修改通过同步 update/accept 注入，持久化通过 persist 注入，因此调度器不另存业务事实。
+ * getRuns 提供稳定 RunRecord 快照，clock/persist/accept 的身份与可靠性由宿主保证；构造不自动扫描任务。
+ * notify 负责首次及后续排队，堆只索引已通知项；连续重复通知会留惰性失效项，没有独立容量上限。 */
 export function createRunTracker(options: {
   clock: Clock; getRuns(): ReadonlyMap<Id, RunRecord>; persist(): Promise<void>;
   poll(run: RunRecord, signal: AbortSignal): Promise<RunPage>;
@@ -72,8 +80,10 @@ export function createRunTracker(options: {
   onError(error: unknown): void;
 }) {
   const heap = createMinHeap<{ id: Id; due: number; token: number; sequence: number }>((a,b) => a.due-b.due || a.sequence-b.sequence);
-  // 同一任务重复通知只更新 token；旧堆项惰性丢弃，不必在堆中查找删除。
+  // token 是每个 ID 最近入堆代次，sequence 仅打破同刻平局；两者不属于持久任务版本。
+  // 旧堆项只在到堆顶时惰性丢弃，tokens 不随每次出堆删除，不能把它当作活跃任务清单。
   const tokens = new Map<Id,number>();
+  // 每个 hold 独占一个 token，释放幂等；影响新读取调度，不改变业务 status 或中止在途采纳。
   const holds = new Set<symbol>();
   let sequence = 0, stopped = false, timer: unknown, active: { controller: AbortController; promise: Promise<void> } | undefined;
   /** 错误展示失败也不能反过来中断游标保存或改变轮询调度。 */
@@ -87,7 +97,8 @@ export function createRunTracker(options: {
     if (stopped || holds.size || active || !heap.peek()) return;
     timer = options.clock.setTimer(() => { timer = undefined; pump(); }, Math.max(0,heap.peek()!.due-options.clock.now()));
   }
-  /** 从当前事实重新取截止时间；通知只建立索引，不改任务状态、不发网络请求。 */
+  /** 从当前事实重新取截止时间；通知只建立索引，不改任务状态、不立即调用 poll。
+   * 无 nextPollAt 则按当前时间排队；不合格/缺失项不入堆，旧项由 pump 的实时资格检查挡住。 */
   function notify(ids: readonly Id[]) {
     if (stopped) return;
     for (const id of ids) {
@@ -98,7 +109,9 @@ export function createRunTracker(options: {
     arm();
   }
   /** 取一个到期任务并执行“先保存身份 → 读/复用页 → 协调 → 保存新游标”。
-   * 在途 promise 统一在 finally 释放，以保证失败和成功路径都能继续调度其他任务。 */
+   * 在途 promise 统一在 finally 释放，以保证失败和成功路径都能继续调度其他任务。
+   * run 在出堆时捕获，await 后不自动刷新；成功响应的 requestId/cursor/controlEpoch 栅栏由 accept 检查。
+   * pendingPage 复用也先过 persist，避免新协调越过可靠受理事实；此处不主动将新 poll 页保存为 pendingPage。 */
   function pump() {
     if (stopped || holds.size || active) return;
     let item = heap.pop();
@@ -113,9 +126,11 @@ export function createRunTracker(options: {
         await options.persist();if(stopped)return;
         // 协调未完成的页优先重用；不能跳到下一页而遗漏该页的文档结果。
         const page=run.pendingPage ?? await options.poll(run,controller.signal);if(stopped)return;
+        // accept 必须同步完成发布/保留页/冲突处理，tracker 不 await 异步回调，也不直接修改文档。
         options.accept(run,page);
         // accept 可能将任务标为 blocked 或留下 pendingPage；按照接受后的事实安排下一次读取。
         const latest=options.getRuns().get(run.id)!;
+        // accept 未抛错后清重试次数；pendingPage 优先延迟1000ms，否则 hasMore 用1ms，其余1000ms。
         options.update(run.id,current=>({...current,attempt:0,nextPollAt:options.clock.now()+(current.pendingPage ? 1000 : current.hasMore ? 1 : 1000)}));
         // 保存失败转入下方错误处理；若连错误状态也无法保存，则阻塞该任务等待显式重试。
         await options.persist();
@@ -125,8 +140,10 @@ export function createRunTracker(options: {
         const current=options.getRuns().get(run.id);
         // 等待期间若取消/应用等控制代次已改变，旧读取的失败不能污染新状态，重新通知即可。
         if(current && (current.controlEpoch??0)!==(run.controlEpoch??0)){notify([run.id]);return;}
+        // 端口须抛 Error 风格对象；此处读取 code/message，不是能归一化任意 thrown 值的通用捕获器。
         const code=(error as {code?:string}).code ?? (error as Error).message ?? 'run_poll_failed';
-        // 身份、权限和协议解释失败停住；其它错误按指数退避，单次延迟最多 30 秒。
+        // 按精确错误码集合阻塞；其它错误按旧 attempt 计算500ms起的指数退避，单次最多30秒。
+        // status/cursor 不在错误分支回滚，accept 已发布的冲突或页证据继续由根状态持有。
         const blocked=['forbidden','unauthorized','identity_changed','invalid_run_response','run_identity_mismatch','run_receipt_expired','run_interpreter_unavailable'].includes(code);
         options.update(run.id,current=>({...current,error:code,blocked,attempt:current.attempt+1,nextPollAt:options.clock.now()+Math.min(30000,500*2**Math.min(current.attempt,6))}));
         // 连错误状态也无法持久化时，在内存中阻塞；不让不可恢复的游标继续向前。
@@ -144,11 +161,15 @@ export function createRunTracker(options: {
       if(timer!==undefined)options.clock.clearTimer(timer);timer=undefined;
       return()=>{if(holds.delete(token)&&!holds.size&&!stopped)arm();};
     },
-    /** 先确认当前状态能保存，再清除阻塞并立即排队；最终是否合格仍由 eligible 决定。 */
+    /** 先保存现有根，再清除所有任务（不只 blocked）的阻塞/error 并改 nextPollAt 为现在；不清 attempt。
+     * 清除后的状态本方法不再 persist，由下一次 pump 的前置屏障保存；终态无尾页仍不轮询。
+     * retry 本身不检查 stopped，关闭后宿主不应再调用；notify 的停止门禁只阻止重新发起读取。 */
     async retry() { await options.persist();for(const id of options.getRuns().keys())options.update(id,run=>({...run,blocked:false,error:undefined,nextPollAt:options.clock.now()}));notify([...options.getRuns().keys()]); },
     /** 等当前在途处理及其保存结束；不保证所有未来轮询或生成任务已结束。 */
     async settle() { while(active)await active.promise; },
-    /** 永久关闭本 tracker，撤销计时、请求中止在途网络并丢弃堆索引；任务事实留给恢复。 */
+    /** 永久关闭本 tracker，撤销计时、请求中止在途网络并丢弃堆索引；不调用远端取消任务。
+     * 同步返回，不等待 active 结束；迟到页在 accept 前被 stopped 挡住，必要时另用 settle 等在途退出。
+     * 已进入 accept/persist 的工作不会被回滚，任务事实留给宿主恢复，tokens/holds 随实例回收。 */
     stop() { stopped=true;if(timer!==undefined)options.clock.clearTimer(timer);timer=undefined;active?.controller.abort();heap.clear(); },
   });
 }

src/lib/canvas-runtime/scope-counts.ts

@@ -8,7 +8,9 @@ import {fault} from '../canvas-core/values.ts';
 /** Snapshot-bound direct membership counts, including nodes and connections. */
 /** 当前捕获快照的直属数量，包含节点和边；不是递归子树大小或 DOM 已挂载数量。 */
 export type CanvasElementCounts=Readonly<Record<Id,number>>;
-/** 要求 counts 精确覆盖 canvasIds、每项非负安全整数，且总和等于声明 total。 */
+/** 检查自有可枚举键数量及 canvasIds 的每个键存在，计数为非负安全整数，总和安全且等于 total。
+ * canvasIds 须由调用方保证唯一；此函数不单独去重，重复声明会破坏“键数量相同即覆盖相同”的前提。
+ * 只验证声明内部一致，不读取真实元素、认证服务或证明后续 payload 已齐；输入也不在此捕获/冻结。 */
 export function validateCanvasElementCounts(value:unknown,canvasIds:readonly Id[],total:number):asserts value is CanvasElementCounts {
  if(!value||typeof value!=='object'||Array.isArray(value))throw fault('invalid_model_coverage');
  const counts=value as Record<Id,unknown>,keys=Object.keys(counts);let sum=0;
@@ -20,7 +22,9 @@ export function validateCanvasElementCounts(value:unknown,canvasIds:readonly Id[
 /** All active IDs in the capture, including records not yet received. */
 /** 完整活 ID 命名空间，即使部分记录尚未传到客户端，也预先知道其直接 owner。 */
 export type ElementOwners=Readonly<Record<Id,Id>>;
-/** 核验每个活 ID 的 owner 合法，并按 owner 反算数量与 counts 一致，不靠已读前缀猜完整性。 */
+/** 要求声明恰有 total 个自有可枚举活 ID，每个非空 ID 的 owner 是 counts 中已有键，再反算数量。
+ * counts 应先经计数校验；此处不独立验证其值域，也不与已读 document 比较 ID/owner 是否对应。
+ * 只做同步声明一致性检查，不捕获/冻结输入；实际 payload 到达后还需匹配这份源快照身份表。 */
 export function validateElementOwners(value:unknown,counts:CanvasElementCounts,total:number):asserts value is ElementOwners {
  if(!value||typeof value!=='object'||Array.isArray(value)||Object.keys(value).length!==total)throw fault('invalid_model_identity');
  // 无原型计数表避免特殊 owner 键污染计数；空 canvas 由缺省 0 与 counts 比较。
@@ -30,8 +34,10 @@ export function validateElementOwners(value:unknown,counts:CanvasElementCounts,t
 }
 
 /** Full captured topology, independent of which entry payloads have arrived. */
-/** 用完整 topology+owner 证明验证单根、父存在、入口唯一/归属正确和无环。
- * 此时入口记录可能尚未收到，入口是否确为 node 仍需 payload 到达后的文档校验。 */
+/** 用源 canvas 表和已验证 owners 声明检查唯一根=projectId、父存在、入口唯一/归属与无环。
+ * 不是完整 CanvasRecord/payload schema 校验；未收到入口时不能证明其为 node、组件可用或实际拥有关系一致。
+ * 每个子 canvas 重新走父链，深树会反复访问共享祖先；同步检查无预算/取消，应由捕获规模约束成本。
+ * 不捕获输入或标记文档已完整；加载器另需核对已收到树/元素与此声明，再建立 owner 的覆盖状态。 */
 export function validateCanvasTopology(canvases:readonly import('../canvas-core/types.ts').CanvasRecord[],owners:ElementOwners,projectId:Id):void {
  if(!Array.isArray(canvases)||!canvases.length)throw fault('invalid_model_topology');
  const table=new Map(canvases.map(canvas=>[canvas?.id,canvas]));if(table.size!==canvases.length||!table.has(projectId))throw fault('invalid_model_topology');

src/lib/canvas-runtime/sha256.ts

@@ -20,7 +20,9 @@ const K=new Uint32Array([
 /** 32位循环右移；区别于简单逻辑右移，低位从左侧回填。 */
 const rotate=(n:number,bits:number)=>(n>>>bits)|(n<<(32-bits));
 /** Incremental bytes only; owns at most a partial block, state and message schedule. */
-/** 新建单次摘要状态；允许多次 update，hex 终结后只可重复读结果，不能继续追加。 */
+/** 新建单次摘要状态，闭包拥有可变 state/block/words；冻结 API 不代表内部计算状态不变。
+ * update 可多次追加，hex 首次终结后缓存结果，不能继续追加；不支持复制状态或导出恢复游标。
+ * 纯同步计算，无异步让出/取消；分块大小与调度由读取 Blob 的调用方控制。 */
 export function createSha256(){
   // length 计原输入字节；pending 计尾块已占字节；result 缓存最终十六进制并标记终结。
   const state=new Uint32Array([0x6a09e667,0xbb67ae85,0x3c6ef372,0xa54ff53a,0x510e527f,0x9b05688c,0x1f83d9ab,0x5be0cd19]),block=new Uint8Array(64),words=new Uint32Array(64);let pending=0,length=0,result:string|undefined;
@@ -35,7 +37,9 @@ export function createSha256(){
     const values=[a,b,c,d,e,f,g,h];for(let i=0;i<8;i++)state[i]=(state[i]+values[i])>>>0;
   }
   return Object.freeze({
-    /** 先补上次尾块，再就地压缩输入完整块，最后只复制不足64字节的尾部。 */
+    /** 先补尾块，再直接读取输入完整块压缩，最后只复制不足 64 字节的尾部，不保留输入引用。
+     * 不修改调用方字节；累计长度必须保持安全整数，终结后即使追加空数组也拒绝。
+     * 这里的就地指同步消费输入，不代表每次 update 只处理固定工作量或自动让出主线程。 */
     update(bytes:Uint8Array){
       if(result!==undefined)throw fault('digest_finalized');if(!(bytes instanceof Uint8Array)||!Number.isSafeInteger(length+bytes.byteLength))throw fault('invalid_digest_input');length+=bytes.byteLength;let offset=0;
       if(pending){const count=Math.min(64-pending,bytes.byteLength);block.set(bytes.subarray(0,count),pending);pending+=count;offset=count;if(pending===64){compress(block,0);pending=0;}}

src/lib/canvas-runtime/storage-port.ts

@@ -6,19 +6,25 @@
 import type { Json } from '../canvas-core/types.ts';
 
 /** Portable durable-store contract. Browser database types belong to the adapter. */
-/** 账号/工作区/项目共同隔离持久事实；同 projectId 不得串用其它账号的存储。 */
+/** 持久键由账号/工作区/项目组成，不含 view/navigation/authEpoch；身份退役另由宿主与 leader 围栏处理。
+ * 类型声明不捕获字符串、不验证权限，adapter 应按此作用域隔离事实，不能仅用 projectId 作全局键。 */
 export type StorageScope = { readonly accountId: string; readonly workspaceId: string; readonly projectId: string };
 /** 可恢复单 Root 图像；formatVersion 是解释器版本，rootRevision 与文档 localRevision 分开。 */
 export type RecoveryImage = { readonly formatVersion: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17; readonly rootRevision: number; readonly localRevision: number; readonly payload: Json };
-/** 同一提交携带恢复图像、文件写入/删除及可选共享 depot cut，adapter 保证合同中的原子性。 */
+/** 恢复图像与可选文件增删/depot 清单的同次原子提交合同；不表示对象构造后已保存。
+ * files 是 Blob 原字节，image/depot 保存逻辑引用/证明；adapter 需在异步前捕获输入并核对身份/删除资格。
+ * 需要删除时还须显式 fileDeletion 能力，不能将独立异步删文件视为与 Root 同一事务。 */
 export type DurableBatch = { readonly image: RecoveryImage; readonly deleteFiles?:readonly string[]; readonly depot?:import('./asset-depot.ts').DepotCut; readonly files?: readonly { readonly id: string; readonly bytes: Blob }[] };
-/** 排他写者句柄；fence 区分代次，active 检查加实际存储校验阻止旧 writer 在新 leader 后继续写。 */
+/** 排他写者句柄，fence 标识持有代次，active 可随 release/失效改变；只读类型不代表 active 永远不变。
+ * 宿主准入检查不能替代 adapter 在真实 I/O/提交处复核 scope/fence/有效性，接口自身不实现跨进程锁。 */
 export type StorageLeader = { readonly scope: StorageScope; readonly fence: number; readonly active: boolean; release(): Promise<void> };
 /** 文件盘点只返回元信息，不为扫描加载全部 Blob 字节。 */
 export type StoredFileInfo={readonly id:string;readonly byteLength:number;readonly mimeType:string};
 /** 分页盘点绑定 rootRevision，nextAfter 是后续页游标，不能跨变更拼接成完整清理依据。 */
 export type FileInventoryPage={readonly files:readonly StoredFileInfo[];readonly rootRevision:number;readonly nextAfter?:string};
-/** 宿主实现的存储能力；可选字段必须显式探测，缺能力不能假装已完成扫描或原子删除。 */
+/** 宿主实现的持久协议，声明本身不执行校验/深冻结、获取锁或操作数据库。
+ * 可选能力须显式探测；引擎的 ledger generation/Root 发布只是内存事实，commit 成功确认后才推进可靠水位。
+ * close 为同步本地句柄收尾，异步 leader.release 独立；失败/取消的 I/O 不自动说明数据从未提交。 */
 export type StoragePort = {
   /** 可选工作区共享资源仓库，文件/引用保留通过 depot 合同处理。 */
   readonly assetDepot?:import('./asset-depot.ts').AssetDepotPort;
@@ -28,9 +34,11 @@ export type StoragePort = {
   readonly fileDeletion?: 'atomic-v1';
   /** 取得作用域 leader，已有有效写者时拒绝，而不是悄悄允许两个 writer。 */
   claim(scope: StorageScope): Promise<StorageLeader>;
-  /** 在有效 leader 下恢复最后可靠图像；null 表示没有已提交快照。 */
+  /** 恢复最后已提交图像，不直接把任意 payload 当合法 Root；codec/engine 仍需版本、结构与身份校验。
+   * null 只表示该作用域没有已提交快照，不证明所有本地文件/共享 depot 记录也不存在。 */
   recover(leader: StorageLeader): Promise<RecoveryImage | null>;
-  /** 原子提交 DurableBatch 并返回真实完成的 rootRevision，不能提前在请求入队时 resolve。 */
+  /** adapter 捕获/验证并原子提交批次，返回实际完成的 durableRootRevision；不能在入队/单条写请求成功时提前 resolve。
+   * 回执不直接修改 editor 或放行 scheduler，调用方还需核对水位并按同切点恢复调度。 */
   commit(leader: StorageLeader, batch: DurableBatch): Promise<{ readonly durableRootRevision: number }>;
   /** 读取指定文件的 Blob，缺失用 undefined；不从文档资源引用猜字节已经存在。 */
   readFile(leader: StorageLeader, id: string): Promise<Blob | undefined>;

src/lib/canvas-runtime/storage.ts

@@ -3,6 +3,7 @@
  * DB schema v5 的七个 store 保存 Root checkpoint/journal、文件与共享 depot，历史/ledger 等在恢复图像内。
  * crypto/JSON 编码在事务外完成；Root、文件增删和 depot 清单在同一事务提交，oncomplete 才算 durable。
  * DB schema、checkpointVersion、journalVersion、RecoveryImage.formatVersion 是独立兼容域，不能混用。
+ * adapter 实例持有连接与 leader 集合，per-leader WeakMap 保存写尾链/可靠基线；close 不代替 engine 的持久化排空。
  */
 import {serializeRecoveryImage} from './recovery-json.ts';
 import {depotStores,createDepotStorage,detachDepotCut,verifyDepotBytes,writeDepotCut,promoteDepotFiles,resolveDepotFile} from './asset-depot-storage.ts';
@@ -18,7 +19,8 @@ export type {StorageScope,RecoveryImage,DurableBatch,StorageLeader,StoredFileInf
 type Metadata = { fence: number; throughRevision?: number; checkpointRevision?: number };
 /** 兼容旧完整图像行：image 与对其 JSON 表示计算的摘要。 */
 type StoredImage = { readonly image: RecoveryImage; readonly checksum: string };
-/** journal 差分：必须匹配前一 Root 的 revision/checksum；v1/v2 摘要覆盖范围不同。 */
+/** journal 差分：必须匹配前一 Root 的 revision/checksum；v1 哈希结果图像，v2 哈希 deltaBody。
+ * 因此 StoredImage.checksum 在内存中也可能是当前日志链节点摘要，并非总是 image 的独立摘要。 */
 type StoredDelta = {journalVersion:1|2;baseRevision:number;baseChecksum:string;header:Omit<RecoveryImage,'payload'>;patches:JournalPatch[];checksum:string};
 /** 新完整 checkpoint 以 UTF-8 Blob 保存，header 便于事务内检查连续性，解析/校验在事务外。 */
 type StoredBlobImage={readonly checkpointVersion:1;readonly header:Omit<RecoveryImage,'payload'>;readonly bytes:Blob;readonly checksum:string};
@@ -68,7 +70,9 @@ const requestValue = <T>(request: IDBRequest<T>) => new Promise<T>((resolve, rej
 const transactionDone = (transaction: IDBTransaction) => new Promise<void>((resolve, reject) => { transaction.oncomplete = () => resolve(); transaction.onabort = () => reject(transaction.error ?? fault('storage_aborted')); transaction.onerror = () => { /* onabort is the terminal barrier. */ }; });
 
 /** Single-origin browser adapter. Web Locks serialize tabs; a DB fence rejects stale handles. */
-/** 需要 IndexedDB 与 Web Locks；缺能力时明确拒绝，不悄悄退成无法可靠恢复的内存存储。 */
+/** 需要 IndexedDB 与 Web Locks；缺能力时明确拒绝，不悄悄退成无法可靠恢复的内存存储。
+ * 构造即开始打开数据库，尚未持有项目写锁；claim 才按 scope 取锁。工厂返回冻结能力外壳，内部连接状态仍可变。
+ * name/options 应由宿主保持稳定，锁名读取 options.name；不能把同一数据库意外装配成不同锁域。 */
 export function createBrowserStorage(options: { indexedDB?: IDBFactory; locks?: LockManager; name?: string; checkpointEvery?: number } = {}): StoragePort {
   const factory = options.indexedDB ?? globalThis.indexedDB, locks = options.locks ?? globalThis.navigator?.locks;
   if (!factory || !locks) throw fault('persistent_storage_unavailable');
@@ -113,13 +117,17 @@ export function createBrowserStorage(options: { indexedDB?: IDBFactory; locks?:
       if (!metadata || metadata.fence !== leader.fence) throw fault('storage_fence_lost');
       check(leader);
       const result = await run(transaction, metadata, key);
+      // readwrite 的原子可见性与可靠回执都在 oncomplete 后成立；callback 返回值只是待采纳结果。
       await done; // Never resolve durability on an individual put callback.
       return result;
     } catch (error) { try { transaction.abort(); } catch { /* Already terminal. */ } await done.catch(() => {}); throw error; }
   }
-  /** 先在只读事务捕获完整日志区间，再在事务外重建/哈希，最后才缓存可靠恢复结果。 */
+  /** 先在只读事务捕获完整日志区间，再在事务外重建/哈希，最后才缓存可靠恢复结果。
+   * 返回的是该只读快照，不保证 crypto 完成时仍是最新 Root；并发较新恢复已入缓存时不将其倒退。
+   * 捕获整个回放区间，逐条 apply/hash 没有独立合作预算；存储信封通过后仍需领域 decodeRecovery 深校验。 */
   async function recoverCut(leader:StorageLeader):Promise<StoredImage|null>{
     const captured=await execute(leader,['checkpoints','journal'],'readonly',async(transaction,metadata,key)=>{
+      // 没有可靠头就返回 null；不据此推断 files/depot 中没有尚未归属或共享的字节。
       if(metadata.throughRevision===undefined)return{cuts:[] as StoredCut[],checkpointRevision:undefined};
       if(metadata.checkpointRevision===undefined)throw fault('recovery_checkpoint_missing');
       const checkpoint=await requestValue<StoredCut|undefined>(transaction.objectStore('checkpoints').get([key,metadata.checkpointRevision]));
@@ -156,14 +164,17 @@ export function createBrowserStorage(options: { indexedDB?: IDBFactory; locks?:
     fileDeletion:'atomic-v1' as const,
     /** 共享仓库也走 execute，因此同样受 metadata fence 与事务终态约束。 */
     assetDepot:createDepotStorage((leader,stores,mode,run)=>execute(leader,stores,mode,tx=>run(tx))),
-    /** 非阻塞申请 scope 排他 Web Lock；取得后先可靠递增 DB fence，再把 leader 暴露给 engine。 */
+    /** 用 ifAvailable 申请 scope 排他 Web Lock：不排队等其它持有者，但仍异步等数据库与 fence 事务。
+     * scope 按入口标量构造锁键、取得后复制进 handle，调用者须在异步 claim 期间保持输入稳定。
+     * 同一 adapter 不同 scope 可持不同锁；execute 仍用 metadata fence 拒绝旧句柄。 */
     async claim(scope: StorageScope) {
       const key = keyFor(scope);
       if (closed) throw fault('storage_closed');
       let unlock!: () => void, acquired!: (leader: StorageLeader) => void, failed!: (error: unknown) => void;
       const released = new Promise<void>(resolve => { unlock = resolve; });
       const result = new Promise<StorageLeader>((resolve, reject) => { acquired = resolve; failed = reject; });
-      // Lock 回调等待 released Promise 保持锁；leader.release 幂等失效句柄后解锁并等回调结束。
+      // result 只交付 handle，held 则覆盖整个持锁生命周期；released 是二者之间的释放闸门。
+      // 首次 release 先失效/移出集合再解锁并等 held，重复调用会立即返回，不是另一次排空等待。
       const held = locks.request(`endoleap-headless:${options.name ?? 'endoleap-headless'}:${key}`, { mode: 'exclusive', ifAvailable: true }, async lock => {
         if (!lock) throw fault('storage_scope_in_use');
         const database = await opening;
@@ -187,10 +198,12 @@ export function createBrowserStorage(options: { indexedDB?: IDBFactory; locks?:
     async recover(leader: StorageLeader) {const cut=await recoverCut(leader);return cut?clone(cut.image):null;},
     /** 捕获批次→校验删除证明→顺序准备编码→原子写 Root/文件/depot；返回实际 durableRootRevision。 */
     async commit(leader: StorageLeader, batch: DurableBatch) {
-      // Detach mutable callers and descriptors before the first await, including queued commits.
+      // 入队前捕获图像与描述符，避免排在旧写入后等待时被调用者改写；codec-owned sealed 图像可直接复用。
+      // file 外壳复制而 Blob 原样借用；depot 用自己的捕获器，均不代表已经可靠落盘。
       const depot=batch.depot?detachDepotCut(batch.depot):undefined;
       const image=isSealedRecoveryImage(batch.image)?batch.image:freeze(clone(batch.image)),files=(batch.files??[]).map(file=>({id:file.id,bytes:file.bytes})),deleteFiles=[...(batch.deleteFiles??[])];if(deleteFiles.length>128||new Set(deleteFiles).size!==deleteFiles.length||deleteFiles.some(id=>typeof id!=='string'||!id||files.some(file=>file.id===id)))throw fault('invalid_file_deletion');if(!isSealedRecoveryImage(image))validateImage(image);
-      // 删除仅接受当前图像中已 purge 的版本化证明，不能在普通文件 API 中绕开 history/pin 保留。
+      // 删除依据当前提交图像的退休声明：最多128个唯一 ID，不能同批又新增。
+      // 这里检查证明形状/归属/任务终态，不自行重算 history pin 或保留期；Root 完整性由引擎负责。
       if(deleteFiles.length){
         type FileProof={id?:string;version?:number;byteLength?:number;mimeType?:string;digest?:string;fileId?:string;retirement?:{version:number;unreferencedAt:number;purgedAt?:number}};
         const payload=image.payload as {runtime?:{orphanFiles?:[string,FileProof][];resources?:[string,FileProof][];imports?:[string,{status:string;source?:FileProof&{previousFiles?:FileProof[]}}][]}};
@@ -203,15 +216,18 @@ export function createBrowserStorage(options: { indexedDB?: IDBFactory; locks?:
         if(image.formatVersion<3||deleteFiles.some(id=>{const marker=proofs.get(id)?.retirement;return !marker||marker.version!==1||!Number.isSafeInteger(marker.unreferencedAt)||marker.unreferencedAt<0||!Number.isSafeInteger(marker.purgedAt)||marker.purgedAt!<marker.unreferencedAt;}))throw fault('invalid_file_deletion');
       }
       check(leader);
-      // 串联同 leader 的保存；前次失败不永久毒化链，但新提交仍必须匹配真实 DB 头与连续 revision。
+      // 同 leader 的 crypto/编码/事务也串在一条 Promise 尾链上，避免各自准备不同基线后乱序提交。
+      // 吞掉旧尾链失败只为继续调度，新请求错误仍向其调用者传播；不自动重试旧批次或跨 leader 排队。
       const task=(writeTails.get(leader)??Promise.resolve()).catch(()=>{}).then(async()=>{
         if(depot)await verifyDepotBytes(depot);
         let base=lastCuts.get(leader)??await recoverCut(leader);
         if(base?.image.rootRevision===image.rootRevision)base=await recoverCut(leader);
         if(files.length&&base){const retired=purgedFileIds(base.image);if(files.some(file=>retired.has(file.id)))throw fault('resource_identity_conflict');}
-        // 周期检查点或新版格式转换可切完整基线，避免旧 reader 被迫从更高格式差分恢复。
+        // checkpoint 决定替换可靠回放起点；没有基线、达到间隔，或基线版本 >=7 且格式变化时建立新起点。
+        // delta 不划算也会写完整 Blob，但若 checkpoint=false，它仍是 journal 中的一行，不压缩旧链。
         const baseCheckpoint=lastCheckpoints.get(leader),checkpoint=!base||((base.image.formatVersion>=7)&&base.image.formatVersion!==image.formatVersion)||image.rootRevision-(baseCheckpoint??0)>=checkpointEvery;
         let stored:StoredImage|undefined,candidate:StoredCut|undefined;
+        // 同 revision 先沿用已恢复的链摘要；事务内仍逐字比较整 image、查 DB 头，不能只凭 revision 接受重试。
         if(base?.image.rootRevision===image.rootRevision){stored={image,checksum:base.checksum};candidate=stored;}
         // 连续且标准信封才尝试 delta；比较真实字节成本，差分过大/不可表达则回退完整 Blob。
         else if(base&&!checkpoint&&image.rootRevision===base.image.rootRevision+1&&JSON.stringify(Object.keys(image))===JSON.stringify(['formatVersion','rootRevision','localRevision','payload'])){
@@ -232,7 +248,8 @@ export function createBrowserStorage(options: { indexedDB?: IDBFactory; locks?:
           const previous=metadata.throughRevision;
           if(previous===undefined&&base)throw fault('recovery_delta_base_mismatch');
           const saved=previous===undefined?undefined:await requestValue<StoredCut>(transaction.objectStore(metadata.checkpointRevision===previous?'checkpoints':'journal').get([key,previous]));
-          // 同 Root 重试只允许完全相同图像/摘要且无新文件写入；缺口或异内容一律拒绝。
+          // 同 Root 重试须图像/摘要相同、无新增文件，且请求删除的行已经不存在；不再写 Root。
+          // 可在这条分支补写 depot 清单/字节与文件指针，支持幂等重建索引；事务失败仍整体回滚。
           if(previous!==undefined&&image.rootRevision!==previous+1){
             if(image.rootRevision!==previous)throw fault('storage_revision_gap');
             if(!saved||saved.checksum!==accepted.checksum||!base||JSON.stringify(base.image)!==JSON.stringify(image)||files.length)throw fault('storage_revision_conflict');for(const id of deleteFiles)if(await requestValue(transaction.objectStore('files').getKey([key,id])))throw fault('storage_revision_conflict');if(depot){await writeDepotCut(transaction,leader.scope,image.rootRevision,depot);await promoteDepotFiles(transaction,leader.scope,key,image,depot);}return{durableRootRevision:previous,checkpointRevision:metadata.checkpointRevision!};
@@ -258,7 +275,9 @@ export function createBrowserStorage(options: { indexedDB?: IDBFactory; locks?:
       });
       writeTails.set(leader,task);return task;
     },
-    /** 按 expectedRootRevision 的稳定 ID 游标分页盘点，最多128项；Root 改变则拒绝拼接旧页。 */
+    /** 按 expectedRootRevision 的稳定 ID 游标分页盘点，最多128项；Root 改变则拒绝拼接旧页。
+     * limit 约束返回的可读取文件数，不约束游标经过的已清理指针数；不计算 digest，也不做远端读取。
+     * 同 Root 的 depot 回收可能改变可读字节，revision 门禁不等于跨多次调用持有同一 IDB 快照。 */
     scanFiles(leader:StorageLeader,input:{expectedRootRevision:number;after?:string;limit:number}) {
       const {expectedRootRevision,after,limit}=input;
       if(!Number.isSafeInteger(expectedRootRevision)||expectedRootRevision<0||!Number.isSafeInteger(limit)||limit<1||limit>128||after!==undefined&&(typeof after!=='string'||!after))return Promise.reject(fault('invalid_file_inventory'));
@@ -280,7 +299,8 @@ export function createBrowserStorage(options: { indexedDB?: IDBFactory; locks?:
     },
     /** 在有效 fence 下读取本地 Blob 或共享字节指针；缺字节返回 undefined，不伪造空文件。 */
     readFile(leader: StorageLeader, id: string) { return execute(leader, ['files',...depotStores], 'readonly', async(transaction, _metadata, key) => resolveDepotFile(transaction,leader.scope,id,await requestValue<unknown>(transaction.objectStore('files').get([key, id])))); },
-    /** 停止新存储操作、释放 leader 并关闭数据库；宿主须先等 engine 保存完成，再释放 adapter。 */
+    /** 同步使 adapter 关闭并触发 leader.release/连接关闭，不返回排空 Promise，也不主动 abort 所有在途事务。
+     * 已开始事务由 IDB 自行结束，未开始任务会在 check 被拒绝；宿主须先等 engine 保存完成再释放 adapter。 */
     close() { closed = true; for (const handle of handles) void handle.release(); void opening.then(database => database.close()).catch(() => {}); },
   });
 }

src/lib/canvas-runtime/traversal-recovery.ts

@@ -9,7 +9,10 @@ import { planHistoryChanges } from '../canvas-core/history.ts';
 import { fault, freeze, readMap } from '../canvas-core/values.ts';
 
 /** Rewind only proved local stack moves, then replay the explicitly retained traversals. Never publish the temporary cursor. */
-/** 输入原 pending、已审阅替代意图、保留选择与文档边界，返回新双栈/entry 候选而不发布。 */
+/** 兼容的纯遍历恢复：pending 的非空 changes 必须全是 undo/redo，同一历史项最多遍历一次。
+ * 输入须为原逻辑顺序且其移动已反映在 snapshot.history；本函数不排序，也不验证恢复选择/替代意图来源。
+ * owner 索引由 entry.operationIds 建立，重复关联会覆盖；协调器须先拒绝歧义并提供按 entry ID 的文档边界。
+ * 返回私有两栈/entry 候选，不发布文档、发送逆操作或写审计；混合编辑/重复遍历交有完整证据的日志恢复处理。 */
 export function replanTraversals(snapshot:EngineSnapshot,pending:readonly OperationIntent[],replacements:ReadonlyMap<Id,OperationIntent|undefined>,kept:ReadonlySet<Id>,boundaries:ReadonlyMap<Id,{before:Document;after:Document}>,registry:Registry):HistoryState {
   const traversals=pending.filter(intent=>intent.changes.length);
   if(traversals.some(intent=>!['undo','redo'].includes(intent.origin)))throw fault('recovery_history_mixed_traversal_not_supported');
@@ -25,12 +28,14 @@ export function replanTraversals(snapshot:EngineSnapshot,pending:readonly Operat
     const id=entryId(intent);if(seen.has(id))throw fault('recovery_history_repeated_traversal_not_supported',[id]);seen.add(id);
     if(intent.origin==='undo')move(redo,undo,id);else move(undo,redo,id);
   }
- // 再按原逻辑顺序重放保留选择；每条都核对新的栈顶和正反向 changes 可执行性。
+ // 按原顺序逐项审阅，连丢弃项也要求命中当前栈顶；丢弃不重做旧移动，导致后项不可达时明确拒绝。
+ // planHistoryChanges 只验证/规划候选方向，结果不在此作为业务文档发布。
   for(const intent of traversals){
     const id=entryId(intent),entry=entries.get(id)!,source=intent.origin==='undo'?undo:redo,destination=intent.origin==='undo'?redo:undo;
     if(source.at(-1)!==id)throw fault('recovery_history_traversal_order',[id]);
     const replacement=replacements.get(intent.id),boundary=boundaries.get(id)!;
-    // 保留但新基线已满足、没有 replacement 时，退休该项而非制造一条无法重做的假历史。
+    // keep 但无 replacement 按协调器给出的“已满足”决定退休该项，不在此重新证明 fresh 文档已满足旧意图。
+    // 有 replacement 时将 changes 统一回 entry 的正向语义，并用 boundary.after 检验反向可行性。
     if(kept.has(intent.id)){
       if(!replacement){source.pop();entries.delete(id);continue;} // No remaining local effect, retired with an audit rather than a fabricated redo.
       const changes=intent.origin==='undo'?invert(replacement.changes):replacement.changes;
@@ -38,7 +43,8 @@ export function replanTraversals(snapshot:EngineSnapshot,pending:readonly Operat
       catch{throw fault('recovery_history_traversal_conflict',[id]);}
       move(source,destination,id);
       entries.set(id,freeze({...entry,changes,operationIds:entry.operationIds.map(operationId=>operationId===intent.id?replacement.id:operationId)}));
-    // 丢弃该 pending 遍历不等于丢弃原 entry：保留经过校验的正向 changes，并移除旧操作关联。
+    // 丢弃 pending 遍历保留原 entry 的正向变化，在 boundary.before 检验原遍历仍可执行，不移动两栈。
+    // 只移除此 intent 的关联，保留同 entry 其它贡献/元数据；不将丢弃等同于清空整项历史。
     }else{
       const changes=intent.origin==='undo'?invert(intent.changes):intent.changes;
       try{planHistoryChanges(boundary.before,intent.origin==='undo'?invert(changes):changes,registry);}
@@ -46,5 +52,6 @@ export function replanTraversals(snapshot:EngineSnapshot,pending:readonly Operat
       entries.set(id,freeze({...entry,changes,operationIds:entry.operationIds.filter(operationId=>operationId!==intent.id)}));
     }
   }
+  // 未改 entry 沿用不可变记录引用；冻结两栈并捕获表成员，不替代外围对恢复 Root 的整体校验。
   return Object.freeze({undo:freeze(undo),redo:freeze(redo),entries:readMap(entries)});
 }

src/lib/canvas-runtime/workspace.ts

@@ -23,7 +23,10 @@ export type WorkspaceOptions = {
 };
 
 /** Workspace owns persistent projects; a view only borrows one and never closes it. */
-/** 创建工作区容器，不立刻打开所有项目，只有 open/openPartial 才取得项目 engine。 */
+/** 建立 workspace 共享池和 projectId→打开 Promise 表，不在构造时 claim 项目存储或恢复文档。
+ * 注入的 digests/images/storage 也由本容器在最终 close 时关闭，跨 workspace 共享它们需宿主另行管理所有权。
+ * options 仍由闭包读取，身份/端口应保持稳定；公开标量与 assetDepot scope 并非每次随外部 options 重写。
+ * getProjects 捕获只读表成员，但 Promise 兑现的 engine 仍是业务 API，不是不可操作的纯数据快照。 */
 export function createWorkspaceRuntime(options: WorkspaceOptions) {
   const digests=options.digests??createDigestPool();
   const displays=createDisplayCache({onError:options.onError});
@@ -33,7 +36,9 @@ export function createWorkspaceRuntime(options: WorkspaceOptions) {
   /** 准入同时要求工作区仍接受任务和宿主身份仍有效，关闭一开始就让旧调用失效。 */
   const current = () => accepting && !closed && options.isCurrentIdentity();
   const assetDepot=options.storage.assetDepot?createAssetDepot({scope:options,port:options.storage.assetDepot,current,digest:(bytes,signal)=>digests.digest(bytes,signal)}):undefined;
-  /** 取得/创建共享项目；打开失败只移除同一个 Promise，迟到失败不能删掉后来重开的实例。 */
+  /** current 通过后按 document.projectId 复用在途/已打开 Promise，避免同 workspace 同项目重复 claim leader。
+   * 命中时不以新 document/versions/loading 替换初始参数；open/openPartial 随后再协调新输入。
+   * 打开拒绝仅移除仍对应自己的 Promise，准入有效时下次可重试；adapters 的同步抛错直接传出。 */
   function acquire(document:Document,versions:ReadonlyMap<Id,number>,loading?:LoadingState){
     if(!current())return Promise.reject(fault('identity_changed'));
     const existing=projects.get(document.projectId);if(existing)return existing;
@@ -46,20 +51,29 @@ export function createWorkspaceRuntime(options: WorkspaceOptions) {
     assetDepot,
     /** 查看项目打开句柄的只读表，不授予外部关闭/替换内部 ownership 的能力。 */
     getProjects: () => readMap(projects),
-    /** 完整源与已有 engine 协调：同捕获完成走 loading.complete，旧版本不覆盖较新的本地基线。 */
+    /** 取得 engine 后复查身份：同 sourceToken 的 loading 用 complete，否则尝试普通 refresh。
+     * 任一传入版本低于当前已知值就跳过整个 refresh；其余一致性由 engine 校验，不在这里合并版本向量。
+     * complete 拒绝总会抛错；refresh 拒绝仅在原 engine 仍 loading 时抛错，非 loading 可保留原 engine 返回。
+     * 因此返回 engine 表示复用成功，不等于传入 document 已被采纳或服务器写入已完成。 */
     open(document: Document, versions: ReadonlyMap<Id, number>,settings:{sourceToken?:string}={}) {
       return acquire(document,versions).then(async engine=>{if(!current())throw fault('identity_changed');const loading=engine.loading.getState();if(loading&&settings.sourceToken===loading.sourceToken){const result=await engine.loading.complete(document,versions,{sourceToken:settings.sourceToken});if(result.status==='rejected')throw fault(result.code,result.targets);}else{const previous=engine.getSnapshot().runtime.versions;if(![...versions].some(([id,value])=>(previous.get(id)??0)>value)){const result=engine.refresh(document,versions);if(result.status==='rejected'&&loading)throw fault(result.code,result.targets);}}return engine;});
     },
-    /** 接入部分源并复用项目 engine，仅相同 sourceToken 的后续块继续 accept。 */
+    /** 新项目以 partial 文档/loading 打开；已有项目只在当前 loading.sourceToken 匹配时 accept。
+     * 不同 token 或已无 loading 时直接返回原 engine，不替换其文档/加载任务；匹配但 accept 拒绝则抛错。 */
     openPartial(document:Document,versions:ReadonlyMap<Id,number>,loading:LoadingState){
       return acquire(document,versions,loading).then(engine=>{if(!current())throw fault('identity_changed');const previous=engine.loading.getState();if(previous?.sourceToken===loading.sourceToken){const result=engine.loading.accept(document,versions,loading);if(result.status==='rejected')throw fault(result.code,result.targets);}return engine;});
     },
-    /** view 离开后工作区仍可补完项目加载；await 前后都检查身份，错误交宿主报告。 */
+    /** view 离开后仍可 resume 已打开项目的背景加载；等待 opening 前后检查 current。
+     * loading.resume 的在途身份/结果围栏由 engine 负责，此方法在其返回后不额外再查 current。
+     * 错误仅在当前身份仍有效时报告 onError，随后原样拒绝；不吞错或清除项目句柄。 */
     async resumeLoading(projectId:Id){
       try{if(!current())throw fault('identity_changed');const opening=projects.get(projectId);if(!opening)throw fault('project_not_open');const engine=await opening;if(!current())throw fault('identity_changed');const result=await engine.loading.resume();if(result.status==='rejected')throw fault(result.code,result.targets);return result;}
       catch(error){if(current()){try{options.onError?.(error);}catch{}}throw error;}
     },
-    /** 幂等/可重试关闭：复用当前 closing Promise，全部 engine 成功后才释放池和 storage。 */
+    /** 先 accepting=false 永久停止此实例新准入，再单飞等待全部在途打开/engine 关闭。
+     * 打开失败视为无需关闭；engine 关闭失败聚合抛错并保留项目/共享池，后续 close 可重试但不重新 accepting。
+     * 项目全成功后才依次同步关闭共享端口；这段不是原子事务，注入端口 close 应可安全重复，抛错也允许重试。
+     * 全部收尾成功才清 projects/置 closed；此接口不证明外部服务或服务器生成任务也已停止。 */
     close() {
       accepting = false; // Fence commands/transports before awaiting pending opens or storage.
       if (closed) return Promise.resolve();

src/lib/canvas-service/assets.ts

@@ -18,13 +18,16 @@ function object(value: unknown): Record<string, unknown> {
   return value as Record<string, unknown>;
 }
 /** 交叉检查冻结请求与元数据载荷：一个上传操作、无canvas写入版本、固定资源身份和原字节属性。
- * 最大原件20MiB；请求body只是可恢复元数据，原始Blob通过上传FormData单独携带。 */
+ * 元数据 byte_length 必须为1字节至20MiB；body 只是固定请求声明，原 Blob 经 FormData 单独携带。
+ * 不改写 request.body，不在这里检查实际 Blob；JSON.parse 等异常沿调用路径处理，不执行文件保存或任务编译。 */
 function payload(request: FrozenRequest) {
   const raw = object(JSON.parse(request.body));
   if (request.kind !== 'asset.upload' || request.protocolVersion !== 2 || raw.protocol_version !== 2 || raw.request_id !== request.id || !uuid.test(request.id) || typeof raw.resource_id !== 'string' || !uuid.test(raw.resource_id) || request.operationIds.length !== 1 || raw.operation_id !== request.operationIds[0] || request.canvasIds.length || Object.keys(request.expectedVersions).length || typeof raw.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(raw.sha256) || typeof raw.byte_length !== 'number' || !Number.isSafeInteger(raw.byte_length) || raw.byte_length < 1 || raw.byte_length > 20 * 1024 * 1024 || typeof raw.name !== 'string' || !raw.name || typeof raw.mime_type !== 'string') throw fault('invalid_asset_request');
   return raw;
 }
-/** 成功状态须匹配协议/请求身份；未知回执仍为 unresolved，普通拒绝也不能证明先前上传未提交。 */
+/** applied 只在2xx+协议/requestId 匹配时成立，捕获完整 JSON 回执，资源字段再由 accept 核对。
+ * 查询404+matching unknown 是可再查的 unresolved；其它4xx 可 blocked，但不能因此制造 not-applied。
+ * 状态解释不解决 ledger 或更新资源，它只返回 scheduler 所需的结果描述。 */
 function status(request: FrozenRequest, response: ServiceResponse, query: boolean): OperationStatus {
   const body = object(response.body), matching = body.protocol_version === 2 && body.request_id === request.id;
   if (matching && body.status === 'applied' && response.status >= 200 && response.status < 300) {
@@ -39,7 +42,9 @@ function status(request: FrozenRequest, response: ServiceResponse, query: boolea
 
 /** Immutable bytes and a preallocated resource ID survive response loss and view changes. */
 /** 校验规范HTTPS源站，构造工作区资源服务与授权域。
- * 上传与查询复用固定身份；本地资源是否保存、任务如何排队由engine负责。 */
+ * 上传与查询复用固定身份；本地文件保存与任务调度由 engine 负责，工厂不自建队列或重试 timer。
+ * origin 只用于规范 sourceURL/authority；实际 HTTP 目的地由 transport 配置，不能据此参数推断 fetch 去向。
+ * options.project/transport 等沿用宿主对象读取合同，应保持配置稳定，不能运行中改 project 破坏授权域/URL 一致性。 */
 export function createFoundryAssets(options: { workspaceId: Id; transport: ServiceTransport; project?: string; origin?: string; displayURL?: (id: Id) => string }): AssetPort {
   if (!uuid.test(options.workspaceId)) throw fault('invalid_service_scope');
   const origin = new URL(options.origin ?? 'https://api.foundry.entroia.com');
@@ -48,19 +53,23 @@ export function createFoundryAssets(options: { workspaceId: Id; transport: Servi
   /** 可持久化的规范原件地址；每段编码，默认项目endoleap，不与宿主代理预览URL混用。 */
   const sourceURL = (id: Id) => `${origin.origin}/projects/${encodeURIComponent(options.project ?? 'endoleap')}/${path}/${encodeURIComponent(id)}`;
   /** 验证已应用回执和本地资源事实一致，包括操作/摘要/长度/规范URL、尺寸和允许MIME。
-   * 限制正整数尺寸及4000万像素，复制并冻结结果后才能登记StoredAsset。 */
+   * 限制正整数尺寸及4000万像素，捕获/冻结 asset 后返回；不在此更新 runtime、清本地原图或写共享仓库。
+   * 接受服务器检测的允许图片 MIME，不要求它与原上传 mimeType 完全相同；实际像素不在此再次解码验证。 */
   const accept = (request: FrozenRequest, result: OperationStatus, resource: ResourceRecord): StoredAsset => {
     const raw = payload(request), receipt = object(result.canonical), asset = object(receipt.asset);
     if (result.outcome !== 'applied' || receipt.protocol_version !== 2 || receipt.request_id !== request.id || receipt.status !== 'applied' || resource.id !== raw.resource_id || resource.operationId !== raw.operation_id || resource.digest !== raw.sha256 || resource.byteLength !== raw.byte_length || asset.id !== resource.id || asset.url !== sourceURL(resource.id) || asset.bytes !== resource.byteLength || typeof asset.width !== 'number' || typeof asset.height !== 'number' || !Number.isSafeInteger(asset.width) || !Number.isSafeInteger(asset.height) || asset.width <= 0 || asset.height <= 0 || asset.width * asset.height > 40_000_000 || !['image/png', 'image/jpeg', 'image/gif', 'image/webp'].includes(asset.mime_type as string)) throw fault('asset_receipt_mismatch');
     return freeze(JSON.parse(JSON.stringify(asset)) as StoredAsset);
   };
-  /** bytes存在走POST上传，否则GET原操作回执；执行错误保留unresolved，不擅自重置资源身份。 */
+  /** 带 bytes 则 POST，否则 GET 原 requestId 回执；只做单次尝试，不换资源/操作/request 身份。
+   * 参数/网络/回执异常按 Error 风格 code 转 unresolved；有明确 code（除 invalid_asset_response）才附 blocked。
+   * signal 传给 transport，不能抢占这里原生 Blob.arrayBuffer/crypto.digest 的执行。 */
   async function execute(request: FrozenRequest, bytes: Blob | undefined, signal: AbortSignal) {
     try {
       const raw = payload(request);
       let body: FormData | undefined;
       if (bytes) {
-        // 上传前再核对真实Blob长度和SHA；这里整体读取ArrayBuffer，受20MiB上传上限，不是流式摘要。
+        // 元数据长度上限已校验，但实际 bytes.size 在整体 arrayBuffer+SHA 后才比对，不是本函数读取前的硬限。
+        // 正常 engine 上传路径先检查实际长度；这里不做流式摘要或内存分块，调用者不能传任意超大 Blob 期待提前拒绝。
         const digest = [...new Uint8Array(await crypto.subtle.digest('SHA-256', await bytes.arrayBuffer()))].map(value => value.toString(16).padStart(2, '0')).join('');
         if (bytes.size !== raw.byte_length || digest !== raw.sha256) throw fault('resource_bytes_mismatch');
         // FormData只携带原图和文件名；幂等请求ID及资源ID通过transport专用头发送。
@@ -75,7 +84,8 @@ export function createFoundryAssets(options: { workspaceId: Id; transport: Servi
   }
   /** 跨项目复用的服务授权端口。resolve读取版本化元数据并核对ID/规范URL，
    * read获取原件字节；字节SHA与授权元数据的一致性由调用它的AssetDepot继续验证。
-   * scope绑定源站/项目/工作区，缓存命中不能替代一次新的领用授权。 */
+   * scope绑定源站/项目/工作区，缓存命中不能替代一次新的领用授权。
+   * resolve 返回冻结元数据，read 返回原字节响应；不在此重新哈希/解码，权限身份与字节预算还依赖 transport 合同。 */
   const authority=Object.freeze({scope:`${origin.origin}/projects/${encodeURIComponent(options.project??'endoleap')}/${path}`,async resolve(id:Id,signal:AbortSignal){if(!uuid.test(id))throw fault('invalid_resource_id');const response=await options.transport({method:'GET',path:`${path}/metadata/${encodeURIComponent(id)}`,signal}),raw=object(response.body);if(response.status!==200)throw fault(typeof raw.error==='string'?raw.error:'asset_authorization_failed');if(raw.metadata_version!==1)throw fault('asset_metadata_interpreter_unavailable');const value={version:1 as const,authority:authority.scope,digest:raw.sha256 as string,asset:raw.asset as StoredAsset};validateSharedAsset(value);if(value.asset.id!==id||value.asset.url!==sourceURL(id))throw fault('asset_authorization_mismatch');return freeze(value);},async read(id:Id,signal:AbortSignal){if(!uuid.test(id))throw fault('invalid_resource_id');const response=await options.transport({method:'GET',path:`${path}/${encodeURIComponent(id)}`,signal,responseFormat:'asset-bytes-v1'});if(response.status!==200||!response.bytes)throw fault('asset_bytes_unavailable');return response.bytes;}});
   // 默认显示地址走同源预览代理；upload/query只委托统一执行器，不复制另一套任务状态。
   return Object.freeze({ authority, sourceURL, displayURL: options.displayURL ?? ((id: Id) => `/api/foundry/${path}/${encodeURIComponent(id)}?variant=preview`), accept,

src/lib/canvas-service/index.ts

@@ -1,6 +1,7 @@
 /**
  * Foundry 服务适配层的公共入口，暴露文档协议、资源服务、生成任务和模型加载器。
  * 这些模块解释服务端数据与请求，不拥有 editor 状态根、history 或调度队列。
+ * 此入口只重导出工厂/类型，不自动连接服务、请求模型或创建 project；宿主负责注入 transport 和生命周期。
  */
 // 底层 transport 与文档增量协议；资源上传和生成各有独立适配器。
 export * from './foundry.ts';

src/lib/canvas-service/model-loader.ts

@@ -10,13 +10,16 @@ import { loadQueryKey, type LoadPort } from '../canvas-runtime/loader.ts';
 import { loadFoundryModel, type ServiceTransport } from './foundry.ts';
 
 /** Negotiate real streaming; older servers may explicitly return complete JSON. */
-/** 绑定工作区和 registry，返回异步分块源；只接受 Foundry canonical-project 查询范围。 */
+/** 创建惰性异步生成器端口；开始迭代才请求，匹配 workspace/format/source/viewKey 后读取 scope.canvasId 的项目模型。
+ * scope/options 按不可变合同借用；authEpoch/queryKey 标记来自宿主 scope，不能代替 transport 的账号/权限检查。
+ * 同一次响应二选一解释 stream 或 JSON，不建立缓存/共享在途任务；这些由 runtime ScopedLoader 持有。 */
 export function createFoundryModelLoader(options: { workspaceId: Id; registry: Registry; transport: ServiceTransport }): LoadPort<CanonicalReadUpdate> {
   return async function* (scope, signal) {
     // query scope 是缓存/权限隔离依据，不能用某工作区的 transport 为另一种查询来源提供结果。
     if (scope.workspaceId !== options.workspaceId || scope.format !== 'canonical-model-v1' || scope.source !== 'foundry' || scope.viewKey !== 'canonical-project') throw fault('invalid_model_load_scope');
     const response=await options.transport({method:'GET',path:`workspaces/${encodeURIComponent(options.workspaceId)}/materials/${encodeURIComponent(scope.canvasId)}/canvas/model`,signal,responseFormat:'model-stream-v1'});
-    // 流解析器控制序列、来源 token 和 EOF；适配器再补权限代次与 queryKey，供共享 loader 拒绝过期结果。
+    // 若 response.stream 存在即进入流路径（须200），解析失败不再偷偷改用 body 或发第二次请求。
+    // decoder 控序列/token/EOF，适配器逐块补 scope.authEpoch/queryKey 和 versions 外壳，供上层做迟到结果准入。
     if(response.stream){
       if(response.status!==200)throw fault('invalid_model_stream');
       for await(const chunk of decodeModelStream(response.stream,scope.canvasId,options.registry,signal))yield Object.freeze({...chunk,serverVersions:Object.freeze(Object.fromEntries(chunk.versions)),permissionEpoch:scope.authEpoch,queryKey:loadQueryKey(scope)});
@@ -26,14 +29,15 @@ export function createFoundryModelLoader(options: { workspaceId: Id; registry: R
     const value = await loadFoundryModel(async()=>response, options.workspaceId, scope.canvasId, options.registry, signal);
     signal.throwIfAborted();
     const projectId = value.status === 'ready' ? value.document.projectId : value.rootId;
-    // 对版本排序以稳定完整 JSON 回退的快照标记；这是结果身份，不是原响应字节的密码学摘要。
+    // 对版本排序后用 [projectId,versions] 生成 token，不包含元素内容，不能把它当成源字节摘要/真实性证明。
     const versions = Object.fromEntries([...(value.status === 'ready' ? value.versions : value.sourceVersions)].sort(([a], [b]) => a.localeCompare(b)));
     const token = JSON.stringify([projectId, versions]);
     const payload = value.status === 'ready' ? { projectId, canvases: [...value.document.canvases.values()], elements: [...value.document.elements.values()], tombstones: [...value.document.tombstones], versions } : { projectId, versions, migrationRequired: true };
     // A serialized payload cost, not a claim about pre-parse network/heap limits.
     // byteLength 是已解析后重新序列化的 payload 成本，不能据此宣称 JSON.parse 前已有网络/堆内存硬上限。
     const byteLength = new TextEncoder().encode(JSON.stringify(payload)).byteLength;
-    // 完整 JSON 一次给出 complete；迁移结果使用 migration 覆盖标记，不伪造已加载 canvas 内容。
+    // JSON 完整结果一次 sequence=0/complete=true；迁移要求用 migration coverage 标记，仍保留其区别于 ready 的状态。
+    // 本端口不把内容发布进 editor，消费者还需模型预览/加载协调以及作用域检查。
     yield Object.freeze({ queryKey: loadQueryKey(scope), projectId, snapshotToken: token, serverVersions: Object.freeze(versions), permissionEpoch: scope.authEpoch,
       sequence: 0, coverage: Object.freeze(value.status === 'ready' ? [...value.document.canvases.keys()].map(id => `canvas:${id}`) : [`migration:${scope.canvasId}`]), complete: true, byteLength, value });
   };

src/lib/canvas-service/model-stream.ts

@@ -18,7 +18,9 @@ const uuid=/^[a-f\d]{8}-[a-f\d]{4}-[a-f\d]{4}-[a-f\d]{4}-[a-f\d]{12}$/i;
 /** 外部记录必须是有限 JSON 对象，拒绝数组和非 JSON 值，不靠类型断言信任网络内容。 */
 const object=(value:unknown):Record<string,unknown>=>{if(!value||typeof value!=='object'||Array.isArray(value)||!validJson(value))throw fault('invalid_model_stream');return value as Record<string,unknown>;};
 /** Bounded NDJSON framing. EOF is required even after a terminal record. */
-/** 有界 UTF-8 NDJSON 分帧。按字节找换行，fatal 解码拒绝损坏编码，最后一条也要求换行结束。 */
+/** 按 LF 分帧，UTF8 decoder 跨 chunk 保留残字节，每行换行时 flush，最后一条也必须以 LF 结束。
+ * 单行预算不计 LF（CRLF 的 CR 仍计入），输出 byteLength 则含 LF；计整 chunk 后才逐行解析。
+ * 同步扫描/字符串拼接/JSON.parse 无合作调度；预算约束原始字节和行数，不代表整个进程堆内存硬限。 */
 async function* lines(source:AsyncIterable<Uint8Array>,signal:AbortSignal){
  const decoder=new TextDecoder('utf-8',{fatal:true});
  /** 统一把解码错误转为协议错误，保持错误码不依赖浏览器具体异常文本。 */
@@ -41,14 +43,17 @@ async function* lines(source:AsyncIterable<Uint8Array>,signal:AbortSignal){
  signal.throwIfAborted();pending+=decode();if(pending||lineBytes)throw fault('incomplete_model_stream');
 }
 /** 解释一条固定快照流。sequence 从0连续增长，snapshotToken 全程相同；
- * header/元素批次可先 yield，终结结果暂存到 EOF，之后多一条记录也判非法。 */
+ * header/元素批次可先 yield，complete 暂存到真正 EOF，之后多一条记录也判非法。
+ * receiving 只校验该阶段可确定的 ID/owner/数量等条件，完整 schema/图引用在终结时再验证。
+ * 消费者须迭代到终结才能得到 ready；放弃迭代不等于源已完整，signal 也不能强制打断不响应取消的 source.next。 */
 export async function* decodeModelStream(source:AsyncIterable<Uint8Array>,canvasId:Id,registry:Registry,signal:AbortSignal){
  let sequence=0,token='',projectId='',expected=0,ended=false;
  // terminal 暂存而不立即 yield，保证 complete 之后的恶意/错误尾部仍能阻止 ready。
  let terminal: {sequence:number;snapshotToken:string;projectId:string;versions:ReadonlyMap<Id,number>;complete:boolean;byteLength:number;coverage:string[];value:CanonicalReadUpdate}|undefined;
  let canvases:CanvasRecord[]=[],versions:ReadonlyMap<Id,number>=new Map(),tombstones:ReadonlyMap<Id,number>=new Map();
  let elementOwners:ElementOwners|undefined;let canvasElementCounts:CanvasElementCounts|undefined;const ownerCounts=new Map<Id,number>();
- // 元素累积用于最终构建文档；流式显示不等于恒定内存，完整模型仍需保存在最终文档中。
+ // elements 累积全部记录，ids 去重，ownerCounts 累计接收归属；这些是本次读取的私有暂存，不是已发布文档。
+ // receiving 分批显示只减重复传播，不使总内存恒定；已 yield 的前缀也不会因后续报错自动回滚消费者状态。
  const elements:ElementRecord[]=[],ids=new Set<Id>(),canvasIds=new Set<Id>();
  for await(const line of lines(source,signal)){
   const raw=object(line.raw);
@@ -66,7 +71,8 @@ export async function* decodeModelStream(source:AsyncIterable<Uint8Array>,canvas
    if(!Array.isArray(raw.removedCanvasIds)||new Set(raw.removedCanvasIds).size!==raw.removedCanvasIds.length||raw.removedCanvasIds.some(id=>typeof id!=='string'||canvasIds.has(id)||!versionMap.has(id))||versionMap.size!==canvasIds.size+raw.removedCanvasIds.length)throw fault('invalid_model_stream');
    for(const [id,value]of Object.entries(object(raw.tombstones))){if(!id||!Number.isSafeInteger(value)||(value as number)<1)throw fault('invalid_model_stream');dead.set(id,value as number);}
    versions=readMap(versionMap);tombstones=readMap(dead);
-   // 数量/所有权证据是可选协议能力；elementOwners 依赖 counts，必须与总数及各 canvas 数量匹配。
+   // 可选 counts/owners 先查声明内部一致性；owners 必须配 counts，声明不代替后续实际记录的数量/归属核验。
+   // header 的 canvas 记录此时尚未用完整文档校验树；预览层若要采用必须继续执行自己的阶段校验。
    if(Object.hasOwn(raw,'canvasElementCounts')){validateCanvasElementCounts(raw.canvasElementCounts,[...canvasIds],expected);canvasElementCounts=freeze({...raw.canvasElementCounts});}
    if(Object.hasOwn(raw,'elementOwners')){if(!canvasElementCounts)throw fault('invalid_model_identity');validateElementOwners(raw.elementOwners,canvasElementCounts,expected);elementOwners=freeze({...raw.elementOwners});}
    const value:CanonicalReadUpdate=freeze({status:'receiving',...(elementOwners?{elementOwners}:{}),...(canvasElementCounts?{canvasElementCounts}:{}),projectId,canvases,elements:[],tombstones,versions,receivedElements:0,totalElements:expected});
@@ -78,10 +84,12 @@ export async function* decodeModelStream(source:AsyncIterable<Uint8Array>,canvas
   if(raw.kind==='elements'){
    if(!Array.isArray(raw.elements)||!raw.elements.length||raw.elements.length>64||elements.length+raw.elements.length>expected)throw fault('invalid_model_stream');
    for(const item of raw.elements){const element=object(item) as unknown as ElementRecord;if(typeof element.id!=='string'||!element.id||ids.has(element.id)||!canvasIds.has(element.ownerCanvasId))throw fault('invalid_model_stream');const count=(ownerCounts.get(element.ownerCanvasId)??0)+1;if(canvasElementCounts&&count>canvasElementCounts[element.ownerCanvasId])throw fault('invalid_model_coverage');ownerCounts.set(element.ownerCanvasId,count);if(elementOwners&&(!Object.hasOwn(elementOwners,element.id)||elementOwners[element.id]!==element.ownerCanvasId))throw fault('invalid_model_identity');ids.add(element.id);elements.push(element);}
-   // 后续 receiving 只交本批新增元素，不重复传播整份前缀；保留累计进度供显示。
+   // receiving 只交本批新记录，canvases/墓碑留空，versions 与总数沿用 header；receivedElements 是累计接收数。
+   // 冻结这个 DTO 不是整批导入提交/可靠保存/所有端点已到齐的证明，显示层继续按依赖门禁采用。
    const value:CanonicalReadUpdate=freeze({status:'receiving',projectId,canvases:[],elements:raw.elements as ElementRecord[],tombstones:readMap(new Map()),versions,receivedElements:elements.length,totalElements:expected});
    yield{sequence:sequence-1,snapshotToken:token,projectId,versions,complete:false,byteLength:line.byteLength,coverage:raw.elements.map(item=>`element:${(item as ElementRecord).id}`),value};
-  // 总元素数一致才构建并校验完整文档；只在校验成功后设 ended，随后必须等 EOF。
+  // complete 数量匹配后 createDocument 捕获全部记录、validateDocument 校树/归属/引用及已知 schema。
+  // terminal 只存候选；ended 后任何记录都拒绝，直到 lines 正常 EOF 才 yield 这份 ready。
   }else if(raw.kind==='complete'){
    if(raw.elementCount!==expected||elements.length!==expected)throw fault('incomplete_model_stream');
    const document=createDocument(projectId,canvases,elements,tombstones);validateDocument(document,registry);ended=true;

src/lib/canvas-service/runs.ts

@@ -2,6 +2,7 @@
  * Foundry生成任务协议适配。启动受理、执行事件、取消和用户应用输出是不同阶段，分别验证身份与作用范围。
  * 受理成功映射为请求applied，只代表启动动作已经生效，不代表付费生成已经完成。
  * 原请求/原计划/目标代次贯穿事件追尾，模型结果仅作为ACK提案交回runtime协调。
+ * 端口不保存 RunRecord、游标或 timer；compile/accept/canonical 同步计算，网络只在 submit/query/catalog/poll 中委托 transport。
  */
 import type { Id, Json, Registry, RunInput } from '../canvas-core/types.ts';
 import { equal, fault, freeze, readMap, validJson } from '../canvas-core/values.ts';
@@ -25,7 +26,8 @@ const string = (value: unknown): string => { if (typeof value !== 'string' || !v
 const integer = (value: unknown, min=0): number => { if (typeof value!=='number'||!Number.isSafeInteger(value)||value<min)throw fault('invalid_run_response');return value; };
 
 /** 校验冻结请求的协议、owner、单操作覆盖及载荷；cancel无文档版本，
- * apply只写目标画布，start则包含生成输入上下文的预期版本，并复用输入大小校验。 */
+ * apply只写目标画布，start则包含生成输入上下文的预期版本，并复用输入大小校验。
+ * 解析原 FrozenRequest.body 仅为核验，不重写已冻结字符串；协议版本与单操作覆盖不等于服务已经执行。 */
 function payload(request: FrozenRequest) {
   const raw=object(JSON.parse(request.body));
   if(!request.ownerCanvasId||!uuid.test(request.ownerCanvasId)||!['run.start','run.cancel','run.apply'].includes(request.kind??'')||request.protocolVersion!==2||!uuid.test(request.id)||raw.protocol_version!==2||raw.request_id!==request.id||request.operationIds.length!==1||raw.operation_id!==request.operationIds[0]||!uuid.test(string(raw.operation_id)))throw fault('invalid_run_request');
@@ -44,7 +46,8 @@ function payload(request: FrozenRequest) {
   }
   return raw;
 }
-/** 检查计划步骤非空、step_id唯一、同一根项目及有效目标代次/画布；不在客户端重新规划执行DAG。 */
+/** 校验非空 steps、唯一 step_id、共同 canonical_root、board UUID 与目标 ID/正代次，保留原步骤对象。
+ * 不重建 DAG、不验证模型目录或依赖是否可执行，也不证明整个 plan 所有扩展字段语义。 */
 function planSteps(plan: unknown, rootId: Id) {
   const steps=array(object(plan).steps).map(object),ids=new Set<string>();
   for(const step of steps){const id=string(step.step_id);if(ids.has(id)||step.canonical_root!==rootId||!uuid.test(string(step.board_id)))throw fault('run_identity_mismatch');ids.add(id);string(step.node_id);integer(step.target_incarnation,1);}
@@ -52,13 +55,16 @@ function planSteps(plan: unknown, rootId: Id) {
 }
 
 /** Admission completion is distinct from paid execution completion. Credentials remain in the transport. */
-/** 为一个根项目提供模型目录、请求编译/结果查询、受理回执和事件读取的RunPort。 */
+/** 绑定 workspace/root/registry/transport，返回无任务私有状态的 RunPort，身份/取消与 I/O 预算由 transport 执行。
+ * options 借用而非深捕获，宿主应保持服务配置稳定；工厂不开始轮询、读取目录或产生付费任务。 */
 export function createFoundryRuns(options: {workspaceId: Id; rootId: Id; registry: Registry; transport: ServiceTransport}): RunPort {
   if(!uuid.test(options.workspaceId)||!uuid.test(options.rootId))throw fault('invalid_service_scope');
   /** 所有任务端点以其入口画布定位，即使输出目标后来移到另一canvas也保留原run所属board。 */
   const path=(board: Id)=>`workspaces/${encodeURIComponent(options.workspaceId)}/materials/${encodeURIComponent(board)}/canvas/ai`;
   /** 验证启动受理：请求/操作/目标代次、queued任务ID、owner版本+1及冻结计划均匹配。
-   * frozen_versions仅列实际读入计划的快照；启动预期版本向量则覆盖所有活动canvas。 */
+   * 请求 expectedVersions 覆盖活动 canvas，plan.frozen_versions 可只列实际读取的子集，但必须含 owner 与每个步骤 board。
+   * owner 冻结版本为请求基线+1，其它列出的版本仍等于原请求基线；不要求计划读遍全部 canvas。
+   * 返回 queued/cursor=0 的 admission 与 owner 局部模型证明，不更新根、不将受理成功当成生成输出完成。 */
   function admissionReceipt(request:FrozenRequest,receipt:Json){
     const raw=payload(request),body=object(receipt),runId=string(body.run_id),board=request.ownerCanvasId!;
     if(request.kind!=='run.start'||body.protocol_version!==2||body.request_id!==request.id||body.operation_id!==raw.operation_id||body.admission!=='accepted'||body.action!==undefined&&body.action!=='run.start'||body.status!=='queued'||!uuid.test(runId)||body.target_incarnation!==raw.target_incarnation||body.document_format_version!==1||body.canvas_version!==request.expectedVersions[board]+1)throw fault('run_identity_mismatch');
@@ -72,7 +78,9 @@ export function createFoundryRuns(options: {workspaceId: Id; rootId: Id; registr
     const admission:RunRecord=freeze({id:runId,requestId:request.id,operationId:request.operationIds[0],boardId:board,target:{id:raw.node_id as Id,incarnation:raw.target_incarnation as number},plan:body.plan as Json,status:'queued',cursor:0,hasMore:true,steps:[],outputs:[],outputEvents:[],attempt:0});
     return{model,admission,rawModel:body.model};
   }
-  /** 验证控制动作回执。cancel只返回任务状态与空文档证明；apply还需目标输出/代次及画布版本+1。 */
+  /** 校验同 request/operation/run/action；cancel 验 run_status 并返回空版本/no-op 文档证明，后续还须读尾页。
+   * apply 再核 node/output/targetCanvas/incarnation、目标版本恰好基线+1；不以本地乐观内容替代服务证明。
+   * 完整上下文响应先裁成目标 canvas 局部证明，清 tombstones/removedCanvasIds，不声称本动作可改写其它画布。 */
   function actionReceipt(request:FrozenRequest,receipt:Json){
     const raw=payload(request),body=object(receipt);
     if(!request.runId||body.protocol_version!==2||body.request_id!==request.id||body.operation_id!==request.operationIds[0]||body.run_id!==request.runId||body.action!==request.kind||body.status!=='applied')throw fault('run_identity_mismatch');
@@ -90,7 +98,9 @@ export function createFoundryRuns(options: {workspaceId: Id; rootId: Id; registr
     return{action:{runId:request.runId,outputId:raw.output_id as Id},model,rawModel:scoped};
   }
   /** submit/query共用解释路径，查询始终用原requestId。终结not-applied须完整匹配动作身份，
-   * unknown/传输异常保持不确定；启动的accepted仅结清受理动作，执行完成另看事件页。 */
+   * unknown/传输异常保持不确定；启动 accepted 仅结清受理动作，执行完成另看事件页。
+   * terminal not-applied 分支按完整证据匹配，不另要求2xx；普通错误/404不能伪造同等确定性。
+   * 这是粗分类：applied 控制回执仍须 actionReceipt 校 runId/输出/模型；不会在 execute 直接解决 ledger。 */
   async function execute(request: FrozenRequest,query: boolean,signal: AbortSignal): Promise<OperationStatus> {
     try{
       const raw=payload(request),suffix=request.kind==='run.start'?'runs':`runs/${encodeURIComponent(request.runId!)}/${request.kind==='run.cancel'?'cancel':'apply'}`;
@@ -106,7 +116,8 @@ export function createFoundryRuns(options: {workspaceId: Id; rootId: Id; registr
     }catch(error){const code=(error as {code?:string}).code;return{outcome:'unresolved',error:code??'ai_transport_unknown',...(code?{blocked:true}:{})};}
   }
   return Object.freeze({
-    /** 读取可用模型与输入/输出模态，验证字段形状并复制结果；不把目录读取当成启动生成。 */
+    /** GET 目录后逐项校 id/模态数组/available/JSON，捕获并冻结；其它 JSON 扩展字段保留。
+     * 不去重 model.id、不缓存目录或证明随后启动仍可用；目录读取本身不受理生成任务。 */
     async catalog(boardId,signal){
       if(!uuid.test(boardId))throw fault('invalid_service_scope');
       const response=await options.transport({responseFormat:'canvas-v2',method:'GET',path:`${path(boardId)}/models`,signal}),body=object(response.body);
@@ -114,7 +125,9 @@ export function createFoundryRuns(options: {workspaceId: Id; rootId: Id; registr
       const models=array(body.models).map(value=>{const model=object(value);string(model.id);for(const key of ['output_modalities','input_modalities'])for(const modality of array(model[key]))string(modality);if(typeof model.available!=='boolean'||!validJson(model))throw fault('invalid_run_response');return JSON.parse(JSON.stringify(model)) as RunModel;});
       return freeze({models,...(typeof body.unavailable_reason==='string'?{unavailableReason:body.unavailable_reason}:{})});
     },
-    /** 从逻辑意图及当前ACK编译请求；不发送网络，也不用尚未确认的working目标替代服务端基线。 */
+    /** 以意图与当前 ACK 编译 payload/参与者/expectedVersions，不发送网络、不在此 JSON.stringify 冻结 body。
+     * cancel 沿原 run 入口且无版本写入，apply 用 ACK 目标 owner/代次，start 用 ACK 完整活动 canvas 向量。
+     * 返回对象可冻结但不是 durable 请求；requestId 与后续冻结/保存/发送由 scheduler 管理。 */
     compile(intent,requestId,snapshot){
       if(intent.operationType==='run.cancel'||intent.operationType==='run.apply'){
         const action=intent.action,run=snapshot.runtime.runs.get(action.runId);
@@ -140,7 +153,8 @@ export function createFoundryRuns(options: {workspaceId: Id; rootId: Id; registr
     },
     // 请求完成与服务端任务执行分离：提交/查询后，accept再核对受理或控制语义。
     submit:(request,signal)=>execute(request,false,signal),query:(request,signal)=>execute(request,true,signal),
-    /** 恢复路径也使用相同回执解释器，生成可对照fresh权威模型的证明。 */
+    /** 历史 applied 恢复也走相同 admission/action 解释器，返回可与 fresh 模型比对的证明。
+     * 不读取服务、不把该证明自动采纳到 Root；缺证据/版本不符仍由解释器拒绝。 */
     verifyApplied(request,receipt){return request.kind==='run.start'?admissionReceipt(request,receipt):actionReceipt(request,receipt);},
     /** 受理回执转为RunRecord与owner ACK候选，实际根发布/本地重放交给engine。 */
     accept(request,status,snapshot){
@@ -154,8 +168,9 @@ export function createFoundryRuns(options: {workspaceId: Id; rootId: Id; registr
       const parsed=actionReceipt(request,status.canonical);
       return{...parsed.action,...(parsed.rawModel?{proposal:mergeFoundryModel(parsed.rawModel,request.canvasIds,snapshot,options.registry,options.rootId)}:{})};
     },
-    /** 从保存游标之后读取最多100条有序事件。验证任务/固定计划、连续seq及迁移后的目标上下文，
-     * 只返回一页数据，不在适配器推进持久游标；runtime协调成功才与文档一起发布next。 */
+    /** 用 after_seq=run.cursor/limit=100 读取一页，核相同 run_id/plan、连续 seq 与 next_seq，不推进持久游标。
+     * step.applied/output 须属于计划步骤；applied 与跨 board 输出额外核目标代次/迁移上下文，普通扩展事件仅保留 JSON。
+     * 实际100项限制在响应解析后检查，不是传输字节/解析内存上限；runtime 协调成功才将 next 与文档同根发布。 */
     async poll(run,signal){
       const response=await options.transport({responseFormat:'canvas-v2',method:'GET',path:`${path(run.boardId)}/runs/${encodeURIComponent(run.id)}?after_seq=${run.cursor}&limit=100`,signal}),body=object(response.body);
       if(response.status!==200)throw fault(response.status===404?'run_receipt_expired':typeof body.error==='string'?body.error:'run_poll_failed');
@@ -175,10 +190,13 @@ export function createFoundryRuns(options: {workspaceId: Id; rootId: Id; registr
       }
       // next必须恰为最后事件序号；hasMore却没有任何事件会造成空转，作为非法响应拒绝。
       if(integer(body.next_seq)!==cursor||events.length>100||body.has_more&&events.length===0)throw fault('invalid_run_response');
+      // events 重新 JSON 捕获；outputs/steps 沿用已验证 body 的数组并冻结，不从它们直接生成本地编辑。
       return freeze({status:body.status as RunStatus,events:JSON.parse(JSON.stringify(events)) as RunEvent[],next:cursor,hasMore:body.has_more,outputs:array(body.outputs) as Json[],steps:array(body.steps) as Json[],...(typeof body.error==='string'?{error:body.error}:{})});
     },
     /** 解释可合图事件：目标代次必须仍有效，局部结果只能改本owner，完整结果才允许跨分区归属变化。
-     * 合并后再检查事件目标的owner/代次和版本，防止合法外壳里夹带另一目标的模型。 */
+     * 读取当前 ACK 目标：局部模型须仍在该 board，complete 上下文才允许变 owner，且共同根必须匹配。
+     * 调用合并 helper 后再核提案目标 owner/代次与事件 canvas_version；不在这里更新 working、history 或事件游标。
+     * 不重新核事件属于哪个 RunRecord/计划，依赖前置 poll 与 engine 的 run/request/controlEpoch 栅栏。 */
     canonical(event,snapshot){
       const board=string(event.board_id),version=integer(event.canvas_version,1),current=snapshot.runtime.acknowledged.elements.get(string(event.node_id));
       const context=object(event.model).complete===true;