docs(canvas): explain host ownership, asset retention and durable storage
This commit is contained in:
@@ -1,14 +1,21 @@
|
||||
/**
|
||||
* 历史残留文件的盘点、保留与身份保护。孤儿不是“当前画布没显示”,而是经过完整引用/任务检查
|
||||
* 仍无归属的实际文件;注册后保留身份,永久清理后也不能忘记记录或把 ID 重新分给其它内容。
|
||||
*/
|
||||
import type {Id,Registry} from '../canvas-core/types.ts';
|
||||
import {equal,fault,freeze,readMap} from '../canvas-core/values.ts';
|
||||
import type {EngineSnapshot,RuntimeState} from './contracts.ts';
|
||||
import {importFiles,terminalImport,validFileRetirement,type FileRetirement} from './import-file-retention.ts';
|
||||
import {resourceRetentionPins} from './resource-retention.ts';
|
||||
|
||||
/** 盘点确认的文件身份/摘要与退休状态,不是上传资源元数据,也不是 DOM 图片缓存。 */
|
||||
export type OrphanFile={readonly version:1;readonly id:Id;readonly byteLength:number;readonly mimeType:string;readonly digest:string;readonly retirement?:FileRetirement};
|
||||
/** 检查 ID、字节数、MIME、SHA256 和退休解释器;失败不默默忽略损坏文件记录。 */
|
||||
export function validateOrphanFile(value:unknown,id:Id):asserts value is OrphanFile {
|
||||
const file=value as OrphanFile;
|
||||
if(!file||file.version!==1||file.id!==id||!id||!Number.isSafeInteger(file.byteLength)||file.byteLength<0||typeof file.mimeType!=='string'||typeof file.digest!=='string'||!/^[a-f0-9]{64}$/.test(file.digest)||file.retirement!==undefined&&!validFileRetirement(file.retirement))throw fault('invalid_orphan_file');
|
||||
}
|
||||
/** 结合 pin 与所有未解释任务/审计证据给出回收阻碍;blockers 非空即 complete=false。 */
|
||||
export function orphanCoverage(snapshot:EngineSnapshot,registry:Registry,displays:ReadonlyMap<Id,number>,temporary:ReadonlyMap<Id,readonly Id[]>) {
|
||||
const pins=resourceRetentionPins(snapshot,registry,displays,temporary),blockers:string[]=[];
|
||||
if(!pins.complete)blockers.push('opaque_references');
|
||||
@@ -20,13 +27,16 @@ export function orphanCoverage(snapshot:EngineSnapshot,registry:Registry,display
|
||||
return Object.freeze({...pins,complete:blockers.length===0,blockers:Object.freeze(blockers)});
|
||||
}
|
||||
/** Registered orphan identities survive repinning. Purged identities cannot be forgotten or reassigned. */
|
||||
/** 在发布前维护孤儿事实与回收 reservations:身份不得与资源/导入源冲突,已 purge 不得改写。 */
|
||||
export function prepareOrphanFiles(previous:RuntimeState,next:RuntimeState,coverage:()=>{complete:boolean;pins:ReadonlyMap<Id,unknown>},reserved:ReadonlySet<Id>,referencesChanged:boolean):RuntimeState {
|
||||
if(!previous.orphanFiles?.size&&!next.orphanFiles?.size)return next;
|
||||
const hasSoft=[...(next.orphanFiles?.values()??[])].some(file=>file.retirement&&file.retirement.purgedAt===undefined);
|
||||
if(previous.orphanFiles===next.orphanFiles&&previous.resources===next.resources&&previous.imports===next.imports&&!reserved.size&&!referencesChanged&&!hasSoft)return next;
|
||||
// 即使孤儿后来被引用也保留其注册身份;只能撤销软退休,不能从表里悄悄删掉历史事实。
|
||||
const sources=importFiles(next.imports);
|
||||
for(const [id,file]of next.orphanFiles??[]){validateOrphanFile(file,id);if(next.resources.has(id)||sources.has(id))throw fault('local_file_identity_conflict',[id]);}
|
||||
for(const [id,file]of previous.orphanFiles??[]){const after=next.orphanFiles?.get(id);if(!after||file.retirement?.purgedAt!==undefined&&!equal(file,after))throw fault('local_file_retired',[id]);}
|
||||
// 覆盖不足/重 pin 取消软退休;永久删除后重 pin 明确拒绝,不能让模型引用失去字节的 ID。
|
||||
const pins=coverage(),clear:Id[]=[];
|
||||
for(const [id,file]of next.orphanFiles??[]){
|
||||
if(reserved.has(id)&&(!pins.complete||pins.pins.has(id)))throw fault('resource_collection_in_progress',[id]);
|
||||
@@ -38,6 +48,7 @@ export function prepareOrphanFiles(previous:RuntimeState,next:RuntimeState,cover
|
||||
}
|
||||
|
||||
/** Read-only I/O may finish late; cancellation detaches its result without publishing it. */
|
||||
/** 取消只让调用者停止采纳读取结果,不保证底层只读 I/O 被终止;迟到成功/失败均已接住。 */
|
||||
export function abortableFileRead<T>(task:Promise<T>,signal:AbortSignal):Promise<T>{
|
||||
return new Promise((resolve,reject)=>{const abort=()=>{signal.removeEventListener('abort',abort);reject(fault('file_inventory_aborted'));};signal.addEventListener('abort',abort,{once:true});if(signal.aborted)abort();task.then(value=>{signal.removeEventListener('abort',abort);if(!signal.aborted)resolve(value);},error=>{signal.removeEventListener('abort',abort);if(!signal.aborted)reject(error);});});
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user