/** * 可暂停/恢复的深复制准备状态机。检查点保存 ID、阶段、游标、DFS stack 和稳定映射, * 不保存元素 payload 的第二份副本;输出记录是由源与映射确定性重建的缓存。 * 每次 step 只推进有限语义工作,但持久源校验、分片调度、checkpoint 保存和渐进加入由 runtime 负责。 */ import {detachJsonData} from './json-data.ts'; import type { CanvasRecord, Change, Document, ElementRecord, Id, Point, Registry, Target } from './types.ts'; import { ancestors, targetElement, validateDocumentSteps, validateDocumentTopologySteps } from './document.ts'; import { duplicateTreeChange, duplicateEdgeChange, duplicateOverlay, type DuplicateOptions, type DuplicatePlan } from './duplicate.ts'; import { clone, equal, fault, freeze, validJson } from './values.ts'; /** 准备流程:选区→索引→根→DFS范围→边→ID分配→映射检查→记录生成→最终校验。 */ const phases=['selection','canvases','members','roots','seed','dfs','edges','allocate-elements','allocate-canvases','mapping','emit','emit-edges','validate','done'] as const; /** DFS/order 项只存 kind+源 ID,恢复时从绑定的源文档取记录,避免双份数据漂移。 */ type Task={kind:'element'|'canvas';id:Id}; /** Internal preparation state: IDs/cursors only. Emitted records are a deterministic derived cache. */ /** 运行中可变 DTO;version=1 是本检查点解释器版本,不是 ImportJob/文档/wire 版本。 * emitted/emittedEdges 是已生成前缀长度,不能当作已加入或已同步元素数量。 */ type MutableCheckpoint={version:1;projectId:Id;sourceToken:string;schemaToken:string;selection:Target[];offset:Point;mapping?:DuplicateOptions['mapping'];phase:typeof phases[number];cursor:number;steps:number;selected:Id[];children:[Id,Id][];members:[Id,Id[]][];roots:Id[];copied:Id[];canvases:Id[];order:Task[];work:Task[];expanding?:{canvas:Id;index:number};edges:Id[];elementIds:[Id,Id][];canvasIds:[Id,Id][];emitted:number;emittedEdges:number}; /** 对检查点结构递归加 readonly;真正外发时 checkpoint() 仍要复制并冻结。 */ type Immutable=T extends object?{readonly [K in keyof T]:Immutable}:T; /** 对外只读检查点合同,可编码为 JSON,由 runtime 与源/任务事实一同持久化。 */ export type DuplicateCheckpoint=Immutable; /** 形状辅助检查:数组成员必须是非空字符串;是否存在/重复由后续检查负责。 */ const ids=(value:unknown):value is Id[]=>Array.isArray(value)&&value.every(id=>typeof id==='string'&&!!id); /** 校验外部检查点格式、阶段/计数/去重与前缀边界;与实际源的一致性在工厂中进一步核验。 */ export function validateDuplicateCheckpoint(value:DuplicateCheckpoint):void{ if(!value||!validJson(value)||value.version!==1)throw fault('copy_checkpoint_interpreter_unavailable'); if(![value.projectId,value.sourceToken,value.schemaToken].every(id=>typeof id==='string'&&!!id)||!phases.includes(value.phase)||!Number.isSafeInteger(value.cursor)||value.cursor<(value.phase==='seed'?-1:0)||![value.steps,value.emitted,value.emittedEdges].every(n=>Number.isSafeInteger(n)&&n>=0)||!Array.isArray(value.selection)||!value.selection.length||value.selection.some(t=>!t||typeof t.id!=='string'||!t.id||!Number.isSafeInteger(t.incarnation)||t.incarnation<1)||!value.offset||![value.offset.x,value.offset.y].every(Number.isFinite))throw fault('invalid_copy_checkpoint'); for(const list of [value.selected,value.roots,value.copied,value.canvases,value.edges])if(!ids(list)||new Set(list).size!==list.length)throw fault('invalid_copy_checkpoint'); for(const list of [value.order,value.work])if(!Array.isArray(list)||list.some(t=>!t||!['element','canvas'].includes(t.kind)||typeof t.id!=='string'||!t.id))throw fault('invalid_copy_checkpoint'); // 元组映射的源键唯一,任务 stack 可有待去重项;不能错误地对所有数组一律去重。 for(const list of [value.children,value.elementIds,value.canvasIds])if(!Array.isArray(list)||list.some(pair=>!ids(pair)||pair.length!==2)||new Set(list.map(pair=>pair[0])).size!==list.length)throw fault('invalid_copy_checkpoint'); if(!Array.isArray(value.members)||value.members.some(pair=>!Array.isArray(pair)||pair.length!==2||typeof pair[0]!=='string'||!pair[0]||!ids(pair[1]))||new Set(value.members.map(pair=>pair[0])).size!==value.members.length||value.emitted>value.order.length||value.emittedEdges>value.edges.length||value.emittedEdges>0&&value.emitted!==value.order.length||value.expanding&&(typeof value.expanding.canvas!=='string'||!value.expanding.canvas||!Number.isSafeInteger(value.expanding.index)||value.expanding.index< -1))throw fault('invalid_copy_checkpoint'); } /** 创建或恢复解释器;绑定 project/sourceToken/schemaToken/选区/偏移/预留映射,任一不符拒绝续跑。 * token 的真实源摘要/定义签名由调用方提供并验证,这里不读取 Blob 或计算 SHA。 */ export function createDuplicatePlanner(document:Document,registry:Registry,selection:readonly Target[],options:DuplicateOptions,binding:{sourceToken:string;schemaToken:string;checkpoint?:DuplicateCheckpoint;topologyOnly?:boolean}){ const offset=options.worldOffset??{x:32,y:32},idFactory=options.createId,suppliedMapping=options.mapping?freeze(clone(options.mapping)):undefined; // 从检查点复制出私有可变 state,旧 checkpoint 保持不变;新任务从 selection 开始。 const state:MutableCheckpoint=binding.checkpoint?clone(binding.checkpoint) as MutableCheckpoint:{version:1,projectId:document.projectId,sourceToken:binding.sourceToken,schemaToken:binding.schemaToken,selection:clone(selection) as Target[],offset:clone(offset),...(suppliedMapping?{mapping:suppliedMapping}:{}),phase:'selection',cursor:0,steps:0,selected:[],children:[],members:[],roots:[],copied:[],canvases:[],order:[],work:[],edges:[],elementIds:[],canvasIds:[],emitted:0,emittedEdges:0}; validateDuplicateCheckpoint(state); if(state.projectId!==document.projectId||state.sourceToken!==binding.sourceToken||state.schemaToken!==binding.schemaToken||!equal(state.selection,selection)||!equal(state.offset,offset)||!equal(state.mapping,suppliedMapping))throw fault('copy_checkpoint_binding_mismatch'); // 从序列化数组重建 Map/Set 查找结构;源有序数组也重建,但不重分配已保存的新 ID。 const sourceElements=[...document.elements.values()],sourceCanvases=[...document.canvases.values()],selected=new Set(state.selected),copied=new Set(state.copied),canvases=new Set(state.canvases),children=new Map(state.children),members=new Map(state.members),elementIds=new Map(state.elementIds),canvasIds=new Map(state.canvasIds),used=new Set([...document.elements.keys(),...document.canvases.keys(),...document.tombstones.keys()]); // 逐项核对源成员、父入口、owner、映射范围与新 ID 冲突,不能只相信 DTO 形状。 for(const id of [...state.selected,...state.roots,...state.copied,...state.edges])if(!document.elements.has(id))throw fault('invalid_copy_checkpoint'); for(const id of state.canvases)if(!document.canvases.has(id))throw fault('invalid_copy_checkpoint'); for(const [entry,id]of children)if(document.canvases.get(id)?.parent?.entryElementId!==entry)throw fault('invalid_copy_checkpoint'); for(const [owner,list]of members)for(const id of list)if(document.elements.get(id)?.ownerCanvasId!==owner)throw fault('invalid_copy_checkpoint'); for(const [list,scope]of [[state.elementIds,copied],[state.canvasIds,canvases]] as const)for(const [id,mapped]of list){if(!scope.has(id)||used.has(mapped))throw fault('invalid_copy_checkpoint');used.add(mapped);} for(const task of [...state.order,...state.work])if(!(task.kind==='element'?document.elements:document.canvases).has(task.id))throw fault('invalid_copy_checkpoint'); // 进入 emit 前必须已分配整个范围的映射,转换引用时不能边输出边猜后续 ID。 if(phases.indexOf(state.phase)>=phases.indexOf('emit')&&(elementIds.size!==copied.size||canvasIds.size!==canvases.size))throw fault('invalid_copy_checkpoint'); // 按当前阶段的真实源长度检查 cursor;seed 特殊地允许 -1 表示压栈结束。 const limits:Partial>={selection:state.selection.length,canvases:sourceCanvases.length,members:sourceElements.length,roots:state.selected.length,seed:state.roots.length,edges:sourceElements.length,'allocate-elements':state.copied.length,'allocate-canvases':state.canvases.length};if(limits[state.phase]!==undefined&&state.cursor>limits[state.phase]!)throw fault('invalid_copy_checkpoint'); const supplied=suppliedMapping?[...Object.keys(suppliedMapping.elements).map(id=>({id,kind:'element' as const})),...Object.keys(suppliedMapping.canvases).map(id=>({id,kind:'canvas' as const}))]:[]; // 这些 Map 是派生输出缓存,overlay 内部可读其增长,不作为第二份发布文档。 const outputElements=new Map(),outputCanvases=new Map(),output=duplicateOverlay(document,outputElements,outputCanvases),changes:Change[]=[]; // 源校验每次重开重新执行;topologyOnly 仅用于明确的结构源,最终输出仍执行完整数据校验。 let treeCache=0,edgeCache=0,sourceChecks:Generator|undefined=(binding.topologyOnly?validateDocumentTopologySteps:validateDocumentSteps)(document,registry),outputChecks:Generator|undefined,validated=false; /** 切换解释阶段并重置/指定该阶段 cursor,不改稳定 ID 或输出前缀。 */ const phase=(next:DuplicateCheckpoint['phase'],cursor=0)=>{state.phase=next;state.cursor=cursor;}; /** 冻结生成记录,追加 changes 并登记到临时输出表,使后续边可读取新端点/owner。 */ function add(change:Exclude){freeze(change);changes.push(change);if(change.kind==='element')outputElements.set(change.id,change.after!);else outputCanvases.set(change.id,change.after!);} /** 由 order 的源 ID 调用共享节点/canvas 转换器,恢复时同样可重建已输出前缀。 */ function tree(index:number){const task=state.order[index];add(duplicateTreeChange(document,registry,task.kind,(task.kind==='element'?document.elements:document.canvases).get(task.id)!,elementIds,canvasIds,canvases,state.offset));} /** 仅在节点/canvas 输出后转换边,保证新端点和其所属树已可供查询。 */ function edge(index:number){add(duplicateEdgeChange(document,registry,document.elements.get(state.edges[index])!,elementIds,canvasIds,output));} /** 只为尚未分配的源项取新 ID;优先宿主预留值,used 同时覆盖源、墓碑与全部新值。 */ function allocate(id:Id,kind:'elements'|'canvases'){const map=suppliedMapping?.[kind],value=map&&Object.hasOwn(map,id)?map[id]:idFactory();if(typeof value!=='string'||!value||used.has(value))throw fault('duplicate_identity',[value]);used.add(value);return value;} return Object.freeze({ /** 源已校验且刚到 emit,范围/映射固定,可以交给运行时逐记录转换,不要求完整计划已生成。 */ ready():boolean{return !sourceChecks&&state.phase==='emit'&&state.emitted===0;}, /** 返回阶段、语义 steps 和已分配数;不冒称解析/加入/网络已完成。 */ progress(){return Object.freeze({phase:state.phase,steps:state.steps,allocated:state.elementIds.length+state.canvasIds.length});}, /** 脱离当前可变 state 并冻结;保存和可靠落盘不在这个方法内。 */ checkpoint():DuplicateCheckpoint{return detachJsonData(state);}, /** 推进一次解释工作;false 表示仍需继续,只有最终输出校验结束才返回 true。 */ step():boolean{ // 恢复的源校验和派生缓存重建不增加语义 steps,不能据 steps 声称重开完全无重算。 if(sourceChecks){if(sourceChecks.next().done)sourceChecks=undefined;return false;} // Reconstruct only the derived output cache. Index/DFS/allocation work stays at its saved cursor. if(treeCache{const parent=document.canvases.get(canvas)!.parent;return parent&&selected.has(parent.entryElementId);}))state.roots.push(id);}else phase('seed',state.roots.length-1);break; case 'seed':if(state.cursor>=0){const id=state.roots[state.cursor--];if(document.elements.get(id)!.structure==='node')state.work.push({kind:'element',id});}else phase('dfs');break; // DFS 的“大分区兄弟压栈”本身也可暂停:expanding 保存未压完的 index,不一口气塞完整列表。 case 'dfs':{ if(state.expanding){const list=members.get(state.expanding.canvas)??[];if(state.expanding.index>=list.length)throw fault('invalid_copy_checkpoint');if(state.expanding.index<0)delete state.expanding;else{const id=list[state.expanding.index--];if(document.elements.get(id)!.structure==='node')state.work.push({kind:'element',id});}break;} const task=state.work.pop();if(!task){phase('edges');break;} if(task.kind==='canvas'){if(canvases.has(task.id))break;canvases.add(task.id);state.canvases.push(task.id);state.order.push(task);state.expanding={canvas:task.id,index:(members.get(task.id)?.length??0)-1};} else{if(copied.has(task.id))break;copied.add(task.id);state.copied.push(task.id);state.order.push(task);const child=children.get(task.id);if(child)state.work.push({kind:'canvas',id:child});}break; } // 扫描上级入边与范围内边;随后 element/canvas 分配都把新 ID 写回 state,恢复可重用。 case 'edges':if(state.cursorelementIds.get(id)!),elementIds:Object.fromEntries(elementIds),canvasIds:Object.fromEntries(canvasIds),changes:[...changes]});}, }); }