96 lines
11 KiB
TypeScript
96 lines
11 KiB
TypeScript
/**
|
||
* 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;}});
|
||
}
|