docs(canvas): explain streamed loading and certified scope admission
This commit is contained in:
@@ -1,3 +1,7 @@
|
||||
/**
|
||||
* 部分加载v5/v6允许闭合范围内导入/复制的准入与恢复校验。
|
||||
* 源token、开始时逻辑sequence和必要canvas集合一起捕获,避免后来的未读树或新ACK改变原复制源含义。
|
||||
*/
|
||||
import type {CanvasRecord,Document,Id,Target} from '../canvas-core/types.ts';
|
||||
import {fault,freeze,equal} from '../canvas-core/values.ts';
|
||||
import type {EngineSnapshot} from './contracts.ts';
|
||||
@@ -7,18 +11,24 @@ import {copyTopology} from './copy-snapshot-index.ts';
|
||||
import {structuralRequestScope} from './loading.ts';
|
||||
import {ownerReady} from './loading-structure.ts';
|
||||
|
||||
// 不可变文档的owner成员/入口子canvas关系索引,复用扫描结果但不另存第二份文档。
|
||||
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。 */
|
||||
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');
|
||||
const source=snapshot.runtime.loadingRead,document=snapshot.document,required=new Set<Id>([target]);
|
||||
/** 每个必要canvas既加入证明,也必须当前ownerReady,不能只记名字就声称已经加载完整。 */
|
||||
const requireScope=(id:Id)=>{required.add(id);if(!ownerReady(state,source,document,id))throw fault('loading_scope_incomplete',[id]);};requireScope(target);
|
||||
if(selection){
|
||||
if(!selection.length)throw fault('empty_copy_selection');const tables=index(document),pending=selection.map(target=>{const element=document.elements.get(target.id);if(!element||element.incarnation!==target.incarnation)throw fault('stale_incarnation',[target.id]);return target.id;}),copied=new Set<Id>(),canvases=new Map<Id,CanvasRecord>(document.canvases);
|
||||
// Missing captured children cannot be mistaken for an empty/leaf selection.
|
||||
// 完整sourceCanvases揭示未收到的子分区,不能把尚未到齐的F当成叶子,误复制空分区。
|
||||
const missingChildren=new Map<Id,Id[]>();for(const canvas of state.sourceCanvases)if(canvas.parent&&!source.document.canvases.has(canvas.id)&&!document.canvases.has(canvas.id)){canvases.set(canvas.id,canvas);const ids=missingChildren.get(canvas.parent.entryElementId)??[];ids.push(canvas.id);missingChildren.set(canvas.parent.entryElementId,ids);}
|
||||
// 显式stack去重深复制选区及全部后代,对每层直属owner检查闭合。
|
||||
while(pending.length){const id=pending.pop()!;if(copied.has(id))continue;copied.add(id);const element=document.elements.get(id);if(!element)throw fault('loading_scope_incomplete',[id]);requireScope(element.ownerCanvasId);
|
||||
for(const child of [...(tables.children.get(id)??[]),...(missingChildren.get(id)??[])]){requireScope(child);pending.push(...(tables.members.get(child)??[]));}
|
||||
}
|
||||
@@ -28,9 +38,11 @@ export function loadingImportAdmission(snapshot:EngineSnapshot,target:Id,selecti
|
||||
// Edges involving born objects are entirely local to this captured namespace.
|
||||
for(const element of document.elements.values())if(element.structure==='connection'&&copied.has(element.target.elementId)&&!copied.has(element.source.elementId))requireScope(element.ownerCanvasId);
|
||||
}
|
||||
// 用当前最大逻辑sequence固定复制源时点,后续用户编辑不应倒灌成原源内容。
|
||||
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仍是可证明范围。 */
|
||||
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);
|
||||
@@ -39,13 +51,16 @@ 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保持不增长。 */
|
||||
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;
|
||||
// 原captured源叠当时已有的逻辑变化重建源时点,不把当前working当成冻结复制快照。
|
||||
for(const record of [...snapshot.runtime.ledger.operations.values()].sort((a,b)=>a.intent.sequence-b.intent.sequence))if(record.intent.sequence<=proof.operationSequence)expected=applyChanges(expected,record.intent.changes,false);
|
||||
const selection=job.preparation?.selection??job.source?.plan?.selection;if(!selection)throw fault('invalid_loading_import',[job.id]);
|
||||
const required=loadingImportAdmission({...snapshot,document:expected},job.source!.targetCanvasId,selection)!;
|
||||
if(!equal(required.requiredCanvasIds,proof.requiredCanvasIds))throw fault('loading_copy_scope_changed',[job.id]);
|
||||
// 逐owner比较canvas与copyTopology;普通payload并非这里完整性证明,源字节/摘要由其它导入层校验。
|
||||
for(const id of proof.requiredCanvasIds){if(!equal(expected.canvases.get(id),document.canvases.get(id)))throw fault('loading_copy_scope_changed',[id]);
|
||||
const wanted=Object.fromEntries([...expected.elements.values()].filter(element=>element.ownerCanvasId===id).map(element=>[element.id,copyTopology(element)])),actual=Object.fromEntries([...document.elements.values()].filter(element=>element.ownerCanvasId===id).map(element=>[element.id,copyTopology(element)]));if(!equal(wanted,actual))throw fault('loading_copy_scope_changed',[id]);
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user