docs(runtime): explain partial loading coordination and gates

This commit is contained in:
2026-11-12 13:44:12 +08:00
parent 59b59c2f03
commit 196866aaf3
+39 -13
View File
@@ -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<Id,number>):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<Id,string>):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<Id,string>):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<Id,number>,state:LoadingState,next:Document,versions:ReadonlyMap<Id,number>,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<state.receivedElements||!equal(state.declaredCanvasIds,nextState.declaredCanvasIds)||!equal(Object.fromEntries(previousVersions),Object.fromEntries(versions))||!equal(Object.fromEntries(previous.tombstones),Object.fromEntries(next.tombstones))||[...previous.canvases].some(([id,record])=>!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<Id,number>,state:LoadingState,next:Document,versions:ReadonlyMap<Id,number>,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<ElementOwners,import('../canvas-core/types.ts').
function namespace(owners:ElementOwners){let value=namespaceSets.get(owners);if(!value){value=readSet(Object.keys(owners));namespaceSets.set(owners,value);}return value;}
/** 计算并缓存单文档 owner 的直属数量,节点/边都计入,不递归累计子树。 */
function directCounts(document:Document):ReadonlyMap<Id,number>{let counts=membershipCounts.get(document);if(!counts){const next=new Map<Id,number>();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));