docs(runtime): clarify elision and reconciliation evidence
This commit is contained in:
@@ -12,11 +12,13 @@ import type { LedgerSnapshot } from './ledger.ts';
|
||||
|
||||
/** A complete read cannot rewind known scopes or change an unchanged-version canvas. */
|
||||
/** 校验完整 fresh read:同项目、合法文档、活 canvas 版本齐全、已知版本和墓碑均不可倒退。
|
||||
* 某 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]);
|
||||
// 活 canvas 必须有版本,但不要求版本表只含活项;已移除 scope 的已知水位也可继续保留。
|
||||
for(const canvas of next.canvases.keys())if(!versions.has(canvas))throw fault('missing_server_version',[canvas]);
|
||||
// 记录服务声明“版本未变”的 owner,随后双向检查元素,既防遗漏删除也防夹带新增。
|
||||
const unchanged=new Set<Id>();
|
||||
@@ -34,10 +36,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。 */
|
||||
/** 计算跨 canvas footprint:声明了非空 intent.canvasIds 就直接沿用,不以是否已冻结为条件。
|
||||
* 否则从变化收集新旧 owner/父级/端点归属;上传和 run.cancel 总是返回空文档参与者。
|
||||
* 不根据画框相交或 run 的 boardId/action 自动猜参与者;ID 有效性与编译覆盖另由边界核对。 */
|
||||
export function operationCanvases(intent: OperationIntent, document: Document, after:Document=document): readonly Id[] {
|
||||
if(intent.operationType==='asset.upload'||intent.operationType==='run.cancel')return[];
|
||||
// 已声明范围按原引用/顺序返回,不在此排序去重;仅下方推导路径用 Set 并排序。
|
||||
if (intent.canvasIds?.length) return intent.canvasIds;
|
||||
// 字段变化不能只查 after;重挂/改端点时旧 owner 也参与版本条件和占用。
|
||||
const ids = new Set<Id>();
|
||||
@@ -64,18 +68,21 @@ 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 可安全跳过,条件冲突仍拒绝;不会自动改写原意图或冻结请求。 */
|
||||
* 底层按同 incarnation/字段存在性判断已满足 after,并检查 field owner 范围;条件冲突仍拒绝。
|
||||
* 不改写意图/冻结请求,不移动 history;historyEffect 只在此验证形状,不重新执行尺寸历史规划。 */
|
||||
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;
|
||||
// 只筛 document.change/run.apply 的变化;上传、run.start/cancel 不因存在 changes 字段就在这里执行。
|
||||
if(record.intent.historyEffect)validateCreationSizeEffect(record.intent.historyEffect);
|
||||
yield {changes:record.intent.changes,canvasIds:record.intent.canvasIds};
|
||||
}
|
||||
}
|
||||
// 本地抵消可能从未进入服务器,水位只加到 working 候选,不能冒充服务器已确认墓碑。
|
||||
const document=replayChanges(withLocalLifecycles(base,ledger),pending());
|
||||
// 全部回放成功后检查最终工作文档;任何异常让调用者丢弃这份候选,不在此处理冲突 UI 或覆盖 ACK。
|
||||
validateDocument(document,registry);
|
||||
return document;
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user