docs(canvas): explain ledger scheduling and recovery invariants
This commit is contained in:
@@ -1,3 +1,8 @@
|
||||
/**
|
||||
* 已确认基线和待同步意图的纯协调工具。先验证 canonical 文档/版本不可倒退,
|
||||
* 再按原逻辑次序条件回放未解决的文档意图,形成 working 候选;不把旧 ACK 整份覆盖当前编辑。
|
||||
* 这里只计算/校验,最终 document/runtime/ledger 的原子发布由 engine/editor 负责。
|
||||
*/
|
||||
import { withLocalLifecycles } from './elision.ts';
|
||||
import { validateCreationSizeEffect } from '../canvas-core/creation-size-plan.ts';
|
||||
import type { Document, Id, OperationIntent, Registry } from '../canvas-core/types.ts';
|
||||
@@ -6,11 +11,14 @@ import { equal, fault } from '../canvas-core/values.ts';
|
||||
import type { LedgerSnapshot } from './ledger.ts';
|
||||
|
||||
/** A complete read cannot rewind known scopes or change an unchanged-version canvas. */
|
||||
/** 校验完整 fresh read:同项目、合法文档、活 canvas 版本齐全、已知版本和墓碑均不可倒退。
|
||||
* 某 canvas 版本没变时,其记录/直属元素必须相同;全向量没变时墓碑集合也不能偷偷改变。 */
|
||||
export function validateCanonicalRead(previous: Document, previousVersions: ReadonlyMap<Id,number>, next: Document, versions: ReadonlyMap<Id,number>, registry: Registry) {
|
||||
if(next.projectId!==previous.projectId)throw fault('project_mismatch');
|
||||
validateDocument(next,registry);
|
||||
for(const [id,version]of versions)if(!Number.isSafeInteger(version)||version<1)throw fault('invalid_canonical_version',[id]);
|
||||
for(const canvas of next.canvases.keys())if(!versions.has(canvas))throw fault('missing_server_version',[canvas]);
|
||||
// 记录服务声明“版本未变”的 owner,随后双向检查元素,既防遗漏删除也防夹带新增。
|
||||
const unchanged=new Set<Id>();
|
||||
for(const [id,version]of previousVersions){
|
||||
if((versions.get(id)??-1)<version)throw fault('stale_canonical_version',[id]);
|
||||
@@ -26,9 +34,12 @@ export function validateCanonicalRead(previous: Document, previousVersions: Read
|
||||
}
|
||||
|
||||
/** The footprint follows ownership; geometry does not decide which canvas owns an object. */
|
||||
/** 计算跨 canvas 操作 footprint:有已冻结意图范围时沿用,否则收集新旧 owner/父级/端点归属。
|
||||
* 上传和 run.cancel 不占文档参与者;空间位置或画框相交不决定 owner。 */
|
||||
export function operationCanvases(intent: OperationIntent, document: Document, after:Document=document): readonly Id[] {
|
||||
if(intent.operationType==='asset.upload'||intent.operationType==='run.cancel')return[];
|
||||
if (intent.canvasIds?.length) return intent.canvasIds;
|
||||
// 字段变化不能只查 after;重挂/改端点时旧 owner 也参与版本条件和占用。
|
||||
const ids = new Set<Id>();
|
||||
for (const change of intent.changes) {
|
||||
if (change.kind === 'canvas') {
|
||||
@@ -52,7 +63,10 @@ export function operationCanvases(intent: OperationIntent, document: Document, a
|
||||
}
|
||||
|
||||
/** Replay once, by logical sequence. A receipt can already contain a desired field value. */
|
||||
/** 将本地生命周期水位叠到 ACK 副本,再按 sequence 回放 document.change/run.apply。
|
||||
* 只有已满足的 after 可安全跳过,条件冲突仍拒绝;不会自动改写原意图或冻结请求。 */
|
||||
export function replayPending(base: Document, ledger: LedgerSnapshot, registry: Registry): Document {
|
||||
/** 已 resolved 项不重放;未冻结、冻结或 blocked 的未解决文档意图仍按原事实参与重建。 */
|
||||
function* pending(){
|
||||
for(const record of [...ledger.operations.values()].sort((a,b)=>a.intent.sequence-b.intent.sequence)){
|
||||
if(record.phase==='resolved'||!['document.change','run.apply'].includes(record.intent.operationType))continue;
|
||||
@@ -60,6 +74,7 @@ export function replayPending(base: Document, ledger: LedgerSnapshot, registry:
|
||||
yield {changes:record.intent.changes,canvasIds:record.intent.canvasIds};
|
||||
}
|
||||
}
|
||||
// 本地抵消可能从未进入服务器,水位只加到 working 候选,不能冒充服务器已确认墓碑。
|
||||
const document=replayChanges(withLocalLifecycles(base,ledger),pending());
|
||||
validateDocument(document,registry);
|
||||
return document;
|
||||
|
||||
Reference in New Issue
Block a user