Files
Endoleap/src/lib/canvas-runtime/model-preview.ts
T

96 lines
11 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* canonical 流读取的临时只读投影,依据依赖闭合生成可展示的合法文档前缀。
* 它没有 history/ledger/文件/持久恢复权,host/engine 另将前缀接入真正项目状态。
* 终结数据必须与同一捕获的前缀一致;已收到数量不等于已能展示数量,缺依赖的记录继续等待。
*/
import {validateCanvasTopology,validateElementOwners,type ElementOwners,validateCanvasElementCounts,type CanvasElementCounts} from './scope-counts.ts';
import type { CanvasRecord, Document, ElementRecord, Id, Registry } from '../canvas-core/types.ts';
import { ancestors, createDocument, validateDocument, validateElementRecord } from '../canvas-core/document.ts';
import { copyReferenceIds } from '../canvas-core/copy-paths.ts';
import { clone, equal, fault, freeze, readMap } from '../canvas-core/values.ts';
import type { CanonicalReadUpdate } from './contracts.ts';
/** host 追加版本向量与 loading 证明后的预览,不能把它等同于完整 ACK 基线。 */
export type LiveModelPreview=ModelPreview&{readonly loading:import('./loading.ts').LoadingState;readonly versions:ReadonlyMap<Id,number>};
/** complete 固定false;receivedElements 计已收到,waitingElements 计还因依赖不能发布的记录。 */
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;
let tombstones:ReadonlyMap<Id,number>=new Map(),published:Document|undefined,snapshot:ModelPreview|undefined;
const canvases=new Map<Id,CanvasRecord>(),records=new Map<Id,ElementRecord>();
/** kind+ID 分命名空间标识依赖,canvas 与 element 即使字符串相同也不混淆。 */
const key=(kind:'canvas'|'element',id:Id)=>JSON.stringify([kind,id]);
// known 只存已经进入合法 published 前缀的键;records 暂存已收到但还未闭合的元素。
const known=new Set<string>();
/** 接收单次 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');
// 已有 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;
}
// 头部一次性声明 topology/数量/可选完整 ID→owner;后续块不允许重定义这些捕获事实。
if(!header){
if(value.receivedElements!==0||value.elements.length||!value.canvases.length||!Number.isSafeInteger(value.totalElements)||value.totalElements<0)throw fault('invalid_model_preview');
projectId=value.projectId;expected=value.totalElements;tombstones=readMap(new Map(value.tombstones));
for(const canvas of value.canvases){if(canvases.has(canvas.id))throw fault('invalid_model_preview');canvases.set(canvas.id,freeze(clone(canvas)));}
const topology=createDocument(projectId,[...canvases.values()]);let roots=0;const entries=new Set<Id>();
for(const canvas of canvases.values()){
if(!canvas.id||!Object.hasOwn(canvas,'parent'))throw fault('invalid_canvas');
ancestors(topology,canvas.id);
if(canvas.parent===null){roots++;if(canvas.id!==projectId)throw fault('project_mismatch');}
else if(!canvas.parent||typeof canvas.parent.entryElementId!=='string'||!canvas.parent.entryElementId||entries.has(canvas.parent.entryElementId))throw fault('invalid_canvas_entry');
else entries.add(canvas.parent.entryElementId);
}
if(roots!==1)throw fault('invalid_roots');if(value.canvasElementCounts!==undefined){validateCanvasElementCounts(value.canvasElementCounts,[...canvases.keys()],expected);canvasElementCounts=freeze(clone(value.canvasElementCounts));}if(value.elementOwners!==undefined){if(!canvasElementCounts)throw fault('invalid_model_identity');validateElementOwners(value.elementOwners,canvasElementCounts,expected);elementOwners=freeze(clone(value.elementOwners));validateCanvasTopology([...canvases.values()],elementOwners,projectId);}header=true;
}else if(value.projectId!==projectId||value.totalElements!==expected||value.canvases.length||value.tombstones.size||value.canvasElementCounts!==undefined||value.elementOwners!==undefined)throw fault('model_preview_changed');
if(value.receivedElements!==received+value.elements.length||value.receivedElements>expected)throw fault('invalid_model_preview');
// Validate the entire incoming batch before publishing any prefix from it.
// 整批预检ID去重、owner、基础记录和可选命名空间;不先发布批前半段再发现后半段非法。
const incoming=new Set<Id>();
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/端点及组件明确声明引用。
const candidates=new Map<string,{canvas?:CanvasRecord;element?:ElementRecord;deps:Set<string>}>();
for(const canvas of canvases.values())if(!known.has(key('canvas',canvas.id)))candidates.set(key('canvas',canvas.id),{canvas,deps:new Set(canvas.parent?[key('canvas',canvas.parent.canvasId),key('element',canvas.parent.entryElementId)]:[])});
for(const element of records.values())if(!known.has(key('element',element.id))){
const deps=new Set([key('canvas',element.ownerCanvasId)]);
if(element.structure==='connection'){deps.add(key('element',element.source.elementId));deps.add(key('element',element.target.elementId));}
const definition=registry.resolve(element)==='known'?registry.components.get(element.componentId):undefined;
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 上加全部未阻塞候选,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 失败即封闭且保留最后合法 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;}});
}