diff --git a/src/lib/canvas-runtime/loading.ts b/src/lib/canvas-runtime/loading.ts index 7c55fb7..32a4843 100644 --- a/src/lib/canvas-runtime/loading.ts +++ b/src/lib/canvas-runtime/loading.ts @@ -16,9 +16,13 @@ import type {CanonicalProposal,RuntimeState} from './contracts.ts'; * version 3 admits certified scopes with a retained read baseline. No HTTP cursor. */ /** 当前捕获的稳定 token、声明 canvas 范围及接收数量;不保存或伪造可续传 HTTP 字节游标。 */ type LoadingBase={readonly sourceToken:string;readonly declaredCanvasIds:readonly Id[];readonly receivedElements:number;readonly totalElements:number}; -/** 版本化范围证据:counts/owners/sourceCanvases 能力逐级增加,缺字段不能当有证明。 */ +/** 版本化范围证据:v1 无计数,v2/3 加直属计数,v4 加全 ID→owner,v5/6 再加完整源树。 + * 版本表示允许解释的协议能力,不表示收到全部 payload 或已可发送;loading 清除前项目仍标记未完整。 */ export type LoadingState=LoadingBase&({readonly version:1;readonly canvasElementCounts?:never;readonly elementOwners?:never;readonly sourceCanvases?:never}|{readonly version:2|3;readonly canvasElementCounts:CanvasElementCounts;readonly elementOwners?:never;readonly sourceCanvases?:never}|{readonly version:4;readonly canvasElementCounts:CanvasElementCounts;readonly elementOwners:ElementOwners;readonly sourceCanvases?:never}|{readonly version:5|6;readonly canvasElementCounts:CanvasElementCounts;readonly elementOwners:ElementOwners;readonly sourceCanvases:readonly CanvasRecord[]}); -/** 验证前缀与捕获头一致:版本、树/ID命名空间、总数、直属计数和源版本向量;不是只比较已加载数量。 */ +/** 校验声明版本/token/范围/接收数及版本值,再按版本核对 counts、owners、源树和当前前缀成员。 + * document.elements.size 可以少于 receivedElements,允许已收但因依赖尚未发布的记录;两者都不能超过总量。 + * 不调用 validateDocument、不捕获/冻结输入或检验 HTTP 身份;外围须提供合法模型/源与不可变声明。 + * 旧版本不允许偷带新证据字段,但不是通用严格 JSON DTO/所有扩展字段过滤器。 */ export function validateLoadingState(value:LoadingState,document:Document,versions:ReadonlyMap):void{ if(!value||![1,2,3,4,5,6].includes(value.version))throw fault('loading_interpreter_unavailable'); for(const [id,version]of versions)if(!Number.isSafeInteger(version)||version<1)throw fault('invalid_canonical_version',[id]); @@ -42,7 +46,9 @@ function pathAllowed(id:Id,document:Document,registry:Registry,loading?:LoadingS const element=document.elements.get(id);if((!loading||loading.version===1)||element?.structure!=='connection'||registry.resolve(element)!=='known')return false; return (directCounts(base).get(element.ownerCanvasId)??0)===loading.canvasElementCounts[element.ownerCanvasId]; } -/** partial 模式的命令预检;新结构证明可处理特定命令,否则仅已有节点几何/安全内容等受限编辑。 */ +/** 部分加载策略入口:v4+ 先问结构门,undefined 才落回已知 node 几何/安全普通内容/可证完整边路径。 + * enabled 仅表示加载策略允许,核心目标代次、capability、业务 policy 和提交校验仍需执行。 + * 本 helper 不是无 loading 时的通用命令放行器;调用方应只在 partial 模式将它作为额外约束。 */ export function loadingCommand(command:Command,document:Document,registry:Registry,loading?:LoadingState,base=document,source?:CanonicalProposal,assets?:ReadonlyMap):Availability{ if(loading&&(loading.version===4||loading.version===5||loading.version===6)&&source){const scoped=structuralCommand(command,document,registry,loading,source,assets);if(scoped)return scoped;} if(command.type==='connection.path')return pathAllowed(command.target.id,document,registry,loading,base)?{enabled:true}:denied; @@ -53,7 +59,9 @@ export function loadingCommand(command:Command,document:Document,registry:Regist } /** Check actual changes too: a feature handler cannot evade command admission by * modifying a protected reference field as a side effect of an allowed edit. */ -/** 再核对 handler 实际输出,防止表面是编辑 title,却顺带修改受保护引用字段;v4+走结构闭合校验。 */ +/** 对 handler 实际 changes 再做加载策略检查;v4+ 以结构候选验证,返回结果在此不发布。 + * 旧分支只允许字段类并逐项针对传入 document 检查,不按顺序执行 changes、不校验 before 或完整 schema。 + * 因此通过不表示变更可直接采用,后续事务执行/文档校验仍负责条件与最终合法性。 */ export function assertLoadingChanges(changes:readonly Change[],document:Document,registry:Registry,loading?:LoadingState,source?:CanonicalProposal,assets?:ReadonlyMap):void{ if(loading&&(loading.version===4||loading.version===5||loading.version===6)&&source){assertStructuralChanges(changes,document,registry,loading,source,assets);return;} for(const change of changes){ @@ -62,7 +70,10 @@ export function assertLoadingChanges(changes:readonly Change[],document:Document if(!element||element.incarnation!==change.target.incarnation||registry.resolve(element)!=='known'||!(change.field==='path'&&pathAllowed(change.target.id,document,registry,loading)||change.field==='geometry'&&element.structure==='node'||change.field.startsWith('data.')&&dataKeyAllowed(element.componentId,change.field.slice(5),registry)))throw fault('model_loading',[change.target.id]); } } -/** 恢复/发布时联合校验 loading/source/ACK/意图/资源/导入,不让单表合法但整体证据矛盾的 Root 通过。 */ +/** 校验部分加载 Root 的组合证据:原源/ACK 对应、各版本禁止的任务类别、资源/导入准入和逻辑回放。 + * 无 loading 时只禁止孤立 loadingRead 即返回,并不在此验证所有普通运行时字段;通用校验由恢复/引擎负责。 + * v4+ 按 sequence 回放所有文档意图而非只 pending,v6 允许合规 asset.upload 并在文档步骤后查首次资源范围。 + * 本函数只验证/构造私有候选,不提交 Root、写存储或放行网络,不能替代持久/身份围栏。 */ export function validateLoadingRuntime(runtime:RuntimeState,registry:Registry):void{ if(!runtime.loading){if(runtime.loadingRead)throw fault('invalid_loading_state');return;} // v3+必须保留独立 loadingRead,旧版本不可偷带该字段;源校验不使用已经推进的 ACK 代替。 @@ -82,15 +93,19 @@ export function validateLoadingRuntime(runtime:RuntimeState,registry:Registry):v validateLoadingAssetUse(record.intent,logical,runtime,registry,assetUses); } } -/** 同一读取的前缀扩展只能追加:token/版本/范围证据/墓碑固定,旧记录不得在后块被修改或移除。 */ +/** 验证 next 文档/声明后,与已验证 previous 比较:同项目/token/证据版本/头部/版本向量/墓碑不变。 + * received 单调,旧 canvas/element 记录逐个保留且相等,允许新闭合记录追加;不是用较新 ACK 覆盖旧源来比较。 + * 不发布/冻结 next,也不证明其传输来源;调用方完成捕获后再合并 ACK、重放 pending 并同 Root 采纳。 */ export function validatePrefixExtension(previous:Document,previousVersions:ReadonlyMap,state:LoadingState,next:Document,versions:ReadonlyMap,nextState:LoadingState,registry:Registry):void{ validateDocument(next,registry);validateLoadingState(nextState,next,versions); if(next.projectId!==previous.projectId||state.sourceToken!==nextState.sourceToken||state.version!==nextState.version||!equal(state.canvasElementCounts,nextState.canvasElementCounts)||!equal(state.elementOwners,nextState.elementOwners)||!equal(state.sourceCanvases,nextState.sourceCanvases)||state.totalElements!==nextState.totalElements||nextState.receivedElements!equal(record,next.canvases.get(id)))||[...previous.elements].some(([id,record])=>!equal(record,next.elements.get(id))))throw fault('loading_source_mismatch'); } /** Full fresh reads may include new records in an unchanged-version scope. Known * records still cannot change without an owner version advancing. */ -/** 校验终结或 fresh read:已知版本不倒退,同版本已知记录不变,墓碑不倒退。 - * 原捕获补完要求相同 token/向量/总量;fresh read 可新增此前未收到项,v4+按新完整捕获协调。 */ +/** 校验完整 next:合法文档/活 canvas 版本、已知版本和墓碑不倒退,同 owner 版本的已知记录不得改变。 + * fresh=false 还要求原 token/向量,按原声明总量/范围/直属计数补完;此处不会自动叠本地已确认编辑。 + * fresh=true 可采用新的完整捕获,v4+ 即使版本向量相同也不强套旧总量/范围计数,但已知记录/生命周期约束仍在。 + * 旧版本 fresh 在向量相同时仍受原总量/计数约束;是否移除 loading/合并 working 由引擎决定。 */ export function validateLoadingCompletion(previous:Document,previousVersions:ReadonlyMap,state:LoadingState,next:Document,versions:ReadonlyMap,registry:Registry,fresh=false,sourceToken?:string):void{ validateDocument(next,registry);if(previous.projectId!==next.projectId)throw fault('project_mismatch'); for(const [id,version]of versions)if(!Number.isSafeInteger(version)||version<1)throw fault('invalid_canonical_version',[id]); @@ -117,7 +132,10 @@ const namespaceSets=new WeakMap{let counts=membershipCounts.get(document);if(!counts){const next=new Map();for(const element of document.elements.values())next.set(element.ownerCanvasId,(next.get(element.ownerCanvasId)??0)+1);counts=next;membershipCounts.set(document,counts);}return counts;} -/** 给 query 同次发布的完整性:整个项目未完仍可有已认证完整 owner;born canvas 另按结构证明处理。 */ +/** 派生查询覆盖状态:无 loading 时标全项目/拓扑完整,有 loading 时 projectComplete 固定 false。 + * v4+ 同时给全源 elementIds 与合法源前缀 loadedElementIds,后者不是传输 received 数;born scope 依 ownerReady 判定。 + * 拓扑完整只按合法前缀 canvas 与声明范围数量判断,成员完整另用源直属计数,不能相互替代。 + * WeakMap 索引依赖 document/owners 不可变;这里不改变 document 或验证网络捕获身份。 */ export function loadingQueryCoverage(snapshot:import('./contracts.ts').EngineSnapshot):import('../canvas-core/queries.ts').QueryCoverage { const loading=snapshot.runtime.loading,base=snapshot.runtime.loadingRead?.document??snapshot.runtime.acknowledged; if(!loading)return{projectComplete:true,topologyComplete:true,completeCanvasIds:[...snapshot.document.canvases.keys()]}; @@ -146,7 +164,9 @@ function validateLoadingRead(runtime:RuntimeState,registry:Registry):void { for(const request of runtime.ledger.requests.values())if(request.kind!==undefined&&request.kind!=='document.change'||!request.canvasIds.length||new Set(request.canvasIds).size!==request.canvasIds.length||Object.keys(request.expectedVersions).length!==request.canvasIds.length||request.canvasIds.some(id=>!ready.has(id)||!Number.isSafeInteger(request.expectedVersions[id])||request.expectedVersions[id]<(source.versions.get(id)??Infinity)||request.expectedVersions[id]>(runtime.versions.get(id)??-1)))throw fault('invalid_loading_request'); } /** Overlay only scopes whose ACK version advanced since this immutable capture. */ -/** 在新源前缀上只叠已推进 ACK 的效果,不叠未确认 pending;pending 由后续条件重放重建。 */ +/** 无 v3+ 保留源时直接返回 read;v4+ 用 appliedSource 叠已确认逻辑效果并验文档。 + * v3 只将版本已超过原捕获的 owner 成员整组换成 ACK,保留新 read 其它 owner、树与墓碑,再更新对应版本。 + * 不叠 pending、不修改 runtime.loadingRead/ACK;引擎随后重放未决意图并发布同一 Root。 */ export function mergeLoadingRead(runtime:RuntimeState,read:CanonicalProposal,registry:Registry):CanonicalProposal { const source=runtime.loadingRead;if((!runtime.loading||runtime.loading.version<3)||!source)return read; if(runtime.loading.version>=4){const projected=appliedSource(runtime,read);validateDocument(projected.document,registry);return projected;} @@ -159,13 +179,17 @@ export function mergeLoadingRead(runtime:RuntimeState,read:CanonicalProposal,reg } /** 以指定元素列表重建源文档,保留同一项目/canvas/墓碑,创建标准只读表而非返回可变拼接对象。 */ function importDocument(document:Document,elements:readonly import('../canvas-core/types.ts').ElementRecord[]):Document{return createDocument(document.projectId,[...document.canvases.values()],elements,document.tombstones);} -/** 发送门:v1/v2不发,v3要求全部参与owner闭合,v4+要求每项符合结构范围;无loading正常放行。 */ +/** 加载范围发送门:无 loading 返回 true,v1/2 返回 false,v3+ 要求非空且全部参与范围有证明。 + * 不检查实际 operation/请求 body、身份/政策、依赖、导入 seal 或磁盘水位;scheduler/engine 还须叠加那些门禁。 + * v6 asset.upload 的空文档参与者由引擎专门准入,不因这里对空数组返回 false 就一概禁止资源上传。 */ export function loadingCanSend(runtime:RuntimeState,canvasIds:readonly Id[],document=runtime.acknowledged):boolean { if(!runtime.loading)return true;if(runtime.loading.version<3)return false;if(runtime.loading.version>=4)return canvasIds.length>0&&canvasIds.every(id=>structuralRequestScope(runtime,runtime.loadingRead!,id)); const ready=new Set(loadingQueryCoverage({runtime,document} as import('./contracts.ts').EngineSnapshot).completeCanvasIds);return canvasIds.length>0&&canvasIds.every(id=>ready.has(id)); } -/** source+已applied changes 必须精确等于 ACK 和版本向量,拒绝旧tail抹去确认后的创建/删除/重挂。 */ +/** 用原 source+applied 意图重建期望,逐表/版本与 ACK 比较,再 validateDocument(ACK)。 + * 请求需符合协议 2/非空参与者/结构范围及版本区间;v6 上传请求例外留给资源专用校验。 + * 原回执是否真实、ledger 内部状态是否合法仍由外围校验保证,此步骤不查询服务器或修复不一致。 */ function validateStructuralRead(runtime:RuntimeState,registry:Registry){ const source=runtime.loadingRead!,expected=appliedSource(runtime,source),ack=runtime.acknowledged; if(expected.document.projectId!==ack.projectId||!equal(Object.fromEntries(expected.document.canvases),Object.fromEntries(ack.canvases))||!equal(Object.fromEntries(expected.document.elements),Object.fromEntries(ack.elements))||!equal(Object.fromEntries(expected.document.tombstones),Object.fromEntries(ack.tombstones))||!equal(Object.fromEntries(expected.versions),Object.fromEntries(runtime.versions)))throw fault('invalid_loading_read'); @@ -173,7 +197,9 @@ function validateStructuralRead(runtime:RuntimeState,registry:Registry){ for(const request of runtime.ledger.requests.values())if(!(runtime.loading?.version===6&&request.kind==='asset.upload')&&(request.protocolVersion!==2||!request.canvasIds.length||Object.keys(request.expectedVersions).length!==request.canvasIds.length||request.canvasIds.some(id=>!structuralRequestScope(runtime,source,id)||!Number.isSafeInteger(request.expectedVersions[id])||request.expectedVersions[id]<(source.versions.get(id)??0)||request.expectedVersions[id]>(runtime.versions.get(id)??0))))throw fault('invalid_loading_request'); } -/** 原源owner须完整;不在源版本表的新canvas须有明确创建意图,不能凭任意ID绕过范围门。 */ +/** 源版本表中的 owner 按原捕获成员数量判完整;不在源表的 ID 须在某条意图中明确创建过 canvas。 + * 新 canvas 分支不按 ledger phase/resolution 过滤,也不单独检查它当前仍存在;实际 changes/请求验证还要继续。 + * 这是范围来源判定,不是任意 canvas 的权限或完整生命周期证明。 */ export function structuralRequestScope(runtime:RuntimeState,source:CanonicalProposal,id:Id):boolean { if(source.versions.has(id))return ownerReady(runtime.loading!,source,source.document,id); return [...runtime.ledger.operations.values()].some(record=>record.intent.changes.some(change=>change.kind==='canvas'&&change.id===id&&!change.before&&!!change.after));