docs(tests): explain progressive import completion and durable seals

tests/headless/imports-engine.test.mjs

@@ -57,6 +57,7 @@ function fixture(initial=original){
 function until(engine,predicate){if(predicate(engine.getSnapshot()))return Promise.resolve();return new Promise((resolve,reject)=>{const timer=setTimeout(()=>{unsubscribe();reject(Error('import condition timed out'));},5000),unsubscribe=engine.editor.subscribe((_,snapshot)=>{if(predicate(snapshot)){clearTimeout(timer);unsubscribe();resolve();}});});}
 
 // 阻塞后端提交时三个 native 元素已本地可见且历史合并为一组；新 incarnation=1，runId 被剔除，放行 ACK 后再检查服务端。
+// completed 是导入 runner 的本地终态，不代表同步账本全部 resolved；因此同一时刻本地三项、服务端零项是合法状态。
 test('native import adds visible records while its backend writer is still awaiting ACK',async()=>{
  const f=fixture(),engine=await f.open(),gate=deferred();f.gate=gate;
  try{const id=engine.imports.startNdjson(file([node('one'),node('two'),node('three')]),'canvas');await until(engine,snapshot=>snapshot.runtime.imports.get(id).status==='completed');assert.equal(engine.getSnapshot().document.elements.size,3);assert.equal(f.server().elements.size,0);assert.equal(engine.getSnapshot().history.undo.length,1);assert.equal(f.files.size,1);for(const element of engine.getSnapshot().document.elements.values()){assert.equal(element.incarnation,1);assert.equal(element.data.runId,undefined);}gate.resolve();await engine.settle();assert.equal(f.server().elements.size,3);assert.equal(f.errors.length,0);decodeRecovery(f.image(),registry);}finally{gate.resolve();await engine.close();}
@@ -69,6 +70,7 @@ test('pause/reopen/resume reuses the durable source and IDs without overwriting
 });
 
 // 导入前缀、手动编辑、导入后缀是三个有序 undo 单元；重开后逐项 undo/redo 仍保留同一编辑与任务完成事实。
+// 导入批次只能在不跨越用户编辑的前提下合并历史；否则会打乱夹在中间的手动改名与导入内容的撤销顺序。
 test('import history on either side of a manual edit remains three ordered undo units after reopening',async()=>{
  const f=fixture();let engine=await f.open();
  try{
@@ -124,6 +126,7 @@ test('a late unavailable-source result cannot change a job cancelled during reop
 
 
 // 普通空恢复 image 可为格式 1，含读取证明后升级到 17；不能仅改 formatVersion 就把证明数据降成旧格式。
+// formatVersion 解释整个恢复镜像，parserVersion 解释源记录，integrityVersion 解释源校验合同；三类数字独立，不要求彼此相同。
 test('proof-bearing recovery cuts use format 17 and cannot be silently downgraded to a legacy image',async()=>{
  const f=fixture(),engine=await f.open();
  try{await engine.persist();assert.equal(f.image().formatVersion,1);const id=engine.imports.startNdjson(file([node('one')]),'canvas');await engine.settle();const image=f.image();assert.equal(image.formatVersion,17);assert.equal(decodeRecovery(image,registry).runtime.imports.get(id).status,'completed');assert.throws(()=>decodeRecovery({...image,formatVersion:1},registry),/unsupported_recovery_version/);}finally{await engine.close();}
@@ -337,6 +340,7 @@ test('closing a project aborts its injected digest without closing another proje
 // 只手动推进回收墙上时间，真实定时器仍服务于调度；用于精确检查源文件退休宽限期。
 const retentionClock=()=>{let now=1000;return{now:()=>now,advance:ms=>{now+=ms;},setTimer:(fn,ms)=>setTimeout(fn,ms),clearTimer:id=>clearTimeout(id)};};
 // 任务本地终态后源文件可标记/宽限期回收，即使文档请求还未 ACK；内容、history 和冻结请求体保持，重开 undo/redo 不依赖已退休源。
+// 已接受 changes 已在模型、历史和冻结请求中保存；删除的是解析用原文件，不是这些状态，也不是图片元素引用的资产字节。
 test('terminal import source collection preserves every imported record, undo unit and pending request across source-v2 reopening',async()=>{
  const f=fixture(),clock=retentionClock(),gate=deferred();f.gate=gate;let engine=await f.open({clock});try{
   const id=engine.imports.startNdjson(file([node('one'),node('two')]),'canvas');await until(engine,snapshot=>snapshot.runtime.imports.get(id).status==='completed');await engine.persist();const job=engine.imports.getJobs().get(id),fileId=job.source.fileId,document=engine.getSnapshot().document,history=engine.getSnapshot().history;
@@ -452,6 +456,7 @@ test('native import publishes and edits a proof-backed prefix before full SHA, w
 });
 
 // 内存中已有完整 SHA 仍不足以放行网络；必须等含该 seal 的恢复 cut 真正落盘，再允许相关文档请求。
+// hash gate 控制校验何时完成，save gate 控制封存证据何时可恢复；分别拦住两阶段，避免把“算完摘要”误当成“保存完成”。
 test('a verified SHA still cannot release pending import writes before the seal cut is durable',async()=>{
  const f=fixture(),hash=deferred(),save=deferred(),saving=deferred(),commit=f.storage.commit,engine=await f.open({digests:{async digest(bytes,signal){await hash.promise;return importSourceDigest(bytes,signal);}}});
  try{const id=engine.imports.startNdjson(file([node('seal-one')]),'canvas');await until(engine,root=>root.runtime.imports.get(id).committedSourceKeys.length===1);await engine.persist();f.storage.commit=async(owner,batch)=>{if(batch.image.payload.runtime.imports?.some(([key,job])=>key===id&&job.source.sha256)){saving.resolve();await save.promise;}return commit(owner,batch);};hash.resolve();await saving.promise;assert.ok(engine.imports.getJobs().get(id).source.sha256);assert.equal(f.requests.length,0);save.resolve();await engine.settle();assert.equal(f.server().elements.size,1);assert.equal(f.errors.length,0);}finally{hash.resolve();save.resolve();await engine.close();}