docs(canvas): explain import execution and lazy copy source recovery

This commit is contained in:
2026-11-12 00:37:50 +08:00
parent 72e84a6cc1
commit 06a422045f
8 changed files with 163 additions and 0 deletions
+9
View File
@@ -1,3 +1,7 @@
/**
* 格式1的完整复制源快照与复制声明签名。源字节在任务准入前从一个不可变文档捕获,
* 后续规划/重开不读取当前用户正在改的live文档;源SHA与持久字节由外层完整性流程绑定。
*/
import type { CanvasRecord, Document, ElementRecord, Registry } from '../canvas-core/types.ts';
import { createDocument, validateDocumentSteps } from '../canvas-core/document.ts';
import { fault } from '../canvas-core/values.ts';
@@ -6,13 +10,16 @@ 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。 */
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。 */
const append=(value:unknown)=>{if(signal.aborted)throw fault('copy_aborted');const text=JSON.stringify(value)+'\n',size=new TextEncoder().encode(text).byteLength;if(size>256*1024)throw fault('record_too_large');bytes+=size;if(bytes>64*1024*1024)throw fault('invalid_import_source');parts.push(text);return size;};
append({kind:'header',version:1,projectId:document.projectId});
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后才返回。 */
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){
@@ -23,6 +30,7 @@ export async function decodeCopySnapshot(bytes:Blob,projectId:string,registry:Re
await budget.step(Math.max(1,Math.ceil((cursor-start)/1024)));
}
if(!header||signal.aborted)throw fault(signal.aborted?'copy_aborted':'invalid_copy_snapshot');
// 不把合法header/记录数量当成完整图合法;parent/owner/端点/schema仍由核心校验。
const document=createDocument(projectId,canvases,elements,tombstones);
for(const _ of validateDocumentSteps(document,registry))await budget.step();
if(signal.aborted)throw fault('copy_aborted');
@@ -30,6 +38,7 @@ export async function decodeCopySnapshot(bytes:Blob,projectId:string,registry:Re
}
/** Copy declarations are a versioned input; never silently reinterpret a persisted preparation. */
/** 仅对源涉及组件的数据版本/structure/copy声明生成稳定签名,防持久准备被新声明静默重解释。 */
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};}));