Zayden-Jung/Endoleap
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs(runtime): explain browser storage and depot transaction boundaries

Browse Source
This commit is contained in:
Codex Bot
2026-11-12 14:31:58 +08:00
parent 0ca2af7a37
commit 85b038a93f
2 changed files with 66 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/lib/canvas-runtime/asset-depot-storage.ts
+34 -14
View File
@@ -2,6 +2,7 @@
* 共享原图的 IndexedDB 实现：asset-depot 存身份/退休事实，asset-bytes 按摘要共享 Blob，
* asset-pins 按项目存与 Root 版本绑定的完整保留清单。所有 execute 都经过主存储的 leader/fence 检查。
* 回收只清本地共享字节，保留身份；同摘要还有其它活身份时不能删实际字节。
* 本模块不创建/提交事务：写入辅助函数借用外层事务，read/collect 借用注入的 execute；错误由其统一 abort。
*/
import {equal,fault,freeze} from '../canvas-core/values.ts';
import {sharedAssetRef,validateSharedAsset,type AssetDepotPort,type DepotCut,type DepotEntry,type SharedAsset} from './asset-depot.ts';
@@ -24,23 +25,31 @@ function authority(value:string){if(typeof value!=='string'||!value||value.lengt
/** 读取身份记录时验证 ref 与键一致、退休时钟合法，损坏数据不能被回收过程忽略。 */
function validateFact(row:Fact,scopeAuthority:string,id:string){validateSharedAsset(row?.ref);if(row.ref.authority!==scopeAuthority||row.ref.asset.id!==id)throw fault('corrupt_asset_depot');for(const n of [row.unreferencedAt,row.purgedAt])if(n!==undefined&&(!Number.isSafeInteger(n)||n<0))throw fault('corrupt_asset_depot');if(row.purgedAt!==undefined&&(row.unreferencedAt===undefined||row.purgedAt<row.unreferencedAt))throw fault('corrupt_asset_depot');}
/** Detach descriptors before awaiting crypto. Blob data is immutable and never JSON cloned. */
/** 第一个 await 前捕获/冻结 descriptors，校验 pin/写入唯一性；Blob 不做 JSON clone。 */
/** 同步重建 pin 数组与标准引用字段，让外层能在第一个 await 前捕获 cut；Blob 沿用不可变字节对象。
* pin ID 与 write ID 分别去重，不要求两表完全相等，也不证明 complete 声明覆盖全部 Root 引用。
* sharedAssetRef 保留 asset 扩展属性的引用，冻结不等于任意外来对象的递归深复制。 */
export function detachDepotCut(cut:DepotCut):DepotCut{
if(!cut||cut.version!==1||typeof cut.complete!=='boolean'||!Array.isArray(cut.pins)||!Array.isArray(cut.writes))throw fault('invalid_depot_cut');authority(cut.authority);
// seen 只检查资源 ID 唯一；每条 owner 列表还要非空、非重复，再复制冻结以脱离可变数组。
const seen=new Set<string>(),pins=cut.pins.map(row=>{if(!Array.isArray(row)||row.length!==2||typeof row[0]!=='string'||!row[0]||seen.has(row[0])||!Array.isArray(row[1])||!row[1].length||row[1].some(owner=>typeof owner!=='string'||!owner)||new Set(row[1]).size!==row[1].length)throw fault('invalid_depot_cut');seen.add(row[0]);return Object.freeze([row[0],Object.freeze([...row[1]])] as const);});
// write 可仅含引用以复用已存字节；提供 Blob 时这里只查类型，长度/摘要留给事务外 verifyDepotBytes。
const written=new Set<string>(),writes=cut.writes.map(row=>{validateSharedAsset(row.ref);if(row.ref.authority!==cut.authority||written.has(row.ref.asset.id)||row.bytes!==undefined&&!(row.bytes instanceof Blob))throw fault('invalid_depot_cut');written.add(row.ref.asset.id);return Object.freeze({ref:sharedAssetRef(row.ref),...(row.bytes?{bytes:row.bytes}:{})});});
return Object.freeze({version:1,authority:cut.authority,complete:cut.complete,pins:Object.freeze(pins),writes:Object.freeze(writes)});
}
/** 在 IDB 事务外计算原图 SHA256 并验长度，避免 await crypto 让事务提前失活。 */
/** 在 IDB 事务外逐项计算原图 SHA256 并验长度，避免 await crypto 让事务提前失活。
* 借用已捕获 cut；未附 bytes 的项不重读存储。一次整 Blob 转 ArrayBuffer，没有分块预算/取消信号。
* 摘要证明内容匹配声明，不验证服务权限、实际图片解码尺寸或 MIME；这些由其它端口负责。 */
export async function verifyDepotBytes(cut:DepotCut){
for(const row of cut.writes)if(row.bytes){if(row.bytes.size!==row.ref.asset.bytes)throw fault('shared_asset_bytes_changed',[row.ref.asset.id]);const digest=[...new Uint8Array(await crypto.subtle.digest('SHA-256',await row.bytes.arrayBuffer()))].map(n=>n.toString(16).padStart(2,'0')).join('');if(digest!==row.ref.digest)throw fault('shared_asset_bytes_changed',[row.ref.asset.id]);}
}
/** Must run in the same transaction as the project Root, including idempotent reindexing. */
/** 必须与项目 Root 同事务：校验既存身份、按 digest 写共享字节，并更新该项目 pin manifest。 */
/** 必须与项目 Root 同事务：校验既存身份、按 digest 写共享字节，并替换该项目 pin manifest。
* 调用前须 detach/verify；本函数不重算摘要，也不自行核对 rootRevision/leader。完成只表示请求已排入事务。 */
export async function writeDepotCut(tx:IDBTransaction,scope:StorageScope,rootRevision:number,cut:DepotCut){
const base=prefix(scope,cut.authority),facts=tx.objectStore('asset-depot'),bytes=tx.objectStore('asset-bytes');
for(const row of cut.writes){const key=[...base,row.ref.asset.id],previous=await value<Fact|undefined>(facts.get(key));if(previous){validateFact(previous,cut.authority,row.ref.asset.id);if(!equal(previous.ref,row.ref))throw fault('shared_asset_identity_conflict',[row.ref.asset.id]);}
// Digest-addressed bytes are shared across resource IDs and projects in this authority.
// 同 account/workspace/authority 的不同资源 ID 共用 digest 字节行。
// 再提供同一身份的已验证 bytes 可清掉软标记与 purgedAt；只有元信息的写入保持既有退休状态。
if(row.bytes)bytes.put(row.bytes,[...base,row.ref.digest]);
facts.put({...previous,ref:row.ref,...(row.bytes?{unreferencedAt:undefined,purgedAt:undefined}:{})},key);
}
@@ -57,9 +66,10 @@ function depotFile(row:unknown,id:string):DepotFile{
if(file.kind!=='asset-depot'||file.resourceId!==id||typeof file.digest!=='string'||!/^[a-f0-9]{64}$/.test(file.digest)||!Number.isSafeInteger(file.byteLength)||file.byteLength<1||file.byteLength>20*1024*1024||typeof file.mimeType!=='string')throw fault('corrupt_file_store');
return file;
}
/** Undefined means bytes were explicitly evicted; identity metadata remains. */
/** Blob 旧行直接返回；指针行核对共享身份/长度，字节已显式清理则返回 undefined。
* 返回时恢复项目原文件 MIME，不因服务检测 MIME 与本地不同而改变原文件合同。 */
/** Blob 旧行与不存在的行直接返回；指针行核对共享身份/长度，已 purge 或共享字节缺失均返回 undefined。
* undefined 本身不能区分从未写入、显式回收和缺失字节；缺少身份事实或字段冲突则抛损坏错误。
* 返回时恢复项目原文件 MIME，不因服务检测 MIME 与本地不同而改变原文件合同。
* 不重新哈希、不向服务器授权/下载；调用方须维持事务生命周期及外层读权限。 */
export async function resolveDepotFile(tx:IDBTransaction,scope:StorageScope,id:string,row:unknown):Promise<Blob|undefined>{
if(row===undefined||row instanceof Blob)return row;
const file=depotFile(row,id),base=prefix(scope,file.authority),fact=await value<Fact|undefined>(tx.objectStore('asset-depot').get([...base,id]));
@@ -73,7 +83,10 @@ export async function resolveDepotFile(tx:IDBTransaction,scope:StorageScope,id:s
return bytes.type===file.mimeType?bytes:bytes.slice(0,bytes.size,file.mimeType);
}
/** Convert only Root-proven stored uploads, after shared bytes and local files are written. */
/** Root 已证明 stored upload 且共享字节存在时，把项目 Blob 行改为指针；未确认上传绝不提前转。 */
/** 从已校验 Root 中读取 stored upload 声明，把本次 cut.writes 对应的项目 Blob 行改为共享指针。
* 只检查声明/身份与 Blob 长度和本地 MIME，不重新对比两份文件内容；字节摘要证明依赖外层流程。
* 缺 resource.stored、资源已 purge、无项目文件或无共享字节时跳过；不是扫描迁移项目中所有文件。
* 借用 Root/共享写入相同事务，后续任何冲突应由外层 abort，不能只保存部分已转换行。 */
export async function promoteDepotFiles(tx:IDBTransaction,scope:StorageScope,key:string,image:RecoveryImage,cut:DepotCut){
type Resource={id:string;digest?:string;byteLength:number;mimeType:string;stored?:SharedAsset['asset'];retirement?:{purgedAt?:number}};
const payload=image.payload as {runtime?:{resources?:readonly (readonly [string,Resource])[]}},entries=payload?.runtime?.resources;
@@ -92,15 +105,19 @@ export async function promoteDepotFiles(tx:IDBTransaction,scope:StorageScope,key
}
/** 注入主 adapter 的事务执行器，统一复用 metadata/fence/事务终态屏障。 */
type Execute=<T>(leader:StorageLeader,stores:string[],mode:IDBTransactionMode,run:(tx:IDBTransaction)=>Promise<T>)=>Promise<T>;
/** 为主 storage 装配 read/collect；调用者不能绕开有效 leader 直接操作跨项目共享行。 */
/** 为主 storage 装配 read/collect；leader/fence/事务终态由注入的 execute 保证，而非本工厂自行实现。
* 工厂不建立第二份缓存或连接；这些数据库身份检查也不替代远端资源授权。 */
export function createDepotStorage(execute:Execute):AssetDepotPort{return Object.freeze({
/** 读取本域身份与尚未 purge 的字节，元信息及 Blob 类型/长度都校验，缺字节不丢身份。 */
async read(leader,scopeAuthority,id){authority(scopeAuthority);if(typeof id!=='string'||!id)throw fault('invalid_resource_id');return execute(leader,depotStores,'readonly',async tx=>{const base=prefix(leader.scope,scopeAuthority),row=await value<Fact|undefined>(tx.objectStore('asset-depot').get([...base,id]));if(!row)return;validateFact(row,scopeAuthority,id);const bytes=row.purgedAt===undefined?await value<Blob|undefined>(tx.objectStore('asset-bytes').get([...base,row.ref.digest])):undefined;if(bytes!==undefined&&(!(bytes instanceof Blob)||bytes.size!==row.ref.asset.bytes))throw fault('corrupt_asset_depot');return freeze({...row,...(bytes?{bytes}:{})}) as DepotEntry;});},
/** 一次至多128身份的两阶段回收：先软标记，保留期过后 purge；完整性门禁覆盖所有本地项目。 */
/** 一页至多128身份的两阶段回收：先软标记，之后另一次访问满足保留期才 purge（即使 retentionMs=0）。
* 每次仍 getAll 本地项目 metadata 与本授权域全部 fact，页大小不限制全量扫描/驻留量。
* complete=true 只表示清单门禁通过；若有 nextAfter，调用者还需继续下一页，不等于整仓库已回收。 */
async collect(leader,input){authority(input.authority);const {now,retentionMs,limit,after}=input;if(!Number.isSafeInteger(now)||now<0||!Number.isSafeInteger(retentionMs)||retentionMs<0||!Number.isSafeInteger(limit)||limit<1||limit>128||after!==undefined&&(typeof after!=='string'||!after))throw fault('invalid_depot_collection');
return execute(leader,depotStores,'readwrite',async tx=>{
const scope=leader.scope,metadata=tx.objectStore('metadata'),keys=await value(metadata.getAllKeys()),heads=await value<{throughRevision?:number}[]>(metadata.getAll()),base=prefix(scope,input.authority),manifests=tx.objectStore('asset-pins'),blockedProjects:string[]=[],pinned=new Set<string>();
// 包括已关闭项目：其 manifest 必须与当前 Root 头一致，任一缺失/过期/opaque 都阻止删除。
// getAllKeys/getAll 在同一事务按相同键序对应。包括同账号工作区的已关闭项目；尚无可靠 Root 的头跳过。
// 每个有 Root 项目的本授权域 manifest 必须同 revision 且 complete；不要求项目当前持有 leader。
for(let i=0;i<keys.length;i++){let parts:unknown;try{parts=JSON.parse(String(keys[i]));}catch{throw fault('corrupt_storage_scope');}if(!Array.isArray(parts)||parts.length!==3||parts.some(p=>typeof p!=='string'||!p))throw fault('corrupt_storage_scope');if(parts[0]!==scope.accountId||parts[1]!==scope.workspaceId||heads[i].throughRevision===undefined)continue;
const pins=await value<Pins|undefined>(manifests.get([...base,parts[2]]));if(!pins||pins.version!==1||pins.rootRevision!==heads[i].throughRevision||pins.complete!==true){blockedProjects.push(parts[2]);continue;}
if(!Array.isArray(pins.pins))throw fault('corrupt_depot_pins');for(const row of pins.pins){if(!Array.isArray(row)||row.length!==2||typeof row[0]!=='string'||!row[0]||!Array.isArray(row[1])||!row[1].length||row[1].some(owner=>typeof owner!=='string'||!owner))throw fault('corrupt_depot_pins');pinned.add(row[0]);}
@@ -109,11 +126,14 @@ export function createDepotStorage(execute:Execute):AssetDepotPort{return Object
if(blockedProjects.length)return freeze({complete:false,blockedProjects,markedIds:[],purgedIds:[],pinnedIds:[]});
const store=tx.objectStore('asset-depot'),factKeys=await value(store.getAllKeys(range(scope,input.authority))),rows=await value<Fact[]>(store.getAll(range(scope,input.authority))),markedIds:string[]=[],purgedIds:string[]=[],pinnedIds:string[]=[];
for(let i=0;i<rows.length;i++){const key=factKeys[i];if(!Array.isArray(key)||key.length!==4||typeof key[3]!=='string')throw fault('corrupt_asset_depot');validateFact(rows[i],input.authority,key[3]);}
// 先验证本域记录，再按资源 ID 游标截取一页，多取一条判断是否还有下一页。
// 所有 fact 先验证再分页：页外损坏也阻止本次回收。复合 IDB 键序提供资源 ID 顺序，after 严格排除自身。
// 多取一条只判断后续候选；已 purge/仍 pinned 的身份也占页名额，不是 limit 个实际删除。
const candidates=rows.map((row,i)=>({row,key:factKeys[i] as string[]})).filter(({key})=>after===undefined||key[3]>after).slice(0,limit+1),page=candidates.slice(0,limit);
// repin 清软标记；无引用首次记录时刻；时钟倒退不提前 purge；永久身份不重新分配。
// repin 只清尚未 purge 的软标记；已 purge 身份即使重新被 pin 也不在此复活字节。
// 未引用首次只记录时刻；之后满足保留期才 purge，时钟倒退不提前清理；身份行始终保留。
for(const {row,key}of page){const id=key[3];if(pinned.has(id)){pinnedIds.push(id);if(row.purgedAt===undefined&&row.unreferencedAt!==undefined){delete row.unreferencedAt;store.put(row,key);}continue;}if(row.purgedAt!==undefined)continue;if(row.unreferencedAt===undefined){row.unreferencedAt=now;markedIds.push(id);store.put(row,key);}else if(now>=row.unreferencedAt&&now-row.unreferencedAt>=retentionMs){row.purgedAt=now;purgedIds.push(id);store.put(row,key);}}
// Preserve a digest while any other live resource identity still owns its bytes.
// rows 与 page 共用本事务读出的 row 对象，已写的 purgedAt 可直接参与全域存活判断。
// 同摘要任一身份尚未 purge（即使未 pin、仍在保留期）都保留字节；最后一份退休后才删 digest 行。
for(const digest of new Set(page.filter(({row})=>row.purgedAt===now).map(({row})=>row.ref.digest)))if(!rows.some(row=>row.ref.digest===digest&&row.purgedAt===undefined))tx.objectStore('asset-bytes').delete([...base,digest]);
return freeze({complete:true,blockedProjects:[],markedIds,purgedIds,pinnedIds,...(candidates.length>limit?{nextAfter:page.at(-1)!.key[3]}:{})});
});
src/lib/canvas-runtime/storage.ts
+32 -12
View File
@@ -3,6 +3,7 @@
* DB schema v5 的七个 store 保存 Root checkpoint/journal、文件与共享 depot，历史/ledger 等在恢复图像内。
* crypto/JSON 编码在事务外完成；Root、文件增删和 depot 清单在同一事务提交，oncomplete 才算 durable。
* DB schema、checkpointVersion、journalVersion、RecoveryImage.formatVersion 是独立兼容域，不能混用。
* adapter 实例持有连接与 leader 集合，per-leader WeakMap 保存写尾链/可靠基线；close 不代替 engine 的持久化排空。
*/
import {serializeRecoveryImage} from './recovery-json.ts';
import {depotStores,createDepotStorage,detachDepotCut,verifyDepotBytes,writeDepotCut,promoteDepotFiles,resolveDepotFile} from './asset-depot-storage.ts';
@@ -18,7 +19,8 @@ export type {StorageScope,RecoveryImage,DurableBatch,StorageLeader,StoredFileInf
type Metadata = { fence: number; throughRevision?: number; checkpointRevision?: number };
/** 兼容旧完整图像行：image 与对其 JSON 表示计算的摘要。 */
type StoredImage = { readonly image: RecoveryImage; readonly checksum: string };
/** journal 差分：必须匹配前一 Root 的 revision/checksum；v1/v2 摘要覆盖范围不同。 */
/** journal 差分：必须匹配前一 Root 的 revision/checksum；v1 哈希结果图像，v2 哈希 deltaBody。
* 因此 StoredImage.checksum 在内存中也可能是当前日志链节点摘要，并非总是 image 的独立摘要。 */
type StoredDelta = {journalVersion:1|2;baseRevision:number;baseChecksum:string;header:Omit<RecoveryImage,'payload'>;patches:JournalPatch[];checksum:string};
/** 新完整 checkpoint 以 UTF-8 Blob 保存，header 便于事务内检查连续性，解析/校验在事务外。 */
type StoredBlobImage={readonly checkpointVersion:1;readonly header:Omit<RecoveryImage,'payload'>;readonly bytes:Blob;readonly checksum:string};
@@ -68,7 +70,9 @@ const requestValue = <T>(request: IDBRequest<T>) => new Promise<T>((resolve, rej
const transactionDone = (transaction: IDBTransaction) => new Promise<void>((resolve, reject) => { transaction.oncomplete = () => resolve(); transaction.onabort = () => reject(transaction.error ?? fault('storage_aborted')); transaction.onerror = () => { /* onabort is the terminal barrier. */ }; });
/** Single-origin browser adapter. Web Locks serialize tabs; a DB fence rejects stale handles. */
/** 需要 IndexedDB 与 Web Locks；缺能力时明确拒绝，不悄悄退成无法可靠恢复的内存存储。 */
/** 需要 IndexedDB 与 Web Locks；缺能力时明确拒绝，不悄悄退成无法可靠恢复的内存存储。
* 构造即开始打开数据库，尚未持有项目写锁；claim 才按 scope 取锁。工厂返回冻结能力外壳，内部连接状态仍可变。
* name/options 应由宿主保持稳定，锁名读取 options.name；不能把同一数据库意外装配成不同锁域。 */
export function createBrowserStorage(options: { indexedDB?: IDBFactory; locks?: LockManager; name?: string; checkpointEvery?: number } = {}): StoragePort {
const factory = options.indexedDB ?? globalThis.indexedDB, locks = options.locks ?? globalThis.navigator?.locks;
if (!factory || !locks) throw fault('persistent_storage_unavailable');
@@ -113,13 +117,17 @@ export function createBrowserStorage(options: { indexedDB?: IDBFactory; locks?:
if (!metadata || metadata.fence !== leader.fence) throw fault('storage_fence_lost');
check(leader);
const result = await run(transaction, metadata, key);
// readwrite 的原子可见性与可靠回执都在 oncomplete 后成立；callback 返回值只是待采纳结果。
await done; // Never resolve durability on an individual put callback.
return result;
} catch (error) { try { transaction.abort(); } catch { /* Already terminal. */ } await done.catch(() => {}); throw error; }
}
/** 先在只读事务捕获完整日志区间，再在事务外重建/哈希，最后才缓存可靠恢复结果。 */
/** 先在只读事务捕获完整日志区间，再在事务外重建/哈希，最后才缓存可靠恢复结果。
* 返回的是该只读快照，不保证 crypto 完成时仍是最新 Root；并发较新恢复已入缓存时不将其倒退。
* 捕获整个回放区间，逐条 apply/hash 没有独立合作预算；存储信封通过后仍需领域 decodeRecovery 深校验。 */
async function recoverCut(leader:StorageLeader):Promise<StoredImage|null>{
const captured=await execute(leader,['checkpoints','journal'],'readonly',async(transaction,metadata,key)=>{
// 没有可靠头就返回 null；不据此推断 files/depot 中没有尚未归属或共享的字节。
if(metadata.throughRevision===undefined)return{cuts:[] as StoredCut[],checkpointRevision:undefined};
if(metadata.checkpointRevision===undefined)throw fault('recovery_checkpoint_missing');
const checkpoint=await requestValue<StoredCut|undefined>(transaction.objectStore('checkpoints').get([key,metadata.checkpointRevision]));
@@ -156,14 +164,17 @@ export function createBrowserStorage(options: { indexedDB?: IDBFactory; locks?:
fileDeletion:'atomic-v1' as const,
/** 共享仓库也走 execute，因此同样受 metadata fence 与事务终态约束。 */
assetDepot:createDepotStorage((leader,stores,mode,run)=>execute(leader,stores,mode,tx=>run(tx))),
/** 非阻塞申请 scope 排他 Web Lock；取得后先可靠递增 DB fence，再把 leader 暴露给 engine。 */
/** 用 ifAvailable 申请 scope 排他 Web Lock：不排队等其它持有者，但仍异步等数据库与 fence 事务。
* scope 按入口标量构造锁键、取得后复制进 handle，调用者须在异步 claim 期间保持输入稳定。
* 同一 adapter 不同 scope 可持不同锁；execute 仍用 metadata fence 拒绝旧句柄。 */
async claim(scope: StorageScope) {
const key = keyFor(scope);
if (closed) throw fault('storage_closed');
let unlock!: () => void, acquired!: (leader: StorageLeader) => void, failed!: (error: unknown) => void;
const released = new Promise<void>(resolve => { unlock = resolve; });
const result = new Promise<StorageLeader>((resolve, reject) => { acquired = resolve; failed = reject; });
// Lock 回调等待 released Promise 保持锁；leader.release 幂等失效句柄后解锁并等回调结束。
// result 只交付 handle，held 则覆盖整个持锁生命周期；released 是二者之间的释放闸门。
// 首次 release 先失效/移出集合再解锁并等 held，重复调用会立即返回，不是另一次排空等待。
const held = locks.request(`endoleap-headless:${options.name ?? 'endoleap-headless'}:${key}`, { mode: 'exclusive', ifAvailable: true }, async lock => {
if (!lock) throw fault('storage_scope_in_use');
const database = await opening;
@@ -187,10 +198,12 @@ export function createBrowserStorage(options: { indexedDB?: IDBFactory; locks?:
async recover(leader: StorageLeader) {const cut=await recoverCut(leader);return cut?clone(cut.image):null;},
/** 捕获批次→校验删除证明→顺序准备编码→原子写 Root/文件/depot；返回实际 durableRootRevision。 */
async commit(leader: StorageLeader, batch: DurableBatch) {
// Detach mutable callers and descriptors before the first await, including queued commits.
// 入队前捕获图像与描述符，避免排在旧写入后等待时被调用者改写；codec-owned sealed 图像可直接复用。
// file 外壳复制而 Blob 原样借用；depot 用自己的捕获器，均不代表已经可靠落盘。
const depot=batch.depot?detachDepotCut(batch.depot):undefined;
const image=isSealedRecoveryImage(batch.image)?batch.image:freeze(clone(batch.image)),files=(batch.files??[]).map(file=>({id:file.id,bytes:file.bytes})),deleteFiles=[...(batch.deleteFiles??[])];if(deleteFiles.length>128||new Set(deleteFiles).size!==deleteFiles.length||deleteFiles.some(id=>typeof id!=='string'||!id||files.some(file=>file.id===id)))throw fault('invalid_file_deletion');if(!isSealedRecoveryImage(image))validateImage(image);
// 删除仅接受当前图像中已 purge 的版本化证明，不能在普通文件 API 中绕开 history/pin 保留。
// 删除依据当前提交图像的退休声明：最多128个唯一 ID，不能同批又新增。
// 这里检查证明形状/归属/任务终态，不自行重算 history pin 或保留期；Root 完整性由引擎负责。
if(deleteFiles.length){
type FileProof={id?:string;version?:number;byteLength?:number;mimeType?:string;digest?:string;fileId?:string;retirement?:{version:number;unreferencedAt:number;purgedAt?:number}};
const payload=image.payload as {runtime?:{orphanFiles?:[string,FileProof][];resources?:[string,FileProof][];imports?:[string,{status:string;source?:FileProof&{previousFiles?:FileProof[]}}][]}};
@@ -203,15 +216,18 @@ export function createBrowserStorage(options: { indexedDB?: IDBFactory; locks?:
if(image.formatVersion<3||deleteFiles.some(id=>{const marker=proofs.get(id)?.retirement;return !marker||marker.version!==1||!Number.isSafeInteger(marker.unreferencedAt)||marker.unreferencedAt<0||!Number.isSafeInteger(marker.purgedAt)||marker.purgedAt!<marker.unreferencedAt;}))throw fault('invalid_file_deletion');
}
check(leader);
// 串联同 leader 的保存；前次失败不永久毒化链，但新提交仍必须匹配真实 DB 头与连续 revision。
// 同 leader 的 crypto/编码/事务也串在一条 Promise 尾链上，避免各自准备不同基线后乱序提交。
// 吞掉旧尾链失败只为继续调度，新请求错误仍向其调用者传播；不自动重试旧批次或跨 leader 排队。
const task=(writeTails.get(leader)??Promise.resolve()).catch(()=>{}).then(async()=>{
if(depot)await verifyDepotBytes(depot);
let base=lastCuts.get(leader)??await recoverCut(leader);
if(base?.image.rootRevision===image.rootRevision)base=await recoverCut(leader);
if(files.length&&base){const retired=purgedFileIds(base.image);if(files.some(file=>retired.has(file.id)))throw fault('resource_identity_conflict');}
// 周期检查点或新版格式转换可切完整基线，避免旧 reader 被迫从更高格式差分恢复。
// checkpoint 决定替换可靠回放起点；没有基线、达到间隔，或基线版本 >=7 且格式变化时建立新起点。
// delta 不划算也会写完整 Blob，但若 checkpoint=false，它仍是 journal 中的一行，不压缩旧链。
const baseCheckpoint=lastCheckpoints.get(leader),checkpoint=!base||((base.image.formatVersion>=7)&&base.image.formatVersion!==image.formatVersion)||image.rootRevision-(baseCheckpoint??0)>=checkpointEvery;
let stored:StoredImage|undefined,candidate:StoredCut|undefined;
// 同 revision 先沿用已恢复的链摘要；事务内仍逐字比较整 image、查 DB 头，不能只凭 revision 接受重试。
if(base?.image.rootRevision===image.rootRevision){stored={image,checksum:base.checksum};candidate=stored;}
// 连续且标准信封才尝试 delta；比较真实字节成本，差分过大/不可表达则回退完整 Blob。
else if(base&&!checkpoint&&image.rootRevision===base.image.rootRevision+1&&JSON.stringify(Object.keys(image))===JSON.stringify(['formatVersion','rootRevision','localRevision','payload'])){
@@ -232,7 +248,8 @@ export function createBrowserStorage(options: { indexedDB?: IDBFactory; locks?:
const previous=metadata.throughRevision;
if(previous===undefined&&base)throw fault('recovery_delta_base_mismatch');
const saved=previous===undefined?undefined:await requestValue<StoredCut>(transaction.objectStore(metadata.checkpointRevision===previous?'checkpoints':'journal').get([key,previous]));
// 同 Root 重试只允许完全相同图像/摘要且无新文件写入；缺口或异内容一律拒绝。
// 同 Root 重试须图像/摘要相同、无新增文件，且请求删除的行已经不存在；不再写 Root。
// 可在这条分支补写 depot 清单/字节与文件指针，支持幂等重建索引；事务失败仍整体回滚。
if(previous!==undefined&&image.rootRevision!==previous+1){
if(image.rootRevision!==previous)throw fault('storage_revision_gap');
if(!saved||saved.checksum!==accepted.checksum||!base||JSON.stringify(base.image)!==JSON.stringify(image)||files.length)throw fault('storage_revision_conflict');for(const id of deleteFiles)if(await requestValue(transaction.objectStore('files').getKey([key,id])))throw fault('storage_revision_conflict');if(depot){await writeDepotCut(transaction,leader.scope,image.rootRevision,depot);await promoteDepotFiles(transaction,leader.scope,key,image,depot);}return{durableRootRevision:previous,checkpointRevision:metadata.checkpointRevision!};
@@ -258,7 +275,9 @@ export function createBrowserStorage(options: { indexedDB?: IDBFactory; locks?:
});
writeTails.set(leader,task);return task;
},
/** 按 expectedRootRevision 的稳定 ID 游标分页盘点，最多128项；Root 改变则拒绝拼接旧页。 */
/** 按 expectedRootRevision 的稳定 ID 游标分页盘点，最多128项；Root 改变则拒绝拼接旧页。
* limit 约束返回的可读取文件数，不约束游标经过的已清理指针数；不计算 digest，也不做远端读取。
* 同 Root 的 depot 回收可能改变可读字节，revision 门禁不等于跨多次调用持有同一 IDB 快照。 */
scanFiles(leader:StorageLeader,input:{expectedRootRevision:number;after?:string;limit:number}) {
const {expectedRootRevision,after,limit}=input;
if(!Number.isSafeInteger(expectedRootRevision)||expectedRootRevision<0||!Number.isSafeInteger(limit)||limit<1||limit>128||after!==undefined&&(typeof after!=='string'||!after))return Promise.reject(fault('invalid_file_inventory'));
@@ -280,7 +299,8 @@ export function createBrowserStorage(options: { indexedDB?: IDBFactory; locks?:
},
/** 在有效 fence 下读取本地 Blob 或共享字节指针；缺字节返回 undefined，不伪造空文件。 */
readFile(leader: StorageLeader, id: string) { return execute(leader, ['files',...depotStores], 'readonly', async(transaction, _metadata, key) => resolveDepotFile(transaction,leader.scope,id,await requestValue<unknown>(transaction.objectStore('files').get([key, id])))); },
/** 停止新存储操作、释放 leader 并关闭数据库；宿主须先等 engine 保存完成，再释放 adapter。 */
/** 同步使 adapter 关闭并触发 leader.release/连接关闭，不返回排空 Promise，也不主动 abort 所有在途事务。
* 已开始事务由 IDB 自行结束，未开始任务会在 check 被拒绝；宿主须先等 engine 保存完成再释放 adapter。 */
close() { closed = true; for (const handle of handles) void handle.release(); void opening.then(database => database.close()).catch(() => {}); },
});
}