Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
feat(library): 暂存未入库原件并在确认归档后释放 (#4730)
Praiseb032d35e6fa5
diff --git a/apps/desktop/src/main/cindy-brain/__tests__/forge.test.ts b/apps/desktop/src/main/cindy-brain/__tests__/forge.test.tsindex e4e0fd31ca..44657f92e6 100644--- a/apps/desktop/src/main/cindy-brain/__tests__/forge.test.ts+++ b/apps/desktop/src/main/cindy-brain/__tests__/forge.test.ts@@ -1704,7 +1704,7 @@ describe('FORGE_GUIDE', () => {it('documents library capabilities as a sessionless support list with stable failure reasons', () => {expect(FORGE_GUIDE).toContain("op: 'capabilities'");- expect(FORGE_GUIDE).toContain("operations:['clipboardWrite','saveAs']");+ expect(FORGE_GUIDE).toContain("operations:['clipboardWrite','saveAs','staging.begin'");expect(FORGE_GUIDE).toContain('不等于此刻有窗口 / 已授权 / 库可用');expect(FORGE_GUIDE).toContain('全部字符串');expect(FORGE_GUIDE).toContain('数组内混入');diff --git a/apps/desktop/src/main/cindy-brain/__tests__/libraryBinding.test.ts b/apps/desktop/src/main/cindy-brain/__tests__/libraryBinding.test.tsindex 396ed5aebd..9fadc3e5c9 100644--- a/apps/desktop/src/main/cindy-brain/__tests__/libraryBinding.test.ts+++ b/apps/desktop/src/main/cindy-brain/__tests__/libraryBinding.test.ts@@ -49,6 +49,10 @@ describe('LibraryBindingStore', () => {expect(set.ok).toBe(true);if (!set.ok) return;expect(set.record.generation).toBe(1);+ expect(set.record.libraryReady).toBe(false);+ await store.markLibraryReady(GHOST_ID);+ expect((await store.getBinding(GHOST_ID))?.libraryReady).toBe(true);+ expect((await store.getBinding(GHOST_ID))?.generation).toBe(1);const after = await store.resolveLibraryRoot(GHOST_ID);expect(after.kind).toBe('custom');diff --git a/apps/desktop/src/main/cindy-brain/__tests__/librarySlot.test.ts b/apps/desktop/src/main/cindy-brain/__tests__/librarySlot.test.tsindex 61a1c0cbf7..11ffee7bd1 100644--- a/apps/desktop/src/main/cindy-brain/__tests__/librarySlot.test.ts+++ b/apps/desktop/src/main/cindy-brain/__tests__/librarySlot.test.ts@@ -27,6 +27,7 @@ import { createLibraryDbCore, type SqliteDatabaseConstructor } from '../libraryDimport { LibrarySqlService } from '../librarySqlService.js';import {classifyGhostLibraryOperationSupport,+ GHOST_LIBRARY_CAPABILITIES_V1,type InstalledGhost,} from '../../../shared/ghost.js';@@ -112,6 +113,7 @@ describe('GhostLibrarySlot', () => {showSaveDialog: (...args: unknown[]) => showSaveDialog(...args),writeClipboardPng: (...args: unknown[]) => writeClipboardPng(...args),syncAgentReadonlyExtraDir: (...args: unknown[]) => syncAgentReadonlyExtraDir(...args),+ getStagingRoot: (id) => path.join(tmp, 'library-staging', id),now: () => clock,};showItemInFolder = vi.fn();@@ -166,7 +168,11 @@ describe('GhostLibrarySlot', () => {expect(r).toEqual({ok: true,op: 'capabilities',- capabilities: { version: 1, operations: ['clipboardWrite', 'saveAs'] },+ capabilities: {+ version: 1,+ operations: [...GHOST_LIBRARY_CAPABILITIES_V1.operations],+ staging: { ...GHOST_LIBRARY_CAPABILITIES_V1.staging },+ },});expect(classifyGhostLibraryOperationSupport(r, 'clipboardWrite')).toBe('supported');expect(classifyGhostLibraryOperationSupport(r, 'saveAs')).toBe('supported');@@ -360,7 +366,11 @@ describe('GhostLibrarySlot', () => {expect(capsWhileUnavailable).toEqual({ok: true,op: 'capabilities',- capabilities: { version: 1, operations: ['clipboardWrite', 'saveAs'] },+ capabilities: {+ version: 1,+ operations: [...GHOST_LIBRARY_CAPABILITIES_V1.operations],+ staging: { ...GHOST_LIBRARY_CAPABILITIES_V1.staging },+ },});// 绝不落默认根冒充。expect(fs.existsSync(path.join(defaultRootBase, GHOST_ID, 'a.txt'))).toBe(false);@@ -433,6 +443,27 @@ describe('GhostLibrarySlot', () => {expect(fs.existsSync(path.join(candidate, GHOST_ID, 'keep.txt'))).toBe(false);});+ it('custom 已 ready 后只丢 ghost 子目录: dispose 后再 open 不得重建空库', async () => {+ const bound = await bindingStore.setBinding(GHOST_ID, candidate);+ expect(bound.ok).toBe(true);+ const open = await slot.handleLibraryRequest(GHOST_ID, { op: 'open' });+ if (!open.ok || open.op !== 'open') throw new Error(JSON.stringify(open));+ expect(open.state).toBe('ready');+ expect((await bindingStore.getBinding(GHOST_ID))?.libraryReady).toBe(true);+ const keep = await slot.handleLibraryRequest(GHOST_ID, { op: 'write', path: 'keep.txt', content: 'keep-me' });+ expect(keep.ok).toBe(true);+ const customRoot = path.join(candidate, GHOST_ID);+ await fs.promises.rename(customRoot, `${customRoot}.parked`);+ await slot.disposeAll();+ const after = await slot.handleLibraryRequest(GHOST_ID, { op: 'open' });+ if (!after.ok || after.op !== 'open') throw new Error(JSON.stringify(after));+ expect(after.state).toBe('unavailable');+ expect(after.reason).toBe('disk-missing');+ expect(fs.existsSync(path.join(customRoot, '.cindy-library', 'meta.json'))).toBe(false);+ expect(fs.existsSync(path.join(`${customRoot}.parked`, 'keep.txt'))).toBe(true);+ const blocked = await slot.handleLibraryRequest(GHOST_ID, { op: 'write', path: 'empty.txt', content: 'nope' });+ expect(blocked).toMatchObject({ ok: false, errorCode: 'LIBRARY_UNAVAILABLE' });+ });it('delayed resolveLibraryRoot: stale custom after parent rename is disk-missing without recreating empty library', async () => {const bound = await bindingStore.setBinding(GHOST_ID, candidate);expect(bound.ok).toBe(true);@@ -1621,4 +1652,449 @@ describe('GhostLibrarySlot', () => {expect(resolveLibraryAssetPath(rootA, path.join(rootA, rel))).toBeNull();expect(resolveLibraryAssetPath('relative-root', ref)).toBeNull();});++ it('staging 在 Library 根不可用时仍可 commit;release 只认当前 Library ACK', async () => {+ const body = 'pixel-bytes';+ const sha = createHash('sha256').update(body).digest('hex');+ const rel = `assets/${sha.slice(0, 2)}/${sha}/blob.png`;+ const recovery = { sceneId: 's1', nodeId: 'n1' };+ const begin = await slot.handleLibraryRequest(GHOST_ID, {+ op: 'staging.begin',+ taskId: 'task-1',+ sourceRevision: 'rev-1',+ totalBytes: Buffer.byteLength(body),+ sha256: sha,+ mime: 'image/png',+ recovery,+ });+ if (!begin.ok || begin.op !== 'staging.begin') throw new Error(JSON.stringify(begin));+ expect(resolveLibraryRoot).not.toHaveBeenCalled();+ const chunk = await slot.handleLibraryRequest(GHOST_ID, {+ op: 'staging.chunk', stagingId: begin.stagingId, seq: 1, content: Buffer.from(body).toString('base64'), encoding: 'base64',+ });+ expect(chunk).toMatchObject({ ok: true, op: 'staging.chunk', accepted: Buffer.byteLength(body) });+ const commit = await slot.handleLibraryRequest(GHOST_ID, { op: 'staging.commit', stagingId: begin.stagingId });+ expect(commit).toMatchObject({+ ok: true, op: 'staging.commit', stagingId: begin.stagingId, taskId: 'task-1',+ sourceRevision: 'rev-1', sha256: sha, bytes: Buffer.byteLength(body), mime: 'image/png', durable: true,+ });+ const listed = await slot.handleLibraryRequest(GHOST_ID, { op: 'staging.list' });+ if (!listed.ok || listed.op !== 'staging.list') throw new Error(JSON.stringify(listed));+ expect(listed.items).toHaveLength(1);+ expect(listed.items[0]?.recovery).toEqual(recovery);++ const bound = await bindingStore.setBinding(GHOST_ID, candidate);+ expect(bound.ok).toBe(true);+ await slot.handleLibraryRequest(GHOST_ID, { op: 'open' });+ await fs.promises.rename(candidate, `${candidate}.parked`);+ const missingRelease = await slot.handleLibraryRequest(GHOST_ID, {+ op: 'staging.release',+ stagingId: begin.stagingId,+ path: rel,+ sha256: sha,+ bytes: Buffer.byteLength(body),+ libraryIdentity: '0'.repeat(64),+ libraryGeneration: 1,+ });+ expect(missingRelease).toMatchObject({ ok: false, errorCode: 'LIBRARY_UNAVAILABLE' });+ await fs.promises.rename(`${candidate}.parked`, candidate);++ const archived = await slot.handleLibraryRequest(GHOST_ID, {+ op: 'write', path: rel, content: Buffer.from(body).toString('base64'), encoding: 'base64',+ });+ if (!archived.ok || archived.op !== 'write') throw new Error(JSON.stringify(archived));+ const released = await slot.handleLibraryRequest(GHOST_ID, {+ op: 'staging.release',+ stagingId: begin.stagingId,+ path: rel,+ sha256: sha,+ bytes: Buffer.byteLength(body),+ libraryIdentity: archived.libraryIdentity,+ libraryGeneration: archived.libraryGeneration,+ });+ expect(released).toEqual({ ok: true, op: 'staging.release', stagingId: begin.stagingId, released: true });+ const listedAfter = await slot.handleLibraryRequest(GHOST_ID, { op: 'staging.list' });+ if (!listedAfter.ok || listedAfter.op !== 'staging.list') throw new Error(JSON.stringify(listedAfter));+ expect(listedAfter.items).toEqual([]);+ expect(fs.existsSync(path.join(tmp, 'library-staging', GHOST_ID, 'tasks', begin.stagingId, 'blob.bin'))).toBe(false);+ });++ it('staging.release 在 hash 期间 relocate/dispose 后不得删原件', async () => {+ const body = 'pixel-bytes';+ const sha = createHash('sha256').update(body).digest('hex');+ const rel = `assets/${sha.slice(0, 2)}/${sha}/blob.png`;+ const begin = await slot.handleLibraryRequest(GHOST_ID, {+ op: 'staging.begin', taskId: 'task-relocate', sourceRevision: 'rev-1',+ totalBytes: Buffer.byteLength(body), sha256: sha, mime: 'image/png', recovery: { n: 1 },+ });+ if (!begin.ok || begin.op !== 'staging.begin') throw new Error(JSON.stringify(begin));+ await slot.handleLibraryRequest(GHOST_ID, {+ op: 'staging.chunk', stagingId: begin.stagingId, seq: 1,+ content: Buffer.from(body).toString('base64'), encoding: 'base64',+ });+ await slot.handleLibraryRequest(GHOST_ID, { op: 'staging.commit', stagingId: begin.stagingId });+ const archived = await slot.handleLibraryRequest(GHOST_ID, {+ op: 'write', path: rel, content: Buffer.from(body).toString('base64'), encoding: 'base64',+ });+ if (!archived.ok || archived.op !== 'write') throw new Error(JSON.stringify(archived));+ const orig = LibraryVault.prototype.hashFile;+ const spy = vi.spyOn(LibraryVault.prototype, 'hashFile').mockImplementation(async function (this: LibraryVault, relPath: string) {+ slot.setRelocating(GHOST_ID, true);+ return orig.call(this, relPath);+ });+ try {+ const released = await slot.handleLibraryRequest(GHOST_ID, {+ op: 'staging.release',+ stagingId: begin.stagingId,+ path: rel,+ sha256: sha,+ bytes: Buffer.byteLength(body),+ libraryIdentity: archived.libraryIdentity,+ libraryGeneration: archived.libraryGeneration,+ });+ expect(released).toMatchObject({ ok: false, errorCode: 'ACK_MISMATCH' });+ } finally {+ spy.mockRestore();+ slot.setRelocating(GHOST_ID, false);+ }+ const still = await slot.handleLibraryRequest(GHOST_ID, { op: 'staging.list' });+ if (!still.ok || still.op !== 'staging.list') throw new Error(JSON.stringify(still));+ expect(still.items.map((item) => item.stagingId)).toContain(begin.stagingId);+ });++ it('staging.release 路径形状对但 hash 前缀不符则 ACK_MISMATCH', async () => {+ const body = 'pixel-bytes';+ const sha = createHash('sha256').update(body).digest('hex');+ const wrong = `assets/aa/${'a'.repeat(64)}/blob.png`;+ const begin = await slot.handleLibraryRequest(GHOST_ID, {+ op: 'staging.begin', taskId: 'task-path', sourceRevision: 'rev-1',+ totalBytes: Buffer.byteLength(body), sha256: sha, mime: 'image/png', recovery: { n: 1 },+ });+ if (!begin.ok || begin.op !== 'staging.begin') throw new Error(JSON.stringify(begin));+ await slot.handleLibraryRequest(GHOST_ID, {+ op: 'staging.chunk', stagingId: begin.stagingId, seq: 1,+ content: Buffer.from(body).toString('base64'), encoding: 'base64',+ });+ await slot.handleLibraryRequest(GHOST_ID, { op: 'staging.commit', stagingId: begin.stagingId });+ await slot.handleLibraryRequest(GHOST_ID, {+ op: 'write', path: wrong, content: Buffer.from(body).toString('base64'), encoding: 'base64',+ });+ const open = await slot.handleLibraryRequest(GHOST_ID, { op: 'open' });+ if (!open.ok || open.op !== 'open') throw new Error(JSON.stringify(open));+ const released = await slot.handleLibraryRequest(GHOST_ID, {+ op: 'staging.release',+ stagingId: begin.stagingId,+ path: wrong,+ sha256: sha,+ bytes: Buffer.byteLength(body),+ libraryIdentity: (open as { libraryIdentity?: string }).libraryIdentity,+ libraryGeneration: (open as { libraryGeneration?: number }).libraryGeneration,+ });+ expect(released).toMatchObject({ ok: false, errorCode: 'ACK_MISMATCH' });+ });++ async function commitAndArchive(taskId: string, payload = 'pixel-bytes') {+ const sha = createHash('sha256').update(payload).digest('hex');+ const rel = `assets/${sha.slice(0, 2)}/${sha}/blob.png`;+ const begin = await slot.handleLibraryRequest(GHOST_ID, {+ op: 'staging.begin', taskId, sourceRevision: 'rev-1',+ totalBytes: Buffer.byteLength(payload), sha256: sha, mime: 'image/png', recovery: { n: 1 },+ });+ if (!begin.ok || begin.op !== 'staging.begin') throw new Error(JSON.stringify(begin));+ await slot.handleLibraryRequest(GHOST_ID, {+ op: 'staging.chunk', stagingId: begin.stagingId, seq: 1,+ content: Buffer.from(payload).toString('base64'), encoding: 'base64',+ });+ await slot.handleLibraryRequest(GHOST_ID, { op: 'staging.commit', stagingId: begin.stagingId });+ const archived = await slot.handleLibraryRequest(GHOST_ID, {+ op: 'write', path: rel, content: Buffer.from(payload).toString('base64'), encoding: 'base64',+ });+ if (!archived.ok || archived.op !== 'write') throw new Error(JSON.stringify(archived));+ return { stagingId: begin.stagingId, sha, rel, archived, payload };+ }++ it('staging.release ACK 后 tombstone 写入前切根则保留原件', async () => {+ const { stagingId, sha, rel, archived } = await commitAndArchive('task-ack-then-root');+ const origWrite = LibraryVault.prototype.write;+ const spy = vi.spyOn(LibraryVault.prototype, 'write').mockImplementation(async function (this: LibraryVault, req) {+ if (typeof req.path === 'string' && req.path.endsWith('tombstone.json')) {+ const sessions = (slot as unknown as { sessions: Map<string, { identity: string; generation: number }> }).sessions;+ const live = sessions.get(GHOST_ID);+ if (live) {+ live.identity = 'f'.repeat(64);+ live.generation = live.generation + 1;+ }+ }+ return origWrite.call(this, req);+ });+ try {+ const released = await slot.handleLibraryRequest(GHOST_ID, {+ op: 'staging.release',+ stagingId,+ path: rel,+ sha256: sha,+ bytes: Buffer.byteLength('pixel-bytes'),+ libraryIdentity: archived.libraryIdentity,+ libraryGeneration: archived.libraryGeneration,+ });+ expect(released).toMatchObject({ ok: false, errorCode: 'ACK_MISMATCH' });+ } finally {+ spy.mockRestore();+ }+ const still = await slot.handleLibraryRequest(GHOST_ID, { op: 'staging.list' });+ if (!still.ok || still.op !== 'staging.list') throw new Error(JSON.stringify(still));+ expect(still.items.map((item) => item.stagingId)).toContain(stagingId);+ expect(fs.existsSync(path.join(tmp, 'library-staging', GHOST_ID, 'tasks', stagingId, 'blob.bin'))).toBe(true);+ });++ it('owner lease 覆盖 ACK await,切账号后不得删原件', async () => {+ let leaseHeld = false;+ let leaseReleased = false;+ await slot.disposeAll();+ slot = new GhostLibrarySlot({+ getGhost: (id) => ghosts.get(id) ?? null,+ bindingStore,+ getDefaultRoot: (id) => path.join(defaultRootBase, id),+ captureOwnerScope: () => captureOwnerScope(),+ createVault: (d) => createVault(d),+ createSqlService: (d) => createSqlService(d),+ getDiskFreeBytes: async () => 1024 ** 4,+ workerScriptPath: () => path.join(tmp, 'unused-worker.js'),+ betterSqliteModulePath: () => 'better-sqlite3',+ showItemInFolder: (...args: unknown[]) => showItemInFolder(...args),+ showSaveDialog: (...args: unknown[]) => showSaveDialog(...args),+ writeClipboardPng: (...args: unknown[]) => writeClipboardPng(...args),+ syncAgentReadonlyExtraDir: (...args: unknown[]) => syncAgentReadonlyExtraDir(...args),+ getStagingRoot: (id) => path.join(tmp, 'library-staging', id),+ now: () => clock,+ captureMutationOwner: () => ({ mode: 'local', dataOwnerId: 'a', generation: 1 }),+ beginMutation: () => {+ leaseHeld = true;+ return () => { leaseReleased = true; leaseHeld = false; };+ },+ });+ const { stagingId, sha, rel, archived } = await commitAndArchive('task-lease-switch');+ expect(leaseHeld).toBe(false);+ const orig = LibraryVault.prototype.hashFile;+ const spy = vi.spyOn(LibraryVault.prototype, 'hashFile').mockImplementation(async function (this: LibraryVault, relPath: string) {+ expect(leaseHeld).toBe(true);+ if (relPath.startsWith('assets/')) scopeKey = 'local:owner-b:1';+ return orig.call(this, relPath);+ });+ try {+ const released = await slot.handleLibraryRequest(GHOST_ID, {+ op: 'staging.release',+ stagingId,+ path: rel,+ sha256: sha,+ bytes: Buffer.byteLength('pixel-bytes'),+ libraryIdentity: archived.libraryIdentity,+ libraryGeneration: archived.libraryGeneration,+ });+ expect(released).toMatchObject({ ok: false, errorCode: 'OWNER_CHANGED' });+ expect(leaseReleased).toBe(true);+ } finally {+ spy.mockRestore();+ scopeKey = 'local:owner-a:1';+ }+ const still = await slot.handleLibraryRequest(GHOST_ID, { op: 'staging.list' });+ if (!still.ok || still.op !== 'staging.list') throw new Error(JSON.stringify(still));+ expect(still.items.map((item) => item.stagingId)).toContain(stagingId);+ });++ it('disposeGhost 等待在途 release 完成后再切会话', async () => {+ const { stagingId, sha, rel, archived } = await commitAndArchive('task-drain');+ let disposeDone = false;+ let disposeDuringWrite = false;+ let pendingDispose: Promise<void> | undefined;+ const origWrite = LibraryVault.prototype.write;+ const spy = vi.spyOn(LibraryVault.prototype, 'write').mockImplementation(async function (this: LibraryVault, req) {+ if (typeof req.path === 'string' && req.path.endsWith('tombstone.json')) {+ pendingDispose = slot.disposeGhost(GHOST_ID).then(() => { disposeDone = true; });+ await new Promise((resolve) => setTimeout(resolve, 20));+ disposeDuringWrite = disposeDone;+ }+ return origWrite.call(this, req);+ });+ try {+ const released = await slot.handleLibraryRequest(GHOST_ID, {+ op: 'staging.release',+ stagingId,+ path: rel,+ sha256: sha,+ bytes: Buffer.byteLength('pixel-bytes'),+ libraryIdentity: archived.libraryIdentity,+ libraryGeneration: archived.libraryGeneration,+ });+ expect(released).toEqual({ ok: true, op: 'staging.release', stagingId, released: true });+ expect(disposeDuringWrite).toBe(false);+ await pendingDispose;+ expect(disposeDone).toBe(true);+ } finally {+ spy.mockRestore();+ }+ });++ it('disposeAll 在 tombstone 窗口先置 relocating 并排空,新 release 不得进入', async () => {+ const { stagingId, sha, rel, archived } = await commitAndArchive('task-dispose-all');+ let disposeAllDuringWrite = false;+ let pendingDispose: Promise<void> | undefined;+ const origWrite = LibraryVault.prototype.write;+ const spy = vi.spyOn(LibraryVault.prototype, 'write').mockImplementation(async function (this: LibraryVault, req) {+ if (typeof req.path === 'string' && req.path.endsWith('tombstone.json')) {+ pendingDispose = slot.disposeAll();+ await new Promise((resolve) => setTimeout(resolve, 20));+ const racing = await slot.handleLibraryRequest(GHOST_ID, {+ op: 'staging.release',+ stagingId,+ path: rel,+ sha256: sha,+ bytes: Buffer.byteLength('pixel-bytes'),+ libraryIdentity: archived.libraryIdentity,+ libraryGeneration: archived.libraryGeneration,+ });+ disposeAllDuringWrite = racing.ok === false && (racing as { errorCode?: string }).errorCode === 'ACK_MISMATCH';+ }+ return origWrite.call(this, req);+ });+ try {+ const released = await slot.handleLibraryRequest(GHOST_ID, {+ op: 'staging.release',+ stagingId,+ path: rel,+ sha256: sha,+ bytes: Buffer.byteLength('pixel-bytes'),+ libraryIdentity: archived.libraryIdentity,+ libraryGeneration: archived.libraryGeneration,+ });+ expect(released).toEqual({ ok: true, op: 'staging.release', stagingId, released: true });+ expect(disposeAllDuringWrite).toBe(true);+ await pendingDispose;+ } finally {+ spy.mockRestore();+ }+ });++ it('staging.release 首次 hash 后正本被删: ACK_MISMATCH 且保留 staging 原件', async () => {+ const body = 'pixel-bytes';+ const sha = createHash('sha256').update(body).digest('hex');+ const rel = `assets/${sha.slice(0, 2)}/${sha}/blob.png`;+ const begin = await slot.handleLibraryRequest(GHOST_ID, {+ op: 'staging.begin', taskId: 'task-hash-delete', sourceRevision: 'rev-1',+ totalBytes: Buffer.byteLength(body), sha256: sha, mime: 'image/png', recovery: { n: 1 },+ });+ if (!begin.ok || begin.op !== 'staging.begin') throw new Error(JSON.stringify(begin));+ await slot.handleLibraryRequest(GHOST_ID, {+ op: 'staging.chunk', stagingId: begin.stagingId, seq: 1,+ content: Buffer.from(body).toString('base64'), encoding: 'base64',+ });+ await slot.handleLibraryRequest(GHOST_ID, { op: 'staging.commit', stagingId: begin.stagingId });+ const archived = await slot.handleLibraryRequest(GHOST_ID, {+ op: 'write', path: rel, content: Buffer.from(body).toString('base64'), encoding: 'base64',+ });+ if (!archived.ok || archived.op !== 'write') throw new Error(JSON.stringify(archived));+ const orig = LibraryVault.prototype.hashFile;+ let seen = 0;+ const spy = vi.spyOn(LibraryVault.prototype, 'hashFile').mockImplementation(async function (this: LibraryVault, relPath: string) {+ const hashed = await orig.call(this, relPath);+ seen += 1;+ if (seen === 1 && relPath === rel) {+ await fs.promises.rm(path.join(defaultRootBase, GHOST_ID, rel), { force: true });+ }+ return hashed;+ });+ try {+ const released = await slot.handleLibraryRequest(GHOST_ID, {+ op: 'staging.release',+ stagingId: begin.stagingId,+ path: rel,+ sha256: sha,+ bytes: Buffer.byteLength(body),+ libraryIdentity: archived.libraryIdentity,+ libraryGeneration: archived.libraryGeneration,+ });+ expect(released).toMatchObject({ ok: false, errorCode: 'ACK_MISMATCH' });+ } finally {+ spy.mockRestore();+ }+ const still = await slot.handleLibraryRequest(GHOST_ID, { op: 'staging.list' });+ if (!still.ok || still.op !== 'staging.list') throw new Error(JSON.stringify(still));+ expect(still.items.map((item) => item.stagingId)).toContain(begin.stagingId);+ expect(fs.existsSync(path.join(tmp, 'library-staging', GHOST_ID, 'tasks', begin.stagingId, 'blob.bin'))).toBe(true);+ });++ it('staging.release 与并发 delete 互斥:核验结束前正本仍在,release 成功后再删', async () => {+ const body = 'pixel-bytes';+ const sha = createHash('sha256').update(body).digest('hex');+ const rel = `assets/${sha.slice(0, 2)}/${sha}/blob.png`;+ const begin = await slot.handleLibraryRequest(GHOST_ID, {+ op: 'staging.begin', taskId: 'task-release-mutex', sourceRevision: 'rev-1',+ totalBytes: Buffer.byteLength(body), sha256: sha, mime: 'image/png', recovery: { n: 1 },+ });+ if (!begin.ok || begin.op !== 'staging.begin') throw new Error(JSON.stringify(begin));+ await slot.handleLibraryRequest(GHOST_ID, {+ op: 'staging.chunk', stagingId: begin.stagingId, seq: 1,+ content: Buffer.from(body).toString('base64'), encoding: 'base64',+ });+ await slot.handleLibraryRequest(GHOST_ID, { op: 'staging.commit', stagingId: begin.stagingId });+ const archived = await slot.handleLibraryRequest(GHOST_ID, {+ op: 'write', path: rel, content: Buffer.from(body).toString('base64'), encoding: 'base64',+ });+ if (!archived.ok || archived.op !== 'write') throw new Error(JSON.stringify(archived));+ const canonical = path.join(defaultRootBase, GHOST_ID, rel);+ let resume!: () => void;+ const held = new Promise<void>((resolve) => { resume = resolve; });+ let entered!: () => void;+ const started = new Promise<void>((resolve) => { entered = resolve; });+ const orig = LibraryVault.prototype.hashFile;+ let heldOnce = false;+ const spy = vi.spyOn(LibraryVault.prototype, 'hashFile').mockImplementation(async function (this: LibraryVault, relPath: string) {+ if (relPath === rel && !heldOnce) {+ heldOnce = true;+ entered();+ await held;+ }+ return orig.call(this, relPath);+ });+ try {+ const releaseP = slot.handleLibraryRequest(GHOST_ID, {+ op: 'staging.release',+ stagingId: begin.stagingId,+ path: rel,+ sha256: sha,+ bytes: Buffer.byteLength(body),+ libraryIdentity: archived.libraryIdentity,+ libraryGeneration: archived.libraryGeneration,+ });+ await started;+ const deleteP = slot.handleLibraryRequest(GHOST_ID, { op: 'delete', path: rel });+ await new Promise((resolve) => setTimeout(resolve, 30));+ expect(fs.existsSync(canonical)).toBe(true);+ resume();+ const released = await releaseP;+ expect(released).toEqual({+ ok: true, op: 'staging.release', stagingId: begin.stagingId, released: true,+ });+ const deleted = await deleteP;+ expect(deleted).toMatchObject({ ok: true, op: 'delete' });+ expect(fs.existsSync(canonical)).toBe(false);+ expect(fs.existsSync(path.join(tmp, 'library-staging', GHOST_ID, 'tasks', begin.stagingId, 'blob.bin'))).toBe(false);+ } finally {+ spy.mockRestore();+ }+ });++ it('disposeAll 释放 stagingStores', async () => {+ const body = 'pixel-bytes';+ const sha = createHash('sha256').update(body).digest('hex');+ const begin = await slot.handleLibraryRequest(GHOST_ID, {+ op: 'staging.begin', taskId: 'task-dispose-stores', sourceRevision: 'rev-1',+ totalBytes: Buffer.byteLength(body), sha256: sha, mime: 'image/png', recovery: { n: 1 },+ });+ if (!begin.ok || begin.op !== 'staging.begin') throw new Error(JSON.stringify(begin));+ const stores = (slot as unknown as { stagingStores: Map<string, unknown> }).stagingStores;+ expect(stores.size).toBeGreaterThan(0);+ await slot.disposeAll();+ expect(stores.size).toBe(0);+ });});diff --git a/apps/desktop/src/main/cindy-brain/__tests__/libraryStaging.test.ts b/apps/desktop/src/main/cindy-brain/__tests__/libraryStaging.test.tsnew file mode 100644index 0000000000..9c045c8b9f--- /dev/null+++ b/apps/desktop/src/main/cindy-brain/__tests__/libraryStaging.test.ts@@ -0,0 +1,1149 @@+/**+ * Host H1 LibraryStagingStore 故障恢复单测。+ * 每条用例执行标题声称的完整序列(失败 → 保留原件 → 去掉故障 → 同实例/新实例恢复),+ * 禁止只断言初次失败。tmpdir 合成数据,零 Electron,不读真实 profile/Library。+ */+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';+import * as fs from 'node:fs';+import * as os from 'node:os';+import * as path from 'node:path';+import { createHash, randomUUID } from 'node:crypto';++import { LibraryStagingStore, DEFAULT_LIBRARY_STAGING_LIMITS } from '../libraryStaging.js';+import { LibraryVault, DEFAULT_LIBRARY_LIMITS } from '../libraryVault.js';++const sha256Of = (s: string | Buffer): string => createHash('sha256').update(s).digest('hex');+const HEX_A = 'a'.repeat(64);+const DEFAULT_READ_CHUNK = DEFAULT_LIBRARY_STAGING_LIMITS.maxChunkBytes;++describe('LibraryStagingStore 故障恢复', () => {+ let tmp: string;+ let scope: string | null = 'local:owner-a:1';+ const ghostId = 'mivo-canvas';+ const body = 'pixel-bytes';+ const sha = sha256Of(body);+ const recovery = { sceneId: 's1', nodeId: 'n1' };++ const makeStore = (+ root = path.join(tmp, 'library-staging', ghostId),+ extra: {+ maxTotalBytes?: number;+ maxConcurrentWrites?: number;+ maxChunkBytes?: number;+ maxTaskBytes?: number;+ reserveBytes?: number;+ streamIdleTimeoutMs?: number;+ listPageSize?: number;+ now?: () => number;+ getDiskFreeBytes?: () => Promise<number | null>;+ ownerScopeKey?: string;+ } = {},+ ): LibraryStagingStore =>+ new LibraryStagingStore({+ rootDir: root,+ ownerScopeKey: extra.ownerScopeKey ?? 'local:owner-a:1',+ ghostId,+ captureOwnerScope: () => extra.ownerScopeKey ?? scope,+ createVault: (deps) => new LibraryVault({+ ...deps,+ limits: {+ ...deps.limits,+ ...(extra.listPageSize !== undefined ? { listPageSize: extra.listPageSize } : {}),+ },+ }),+ getDiskFreeBytes: extra.getDiskFreeBytes ?? (async () => 1024 ** 4),+ now: extra.now,+ limits: {+ maxTotalBytes: extra.maxTotalBytes ?? 64,+ maxConcurrentWrites: extra.maxConcurrentWrites ?? 2,+ reserveBytes: extra.reserveBytes ?? 1,+ ...(extra.maxChunkBytes !== undefined ? { maxChunkBytes: extra.maxChunkBytes } : {}),+ ...(extra.maxTaskBytes !== undefined ? { maxTaskBytes: extra.maxTaskBytes } : {}),+ ...(extra.streamIdleTimeoutMs !== undefined ? { streamIdleTimeoutMs: extra.streamIdleTimeoutMs } : {}),+ },+ });++ beforeEach(async () => {+ tmp = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'cindy-library-staging-'));+ scope = 'local:owner-a:1';+ });+ afterEach(async () => {+ vi.restoreAllMocks();+ await fs.promises.rm(tmp, { recursive: true, force: true });+ });++ async function beginChunk(+ store: LibraryStagingStore,+ taskId: string,+ payload: string | Buffer,+ sourceRevision = 'rev-1',+ ) {+ const buf = typeof payload === 'string' ? Buffer.from(payload) : payload;+ const digest = sha256Of(buf);+ const begin = await store.begin({+ ghostId, taskId, sourceRevision,+ totalBytes: buf.byteLength, sha256: digest, mime: 'image/png', recovery,+ });+ if (!begin.ok) throw new Error(`begin ${taskId}: ${JSON.stringify(begin)}`);+ const chunk = await store.chunk({+ ghostId, stagingId: begin.stagingId, seq: 1,+ content: buf.toString('base64'), encoding: 'base64',+ });+ if (!chunk.ok) throw new Error(`chunk ${taskId}: ${JSON.stringify(chunk)}`);+ return { stagingId: begin.stagingId, digest, bytes: buf.byteLength };+ }++ async function commitOne(+ store = makeStore(),+ taskId = 'task-1',+ payload: string | Buffer = body,+ sourceRevision = 'rev-1',+ ) {+ const started = await beginChunk(store, taskId, payload, sourceRevision);+ const commit = await store.commit({ ghostId, stagingId: started.stagingId });+ if (!commit.ok) throw new Error(`commit ${taskId}: ${JSON.stringify(commit)}`);+ return { store, stagingId: started.stagingId, commit, digest: started.digest };+ }++ function blobAbs(root: string, stagingId: string): string {+ return path.join(root, 'tasks', stagingId, 'blob.bin');+ }+ function manifestAbs(root: string, stagingId: string): string {+ return path.join(root, 'tasks', stagingId, 'manifest.json');+ }+ function tombstoneAbs(root: string, stagingId: string): string {+ return path.join(root, 'tasks', stagingId, 'tombstone.json');+ }+ function intentAbs(root: string, stagingId: string): string {+ return path.join(root, 'tasks', stagingId, 'intent.json');+ }+ function matchingAck(commit: { sha256: string; bytes: number }) {+ return {+ ok: true as const,+ path: `assets/${commit.sha256.slice(0, 2)}/${commit.sha256}/blob.png`,+ sha256: commit.sha256,+ bytes: commit.bytes,+ libraryIdentity: HEX_A,+ libraryGeneration: 0,+ };+ }++ async function listAllPublic(store: LibraryStagingStore, limit = 2) {+ const items: Array<{ stagingId: string; bytes: number; taskId: string }> = [];+ let cursor: string | undefined;+ for (;;) {+ const page = await store.list({ ghostId, cursor, limit });+ if (!page.ok) throw new Error(`list: ${JSON.stringify(page)}`);+ items.push(...page.items.map((item) => ({+ stagingId: item.stagingId, bytes: item.bytes, taskId: item.taskId,+ })));+ if (!page.hasMore) {+ expect(page.nextCursor).toBeNull();+ return { items, last: page };+ }+ expect(typeof page.nextCursor).toBe('string');+ cursor = page.nextCursor ?? undefined;+ }+ }++ it('commit 后新实例 list/read 可恢复;未提交流不出现', async () => {+ const root = path.join(tmp, 'library-staging', ghostId);+ const live = makeStore(root);+ const uploading = await live.begin({+ ghostId, taskId: 'partial', sourceRevision: 'r',+ totalBytes: 8, sha256: '0'.repeat(64), mime: 'image/png', recovery,+ });+ if (!uploading.ok) throw new Error(JSON.stringify(uploading));+ const { stagingId } = await commitOne(live);+ const restored = makeStore(root);+ const listed = await restored.list({ ghostId });+ if (!listed.ok) throw new Error(JSON.stringify(listed));+ expect(listed.items.map((item) => item.stagingId)).toEqual([stagingId]);+ expect(listed.items[0]?.durable).toBe(true);+ expect(listed.items[0]?.recovery).toEqual(recovery);+ const read = await restored.read({ ghostId, stagingId });+ if (!read.ok) throw new Error(JSON.stringify(read));+ expect(Buffer.from(read.content, 'base64').toString('utf8')).toBe(body);+ });++ it('坏 manifest:list 失败非空,原件保留;修复后同一实例 list/read 成功且无重复', async () => {+ const root = path.join(tmp, 'library-staging', ghostId);+ const { stagingId: firstId } = await commitOne(makeStore(root, { maxTotalBytes: 1024 }), 'task-a', 'alpha');+ const { stagingId: secondId } = await commitOne(makeStore(root, { maxTotalBytes: 1024 }), 'task-b', 'bravo');+ const originalManifest = await fs.promises.readFile(manifestAbs(root, secondId), 'utf8');+ await fs.promises.writeFile(manifestAbs(root, secondId), '{not json');++ const same = makeStore(root, { maxTotalBytes: 1024 });+ const listed = await same.list({ ghostId });+ expect(listed).toMatchObject({ ok: false, errorCode: 'LIBRARY_UNAVAILABLE' });+ expect(fs.existsSync(blobAbs(root, firstId))).toBe(true);+ expect(fs.existsSync(blobAbs(root, secondId))).toBe(true);+ const blocked = await same.begin({+ ghostId, taskId: 'task-x', sourceRevision: 'rev-x',+ totalBytes: 1, sha256: '0'.repeat(64), mime: 'image/png', recovery,+ });+ expect(blocked).toMatchObject({ ok: false, errorCode: 'LIBRARY_UNAVAILABLE' });+ expect(blocked.ok).toBe(false);++ await fs.promises.writeFile(manifestAbs(root, secondId), originalManifest);+ const recovered = await same.list({ ghostId });+ if (!recovered.ok) throw new Error(`same-instance recover: ${JSON.stringify(recovered)}`);+ const ids = recovered.items.map((item) => item.stagingId).sort();+ expect(ids).toEqual([firstId, secondId].sort());+ expect(new Set(ids).size).toBe(2);+ const readFirst = await same.read({ ghostId, stagingId: firstId });+ const readSecond = await same.read({ ghostId, stagingId: secondId });+ if (!readFirst.ok || !readSecond.ok) throw new Error('same-instance read failed');+ expect(Buffer.from(readFirst.content, 'base64').toString('utf8')).toBe('alpha');+ expect(Buffer.from(readSecond.content, 'base64').toString('utf8')).toBe('bravo');+ });++ it('不可读 manifest(目录占位)同样 LIBRARY_UNAVAILABLE,修复后同一实例恢复', async () => {+ const root = path.join(tmp, 'library-staging', ghostId);+ const { stagingId } = await commitOne(makeStore(root));+ const original = await fs.promises.readFile(manifestAbs(root, stagingId), 'utf8');+ await fs.promises.rm(manifestAbs(root, stagingId));+ await fs.promises.mkdir(manifestAbs(root, stagingId));++ const same = makeStore(root);+ expect(await same.list({ ghostId })).toMatchObject({ ok: false, errorCode: 'LIBRARY_UNAVAILABLE' });+ expect(fs.existsSync(blobAbs(root, stagingId))).toBe(true);++ await fs.promises.rm(manifestAbs(root, stagingId), { recursive: true, force: true });+ await fs.promises.writeFile(manifestAbs(root, stagingId), original);+ const listed = await same.list({ ghostId });+ if (!listed.ok) throw new Error(JSON.stringify(listed));+ expect(listed.items.map((item) => item.stagingId)).toEqual([stagingId]);+ const read = await same.read({ ghostId, stagingId });+ if (!read.ok) throw new Error(JSON.stringify(read));+ expect(Buffer.from(read.content, 'base64').toString('utf8')).toBe(body);+ });++ it('无 manifest 的 blob 计入额度且不列为 committed,不卡住同 task', async () => {+ const root = path.join(tmp, 'library-staging', ghostId);+ const orphanId = randomUUID();+ await fs.promises.mkdir(path.join(root, 'tasks', orphanId), { recursive: true });+ await fs.promises.writeFile(path.join(root, 'tasks', orphanId, 'blob.bin'), 'x'.repeat(60));+ const store = makeStore(root);+ const begin = await store.begin({+ ghostId, taskId: 'task-1', sourceRevision: 'rev-1',+ totalBytes: Buffer.byteLength(body), sha256: sha, mime: 'image/png', recovery,+ });+ expect(begin).toMatchObject({ ok: false, errorCode: 'STAGING_QUOTA' });+ expect(fs.existsSync(path.join(root, 'tasks', orphanId, 'blob.bin'))).toBe(true);+ const listed = await store.list({ ghostId });+ if (!listed.ok) throw new Error(JSON.stringify(listed));+ expect(listed.items).toEqual([]);+ });++ it('活跃预留+关闭 unlink 失败残片+orphan+committed-pending+durable 合计占额,不得双计活跃 tmp', async () => {+ const root = path.join(tmp, 'quota-mix', ghostId);+ const orphanId = randomUUID();+ await fs.promises.mkdir(path.join(root, 'tasks', orphanId), { recursive: true });+ await fs.promises.writeFile(path.join(root, 'tasks', orphanId, 'blob.bin'), 'O'.repeat(10));+ const store = makeStore(root, { maxTotalBytes: 50, maxConcurrentWrites: 4 });++ const durable = await commitOne(store, 'durable-task', 'D'.repeat(10));+ const small = await store.begin({+ ghostId, taskId: 'small-beside-orphan', sourceRevision: 'r',+ totalBytes: 8, sha256: sha256Of('s'.repeat(8)), mime: 'image/png', recovery,+ });+ if (!small.ok) throw new Error(`small begin beside orphan: ${JSON.stringify(small)}`);+ const smallChunk = await store.chunk({+ ghostId, stagingId: small.stagingId, seq: 1,+ content: Buffer.from('s'.repeat(8)).toString('base64'), encoding: 'base64',+ });+ if (!smallChunk.ok) throw new Error(JSON.stringify(smallChunk));++ const realUnlink = fs.promises.unlink.bind(fs.promises);+ const unlinkSpy = vi.spyOn(fs.promises, 'unlink').mockImplementation(async (target, ...rest) => {+ if (String(target).includes(`${path.sep}.cindy-library${path.sep}tmp${path.sep}`)) {+ throw Object.assign(new Error('EACCES unlink tmp'), { code: 'EACCES' });+ }+ return realUnlink(target, ...rest);+ });+ const aborted = await store.abort({ ghostId, stagingId: small.stagingId });+ expect(aborted).toMatchObject({ ok: true, aborted: true });+ unlinkSpy.mockRestore();+ const tmpDir = path.join(root, '.cindy-library', 'tmp');+ const leftover = (await fs.promises.readdir(tmpDir)).filter((name) => name !== '.' && name !== '..');+ expect(leftover.length).toBeGreaterThan(0);+ const leftoverBytes = leftover.reduce((sum, name) => {+ const st = fs.statSync(path.join(tmpDir, name));+ return sum + (st.isFile() ? st.size : 0);+ }, 0);+ expect(leftoverBytes).toBeGreaterThan(0);++ const active = await store.begin({+ ghostId, taskId: 'still-active', sourceRevision: 'r',+ totalBytes: 5, sha256: sha256Of('A'.repeat(5)), mime: 'image/png', recovery,+ });+ if (!active.ok) throw new Error(`active reservation: ${JSON.stringify(active)}`);++ const origWrite = LibraryVault.prototype.write;+ const writeSpy = vi.spyOn(LibraryVault.prototype, 'write').mockImplementation(async function (this: LibraryVault, req) {+ if (typeof req.path === 'string' && req.path.endsWith('manifest.json')) {+ return { ok: false, errorCode: 'INTERNAL', message: 'manifest write failed' };+ }+ return origWrite.call(this, req);+ });+ let pendingId: string | undefined;+ try {+ const pending = await beginChunk(store, 'pending-task', 'P'.repeat(10));+ pendingId = pending.stagingId;+ const failedCommit = await store.commit({ ghostId, stagingId: pending.stagingId });+ expect(failedCommit.ok).toBe(false);+ expect(fs.existsSync(blobAbs(root, pending.stagingId))).toBe(true);+ expect(fs.existsSync(manifestAbs(root, pending.stagingId))).toBe(false);++ // durable 10 + orphan 10 + closed residue >=8 + active 5 + pending 10 >= 43; +8 exceeds 50.+ const extra = await store.begin({+ ghostId, taskId: 'extra-over-quota', sourceRevision: 'rev-1',+ totalBytes: 8, sha256: sha256Of('E'.repeat(8)), mime: 'image/png', recovery,+ });+ expect(extra).toMatchObject({ ok: false, errorCode: 'STAGING_QUOTA' });+ } finally {+ writeSpy.mockRestore();+ }++ if (!pendingId) throw new Error('pending stagingId missing');+ const chunkSpy = vi.spyOn(LibraryVault.prototype, 'writeChunk');+ const beginSpy = vi.spyOn(LibraryVault.prototype, 'writeBegin');+ try {+ const retried = await store.commit({ ghostId, stagingId: pendingId });+ if (!retried.ok) throw new Error(`retry commit after manifest fault removed: ${JSON.stringify(retried)}`);+ expect(retried.durable).toBe(true);+ expect(retried.bytes).toBe(10);+ expect(chunkSpy).not.toHaveBeenCalled();+ expect(beginSpy).not.toHaveBeenCalled();+ } finally {+ chunkSpy.mockRestore();+ beginSpy.mockRestore();+ }+ expect(fs.existsSync(manifestAbs(root, pendingId))).toBe(true);+ expect(fs.existsSync(blobAbs(root, durable.stagingId))).toBe(true);+ expect(fs.existsSync(path.join(root, 'tasks', orphanId, 'blob.bin'))).toBe(true);+ });++ it('abort 真正调用后关闭残片计入额度,不得与活跃预留重复计费', async () => {+ const root = path.join(tmp, 'abort-residue', ghostId);+ const store = makeStore(root, { maxTotalBytes: 20 });+ const begin = await store.begin({+ ghostId, taskId: 'abort-me', sourceRevision: 'r',+ totalBytes: 12, sha256: sha256Of('z'.repeat(12)), mime: 'image/png', recovery,+ });+ if (!begin.ok) throw new Error(JSON.stringify(begin));+ const chunked = await store.chunk({+ ghostId, stagingId: begin.stagingId, seq: 1,+ content: Buffer.from('z'.repeat(12)).toString('base64'), encoding: 'base64',+ });+ if (!chunked.ok) throw new Error(JSON.stringify(chunked));+ const realUnlink = fs.promises.unlink.bind(fs.promises);+ const unlinkSpy = vi.spyOn(fs.promises, 'unlink').mockImplementation(async (target, ...rest) => {+ if (String(target).includes(`${path.sep}.cindy-library${path.sep}tmp${path.sep}`)) {+ throw Object.assign(new Error('EACCES unlink tmp'), { code: 'EACCES' });+ }+ return realUnlink(target, ...rest);+ });+ const aborted = await store.abort({ ghostId, stagingId: begin.stagingId });+ expect(aborted).toMatchObject({ ok: true, aborted: true });+ unlinkSpy.mockRestore();+ const tmpDir = path.join(root, '.cindy-library', 'tmp');+ const leftover = (await fs.promises.readdir(tmpDir)).filter((name) => {+ const st = fs.statSync(path.join(tmpDir, name));+ return st.isFile() && st.size > 0;+ });+ expect(leftover.length).toBeGreaterThan(0);++ const over = await store.begin({+ ghostId, taskId: 'task-over', sourceRevision: 'rev-1',+ totalBytes: 9, sha256: sha256Of('n'.repeat(9)), mime: 'image/png', recovery,+ });+ expect(over).toMatchObject({ ok: false, errorCode: 'STAGING_QUOTA' });++ const exact = await store.begin({+ ghostId, taskId: 'task-exact', sourceRevision: 'rev-1',+ totalBytes: 8, sha256: sha256Of('e'.repeat(8)), mime: 'image/png', recovery,+ });+ if (!exact.ok) throw new Error(`no-double-count exact fill: ${JSON.stringify(exact)}`);+ const abortExact = await store.abort({ ghostId, stagingId: exact.stagingId });+ expect(abortExact).toMatchObject({ ok: true, aborted: true });+ });++ it('writeCommit 成功但 manifest 失败后占额;去掉故障后同一 id 提交成功且不再重传字节', async () => {+ const root = path.join(tmp, 'pending-retry', ghostId);+ const store = makeStore(root, { maxTotalBytes: 40 });+ const origWrite = LibraryVault.prototype.write;+ const writeSpy = vi.spyOn(LibraryVault.prototype, 'write').mockImplementation(async function (this: LibraryVault, req) {+ if (typeof req.path === 'string' && req.path.endsWith('manifest.json')) {+ return { ok: false, errorCode: 'INTERNAL', message: 'manifest write failed' };+ }+ return origWrite.call(this, req);+ });+ const started = await beginChunk(store, 'pending', 'a'.repeat(20));+ const failedCommit = await store.commit({ ghostId, stagingId: started.stagingId });+ expect(failedCommit.ok).toBe(false);+ writeSpy.mockRestore();++ const extra = await store.begin({+ ghostId, taskId: 'extra', sourceRevision: 'rev-1',+ totalBytes: 21, sha256: sha256Of('b'.repeat(21)), mime: 'image/png', recovery,+ });+ expect(extra).toMatchObject({ ok: false, errorCode: 'STAGING_QUOTA' });++ const chunkSpy = vi.spyOn(LibraryVault.prototype, 'writeChunk');+ const beginSpy = vi.spyOn(LibraryVault.prototype, 'writeBegin');+ try {+ const retried = await store.commit({ ghostId, stagingId: started.stagingId });+ if (!retried.ok) throw new Error(`retry commit: ${JSON.stringify(retried)}`);+ expect(retried.durable).toBe(true);+ expect(chunkSpy).not.toHaveBeenCalled();+ expect(beginSpy).not.toHaveBeenCalled();+ } finally {+ chunkSpy.mockRestore();+ beginSpy.mockRestore();+ }+ const listed = await store.list({ ghostId });+ if (!listed.ok) throw new Error(JSON.stringify(listed));+ expect(listed.items.map((item) => item.stagingId)).toEqual([started.stagingId]);+ });++ it('任务目录、tasks 父目录、vault 根 fsync 失败均真正命中对应方法:初次不得 durable,去掉故障后同 id 提交成功且新 Store 可 list/read', async () => {+ const cases: Array<{+ label: string;+ failWhen: (relPath: unknown, stagingId: string) => boolean;+ }> = [+ {+ label: 'task-dir',+ failWhen: (relPath, stagingId) => relPath === `tasks/${stagingId}`,+ },+ {+ label: 'tasks-parent',+ failWhen: (relPath) => relPath === 'tasks',+ },+ {+ label: 'vault-root',+ failWhen: (relPath) => relPath === '',+ },+ ];++ for (const item of cases) {+ const root = path.join(tmp, `fsync-${item.label}`, ghostId);+ const store = makeStore(root, { maxTotalBytes: 1024 });+ const started = await beginChunk(store, `fsync-${item.label}`, body);+ const seen: unknown[] = [];+ const orig = LibraryVault.prototype.fsyncDir;+ const spy = vi.spyOn(LibraryVault.prototype, 'fsyncDir').mockImplementation(async function (this: LibraryVault, relPath?: unknown) {+ seen.push(relPath);+ if (item.failWhen(relPath, started.stagingId)) {+ return { ok: false, errorCode: 'INTERNAL', message: `${item.label} fsync 失败` };+ }+ return orig.call(this, relPath);+ });+ try {+ const commit = await store.commit({ ghostId, stagingId: started.stagingId });+ expect(commit.ok, `${item.label} 初次 commit 应失败`).toBe(false);+ if (!commit.ok) expect(commit.errorCode).toBe('INTERNAL');+ expect(commit).not.toHaveProperty('durable');+ expect(seen.some((rel) => item.failWhen(rel, started.stagingId)), `${item.label} 未命中 fsyncDir`).toBe(true);+ expect(fs.existsSync(blobAbs(root, started.stagingId))).toBe(true);+ const listed = await store.list({ ghostId });+ if (listed.ok) {+ expect(listed.items.every((row) => row.stagingId !== started.stagingId)).toBe(true);+ }+ } finally {+ spy.mockRestore();+ }++ const retried = await store.commit({ ghostId, stagingId: started.stagingId });+ if (!retried.ok) throw new Error(`${item.label} retry commit: ${JSON.stringify(retried)}`);+ expect(retried.durable).toBe(true);+ const restored = makeStore(root, { maxTotalBytes: 1024 });+ const listed = await restored.list({ ghostId });+ if (!listed.ok) throw new Error(`${item.label} new store list: ${JSON.stringify(listed)}`);+ expect(listed.items.map((row) => row.stagingId)).toEqual([started.stagingId]);+ const read = await restored.read({ ghostId, stagingId: started.stagingId });+ if (!read.ok) throw new Error(`${item.label} new store read: ${JSON.stringify(read)}`);+ expect(Buffer.from(read.content, 'base64').toString('utf8')).toBe(body);+ }+ });++ it('release:错误 ACK 保留原件;tombstone fsync 失败保留原件;manifest 删除失败后同实例与新 Store 收敛;损坏 tombstone 不得静默删原件;成功释放精确还额', async () => {+ const root = path.join(tmp, 'release', ghostId);+ const store = makeStore(root, { maxTotalBytes: 64 });+ const { stagingId, commit } = await commitOne(store);++ const mismatch = await store.release({+ ghostId, stagingId,+ ack: {+ ok: true,+ path: 'assets/aa/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/blob.png',+ sha256: '1'.repeat(64), bytes: 1, libraryIdentity: HEX_A, libraryGeneration: 0,+ },+ });+ expect(mismatch).toMatchObject({ ok: false, errorCode: 'ACK_MISMATCH' });+ expect(fs.existsSync(blobAbs(root, stagingId))).toBe(true);+ const still = await store.list({ ghostId });+ if (!still.ok) throw new Error(JSON.stringify(still));+ expect(still.items.map((item) => item.stagingId)).toContain(stagingId);++ const origFsync = LibraryVault.prototype.fsyncDir;+ const tombFsync = vi.spyOn(LibraryVault.prototype, 'fsyncDir').mockImplementation(async function (this: LibraryVault, relPath?: unknown) {+ if (typeof relPath === 'string' && relPath === `tasks/${stagingId}` && fs.existsSync(tombstoneAbs(root, stagingId))) {+ return { ok: false, errorCode: 'INTERNAL', message: 'tombstone fsync 失败' };+ }+ return origFsync.call(this, relPath);+ });+ try {+ const blocked = await store.release({ ghostId, stagingId, ack: matchingAck(commit) });+ expect(blocked.ok).toBe(false);+ expect(fs.existsSync(blobAbs(root, stagingId))).toBe(true);+ } finally {+ tombFsync.mockRestore();+ }++ const origDelete = LibraryVault.prototype.delete;+ let blobDeleted = false;+ const deleteSpy = vi.spyOn(LibraryVault.prototype, 'delete').mockImplementation(async function (this: LibraryVault, req) {+ if (typeof req.path === 'string' && req.path.endsWith('manifest.json') && blobDeleted) {+ return { ok: false, errorCode: 'INTERNAL', message: 'manifest delete failed' };+ }+ const result = await origDelete.call(this, req);+ if (result.ok && typeof req.path === 'string' && req.path.endsWith('blob.bin')) blobDeleted = true;+ return result;+ });+ try {+ const failed = await store.release({ ghostId, stagingId, ack: matchingAck(commit) });+ expect(failed.ok).toBe(false);+ const retrySame = await store.release({ ghostId, stagingId, ack: matchingAck(commit) });+ expect(retrySame.ok).toBe(false);+ const midFault = makeStore(root, { maxTotalBytes: 64 });+ const midListed = await midFault.list({ ghostId });+ expect(midListed.ok).toBe(false);+ if (!midListed.ok) expect(['LIBRARY_UNAVAILABLE', 'INTERNAL']).toContain(midListed.errorCode);+ const occupied = await store.begin({+ ghostId, taskId: 'quota-while-cleanup-fails', sourceRevision: 'r',+ totalBytes: 55, sha256: sha256Of('q'.repeat(55)), mime: 'image/png', recovery,+ });+ expect(occupied).toMatchObject({ ok: false, errorCode: 'STAGING_QUOTA' });+ } finally {+ deleteSpy.mockRestore();+ }++ const converged = await store.release({ ghostId, stagingId, ack: matchingAck(commit) });+ expect(converged).toEqual({ ok: true, stagingId, released: true });+ expect(fs.existsSync(blobAbs(root, stagingId))).toBe(false);++ const restored = makeStore(root, { maxTotalBytes: 64 });+ const listed = await restored.list({ ghostId });+ if (!listed.ok) throw new Error(`new store after release: ${JSON.stringify(listed)}`);+ expect(listed.items).toEqual([]);+ const again = await restored.release({ ghostId, stagingId, ack: matchingAck(commit) });+ expect(again).toMatchObject({ ok: true, released: false });++ const { stagingId: liveId, commit: liveCommit } = await commitOne(restored, 'task-live', 'keep-me');+ await fs.promises.writeFile(tombstoneAbs(root, liveId), '{not a tombstone');+ const corruptStore = makeStore(root, { maxTotalBytes: 64 });+ const corruptList = await corruptStore.list({ ghostId });+ expect(corruptList).toMatchObject({ ok: false, errorCode: 'LIBRARY_UNAVAILABLE' });+ expect(fs.existsSync(blobAbs(root, liveId))).toBe(true);+ await fs.promises.rm(tombstoneAbs(root, liveId), { force: true });+ const repaired = await corruptStore.list({ ghostId });+ if (!repaired.ok) throw new Error(`tombstone repaired: ${JSON.stringify(repaired)}`);+ expect(repaired.items.map((item) => item.stagingId)).toEqual([liveId]);+ const liveRead = await corruptStore.read({ ghostId, stagingId: liveId });+ if (!liveRead.ok) throw new Error(JSON.stringify(liveRead));+ expect(Buffer.from(liveRead.content, 'base64').toString('utf8')).toBe('keep-me');++ const released = await corruptStore.release({ ghostId, stagingId: liveId, ack: matchingAck(liveCommit) });+ expect(released).toEqual({ ok: true, stagingId: liveId, released: true });+ const afterRelease = await corruptStore.begin({+ ghostId, taskId: 'after-release', sourceRevision: 'rev-1',+ totalBytes: Buffer.byteLength(body), sha256: sha, mime: 'image/png', recovery,+ });+ expect(afterRelease.ok).toBe(true);+ });++ it('有效 tombstone+残留 blob/manifest:新 Store 成功清理后立即归还全部 bytes,不得把已删除 leftover 计入 orphan', async () => {+ const root = path.join(tmp, 'tombstone-quota', ghostId);+ const maxTotalBytes = 40;+ const payload = 'T'.repeat(maxTotalBytes);+ const writer = makeStore(root, { maxTotalBytes });+ const { stagingId } = await commitOne(writer, 'crash-release', payload);+ expect(fs.existsSync(blobAbs(root, stagingId))).toBe(true);+ expect(fs.existsSync(manifestAbs(root, stagingId))).toBe(true);+ await fs.promises.writeFile(+ tombstoneAbs(root, stagingId),+ JSON.stringify({ version: 1, stagingId, released: true }),+ );+ expect(fs.existsSync(blobAbs(root, stagingId))).toBe(true);+ expect(fs.existsSync(manifestAbs(root, stagingId))).toBe(true);+ expect(fs.existsSync(tombstoneAbs(root, stagingId))).toBe(true);++ const restored = makeStore(root, { maxTotalBytes });+ const listed = await restored.list({ ghostId });+ if (!listed.ok) throw new Error(`loadJournal after valid tombstone: ${JSON.stringify(listed)}`);+ expect(listed.items).toEqual([]);+ expect(fs.existsSync(blobAbs(root, stagingId))).toBe(false);+ expect(fs.existsSync(manifestAbs(root, stagingId))).toBe(false);+ expect(fs.existsSync(tombstoneAbs(root, stagingId))).toBe(false);++ const reclaimed = await restored.begin({+ ghostId, taskId: 'reclaimed-after-tombstone-cleanup', sourceRevision: 'rev-1',+ totalBytes: maxTotalBytes, sha256: sha256Of(payload), mime: 'image/png', recovery,+ });+ expect(reclaimed, `quota not returned after successful tombstone cleanup: ${JSON.stringify(reclaimed)}`).toMatchObject({ ok: true });+ if (!reclaimed.ok) return;+ const aborted = await restored.abort({ ghostId, stagingId: reclaimed.stagingId });+ expect(aborted).toMatchObject({ ok: true, aborted: true });+ });++ it('manifest 写失败后 commitPending blob 已落地:拒 abort 且不调 writeAbort,超额 begin 必须 STAGING_QUOTA,同 id commit 重试成功', async () => {+ const root = path.join(tmp, 'commit-pending-abort', ghostId);+ const maxTotalBytes = 40;+ const store = makeStore(root, { maxTotalBytes });+ const started = await beginChunk(store, 'pending-abort', 'a'.repeat(20));+ const origWrite = LibraryVault.prototype.write;+ const writeSpy = vi.spyOn(LibraryVault.prototype, 'write').mockImplementation(async function (this: LibraryVault, req) {+ if (typeof req.path === 'string' && req.path.endsWith('manifest.json')) {+ return { ok: false, errorCode: 'INTERNAL', message: 'manifest write failed' };+ }+ return origWrite.call(this, req);+ });+ const failedCommit = await store.commit({ ghostId, stagingId: started.stagingId });+ writeSpy.mockRestore();+ expect(failedCommit.ok).toBe(false);+ expect(fs.existsSync(blobAbs(root, started.stagingId))).toBe(true);+ expect(fs.existsSync(manifestAbs(root, started.stagingId))).toBe(false);++ const writeAbort = vi.spyOn(LibraryVault.prototype, 'writeAbort');+ const aborted = await store.abort({ ghostId, stagingId: started.stagingId });+ expect(writeAbort).not.toHaveBeenCalled();+ writeAbort.mockRestore();+ expect(aborted).toMatchObject({ ok: false, errorCode: 'STREAM_INVALID' });+ expect(fs.existsSync(blobAbs(root, started.stagingId))).toBe(true);+ expect(fs.existsSync(manifestAbs(root, started.stagingId))).toBe(false);++ const over = await store.begin({+ ghostId, taskId: 'over-after-pending-abort', sourceRevision: 'rev-1',+ totalBytes: 21, sha256: sha256Of('b'.repeat(21)), mime: 'image/png', recovery,+ });+ expect(over, `abort dropped undeleted blob from quota: ${JSON.stringify(over)}`).toMatchObject({+ ok: false, errorCode: 'STAGING_QUOTA',+ });+ expect(fs.existsSync(blobAbs(root, started.stagingId))).toBe(true);++ const retried = await store.commit({ ghostId, stagingId: started.stagingId });+ expect(retried).toMatchObject({ ok: true, stagingId: started.stagingId, durable: true, bytes: 20 });+ expect(fs.existsSync(blobAbs(root, started.stagingId))).toBe(true);+ expect(fs.existsSync(manifestAbs(root, started.stagingId))).toBe(true);+ });++ it('abort 不得删除已提交原件;不存在 TTL 清掉 unique durable', async () => {+ const root = path.join(tmp, 'no-ttl', ghostId);+ const store = makeStore(root, { maxTotalBytes: 1024 });+ const { stagingId } = await commitOne(store);+ const abortDurable = await store.abort({ ghostId, stagingId });+ expect(abortDurable).toMatchObject({ ok: false, errorCode: 'STREAM_INVALID' });+ expect(fs.existsSync(blobAbs(root, stagingId))).toBe(true);++ const other = await beginChunk(store, 'other', 'other-bytes');+ const abortedOther = await store.abort({ ghostId, stagingId: other.stagingId });+ expect(abortedOther).toMatchObject({ ok: true, aborted: true });+ await new Promise((resolve) => setTimeout(resolve, 20));+ const listed = await store.list({ ghostId });+ if (!listed.ok) throw new Error(JSON.stringify(listed));+ expect(listed.items.map((item) => item.stagingId)).toEqual([stagingId]);+ expect(fs.existsSync(blobAbs(root, stagingId))).toBe(true);+ });++ it('超过 Vault.listPageSize 的恢复与公开 list 游标:每条 durable 恰好一次且跨页合计字节', async () => {+ const pageSize = 2;+ expect(pageSize).toBeLessThan(DEFAULT_LIBRARY_LIMITS.listPageSize);+ const root = path.join(tmp, 'pages', ghostId);+ const writer = makeStore(root, { maxTotalBytes: 4096, listPageSize: pageSize });+ const expected = new Map<string, number>();+ for (let i = 0; i < pageSize + 3; i += 1) {+ const payload = `page-item-${i}`;+ const committed = await commitOne(writer, `task-${i}`, payload, `rev-${i}`);+ expected.set(committed.stagingId, Buffer.byteLength(payload));+ }+ expect(expected.size).toBeGreaterThan(DEFAULT_LIBRARY_LIMITS.listPageSize > pageSize ? pageSize : 0);+ expect(expected.size).toBeGreaterThan(pageSize);++ const vaultList = vi.spyOn(LibraryVault.prototype, 'list');+ const restored = makeStore(root, { maxTotalBytes: 4096, listPageSize: pageSize });+ const walked = await listAllPublic(restored, pageSize);+ const taskDirPages = vaultList.mock.calls.filter((args) => args[0]?.path === 'tasks').length;+ vaultList.mockRestore();+ expect(taskDirPages).toBeGreaterThan(1);++ const seen = walked.items.map((item) => item.stagingId);+ expect(seen.sort()).toEqual([...expected.keys()].sort());+ expect(new Set(seen).size).toBe(expected.size);+ const totalBytes = walked.items.reduce((sum, item) => sum + item.bytes, 0);+ const expectedBytes = [...expected.values()].reduce((sum, n) => sum + n, 0);+ expect(totalBytes).toBe(expectedBytes);+ expect(walked.items.length).toBeGreaterThan(pageSize);+ });++ it('成功恢复后多次 list/read/chunk 不再对已保留原件全量 hash', async () => {+ const root = path.join(tmp, 'no-rehash', ghostId);+ const { stagingId } = await commitOne(makeStore(root, { maxTotalBytes: 1024 }), 'kept', 'kept-bytes');+ const origHash = LibraryVault.prototype.hashFile;+ const hashSpy = vi.spyOn(LibraryVault.prototype, 'hashFile').mockImplementation(function (this: LibraryVault, relPath: string) {+ return origHash.call(this, relPath);+ });+ const restored = makeStore(root, { maxTotalBytes: 1024 });+ const listed = await restored.list({ ghostId });+ if (!listed.ok) throw new Error(JSON.stringify(listed));+ expect(listed.items.map((item) => item.stagingId)).toEqual([stagingId]);+ const hashesDuringRecovery = hashSpy.mock.calls.filter((args) => args[0] === `tasks/${stagingId}/blob.bin`).length;+ expect(hashesDuringRecovery).toBeGreaterThan(0);+ hashSpy.mockClear();++ const listedAgain = await restored.list({ ghostId });+ if (!listedAgain.ok) throw new Error(JSON.stringify(listedAgain));+ const read1 = await restored.read({ ghostId, stagingId });+ const read2 = await restored.read({ ghostId, stagingId, offset: 0, length: 4 });+ if (!read1.ok || !read2.ok) throw new Error('read after recovery failed');+ const extra = await beginChunk(restored, 'extra-after-recovery', 'xy');+ const extraChunk = await restored.chunk({+ ghostId, stagingId: extra.stagingId, seq: 1,+ content: Buffer.from('xy').toString('base64'), encoding: 'base64',+ });+ expect(extraChunk.ok).toBe(true);+ const retainedHashCalls = hashSpy.mock.calls.filter((args) => args[0] === `tasks/${stagingId}/blob.bin`);+ expect(retainedHashCalls).toEqual([]);+ });++ it('省略 length 的 >16MiB 原件返回 <=maxChunkBytes 前缀;显式分段正确;非法 offset/length 为 PATH_INVALID', async () => {+ const root = path.join(tmp, 'read-16m', ghostId);+ const store = makeStore(root, { maxTotalBytes: 32 * 1024 * 1024 });+ const payload = Buffer.alloc(DEFAULT_READ_CHUNK + 64, 7);+ payload[0] = 11;+ payload[DEFAULT_READ_CHUNK] = 22;+ payload[payload.byteLength - 1] = 33;+ const digest = sha256Of(payload);+ const begin = await store.begin({+ ghostId, taskId: 'big-image', sourceRevision: 'rev-1',+ totalBytes: payload.byteLength, sha256: digest, mime: 'image/png', recovery,+ });+ if (!begin.ok) throw new Error(JSON.stringify(begin));+ const first = payload.subarray(0, DEFAULT_READ_CHUNK);+ const rest = payload.subarray(DEFAULT_READ_CHUNK);+ const chunk1 = await store.chunk({+ ghostId, stagingId: begin.stagingId, seq: 1,+ content: first.toString('base64'), encoding: 'base64',+ });+ if (!chunk1.ok) throw new Error(JSON.stringify(chunk1));+ const chunk2 = await store.chunk({+ ghostId, stagingId: begin.stagingId, seq: 2,+ content: rest.toString('base64'), encoding: 'base64',+ });+ if (!chunk2.ok) throw new Error(JSON.stringify(chunk2));+ const commit = await store.commit({ ghostId, stagingId: begin.stagingId });+ if (!commit.ok) throw new Error(JSON.stringify(commit));++ const omitted = await store.read({ ghostId, stagingId: begin.stagingId });+ if (!omitted.ok) throw new Error(JSON.stringify(omitted));+ expect(omitted.bytes).toBe(DEFAULT_READ_CHUNK);+ expect(omitted.bytes).toBeLessThanOrEqual(DEFAULT_READ_CHUNK);+ expect(Buffer.from(omitted.content, 'base64').equals(first)).toBe(true);+ expect(omitted.sha256).toBe(sha256Of(first));++ const tail = await store.read({+ ghostId, stagingId: begin.stagingId, offset: DEFAULT_READ_CHUNK, length: 64,+ });+ if (!tail.ok) throw new Error(JSON.stringify(tail));+ expect(tail.bytes).toBe(64);+ expect(Buffer.from(tail.content, 'base64').equals(rest)).toBe(true);+ expect(tail.sha256).toBe(sha256Of(rest));++ const mid = await store.read({ ghostId, stagingId: begin.stagingId, offset: 1, length: 3 });+ if (!mid.ok) throw new Error(JSON.stringify(mid));+ expect(Buffer.from(mid.content, 'base64').equals(payload.subarray(1, 4))).toBe(true);++ const smallRoot = path.join(tmp, 'read-small', ghostId);+ const small = makeStore(smallRoot, { maxTotalBytes: 1024 });+ const { stagingId } = await commitOne(small, 'small-1', 'abcdefghijklmnopqrst');+ const whole = await small.read({ ghostId, stagingId });+ if (!whole.ok) throw new Error(JSON.stringify(whole));+ expect(whole.bytes).toBe(Buffer.byteLength('abcdefghijklmnopqrst'));++ expect(await small.read({ ghostId, stagingId, offset: -1 })).toMatchObject({ ok: false, errorCode: 'PATH_INVALID' });+ expect(await small.read({ ghostId, stagingId, length: 1.5 })).toMatchObject({ ok: false, errorCode: 'PATH_INVALID' });+ expect(await small.read({ ghostId, stagingId, offset: Number.NaN })).toMatchObject({ ok: false, errorCode: 'PATH_INVALID' });+ expect(await small.read({ ghostId, stagingId, length: Number.POSITIVE_INFINITY })).toMatchObject({ ok: false, errorCode: 'PATH_INVALID' });+ expect(await small.read({ ghostId, stagingId, offset: Number.NEGATIVE_INFINITY })).toMatchObject({ ok: false, errorCode: 'PATH_INVALID' });+ expect(await small.read({ ghostId, stagingId, length: DEFAULT_READ_CHUNK + 1 })).toMatchObject({ ok: false, errorCode: 'TOO_LARGE' });+ }, 60_000);++ it('同一 task/revision/metadata 在活跃上传与 commit 后 begin 幂等;末块精确重复接受、冲突重复拒绝', async () => {+ const store = makeStore(path.join(tmp, 'idempotent', ghostId), { maxTotalBytes: 1024, maxConcurrentWrites: 2 });+ const payload = 'abcd';+ const digest = sha256Of(payload);+ const first = await store.begin({+ ghostId, taskId: 'same-task', sourceRevision: 'rev-1',+ totalBytes: 4, sha256: digest, mime: 'image/png', recovery,+ });+ if (!first.ok) throw new Error(JSON.stringify(first));+ const againActive = await store.begin({+ ghostId, taskId: 'same-task', sourceRevision: 'rev-1',+ totalBytes: 4, sha256: digest, mime: 'image/png', recovery,+ });+ expect(againActive).toEqual({ ok: true, stagingId: first.stagingId });+ const other = await store.begin({+ ghostId, taskId: 'other-task', sourceRevision: 'rev-1',+ totalBytes: 4, sha256: sha256Of('wxyz'), mime: 'image/png', recovery,+ });+ expect(other.ok).toBe(true);++ const chunk = await store.chunk({+ ghostId, stagingId: first.stagingId, seq: 1,+ content: Buffer.from(payload).toString('base64'), encoding: 'base64',+ });+ expect(chunk).toMatchObject({ ok: true, accepted: 4 });+ const dup = await store.chunk({+ ghostId, stagingId: first.stagingId, seq: 1,+ content: Buffer.from(payload).toString('base64'), encoding: 'base64',+ });+ expect(dup).toMatchObject({ ok: true, accepted: 4 });+ const conflict = await store.chunk({+ ghostId, stagingId: first.stagingId, seq: 1,+ content: Buffer.from('abce').toString('base64'), encoding: 'base64',+ });+ expect(conflict).toMatchObject({ ok: false, errorCode: 'STREAM_INVALID' });+ const gap = await store.chunk({+ ghostId, stagingId: first.stagingId, seq: 3,+ content: Buffer.from(payload).toString('base64'), encoding: 'base64',+ });+ expect(gap).toMatchObject({ ok: false, errorCode: 'STREAM_INVALID' });++ const commit = await store.commit({ ghostId, stagingId: first.stagingId });+ if (!commit.ok) throw new Error(JSON.stringify(commit));+ const againCommitted = await store.begin({+ ghostId, taskId: 'same-task', sourceRevision: 'rev-1',+ totalBytes: 4, sha256: digest, mime: 'image/png', recovery,+ });+ expect(againCommitted).toEqual({ ok: true, stagingId: first.stagingId });+ const conflictingMeta = await store.begin({+ ghostId, taskId: 'same-task', sourceRevision: 'rev-1',+ totalBytes: 4, sha256: sha256Of('abce'), mime: 'image/png', recovery,+ });+ expect(conflictingMeta).toMatchObject({ ok: false, errorCode: 'ALREADY_EXISTS' });+ });++ it('null owner 与切账号后不得写新文件或读旧数据', async () => {+ const { store, stagingId } = await commitOne();+ scope = null;+ const listed = await store.list({ ghostId });+ expect(listed).toMatchObject({ ok: false, errorCode: 'OWNER_CHANGED' });+ scope = 'local:owner-b:1';+ const crossed = await store.read({ ghostId, stagingId });+ expect(crossed).toMatchObject({ ok: false, errorCode: 'OWNER_CHANGED' });+ });++ it('manifest 已落盘且 journalSync/delete 失败后,同实例重试读回身份并 durable,冲突 manifest 拒绝覆盖', async () => {+ const root = path.join(tmp, 'retained-manifest', ghostId);+ const store = makeStore(root, { maxTotalBytes: 1024 });+ const started = await beginChunk(store, 'retained', body);+ expect(fs.existsSync(intentAbs(root, started.stagingId))).toBe(true);+ const origWrite = LibraryVault.prototype.write;+ const origFsync = LibraryVault.prototype.fsyncDir;+ const origDelete = LibraryVault.prototype.delete;+ let failJournal = false;+ const writeSpy = vi.spyOn(LibraryVault.prototype, 'write').mockImplementation(async function (this: LibraryVault, req) {+ const result = await origWrite.call(this, req);+ if (typeof req.path === 'string' && req.path.endsWith('manifest.json') && result.ok) failJournal = true;+ return result;+ });+ const fsyncSpy = vi.spyOn(LibraryVault.prototype, 'fsyncDir').mockImplementation(async function (this: LibraryVault, relPath?: unknown) {+ if (failJournal) return { ok: false, errorCode: 'INTERNAL', message: 'journal fsync 失败' };+ return origFsync.call(this, relPath);+ });+ const deleteSpy = vi.spyOn(LibraryVault.prototype, 'delete').mockImplementation(async function (this: LibraryVault, req) {+ if (typeof req.path === 'string' && req.path.endsWith('manifest.json')) {+ return { ok: false, errorCode: 'INTERNAL', message: 'manifest delete failed' };+ }+ return origDelete.call(this, req);+ });+ try {+ const failed = await store.commit({ ghostId, stagingId: started.stagingId });+ expect(failed.ok).toBe(false);+ if (!failed.ok) expect(failed.errorCode).toBe('INTERNAL');+ expect(fs.existsSync(manifestAbs(root, started.stagingId))).toBe(true);+ expect(fs.existsSync(blobAbs(root, started.stagingId))).toBe(true);+ } finally {+ writeSpy.mockRestore();+ fsyncSpy.mockRestore();+ deleteSpy.mockRestore();+ }+ const retried = await store.commit({ ghostId, stagingId: started.stagingId });+ expect(retried).toMatchObject({ ok: true, stagingId: started.stagingId, durable: true, bytes: Buffer.byteLength(body) });+ const listed = await store.list({ ghostId });+ if (!listed.ok) throw new Error(JSON.stringify(listed));+ expect(listed.items.map((item) => item.stagingId)).toEqual([started.stagingId]);++ const conflictRoot = path.join(tmp, 'conflict-manifest', ghostId);+ const conflictStore = makeStore(conflictRoot, { maxTotalBytes: 1024 });+ const other = await beginChunk(conflictStore, 'conflict', body);+ const origFsync2 = LibraryVault.prototype.fsyncDir;+ const plant = vi.spyOn(LibraryVault.prototype, 'fsyncDir').mockImplementation(async function (this: LibraryVault, relPath?: unknown) {+ if (relPath === `tasks/${other.stagingId}` && !fs.existsSync(manifestAbs(conflictRoot, other.stagingId))) {+ const r = await origFsync2.call(this, relPath);+ await fs.promises.writeFile(manifestAbs(conflictRoot, other.stagingId), JSON.stringify({+ version: 1, durable: true, intent: false,+ stagingId: other.stagingId, ghostId, ownerScopeKey: 'local:owner-a:1',+ taskId: 'not-this-task', sourceRevision: 'rev-x',+ sha256: other.digest, bytes: other.bytes, mime: 'image/png', recovery,+ }));+ return r;+ }+ return origFsync2.call(this, relPath);+ });+ try {+ const conflicted = await conflictStore.commit({ ghostId, stagingId: other.stagingId });+ expect(conflicted).toMatchObject({ ok: false, errorCode: 'ALREADY_EXISTS' });+ const onDisk = JSON.parse(await fs.promises.readFile(manifestAbs(conflictRoot, other.stagingId), 'utf8')) as { taskId: string };+ expect(onDisk.taskId).toBe('not-this-task');+ expect(fs.existsSync(blobAbs(conflictRoot, other.stagingId))).toBe(true);+ } finally {+ plant.mockRestore();+ }+ });++ it('intent 在 blob 就位前 fsync 失败则回滚;intent+blob 重启后恢复;冲突/不完整 fail-closed 保留源;release 清 intent;无配额泄漏', async () => {+ const fsyncRoot = path.join(tmp, 'intent-fsync', ghostId);+ const fsyncStore = makeStore(fsyncRoot, { maxTotalBytes: 1024 });+ const origFsync = LibraryVault.prototype.fsyncDir;+ const fsyncSpy = vi.spyOn(LibraryVault.prototype, 'fsyncDir').mockImplementation(async function (this: LibraryVault, relPath?: unknown) {+ if (relPath === 'tasks' || relPath === '') {+ return { ok: false, errorCode: 'INTERNAL', message: 'intent parent fsync 失败' };+ }+ return origFsync.call(this, relPath);+ });+ try {+ const began = await fsyncStore.begin({+ ghostId, taskId: 'intent-fsync', sourceRevision: 'rev-1',+ totalBytes: Buffer.byteLength(body), sha256: sha, mime: 'image/png', recovery,+ });+ expect(began.ok).toBe(false);+ if (!began.ok) expect(began.errorCode).toBe('INTERNAL');+ } finally {+ fsyncSpy.mockRestore();+ }+ const taskDirs = fs.existsSync(path.join(fsyncRoot, 'tasks'))+ ? await fs.promises.readdir(path.join(fsyncRoot, 'tasks'))+ : [];+ for (const id of taskDirs) {+ expect(fs.existsSync(intentAbs(fsyncRoot, id))).toBe(false);+ expect(fs.existsSync(blobAbs(fsyncRoot, id))).toBe(false);+ }++ const recoverRoot = path.join(tmp, 'intent-recover', ghostId);+ const live = makeStore(recoverRoot, { maxTotalBytes: 20 });+ const started = await beginChunk(live, 'intent-crash', 'x'.repeat(20));+ expect(fs.existsSync(intentAbs(recoverRoot, started.stagingId))).toBe(true);+ const origWrite = LibraryVault.prototype.write;+ const writeSpy = vi.spyOn(LibraryVault.prototype, 'write').mockImplementation(async function (this: LibraryVault, req) {+ if (typeof req.path === 'string' && req.path.endsWith('manifest.json')) {+ return { ok: false, errorCode: 'INTERNAL', message: 'manifest write failed' };+ }+ return origWrite.call(this, req);+ });+ try {+ const failed = await live.commit({ ghostId, stagingId: started.stagingId });+ expect(failed.ok).toBe(false);+ expect(fs.existsSync(blobAbs(recoverRoot, started.stagingId))).toBe(true);+ expect(fs.existsSync(manifestAbs(recoverRoot, started.stagingId))).toBe(false);+ expect(fs.existsSync(intentAbs(recoverRoot, started.stagingId))).toBe(true);+ } finally {+ writeSpy.mockRestore();+ }+ const restored = makeStore(recoverRoot, { maxTotalBytes: 20 });+ const listed = await restored.list({ ghostId });+ if (!listed.ok) throw new Error(`intent recover list: ${JSON.stringify(listed)}`);+ expect(listed.items.map((item) => item.stagingId)).toEqual([started.stagingId]);+ expect(listed.items[0]?.durable).toBe(true);+ expect(fs.existsSync(manifestAbs(recoverRoot, started.stagingId))).toBe(true);+ const read = await restored.read({ ghostId, stagingId: started.stagingId });+ if (!read.ok) throw new Error(JSON.stringify(read));+ expect(Buffer.from(read.content, 'base64').toString('utf8')).toBe('x'.repeat(20));+ const leaked = await restored.begin({+ ghostId, taskId: 'should-quota', sourceRevision: 'rev-1',+ totalBytes: 1, sha256: sha256Of('y'), mime: 'image/png', recovery,+ });+ expect(leaked).toMatchObject({ ok: false, errorCode: 'STAGING_QUOTA' });+ const released = await restored.release({+ ghostId, stagingId: started.stagingId, ack: matchingAck({ sha256: started.digest, bytes: 20 }),+ });+ expect(released).toEqual({ ok: true, stagingId: started.stagingId, released: true });+ expect(fs.existsSync(intentAbs(recoverRoot, started.stagingId))).toBe(false);+ expect(fs.existsSync(blobAbs(recoverRoot, started.stagingId))).toBe(false);++ const conflictId = randomUUID();+ const conflictRoot = path.join(tmp, 'intent-conflict', ghostId);+ await fs.promises.mkdir(path.join(conflictRoot, 'tasks', conflictId), { recursive: true });+ await fs.promises.writeFile(path.join(conflictRoot, 'tasks', conflictId, 'blob.bin'), body);+ await fs.promises.writeFile(path.join(conflictRoot, 'tasks', conflictId, 'intent.json'), JSON.stringify({+ version: 1, intent: true,+ stagingId: conflictId, ghostId, ownerScopeKey: 'local:owner-a:1',+ taskId: 'guessed', sourceRevision: 'rev-1',+ sha256: '0'.repeat(64), bytes: Buffer.byteLength(body), mime: 'image/png', recovery,+ }));+ const conflicted = makeStore(conflictRoot, { maxTotalBytes: 1024 });+ const conflictList = await conflicted.list({ ghostId });+ expect(conflictList).toMatchObject({ ok: false, errorCode: 'LIBRARY_UNAVAILABLE' });+ expect(fs.existsSync(blobAbs(conflictRoot, conflictId))).toBe(true);+ });++ it('闲置未完成上传超时后让出并发槽,不扫 commitPending/durable', async () => {+ let now = 1_000;+ const store = makeStore(path.join(tmp, 'idle-busy', ghostId), {+ maxConcurrentWrites: 1,+ maxTotalBytes: 1024,+ streamIdleTimeoutMs: 10,+ now: () => now,+ });+ const first = await store.begin({+ ghostId, taskId: 'idle-one', sourceRevision: 'r',+ totalBytes: 4, sha256: sha256Of('idle'), mime: 'image/png', recovery,+ });+ if (!first.ok) throw new Error(JSON.stringify(first));+ const busy = await store.begin({+ ghostId, taskId: 'blocked', sourceRevision: 'r',+ totalBytes: 4, sha256: sha256Of('next'), mime: 'image/png', recovery,+ });+ expect(busy).toMatchObject({ ok: false, errorCode: 'STAGING_BUSY' });+ now = 1_020;+ const second = await store.begin({+ ghostId, taskId: 'after-idle', sourceRevision: 'r',+ totalBytes: 4, sha256: sha256Of('next'), mime: 'image/png', recovery,+ });+ if (!second.ok) throw new Error(JSON.stringify(second));+ expect(second.stagingId).not.toBe(first.stagingId);+ expect(fs.existsSync(intentAbs(path.join(tmp, 'idle-busy', ghostId), first.stagingId))).toBe(false);+ expect(await store.abort({ ghostId, stagingId: second.stagingId })).toMatchObject({ ok: true, aborted: true });++ const durable = await commitOne(store, 'keep-durable', 'keep');+ now = 2_000;+ const stillListed = await store.list({ ghostId });+ if (!stillListed.ok) throw new Error(JSON.stringify(stillListed));+ expect(stillListed.items.map((item) => item.stagingId)).toContain(durable.stagingId);+ });++ it('并发预留计入磁盘保留水位,不删已落地 commitPending 原件', async () => {+ const gib = 1024 ** 3;+ const store = makeStore(path.join(tmp, 'reserve', ghostId), {+ maxConcurrentWrites: 2,+ maxTotalBytes: 8 * gib,+ maxTaskBytes: 4 * gib,+ reserveBytes: gib,+ getDiskFreeBytes: async () => 6 * gib,+ });+ const hashA = 'a'.repeat(64);+ const hashB = 'b'.repeat(64);+ const first = await store.begin({+ ghostId, taskId: 'reserve-a', sourceRevision: 'r',+ totalBytes: 3 * gib, sha256: hashA, mime: 'image/png', recovery,+ });+ if (!first.ok) throw new Error(JSON.stringify(first));+ const second = await store.begin({+ ghostId, taskId: 'reserve-b', sourceRevision: 'r',+ totalBytes: 3 * gib, sha256: hashB, mime: 'image/png', recovery,+ });+ expect(second).toMatchObject({ ok: false, errorCode: 'DISK_FULL' });+ const abortFirst = await store.abort({ ghostId, stagingId: first.stagingId });+ expect(abortFirst).toMatchObject({ ok: true, aborted: true });+ });++ it('闲置清扫 unlink 失败后本次 begin 仍计入残片额度', async () => {+ let now = 1_000;+ const root = path.join(tmp, 'idle-residue', ghostId);+ const store = makeStore(root, {+ maxConcurrentWrites: 2,+ maxTotalBytes: 60,+ streamIdleTimeoutMs: 10,+ now: () => now,+ });+ const payload = 'x'.repeat(50);+ const first = await store.begin({+ ghostId, taskId: 'idle-residue', sourceRevision: 'r',+ totalBytes: payload.length, sha256: sha256Of(payload), mime: 'image/png', recovery,+ });+ if (!first.ok) throw new Error(JSON.stringify(first));+ const chunk = await store.chunk({+ ghostId, stagingId: first.stagingId, seq: 1,+ content: Buffer.from(payload).toString('base64'), encoding: 'base64',+ });+ if (!chunk.ok) throw new Error(JSON.stringify(chunk));+ const realUnlink = fs.promises.unlink.bind(fs.promises);+ const unlinkSpy = vi.spyOn(fs.promises, 'unlink').mockImplementation(async (target, ...rest) => {+ if (String(target).includes(`${path.sep}.cindy-library${path.sep}tmp${path.sep}`)) {+ throw Object.assign(new Error('EACCES unlink tmp'), { code: 'EACCES' });+ }+ return realUnlink(target, ...rest);+ });+ now = 1_020;+ const second = await store.begin({+ ghostId, taskId: 'after-residue', sourceRevision: 'r',+ totalBytes: 20, sha256: sha256Of('y'.repeat(20)), mime: 'image/png', recovery,+ });+ unlinkSpy.mockRestore();+ expect(second).toMatchObject({ ok: false, errorCode: 'STAGING_QUOTA' });+ });++ it('磁盘保留只扣未写入剩余;commitPending 不再重复占预留', async () => {+ const store = makeStore(path.join(tmp, 'unwritten-reserve', ghostId), {+ maxConcurrentWrites: 2,+ maxTotalBytes: 10_000,+ maxTaskBytes: 10_000,+ maxChunkBytes: 10_000,+ reserveBytes: 10,+ getDiskFreeBytes: async () => 1000,+ });+ const payload = 'z'.repeat(80);+ const first = await store.begin({+ ghostId, taskId: 'partial', sourceRevision: 'r',+ totalBytes: payload.length, sha256: sha256Of(payload), mime: 'image/png', recovery,+ });+ if (!first.ok) throw new Error(JSON.stringify(first));+ const chunk = await store.chunk({+ ghostId, stagingId: first.stagingId, seq: 1,+ content: Buffer.from(payload).toString('base64'), encoding: 'base64',+ });+ if (!chunk.ok) throw new Error(JSON.stringify(chunk));+ const next = await store.begin({+ ghostId, taskId: 'fits-remaining', sourceRevision: 'r',+ totalBytes: 960, sha256: sha256Of('n'.repeat(960)), mime: 'image/png', recovery,+ });+ expect(next.ok).toBe(true);+ });++ it('同 owner 进程重启 generation 变化后仍恢复磁盘 durable,不报 manifest 字段非法', async () => {+ const root = path.join(tmp, 'gen-restart', ghostId);+ const first = makeStore(root, { ownerScopeKey: 'local:local-v1:2', maxTotalBytes: 1024 });+ const committed = await commitOne(first, 'restart-task', body);+ const onDisk = JSON.parse(await fs.promises.readFile(manifestAbs(root, committed.stagingId), 'utf8')) as {+ ownerScopeKey: string;+ version: number;+ durable: boolean;+ };+ expect(onDisk).toMatchObject({ ownerScopeKey: 'local:local-v1:2', version: 1, durable: true });+ expect(fs.existsSync(blobAbs(root, committed.stagingId))).toBe(true);++ const restarted = makeStore(root, { ownerScopeKey: 'local:local-v1:0', maxTotalBytes: 1024 });+ const listed = await restarted.list({ ghostId });+ if (!listed.ok) throw new Error(JSON.stringify(listed));+ expect(listed.items.map((item) => item.stagingId)).toEqual([committed.stagingId]);+ const read = await restarted.read({ ghostId, stagingId: committed.stagingId });+ if (!read.ok) throw new Error(JSON.stringify(read));+ expect(read.sha256).toBe(committed.digest);++ const otherOwner = makeStore(root, { ownerScopeKey: 'local:owner-b:0', maxTotalBytes: 1024 });+ expect(await otherOwner.list({ ghostId })).toMatchObject({+ ok: false, errorCode: 'LIBRARY_UNAVAILABLE', message: 'staging manifest 字段非法',+ });+ });+});diff --git a/apps/desktop/src/main/cindy-brain/__tests__/libraryVault.test.ts b/apps/desktop/src/main/cindy-brain/__tests__/libraryVault.test.tsindex 55ce4afe88..6ad9228aa5 100644--- a/apps/desktop/src/main/cindy-brain/__tests__/libraryVault.test.ts+++ b/apps/desktop/src/main/cindy-brain/__tests__/libraryVault.test.ts@@ -124,6 +124,34 @@ describe('LibraryVault', () => {expect(stat.isDirectory()).toBe(true);});+ it('custom 已建过(allowCustomInit=false)且新 vault: ghost 子目录 MISSING 不得空库重建', async () => {+ const parent = path.join(tmpRoot, 'picked-no-init');+ const custom = path.join(parent, 'mivo-canvas');+ await fs.promises.mkdir(parent, { recursive: true });+ const vault = makeVault({+ rootDir: () => custom,+ locationKind: 'custom',+ allowCustomInit: false,+ });+ const missing = await vault.open();+ expect(missing).toMatchObject({ ok: true, state: 'unavailable', reason: 'disk-missing' });+ expect(fs.existsSync(path.join(custom, '.cindy-library', 'meta.json'))).toBe(false);+ });++ it('custom 已 open 后 ghost 子目录消失: 再 open 报 disk-missing 且不重建空库', async () => {+ const parent = path.join(tmpRoot, 'picked-ghost-gone');+ const custom = path.join(parent, 'mivo-canvas');+ await fs.promises.mkdir(custom, { recursive: true });+ await fs.promises.writeFile(path.join(custom, 'keep.txt'), 'keep-me');+ const vault = makeVault({ rootDir: () => custom, locationKind: 'custom' });+ expect(await vault.open()).toMatchObject({ ok: true, state: 'ready' });+ await fs.promises.rename(custom, `${custom}.parked`);+ const missing = await vault.open();+ expect(missing).toMatchObject({ ok: true, state: 'unavailable', reason: 'disk-missing' });+ expect(fs.existsSync(custom)).toBe(false);+ expect(fs.existsSync(path.join(parent, 'mivo-canvas', '.cindy-library', 'meta.json'))).toBe(false);+ expect(fs.existsSync(path.join(`${custom}.parked`, 'keep.txt'))).toBe(true);+ });it('custom 用户父目录消失: open 报 disk-missing 且不重建空库; keep 仍在 rename 走的目录', async () => {const parent = path.join(tmpRoot, 'picked');const custom = path.join(parent, 'mivo-canvas');@@ -565,6 +593,73 @@ describe('LibraryVault', () => {// staging 清空。const tmpEntries = await fs.promises.readdir(path.join(libraryRoot, '.cindy-library', 'tmp'));expect(tmpEntries).toEqual([]);+ const dirSync = await vault.fsyncDir('assets');+ expect(dirSync.ok).toBe(true);+ if (dirSync.ok) {+ if (process.platform === 'win32') expect(dirSync.fsynced).toBe(false);+ else expect(dirSync.fsynced).toBe(true);+ }+ const residue = await vault.tmpResidueBytes();+ expect(residue).toEqual({ ok: true, bytes: 0 });+ });++ it('fsyncCreatedAncestors 同步新建根的父目录项,只 fsync 根不等于根 entry 已耐久', async () => {+ const nestedRoot = path.join(tmpRoot, 'owners', 'a', 'library-staging', 'test-ghost');+ const vault = makeVault({ rootDir: () => nestedRoot });+ const opened = await vault.open();+ expect(opened.ok).toBe(true);+ const parent = path.dirname(nestedRoot);+ expect(fs.existsSync(parent)).toBe(true);+ const synced = new Set<string>();+ const origOpen = fs.promises.open.bind(fs.promises);+ const spy = vi.spyOn(fs.promises, 'open').mockImplementation(async (file, flags, mode) => {+ const handle = await origOpen(file, flags, mode);+ if (typeof file === 'string' && flags === 'r') {+ const origSync = handle.sync.bind(handle);+ handle.sync = async () => {+ synced.add(path.resolve(file));+ return origSync();+ };+ }+ return handle;+ });+ try {+ const ok = await vault.fsyncCreatedAncestors();+ expect(ok.ok).toBe(true);+ if (process.platform === 'win32') {+ if (ok.ok) expect(ok.fsynced).toBe(false);+ } else {+ if (ok.ok) expect(ok.fsynced).toBe(true);+ expect(synced.has(path.resolve(parent))).toBe(true);+ }+ } finally {+ spy.mockRestore();+ }+ });++ it('fsyncCreatedAncestors 父目录 fsync 失败则 INTERNAL,不得当耐久', async () => {+ const nestedRoot = path.join(tmpRoot, 'owners', 'b', 'library-staging', 'test-ghost');+ const vault = makeVault({ rootDir: () => nestedRoot });+ await vault.open();+ const parent = path.resolve(path.dirname(nestedRoot));+ const origOpen = fs.promises.open.bind(fs.promises);+ const spy = vi.spyOn(fs.promises, 'open').mockImplementation(async (file, flags, mode) => {+ if (typeof file === 'string' && path.resolve(file) === parent && flags === 'r') {+ throw Object.assign(new Error('EIO'), { code: 'EIO' });+ }+ return origOpen(file, flags, mode);+ });+ try {+ const failed = await vault.fsyncCreatedAncestors();+ if (process.platform === 'win32') {+ expect(failed).toEqual({ ok: true, fsynced: false });+ } else {+ expect(failed.ok).toBe(false);+ if (!failed.ok) expect(failed.errorCode).toBe('INTERNAL');+ }+ } finally {+ spy.mockRestore();+ }});it('sha256 声明不符 → STREAM_INVALID 且不留目标文件', async () => {@@ -637,6 +732,8 @@ describe('LibraryVault', () => {const flat = await vault.list({ path: 'canvases/c1' });if (flat.ok) expect(flat.entries.map((e) => e.path)).toEqual(['canvases/c1/state.json']);+ const compatible = await vault.list({ recursive: false });+ expect(compatible.ok).toBe(true);});});@@ -771,6 +868,11 @@ describe('LibraryVault', () => {expect(r.ok).toBe(false);const d = await vault.delete({ path: 'escape-door/anything' });expect(d.ok).toBe(false);+ const compatible = await vault.list({ recursive: false });+ expect(compatible.ok).toBe(true);+ const strict = await vault.list({ recursive: false, strict: true });+ expect(strict.ok).toBe(false);+ if (!strict.ok) expect(strict.errorCode).toBe('LIBRARY_UNAVAILABLE');});});@@ -789,6 +891,8 @@ describe('LibraryVault', () => {expect(r.sha256).toBe(sha256Of(body));expect(r.bytes).toBe(Buffer.byteLength(body));}+ const hashed = await vault.hashFile(rel);+ expect(hashed).toEqual({ ok: true, path: rel, bytes: Buffer.byteLength(body), sha256: sha256Of(body) });});it('打开后目标 identity 变化 → INTERNAL 且不得返回字节', async () => {diff --git a/apps/desktop/src/main/cindy-brain/forge.ts b/apps/desktop/src/main/cindy-brain/forge.tsindex 29adb1a6f1..010955c086 100644--- a/apps/desktop/src/main/cindy-brain/forge.ts+++ b/apps/desktop/src/main/cindy-brain/forge.ts@@ -3586,7 +3586,10 @@ const st = await cindy.library({ op: 'status' });// 只读能力查询:资格审与 op 合法性之后、会话创建之前返回;不打开库、不弹窗const caps = await cindy.library({ op: 'capabilities' });// caps = { ok:true, op:'capabilities',-// capabilities:{ version:1, operations:['clipboardWrite','saveAs'] } }+// capabilities:{ version:1,+// operations:['clipboardWrite','saveAs','staging.begin',...],+// staging:{ version:1, maxTaskBytes, maxTotalBytes,+// maxConcurrentWrites, maxChunkBytes, reserveBytes } } }// operations 只表示宿主实现了这些 op,不等于此刻有窗口 / 已授权 / 库可用// 文件操作(全 Family;写入原子化,大文件走分块流)@@ -3633,6 +3636,18 @@ await cindy.library({ op: 'db.migrate', dbPath: 'canvas.sqlite', targetVersion:{ toVersion: 2, sql: ['CREATE TABLE v2 (a TEXT)'] }] });await cindy.library({ op: 'db.backup', dbPath: 'library.sqlite' }); // 宿主命名空间await cindy.library({ op: 'db.check', dbPath: 'library.sqlite' }); // quick_check++// 后台暂存(staging.*):独立于可迁移 Library 根,不是第二媒体库,不返回 imageRef。+const up = await cindy.library({+ op: 'staging.begin', taskId, sourceRevision, totalBytes, sha256, mime, recovery,+});+await cindy.library({ op: 'staging.chunk', stagingId: up.stagingId, seq: 1, content: b64, encoding: 'base64' });+const receipt = await cindy.library({ op: 'staging.commit', stagingId: up.stagingId });+// receipt.durable === true 才可当跨退出原件。release 带当前 Library ACK 的 bytes(不是 begin 的 totalBytes),且画布已保存后才调用。+await cindy.library({+ op: 'staging.release', stagingId: up.stagingId, path, sha256, bytes,+ libraryIdentity, libraryGeneration,+});\`\`\`关键语义(全部由宿主强制):@@ -3649,6 +3664,7 @@ await cindy.library({ op: 'db.check', dbPath: 'library.sqlite' }); // quick_chopen/status 失败),非法请求=\`INVALID_REQUEST\`(含非法/越界 dbPath 与未知 op),取消=\`CANCELLED\`;成功 open/status 的 \`state:'unavailable'\` 仍用结果体 reason(如 disk-missing),不是失败 reason 枚举;查询/传输层本地分类 \`TIMEOUT\` / \`TRANSPORT_ERROR\`;+- **staging.***:后台暂存,不是媒体库、不弹新 UI。\`staging.read\` 未传 length 默认 16MiB 分片;负数/NaN offset/length 是 \`PATH_INVALID\`。release 必须带当前 Library ACK 的 \`bytes\`(不是 begin 的 \`totalBytes\`),且只在画布保存后调用。父目录 fsync 失败不得 \`durable:true\`。- **capabilities**:先查 \`{ op:'capabilities' }\`。仅 \`version===1\` 且\`operations\` 为**全部字符串**的数组才有效;额外字段忽略,未知 operation 忽略,已知项保留;有效 v1 清单缺少某项才是 unsupported。缺字段、错类型(含数组内混入diff --git a/apps/desktop/src/main/cindy-brain/index.ts b/apps/desktop/src/main/cindy-brain/index.tsindex bb4b3c78c0..4a6d1ae813 100644--- a/apps/desktop/src/main/cindy-brain/index.ts+++ b/apps/desktop/src/main/cindy-brain/index.ts@@ -327,6 +327,7 @@ import { GhostFsSlot } from './fsSlot.js';import { GhostLibrarySlot } from './librarySlot.js';import { LibraryBindingStore, validateLibraryCandidateLocation } from './libraryBinding.js';import { LibraryVault, statfsFreeBytes, DEFAULT_LIBRARY_LIMITS } from './libraryVault.js';+import { LibraryStagingStore } from './libraryStaging.js';import { LibrarySqlService, defaultLibraryDbWorkerPath } from './librarySqlService.js';import { trashGhostLibrary } from './libraryTrash.js';import { migrateGhostLibrary } from './libraryMigrate.js';@@ -1031,8 +1032,9 @@ export async function interruptGhostCallsForAccountBoundary(): Promise<void> {getForgeOidcInstallConfirmBridge()?.cancelAll();runtimeSingleton?.destroyAll();resetNodeRuntimeBrokerForAccountBoundary();- // Library 会话一并作废:关 db worker + 作废 handle——在途写入已在串行链上- // 归属原 owner 完成或随 vault.invalidate 作废,新 owner 解析到全新根。+ // Drain in-flight staging.release (tombstone/fsync) before tearing Library+ // sessions. Owner mutation leases stay held until each call unwinds; waiting+ // for idle first would let marker-window teardown race the lease.await getGhostLibrarySlot().disposeAll();if (libraryExtraDirSync) {await libraryExtraDirSync(null).catch((error) => {@@ -5403,6 +5405,10 @@ export function getGhostLibrarySlot(): GhostLibrarySlot {getGhost: findAvailableGhost,bindingStore,getDefaultRoot: (ghostId) => ownerScopedUserDataPath('libraries', ghostId),+ getStagingRoot: (ghostId) => ownerScopedUserDataPath('library-staging', ghostId),+ createStagingStore: (deps) => new LibraryStagingStore(deps),+ captureMutationOwner: () => captureGhostMutationOwner(),+ beginMutation: (expected) => beginGhostMutation(expected as ActiveAppSession | undefined),captureOwnerScope: () => activeOwnerScopeKey(),createVault: (deps) => new LibraryVault(deps),createSqlService: (deps) => new LibrarySqlService(deps),@@ -5620,30 +5626,36 @@ export async function getGhostLibraryOverview(ghostId: string): Promise<GhostLib*/export async function deleteGhostLibraryForActiveOwner(ghostId: string): Promise<{ ok: boolean; message?: string }> {if (!isValidGhostId(ghostId)) return { ok: false, message: '非法插件 id' };- await getGhostLibrarySlot().disposeGhost(ghostId);- const result = await trashGhostLibrary(ghostId, {- // 默认根与自定义根都经 binding store 的解析口径(漂移时返回 null → 上层- // 引导恢复位置,不误删)。- resolveLibraryRoot: async (id) => {- const resolution = await getGhostLibraryBindingStore().resolveLibraryRoot(id);- return resolution.kind === 'custom' ? resolution.root : ownerScopedUserDataPath('libraries', id);- },- trashRoot: () => ownerScopedUserDataPath('libraries-trash'),- removeBinding: async (id) => {- await getGhostLibraryBindingStore().removeBinding(id);- },- log,- });- if (result.ok) {- await refreshMivoLibraryExtraDirGrant().catch((error) => {- log.warn('library extraDirs delete sync failed', {- ghostId,- error: error instanceof Error ? error.message : String(error),- });+ const slot = getGhostLibrarySlot();+ slot.setRelocating(ghostId, true);+ try {+ await slot.disposeGhost(ghostId);+ const result = await trashGhostLibrary(ghostId, {+ // 默认根与自定义根都经 binding store 的解析口径(漂移时返回 null → 上层+ // 引导恢复位置,不误删)。+ resolveLibraryRoot: async (id) => {+ const resolution = await getGhostLibraryBindingStore().resolveLibraryRoot(id);+ return resolution.kind === 'custom' ? resolution.root : ownerScopedUserDataPath('libraries', id);+ },+ trashRoot: () => ownerScopedUserDataPath('libraries-trash'),+ removeBinding: async (id) => {+ await getGhostLibraryBindingStore().removeBinding(id);+ },+ log,});- return { ok: true };+ if (result.ok) {+ await refreshMivoLibraryExtraDirGrant().catch((error) => {+ log.warn('library extraDirs delete sync failed', {+ ghostId,+ error: error instanceof Error ? error.message : String(error),+ });+ });+ return { ok: true };+ }+ return { ok: false, message: result.message };+ } finally {+ slot.setRelocating(ghostId, false);}- return { ok: false, message: result.message };}let libraryBindingStoreSingleton: LibraryBindingStore | null = null;@@ -7977,15 +7989,19 @@ export function registerGhostIpc(): void {throwIpcError('INVALID_PARAMS', '参数非法');}const releaseMutation = beginGhostMutation();+ const slot = getGhostLibrarySlot();try {+ slot.setRelocating(id, true);+ await slot.disposeGhost(id); // drain in-flight staging.release before binding changesconst set = await getGhostLibraryBindingStore().setBinding(id, candidate, (root) =>statfsFreeBytes(root),);if (!set.ok) return { ok: false as const, message: set.message };- await getGhostLibrarySlot().disposeGhost(id); // 作废会话,下一请求用新根+ await slot.disposeGhost(id); // 作废会话,下一请求用新根await refreshMivoLibraryExtraDirGrant();return { ok: true as const, warnings: set.warnings };} finally {+ slot.setRelocating(id, false);releaseMutation();}});@@ -8021,12 +8037,16 @@ export function registerGhostIpc(): void {assertTrustedAppRendererEvent(event);if (typeof id !== 'string' || !isValidGhostId(id)) throwIpcError('INVALID_PARAMS', '非法插件 id');const releaseMutation = beginGhostMutation();+ const slot = getGhostLibrarySlot();try {+ slot.setRelocating(id, true);+ await slot.disposeGhost(id);await getGhostLibraryBindingStore().removeBinding(id);- await getGhostLibrarySlot().disposeGhost(id);+ await slot.disposeGhost(id);await refreshMivoLibraryExtraDirGrant();return { ok: true as const };} finally {+ slot.setRelocating(id, false);releaseMutation();}});diff --git a/apps/desktop/src/main/cindy-brain/libraryBinding.ts b/apps/desktop/src/main/cindy-brain/libraryBinding.tsindex f043f3cd10..f1528f531e 100644--- a/apps/desktop/src/main/cindy-brain/libraryBinding.ts+++ b/apps/desktop/src/main/cindy-brain/libraryBinding.ts@@ -33,6 +33,11 @@ export interface LibraryBindingRecord {grantedAt: number;/** 每次重新绑定递增;迁移切换时原子写入。 */generation: number;+ /**+ * false = 授权后尚未成功建出 `<parent>/<ghostId>`。缺省/true = 已经建过,+ * ghost 子目录 MISSING 时不得空库重建。旧文件无此字段按已建过处理。+ */+ libraryReady?: boolean;}export interface LibraryBindingFileData {@@ -263,6 +268,7 @@ export class LibraryBindingStore {identity,grantedAt: this.now,generation: (prev?.generation ?? 0) + 1,+ libraryReady: false,};data.bindings[ghostId] = record;await this.writeData(data);@@ -286,6 +292,17 @@ export class LibraryBindingStore {return this.readData().then((d) => d.bindings[ghostId] ?? null);}+ /** First successful custom open: persist ready without bumping generation. */+ async markLibraryReady(ghostId: string): Promise<void> {+ await this.runSerialized(async () => {+ const data = await this.readData();+ const rec = data.bindings[ghostId];+ if (!rec || rec.libraryReady === true) return;+ data.bindings[ghostId] = { ...rec, libraryReady: true };+ await this.writeData(data);+ });+ }+/*** 解析库根:无 binding → 系统默认;有 binding → 漂移检测(realpath 重解 +* identity 比对)。漂移时返回 root:null,上层必须进入 unavailable 状态并diff --git a/apps/desktop/src/main/cindy-brain/librarySlot.ts b/apps/desktop/src/main/cindy-brain/librarySlot.tsindex bd80313c6d..25c3e262a0 100644--- a/apps/desktop/src/main/cindy-brain/librarySlot.ts+++ b/apps/desktop/src/main/cindy-brain/librarySlot.ts@@ -34,6 +34,13 @@ import { LibraryVault, validateLibraryRelPath, DEFAULT_LIBRARY_LIMITS, type Librimport { LibraryBindingStore, type LibraryLocationResolution } from './libraryBinding.js';import { LibrarySqlService, type LibrarySqlServiceDeps } from './librarySqlService.js';import type { LibraryDbResult } from './libraryDbCore.js';+import {+ isGhostLibraryStagingOp,+ LibraryStagingStore,+ type LibraryStagingAck,+ type LibraryStagingDeps,+ type LibraryStagingFailure,+} from './libraryStaging.js';/** 正本相对键:assets/<hash 前 2 位>/<64-hex>/blob.<ext>(不是 <hash>.<ext>)。 */const LIBRARY_BLOB_REL_RE = /^assets\/([0-9a-f]{2})\/([0-9a-f]{64})\/blob\.([A-Za-z0-9]+)$/i;@@ -210,6 +217,12 @@ export interface GhostLibrarySlotDeps {ghostId: string,root: string | null,): Promise<boolean | 'granted' | 'not-granted' | 'superseded' | void>;+ /** owner-scoped staging 根(生产 = ownerScopedUserDataPath('library-staging', ghostId))。 */+ getStagingRoot?(ghostId: string): string;+ createStagingStore?(deps: LibraryStagingDeps): LibraryStagingStore;+ /** Capture owner before staging awaits; beginMutation holds the lease across verify+release. */+ captureMutationOwner?(): unknown;+ beginMutation?(expected?: unknown): () => void;}const fail = (@@ -249,6 +262,12 @@ export class GhostLibrarySlot {libraryGeneration: number;libraryIdentity: string;}>();+ /** owner-scoped staging,独立于可迁移 Library 根;按 owner×ghost 隔离,根捕获后不漂移。 */+ private readonly stagingStores = new Map<string, LibraryStagingStore>();+ /** In-flight staging.release per ghost. disposeGhost drains these so bind/relocate cannot cut the Library mid-transaction. */+ private readonly stagingReleaseInflight = new Map<string, { count: number; drain: Promise<void> | null; resolveDrain: (() => void) | null }>();+ /** Mutating Library ops and staging.release share one chain per ghost so hash-then-delete cannot race a concurrent write/delete/rename. */+ private readonly ghostExclusive = new Map<string, Promise<unknown>>();constructor(private readonly deps: GhostLibrarySlotDeps) {}@@ -258,6 +277,81 @@ export class GhostLibrarySlot {else this.relocating.delete(ghostId);}+ private beginStagingRelease(ghostId: string): () => void {+ let state = this.stagingReleaseInflight.get(ghostId);+ if (!state) {+ state = { count: 0, drain: null, resolveDrain: null };+ this.stagingReleaseInflight.set(ghostId, state);+ }+ if (state.count === 0) {+ state.drain = new Promise<void>((resolve) => {+ state.resolveDrain = resolve;+ });+ }+ state.count += 1;+ let released = false;+ return () => {+ if (released) return;+ released = true;+ const live = this.stagingReleaseInflight.get(ghostId);+ if (!live) return;+ live.count -= 1;+ if (live.count === 0) {+ live.resolveDrain?.();+ live.resolveDrain = null;+ live.drain = null;+ this.stagingReleaseInflight.delete(ghostId);+ }+ };+ }++ private async waitForStagingReleases(ghostId: string): Promise<void> {+ for (;;) {+ const state = this.stagingReleaseInflight.get(ghostId);+ if (!state || state.count === 0 || !state.drain) return;+ await state.drain;+ }+ }++ private runGhostExclusive<T>(ghostId: string, fn: () => Promise<T>): Promise<T> {+ const prev = this.ghostExclusive.get(ghostId) ?? Promise.resolve();+ const next = prev.then(fn, fn);+ this.ghostExclusive.set(ghostId, next.then(() => undefined, () => undefined));+ return next;+ }++ private async confirmReleaseLibrary(+ ghostId: string,+ session: GhostLibrarySession,+ ack: Extract<LibraryStagingAck, { ok: true }>,+ ): Promise<LibraryStagingFailure | null> {+ const live = this.sessions.get(ghostId);+ if (+ this.deps.captureOwnerScope() !== session.ownerScopeKey+ || !live+ || live !== session+ || live.identity !== ack.libraryIdentity+ || live.generation !== ack.libraryGeneration+ ) {+ return { ok: false, errorCode: 'ACK_MISMATCH', message: 'Library epoch 已变化,原件已保留' };+ }+ const hashed = await session.vault.hashFile(ack.path);+ if (!hashed.ok || hashed.sha256 !== ack.sha256 || hashed.bytes !== ack.bytes) {+ return { ok: false, errorCode: 'ACK_MISMATCH', message: 'Library 正本已变化,原件已保留' };+ }+ return null;+ }++ /** Relocate/delete/account-boundary gate: reject new release, drain inflight, then teardown. */+ async invalidateGhost(ghostId: string): Promise<void> {+ this.setRelocating(ghostId, true);+ try {+ await this.disposeGhost(ghostId);+ } finally {+ this.setRelocating(ghostId, false);+ }+ }+/** 处理一条 library-request(ghost-pipe:send 的 invoke 返回值即本结果)。 */async handleLibraryRequest(ghostId: string, payload: unknown): Promise<GhostPipeLibraryResult> {try {@@ -289,26 +383,38 @@ export class GhostLibrarySlot {capabilities: {version: GHOST_LIBRARY_CAPABILITIES_V1.version,operations: [...GHOST_LIBRARY_CAPABILITIES_V1.operations],+ staging: { ...GHOST_LIBRARY_CAPABILITIES_V1.staging },},};}+ if (isGhostLibraryStagingOp(op)) {+ if (op === 'staging.release') {+ if (this.relocating.has(ghostId)) {+ return fail('ACK_MISMATCH', 'Library 正在迁移到新位置,原件已保留');+ }+ return this.runGhostExclusive(ghostId, () => this.dispatchStaging(ghostId, op, req));+ }+ return this.dispatchStaging(ghostId, op, req);+ }// 迁移期只读:写类操作在 copying 全程拒绝(读与状态查询照常)。+ const writeOps: ReadonlySet<string> = new Set([+ 'write', 'writeBegin', 'writeChunk', 'writeCommit', 'writeAbort',+ 'mkdir', 'delete', 'rename',+ 'db.open', 'db.exec', 'db.batch', 'db.migrate', 'db.backup',+ ]);if (this.relocating.has(ghostId)) {- const writeOps: ReadonlySet<string> = new Set([- 'write', 'writeBegin', 'writeChunk', 'writeCommit', 'writeAbort',- 'mkdir', 'delete', 'rename',- 'db.open', 'db.exec', 'db.batch', 'db.migrate', 'db.backup',- ]);if (writeOps.has(op)) {return fail('LIBRARY_READONLY', 'Library 正在迁移到新位置,写入已暂停;请稍后重试');}}- // 会话获取/作废:owner scope 变了(切换在途或已切),旧会话的根与连接- // 一并作废——绝不把上个 owner 的库当成本 owner 的库继续用。- const scopeKey = this.deps.captureOwnerScope();- const session = await this.getOrCreateSession(ghostId, scopeKey);- return this.runOp(ghostId, session, op, req);+ const runSessionOp = async (): Promise<GhostPipeLibraryResult> => {+ const scopeKey = this.deps.captureOwnerScope();+ const session = await this.getOrCreateSession(ghostId, scopeKey);+ return this.runOp(ghostId, session, op, req);+ };+ if (writeOps.has(op)) return this.runGhostExclusive(ghostId, runSessionOp);+ return runSessionOp();}private async getOrCreateSession(ghostId: string, scopeKey: string | null): Promise<GhostLibrarySession> {@@ -348,10 +454,15 @@ export class GhostLibrarySlot {&& (opened.reason === 'disk-missing' || opened.reason === 'binding-moved')) {await this.latchCustomUnavailable(session, ghostId, opened.reason);- } else if (session.vault.getMeta()?.orphaned) {- // 重装自愈:能走到这里 = 插件已装入且启用,清掉卸载时留的 orphaned- // 标记(best-effort,失败不影响使用)。- await session.vault.clearOrphaned().catch(() => {});+ } else {+ if (opened.ok && opened.state === 'ready' && resolution.kind === 'custom' && resolution.root !== null) {+ await this.deps.bindingStore.markLibraryReady(ghostId).catch(() => {});+ }+ if (session.vault.getMeta()?.orphaned) {+ // 重装自愈:能走到这里 = 插件已装入且启用,清掉卸载时留的 orphaned+ // 标记(best-effort,失败不影响使用)。+ await session.vault.clearOrphaned().catch(() => {});+ }}} else if (this.extraDirGrant?.ghostId === ghostId) {await this.syncAgentReadonlyExtraDir(ghostId, null);@@ -463,7 +574,9 @@ export class GhostLibrarySlot {customParentGrant: resolution.kind === 'custom' && resolution.root !== null? { realPathAtGrant: resolution.record.realPathAtGrant, identity: resolution.record.identity }: undefined,- log: this.deps.log,+ allowCustomInit: resolution.kind === 'custom' && resolution.root !== null+ ? resolution.record.libraryReady === false+ : undefined, log: this.deps.log,});const sql = this.deps.createSqlService({workerScriptPath: this.deps.workerScriptPath,@@ -566,6 +679,219 @@ export class GhostLibrarySlot {}}+ private stagingStoreKey(ownerScopeKey: string, ghostId: string): string {+ return `${ownerScopeKey}\0${ghostId}`;+ }++ private getOrCreateStagingStore(ghostId: string, ownerScopeKey: string): LibraryStagingStore {+ const key = this.stagingStoreKey(ownerScopeKey, ghostId);+ const existing = this.stagingStores.get(key);+ if (existing) return existing;+ const rootDir = this.deps.getStagingRoot+ ? this.deps.getStagingRoot(ghostId)+ : path.join(this.deps.getDefaultRoot(ghostId), '..', '..', 'library-staging', ghostId);+ const create = this.deps.createStagingStore ?? ((deps: LibraryStagingDeps) => new LibraryStagingStore(deps));+ const store = create({+ rootDir,+ ownerScopeKey,+ ghostId,+ captureOwnerScope: () => this.deps.captureOwnerScope(),+ createVault: (vaultDeps) => this.deps.createVault(vaultDeps),+ getDiskFreeBytes: this.deps.getDiskFreeBytes,+ log: this.deps.log,+ });+ this.stagingStores.set(key, store);+ return store;+ }++ private stagingFail(r: LibraryStagingFailure): GhostPipeLibraryResult {+ return r.errorCode === 'LIBRARY_UNAVAILABLE'+ ? fail(r.errorCode, r.message, 'LIBRARY_UNAVAILABLE')+ : { ok: false, errorCode: r.errorCode, message: r.message };+ }++ private async verifyLibraryAck(+ ghostId: string,+ req: Record<string, unknown>,+ ): Promise<LibraryStagingAck | LibraryStagingFailure> {+ const pathRel = typeof req.path === 'string' ? req.path : '';+ const sha256 = typeof req.sha256 === 'string' ? req.sha256 : '';+ const bytes = typeof req.bytes === 'number' ? req.bytes : NaN;+ const libraryIdentity = typeof req.libraryIdentity === 'string' ? req.libraryIdentity : '';+ const libraryGeneration = typeof req.libraryGeneration === 'number' ? req.libraryGeneration : NaN;+ if (!isLibraryBlobRelPath(pathRel) || !/^[0-9a-f]{64}$/.test(sha256) || !Number.isInteger(bytes) || bytes < 0) {+ return { ok: false, errorCode: 'ACK_MISMATCH', message: 'Library ACK 字段非法,原件已保留' };+ }+ const ext = pathRel.split('.').pop() ?? '';+ if (libraryBlobRelPath(sha256, ext) !== pathRel) {+ return { ok: false, errorCode: 'ACK_MISMATCH', message: 'Library ACK 不是 content-addressed 正本路径,原件已保留' };+ }+ if (!/^[0-9a-f]{64}$/.test(libraryIdentity) || !Number.isInteger(libraryGeneration) || libraryGeneration < 0) {+ return { ok: false, errorCode: 'ACK_MISMATCH', message: 'Library epoch 非法,原件已保留' };+ }+ const scopeKey = this.deps.captureOwnerScope();+ if (scopeKey === null) {+ return { ok: false, errorCode: 'OWNER_CHANGED', message: '当前没有有效账号,staging 已拒绝' };+ }+ const session = await this.getOrCreateSession(ghostId, scopeKey);+ if (session.drift !== null) {+ return { ok: false, errorCode: 'LIBRARY_UNAVAILABLE', message: `Library 不可用(${session.drift})` };+ }+ if (session.identity !== libraryIdentity || session.generation !== libraryGeneration) {+ return { ok: false, errorCode: 'ACK_MISMATCH', message: 'Library epoch 与当前库不一致,原件已保留' };+ }+ const opened = await session.vault.open();+ if (this.deps.captureOwnerScope() !== scopeKey) {+ return { ok: false, errorCode: 'OWNER_CHANGED', message: '账号已切换,staging 操作已取消' };+ }+ if (!opened.ok) return { ok: false, errorCode: 'LIBRARY_UNAVAILABLE', message: opened.message };+ if (opened.state === 'unavailable') {+ return { ok: false, errorCode: 'LIBRARY_UNAVAILABLE', message: `Library 不可用(${opened.reason ?? 'io'})` };+ }+ const hashed = await session.vault.hashFile(pathRel);+ if (this.deps.captureOwnerScope() !== scopeKey) {+ return { ok: false, errorCode: 'OWNER_CHANGED', message: '账号已切换,staging 操作已取消' };+ }+ if (!hashed.ok) {+ return hashed.errorCode === 'LIBRARY_UNAVAILABLE'+ ? { ok: false, errorCode: 'LIBRARY_UNAVAILABLE', message: hashed.message }+ : { ok: false, errorCode: 'ACK_MISMATCH', message: 'Library ACK 目标不存在或无法核验,原件已保留' };+ }+ if (hashed.sha256 !== sha256 || hashed.bytes !== bytes) {+ return { ok: false, errorCode: 'ACK_MISMATCH', message: 'Library ACK 与 staging 原件不一致,原件已保留' };+ }+ const live = this.sessions.get(ghostId);+ if (+ this.relocating.has(ghostId)+ || this.deps.captureOwnerScope() !== scopeKey+ || !live+ || live !== session+ || live.identity !== libraryIdentity+ || live.generation !== libraryGeneration+ ) {+ return { ok: false, errorCode: 'ACK_MISMATCH', message: 'Library epoch 已变化,原件已保留' };+ }+ return { ok: true, path: pathRel, sha256, bytes, libraryIdentity, libraryGeneration };+ }++ private async dispatchStaging(+ ghostId: string,+ op: string,+ req: Record<string, unknown>,+ ): Promise<GhostPipeLibraryResult> {+ const ownerScopeKey = this.deps.captureOwnerScope();+ if (ownerScopeKey === null) {+ return fail('OWNER_CHANGED', '当前没有有效账号,staging 已拒绝');+ }+ let expectedOwner: unknown;+ try {+ expectedOwner = this.deps.captureMutationOwner?.();+ } catch (err) {+ return fail('OWNER_CHANGED', err instanceof Error ? err.message : '账号切换中,staging 已拒绝');+ }+ let releaseLease: (() => void) | undefined;+ if (this.deps.beginMutation) {+ try {+ releaseLease = this.deps.beginMutation(expectedOwner);+ } catch (err) {+ return fail('OWNER_CHANGED', err instanceof Error ? err.message : '账号已切换,staging 已拒绝');+ }+ }+ try {+ const store = this.getOrCreateStagingStore(ghostId, ownerScopeKey);+ switch (op) {+ case 'staging.begin': {+ const r = await store.begin({+ ghostId,+ taskId: req.taskId,+ sourceRevision: req.sourceRevision,+ totalBytes: req.totalBytes,+ sha256: req.sha256,+ mime: req.mime,+ recovery: req.recovery,+ });+ if (!r.ok) return this.stagingFail(r);+ return { ok: true, op: 'staging.begin', stagingId: r.stagingId };+ }+ case 'staging.chunk': {+ const r = await store.chunk({+ ghostId,+ stagingId: req.stagingId,+ seq: req.seq,+ content: req.content,+ encoding: req.encoding,+ });+ if (!r.ok) return this.stagingFail(r);+ return { ok: true, op: 'staging.chunk', accepted: r.accepted };+ }+ case 'staging.commit': {+ const r = await store.commit({ ghostId, stagingId: req.stagingId });+ if (!r.ok) return this.stagingFail(r);+ return {+ ok: true, op: 'staging.commit',+ stagingId: r.stagingId, taskId: r.taskId, sourceRevision: r.sourceRevision,+ sha256: r.sha256, bytes: r.bytes, mime: r.mime, durable: true,+ };+ }+ case 'staging.list': {+ const r = await store.list({ ghostId, cursor: req.cursor, limit: req.limit });+ if (!r.ok) return this.stagingFail(r);+ return { ok: true, op: 'staging.list', items: r.items, hasMore: r.hasMore, nextCursor: r.nextCursor };+ }+ case 'staging.read': {+ const r = await store.read({+ ghostId,+ stagingId: req.stagingId,+ offset: req.offset,+ length: req.length,+ });+ if (!r.ok) return this.stagingFail(r);+ return {+ ok: true, op: 'staging.read',+ stagingId: r.stagingId, content: r.content, encoding: r.encoding,+ bytes: r.bytes, sha256: r.sha256,+ };+ }+ case 'staging.abort': {+ const r = await store.abort({ ghostId, stagingId: req.stagingId });+ if (!r.ok) return this.stagingFail(r);+ return { ok: true, op: 'staging.abort', aborted: r.aborted };+ }+ case 'staging.release': {+ if (this.relocating.has(ghostId)) {+ return fail('ACK_MISMATCH', 'Library 正在迁移到新位置,原件已保留');+ }+ const releaseDone = this.beginStagingRelease(ghostId);+ try {+ const ack = await this.verifyLibraryAck(ghostId, req);+ if (this.relocating.has(ghostId)) {+ return fail('ACK_MISMATCH', 'Library 正在迁移到新位置,原件已保留');+ }+ const session = ack.ok === true ? this.sessions.get(ghostId) : undefined;+ const r = await store.release({+ ghostId,+ stagingId: req.stagingId,+ ack,+ confirmLibrary: ack.ok !== true+ ? undefined+ : () => (session+ ? this.confirmReleaseLibrary(ghostId, session, ack)+ : { ok: false, errorCode: 'ACK_MISMATCH', message: 'Library epoch 已变化,原件已保留' }),+ });+ if (!r.ok) return this.stagingFail(r);+ return { ok: true, op: 'staging.release', stagingId: r.stagingId, released: r.released };+ } finally {+ releaseDone();+ }+ }+ default:+ return fail('PATH_INVALID', `op 必须是 ${GHOST_LIBRARY_OPS.join(' / ')}`, 'INVALID_REQUEST');+ }+ } finally {+ releaseLease?.();+ }+ }+private async teardownSession(ghostId: string, expected?: GhostLibrarySession): Promise<void> {const session = this.sessions.get(ghostId);if (!session) return;@@ -584,12 +910,34 @@ export class GhostLibrarySlot {/** 停用/卸载/owner 切换收口:作废全部会话(commit 5 的生命周期接线点)。 */async disposeGhost(ghostId: string): Promise<void> {+ await this.waitForStagingReleases(ghostId);await this.teardownSession(ghostId);+ await this.disposeStagingStores(ghostId);}async disposeAll(): Promise<void> {- for (const id of Array.from(this.sessions.keys())) {- await this.teardownSession(id);+ const ids = new Set([...this.sessions.keys(), ...this.stagingReleaseInflight.keys()]);+ for (const key of this.stagingStores.keys()) {+ const ghostId = key.split('\0')[1];+ if (ghostId) ids.add(ghostId);+ }+ for (const id of ids) this.setRelocating(id, true);+ try {+ for (const id of ids) await this.disposeGhost(id);+ await this.disposeStagingStores();+ } finally {+ for (const id of ids) this.setRelocating(id, false);+ }+ }++ private async disposeStagingStores(ghostId?: string): Promise<void> {+ const entries = [...this.stagingStores.entries()].filter(([key]) => {+ if (!ghostId) return true;+ return key.split('\0')[1] === ghostId;+ });+ for (const [key, store] of entries) {+ this.stagingStores.delete(key);+ await store.dispose().catch(() => {});}}diff --git a/apps/desktop/src/main/cindy-brain/libraryStaging.ts b/apps/desktop/src/main/cindy-brain/libraryStaging.tsnew file mode 100644index 0000000000..774310c173--- /dev/null+++ b/apps/desktop/src/main/cindy-brain/libraryStaging.ts@@ -0,0 +1,1164 @@+/**+ * libraryStaging.ts — LibraryVault adapter for owner-scoped upload staging.+ * File bytes/fsync/rename/hash go through LibraryVault. This layer only owns+ * task identity, hard quota, recovery manifests, tombstones, and release.+ */++import { randomUUID } from 'node:crypto';++import {+ LibraryVault,+ DEFAULT_LIBRARY_LIMITS,+ type LibraryVaultDeps,+} from './libraryVault.js';++export type LibraryStagingErrorCode =+ | 'PATH_INVALID'+ | 'TOO_LARGE'+ | 'STAGING_QUOTA'+ | 'STAGING_BUSY'+ | 'DISK_FULL'+ | 'STREAM_INVALID'+ | 'NOT_FOUND'+ | 'ALREADY_EXISTS'+ | 'OWNER_CHANGED'+ | 'ACK_MISMATCH'+ | 'LIBRARY_UNAVAILABLE'+ | 'INTERNAL';++export type LibraryStagingFailure = { ok: false; errorCode: LibraryStagingErrorCode; message: string };+export type LibraryStagingSuccess<T> = { ok: true } & T;+export type LibraryStagingResult<T> = LibraryStagingSuccess<T> | LibraryStagingFailure;++export interface LibraryStagingLimits {+ maxTaskBytes: number;+ maxTotalBytes: number;+ maxConcurrentWrites: number;+ maxChunkBytes: number;+ reserveBytes: number;+ /** Incomplete upload idle timeout; durables/commitPending are never swept. */+ streamIdleTimeoutMs: number;+ maxRecoveryMetadataBytes: number;+ defaultListLimit: number;+ maxListLimit: number;+}++export const DEFAULT_LIBRARY_STAGING_LIMITS: LibraryStagingLimits = {+ maxTaskBytes: 8 * 1024 * 1024 * 1024,+ maxTotalBytes: 8 * 1024 * 1024 * 1024,+ maxConcurrentWrites: 4,+ maxChunkBytes: 16 * 1024 * 1024,+ reserveBytes: 1024 * 1024 * 1024,+ streamIdleTimeoutMs: DEFAULT_LIBRARY_LIMITS.streamIdleTimeoutMs,+ maxRecoveryMetadataBytes: 64 * 1024,+ defaultListLimit: 100,+ maxListLimit: 500,+};++export const GHOST_LIBRARY_STAGING_OPS = [+ 'staging.begin',+ 'staging.chunk',+ 'staging.commit',+ 'staging.list',+ 'staging.read',+ 'staging.release',+ 'staging.abort',+] as const;+export type GhostLibraryStagingOp = (typeof GHOST_LIBRARY_STAGING_OPS)[number];++export interface LibraryStagingReceipt {+ stagingId: string;+ taskId: string;+ sourceRevision: string;+ sha256: string;+ bytes: number;+ mime: string;+ durable: true;+}++export interface LibraryStagingListItem extends LibraryStagingReceipt {+ recovery: Record<string, unknown>;+}++export type LibraryStagingAck =+ | {+ ok: true;+ path: string;+ sha256: string;+ bytes: number;+ libraryIdentity: string;+ libraryGeneration: number;+ }+ | LibraryStagingFailure;++export interface LibraryStagingDeps {+ rootDir: string;+ ownerScopeKey: string;+ ghostId: string;+ captureOwnerScope(): string | null;+ createVault?(deps: LibraryVaultDeps): LibraryVault;+ getDiskFreeBytes?(root: string): Promise<number | null>;+ log?: LibraryVaultDeps['log'];+ limits?: Partial<LibraryStagingLimits>;+ now?(): number;+}++const HEX64 = /^[0-9a-f]{64}$/;+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;+const TASK_ID_MAX = 128;+const MIME_MAX = 256;++const fail = (errorCode: LibraryStagingErrorCode, message: string): LibraryStagingFailure => ({+ ok: false, errorCode, message,+});++export function isGhostLibraryStagingOp(op: string): op is GhostLibraryStagingOp {+ return (GHOST_LIBRARY_STAGING_OPS as readonly string[]).includes(op);+}++function vaultFail(r: { errorCode: string; message: string }): LibraryStagingFailure {+ const code = r.errorCode as LibraryStagingErrorCode;+ const allowed: LibraryStagingErrorCode[] = [+ 'PATH_INVALID', 'TOO_LARGE', 'DISK_FULL', 'STREAM_INVALID', 'NOT_FOUND',+ 'ALREADY_EXISTS', 'LIBRARY_UNAVAILABLE', 'INTERNAL',+ ];+ return fail(allowed.includes(code) ? code : 'INTERNAL', r.message);+}++function parseBoundedString(value: unknown, field: string, max: number): string | LibraryStagingFailure {+ if (typeof value !== 'string' || value.length === 0 || value.length > max) {+ return fail('PATH_INVALID', `${field} 必须是 1..${max} 字符`);+ }+ return value;+}++function parseSha256(value: unknown): string | LibraryStagingFailure {+ if (typeof value !== 'string' || !HEX64.test(value)) return fail('PATH_INVALID', 'sha256 必须是 64 位小写十六进制');+ return value;+}++function parseStagingId(value: unknown): string | LibraryStagingFailure {+ if (typeof value !== 'string' || !UUID.test(value)) return fail('PATH_INVALID', 'stagingId 必须是 UUID');+ return value;+}++function parseRecovery(value: unknown, maxBytes: number): LibraryStagingResult<{ recovery: Record<string, unknown> }> {+ if (value === undefined || value === null || typeof value !== 'object' || Array.isArray(value)) {+ return fail('PATH_INVALID', 'recovery 必须是 JSON 对象');+ }+ let serialized: string;+ try {+ serialized = JSON.stringify(value);+ } catch {+ return fail('PATH_INVALID', 'recovery 不是合法 JSON');+ }+ if (Buffer.byteLength(serialized, 'utf8') > maxBytes) {+ return fail('TOO_LARGE', `recovery 超上限(${maxBytes} 字节)`);+ }+ return { ok: true, recovery: JSON.parse(serialized) as Record<string, unknown> };+}++function decodeStrictBase64(content: unknown, maxBytes: number): Buffer | LibraryStagingFailure {+ if (typeof content !== 'string') return fail('PATH_INVALID', 'content 必须是 base64 字符串');+ const compact = content.replace(/[\r\n]/g, '');+ if (compact.length === 0) return Buffer.alloc(0);+ const maxChars = Math.floor((maxBytes * 4) / 3) + 8;+ if (compact.length > maxChars) return fail('TOO_LARGE', `单块超上限(${maxBytes} 字节)`);+ if (compact.length % 4 !== 0) return fail('PATH_INVALID', 'content 不是合法 base64');+ if (!/^[A-Za-z0-9+/]+={0,2}$/.test(compact)) return fail('PATH_INVALID', 'content 不是合法 base64');+ const decoded = Buffer.from(compact, 'base64');+ if (decoded.toString('base64') !== compact) return fail('PATH_INVALID', 'content 不是合法 base64');+ if (decoded.byteLength > maxBytes) return fail('TOO_LARGE', `单块超上限(${maxBytes} 字节)`);+ return decoded;+}++function taskKey(taskId: string, sourceRevision: string): string {+ return `${taskId}\0${sourceRevision}`;+}++function sameRecovery(a: Record<string, unknown>, b: Record<string, unknown>): boolean {+ return JSON.stringify(a) === JSON.stringify(b);+}++function blobPath(id: string): string {+ return `tasks/${id}/blob.bin`;+}+function intentPath(id: string): string {+ return `tasks/${id}/intent.json`;+}+function manifestPath(id: string): string {+ return `tasks/${id}/manifest.json`;+}+function tombstonePath(id: string): string {+ return `tasks/${id}/tombstone.json`;+}++interface UploadRecord {+ stagingId: string;+ streamId: string;+ taskId: string;+ sourceRevision: string;+ totalBytes: number;+ sha256Declared: string;+ mime: string;+ recovery: Record<string, unknown>;+ nextSeq: number;+ lastChunk: Buffer | null;+ lastAt: number;+ written: number;+ /** writeCommit succeeded; keep mapping until manifest+dirsync durable. */+ commitPending: boolean;+}++interface DurableRecord {+ stagingId: string;+ taskId: string;+ sourceRevision: string;+ sha256: string;+ bytes: number;+ mime: string;+ recovery: Record<string, unknown>;+}++interface TaskIdentity {+ stagingId: string;+ ghostId: string;+ ownerScopeKey: string;+ taskId: string;+ sourceRevision: string;+ sha256: string;+ bytes: number;+ mime: string;+ recovery: Record<string, unknown>;+}++interface DurableManifest extends TaskIdentity {+ version: 1;+ durable: true;+}++interface IntentMarker extends TaskIdentity {+ version: 1;+ intent: true;+}++function receiptOf(record: DurableRecord): LibraryStagingReceipt {+ return {+ stagingId: record.stagingId,+ taskId: record.taskId,+ sourceRevision: record.sourceRevision,+ sha256: record.sha256,+ bytes: record.bytes,+ mime: record.mime,+ durable: true,+ };+}++/** Disk identity ignores process-lifetime generation (`local:id:2` ≡ `local:id:0`). */+function durableOwnerScopeKey(scopeKey: string): string {+ const parsed = /^(local|cloud|signed-out):(.+):(\d+)$/.exec(scopeKey);+ return parsed ? `${parsed[1]}:${parsed[2]}` : scopeKey;+}++function sameDurableOwner(persisted: unknown, live: string): boolean {+ return typeof persisted === 'string' && durableOwnerScopeKey(persisted) === durableOwnerScopeKey(live);+}++function parseTaskIdentity(+ parsed: Record<string, unknown>,+ stagingId: string,+ ghostId: string,+ ownerScopeKey: string,+ kind: 'manifest' | 'intent',+): TaskIdentity | LibraryStagingFailure {+ const label = kind === 'manifest' ? 'staging manifest' : 'staging intent';+ if (+ parsed.stagingId !== stagingId+ || parsed.ghostId !== ghostId+ || !sameDurableOwner(parsed.ownerScopeKey, ownerScopeKey)+ || typeof parsed.taskId !== 'string' || parsed.taskId.length === 0 || parsed.taskId.length > TASK_ID_MAX+ || typeof parsed.sourceRevision !== 'string' || parsed.sourceRevision.length === 0 || parsed.sourceRevision.length > TASK_ID_MAX+ || typeof parsed.sha256 !== 'string' || !HEX64.test(parsed.sha256)+ || typeof parsed.bytes !== 'number' || !Number.isInteger(parsed.bytes) || parsed.bytes < 0+ || typeof parsed.mime !== 'string' || parsed.mime.length === 0 || parsed.mime.length > MIME_MAX+ || typeof parsed.recovery !== 'object' || parsed.recovery === null || Array.isArray(parsed.recovery)+ ) {+ return fail('LIBRARY_UNAVAILABLE', `${label} 字段非法`);+ }+ return {+ stagingId,+ ghostId,+ ownerScopeKey,+ taskId: parsed.taskId,+ sourceRevision: parsed.sourceRevision,+ sha256: parsed.sha256,+ bytes: parsed.bytes,+ mime: parsed.mime,+ recovery: parsed.recovery as Record<string, unknown>,+ };+}++function parseJsonObject(raw: string, label: string): { ok: true; value: Record<string, unknown> } | LibraryStagingFailure {+ if (Buffer.byteLength(raw, 'utf8') > 256 * 1024) return fail('LIBRARY_UNAVAILABLE', `${label} 过大`);+ try {+ const parsed = JSON.parse(raw) as unknown;+ if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {+ return fail('LIBRARY_UNAVAILABLE', `${label} 不可读`);+ }+ return { ok: true, value: parsed as Record<string, unknown> };+ } catch {+ return fail('LIBRARY_UNAVAILABLE', `${label} 不可读`);+ }+}++function parseManifest(+ raw: string,+ stagingId: string,+ ghostId: string,+ ownerScopeKey: string,+): DurableManifest | LibraryStagingFailure {+ const parsed = parseJsonObject(raw, 'staging manifest');+ if (!parsed.ok) return parsed;+ if (parsed.value.version !== 1 || parsed.value.durable !== true || parsed.value.intent === true) {+ return fail('LIBRARY_UNAVAILABLE', 'staging manifest 字段非法');+ }+ const identity = parseTaskIdentity(parsed.value, stagingId, ghostId, ownerScopeKey, 'manifest');+ if ('errorCode' in identity) return identity;+ return { ...identity, version: 1, durable: true };+}++function parseIntent(+ raw: string,+ stagingId: string,+ ghostId: string,+ ownerScopeKey: string,+): IntentMarker | LibraryStagingFailure {+ const parsed = parseJsonObject(raw, 'staging intent');+ if (!parsed.ok) return parsed;+ if (parsed.value.version !== 1 || parsed.value.intent !== true || parsed.value.durable === true) {+ return fail('LIBRARY_UNAVAILABLE', 'staging intent 字段非法');+ }+ const identity = parseTaskIdentity(parsed.value, stagingId, ghostId, ownerScopeKey, 'intent');+ if ('errorCode' in identity) return identity;+ return { ...identity, version: 1, intent: true };+}++function identityMatches(actual: TaskIdentity, expected: TaskIdentity): boolean {+ return actual.stagingId === expected.stagingId+ && actual.ghostId === expected.ghostId+ && actual.ownerScopeKey === expected.ownerScopeKey+ && actual.taskId === expected.taskId+ && actual.sourceRevision === expected.sourceRevision+ && actual.sha256 === expected.sha256+ && actual.bytes === expected.bytes+ && actual.mime === expected.mime+ && sameRecovery(actual.recovery, expected.recovery);+}++export class LibraryStagingStore {+ private readonly limits: LibraryStagingLimits;+ private readonly ownerScopeKey: string;+ private readonly ghostId: string;+ private readonly now: () => number;+ private readonly vault: LibraryVault;+ private readonly uploads = new Map<string, UploadRecord>();+ private readonly byTask = new Map<string, string>();+ private durables = new Map<string, DurableRecord>();+ private durableBytes = 0;+ private orphanBlobBytes = 0;+ private closedTmpBytes = 0;+ private chain: Promise<unknown> = Promise.resolve();+ private opened = false;+ private journalReady = false;+ private closedTmpStale = false;++ constructor(private readonly deps: LibraryStagingDeps) {+ this.limits = { ...DEFAULT_LIBRARY_STAGING_LIMITS, ...(deps.limits ?? {}) };+ this.ownerScopeKey = deps.ownerScopeKey;+ this.ghostId = deps.ghostId;+ this.now = deps.now ?? Date.now;+ const capturedRoot = deps.rootDir;+ const createVault = deps.createVault ?? ((vaultDeps: LibraryVaultDeps) => new LibraryVault(vaultDeps));+ this.vault = createVault({+ rootDir: () => capturedRoot,+ ghostId: deps.ghostId,+ getDiskFreeBytes: deps.getDiskFreeBytes,+ log: deps.log,+ limits: {+ writeMaxBytes: this.limits.maxChunkBytes,+ readMaxBytes: this.limits.maxChunkBytes,+ streamMaxTotalBytes: this.limits.maxTaskBytes,+ diskReserveBytes: this.limits.reserveBytes,+ softLimitBytes: this.limits.maxTotalBytes,+ },+ onStreamClosed: (streamId) => {+ for (const [id, upload] of this.uploads) {+ if (upload.streamId !== streamId || upload.commitPending) continue;+ this.uploads.delete(id);+ this.byTask.delete(taskKey(upload.taskId, upload.sourceRevision));+ this.closedTmpStale = true;+ }+ },+ });+ }++ private runSerialized<T>(fn: () => Promise<T>): Promise<T> {+ const next = this.chain.then(fn, fn);+ this.chain = next.catch(() => {});+ return next;+ }++ private requireOwner(): LibraryStagingFailure | null {+ const live = this.deps.captureOwnerScope();+ if (live === null || live !== this.ownerScopeKey) {+ return fail('OWNER_CHANGED', '账号已切换,staging 操作已取消');+ }+ return null;+ }++ private async ensureOpen(): Promise<LibraryStagingFailure | null> {+ const opened = await this.vault.open();+ if (!opened.ok) return vaultFail(opened);+ if (opened.state === 'unavailable') {+ return fail('LIBRARY_UNAVAILABLE', `staging 不可用(${opened.reason ?? 'io'})`);+ }+ this.opened = true;+ return null;+ }++ private async listAll(rel: string): Promise<LibraryStagingResult<{ entries: Array<{ path: string; kind: 'file' | 'dir'; bytes: number }> }>> {+ const entries: Array<{ path: string; kind: 'file' | 'dir'; bytes: number }> = [];+ let cursor: string | null = null;+ for (;;) {+ const page = await this.vault.list({+ path: rel,+ recursive: false,+ cursor,+ limit: DEFAULT_LIBRARY_LIMITS.listPageSize,+ strict: true,+ });+ if (!page.ok) {+ if (page.errorCode === 'NOT_FOUND' && entries.length === 0) {+ return { ok: true, entries: [] };+ }+ return vaultFail(page);+ }+ entries.push(...page.entries.map((item) => ({ path: item.path, kind: item.kind, bytes: item.bytes })));+ if (!page.hasMore || page.nextCursor === null) break;+ cursor = page.nextCursor;+ }+ return { ok: true, entries };+ }++ private async loadJournal(): Promise<LibraryStagingFailure | null> {+ if (this.journalReady) return null;+ const openFail = await this.ensureOpen();+ if (openFail) return openFail;+ const residue = await this.vault.tmpResidueBytes();+ if (!residue.ok) return vaultFail(residue);+ const listed = await this.listAll('tasks');+ if (!listed.ok) return listed;+ const next = new Map<string, DurableRecord>();+ let durableBytes = 0;+ let orphanBlobBytes = 0;+ for (const entry of listed.entries) {+ if (entry.kind !== 'dir' || !UUID.test(entry.path.slice('tasks/'.length))) continue;+ const stagingId = entry.path.slice('tasks/'.length);+ const inner = await this.listAll(entry.path);+ if (!inner.ok) return inner;+ const names = new Set(inner.entries.map((item) => item.path.split('/').pop()));+ if (names.has('tombstone.json')) {+ const marker = await this.readTombstone(stagingId);+ if (!marker.ok) return marker;+ const cleaned = await this.finishReleaseUnlocked(stagingId);+ if (cleaned) {+ // Fail closed without installing a partial journal. Retry after repair+ // must not see a half-loaded durables map. Do not count the pre-delete+ // leftover size as orphan quota: cleanup already removed those bytes.+ return cleaned;+ }+ continue;+ }+ if (names.has('manifest.json')) {+ const recovered = await this.recoverDurableFromDisk(stagingId, names.has('intent.json'));+ if (!recovered.ok) return recovered;+ next.set(stagingId, recovered.record);+ durableBytes += recovered.record.bytes;+ continue;+ }+ if (names.has('intent.json') && names.has('blob.bin')) {+ const recovered = await this.recoverDurableFromIntent(stagingId);+ if (!recovered.ok) return recovered;+ next.set(stagingId, recovered.record);+ durableBytes += recovered.record.bytes;+ continue;+ }+ const blob = inner.entries.find((item) => item.path.endsWith('/blob.bin') && item.kind === 'file');+ if (blob) orphanBlobBytes += blob.bytes;+ }+ this.durables = next;+ this.durableBytes = durableBytes;+ this.orphanBlobBytes = orphanBlobBytes;+ this.closedTmpBytes = residue.bytes;+ for (const record of next.values()) {+ this.byTask.set(taskKey(record.taskId, record.sourceRevision), record.stagingId);+ }+ for (const upload of this.uploads.values()) {+ this.byTask.set(taskKey(upload.taskId, upload.sourceRevision), upload.stagingId);+ }+ this.journalReady = true;+ return null;+ }++ /** In-memory uploads already reserve their declared size; do not also add vault stream bytes. */+ private trackedUploadBytes(): number {+ let total = 0;+ for (const upload of this.uploads.values()) total += upload.totalBytes;+ return total;+ }++ private quotaBytes(): number {+ return this.durableBytes+ + this.orphanBlobBytes+ + this.closedTmpBytes+ + this.trackedUploadBytes();+ }++ /** Idle incomplete uploads only. Durables and commitPending originals are never TTL-deleted. */+ private async sweepIdleUploadsUnlocked(): Promise<void> {+ const cutoff = this.now() - this.limits.streamIdleTimeoutMs;+ for (const upload of [...this.uploads.values()]) {+ if (upload.commitPending || upload.lastAt >= cutoff) continue;+ await this.vault.writeAbort({ streamId: upload.streamId }).catch(() => {});+ this.uploads.delete(upload.stagingId);+ this.byTask.delete(taskKey(upload.taskId, upload.sourceRevision));+ await this.vault.delete({ path: intentPath(upload.stagingId) }).catch(() => {});+ this.closedTmpStale = true;+ }+ }++ /** Bytes declared but not yet on disk. commitPending blobs are already landed. */+ private unwrittenReservationBytes(): number {+ let total = 0;+ for (const upload of this.uploads.values()) {+ if (upload.commitPending) continue;+ total += Math.max(0, upload.totalBytes - upload.written);+ }+ return total;+ }++ private async checkDiskReserveUnlocked(extraBytes: number): Promise<LibraryStagingFailure | null> {+ if (!this.deps.getDiskFreeBytes) return null;+ let free: number | null = null;+ try {+ free = await this.deps.getDiskFreeBytes(this.deps.rootDir);+ } catch {+ return null;+ }+ if (free !== null && free - this.unwrittenReservationBytes() - extraBytes < this.limits.reserveBytes) {+ return fail('DISK_FULL', `磁盘剩余空间低于保留水位(${this.limits.reserveBytes} 字节);请清理磁盘或确认归档后释放`);+ }+ return null;+ }++ private async requireReady(): Promise<LibraryStagingFailure | null> {+ const denied = this.requireOwner();+ if (denied) return denied;+ const loaded = await this.loadJournal();+ if (this.requireOwner()) return fail('OWNER_CHANGED', '账号已切换,staging 操作已取消');+ if (loaded) return loaded;+ if (this.closedTmpStale) {+ const residue = await this.refreshClosedTmp();+ if (residue) return residue;+ this.closedTmpStale = false;+ }+ return null;+ }++ private async refreshClosedTmp(): Promise<LibraryStagingFailure | null> {+ const residue = await this.vault.tmpResidueBytes();+ if (!residue.ok) return vaultFail(residue);+ this.closedTmpBytes = residue.bytes;+ return null;+ }++ /** New tasks/<id> is not durable until the parent tasks dir, vault root, and any newly created root ancestors are fsynced. */+ private async fsyncDurablePath(stagingId: string): Promise<LibraryStagingFailure | null> {+ for (const rel of [`tasks/${stagingId}`, 'tasks', ''] as const) {+ const synced = await this.vault.fsyncDir(rel);+ if (!synced.ok) return vaultFail(synced);+ if (process.platform !== 'win32' && synced.fsynced !== true) {+ return fail('INTERNAL', '目录 fsync 失败');+ }+ }+ const ancestors = await this.vault.fsyncCreatedAncestors();+ if (!ancestors.ok) return vaultFail(ancestors);+ if (process.platform !== 'win32' && ancestors.fsynced !== true) {+ return fail('INTERNAL', '根目录项 fsync 失败');+ }+ return null;+ }++ private async readTombstone(stagingId: string): Promise<LibraryStagingResult<{ stagingId: string }>> {+ const raw = await this.vault.read({ path: tombstonePath(stagingId), encoding: 'utf8' });+ if (!raw.ok) {+ return raw.errorCode === 'NOT_FOUND'+ ? fail('NOT_FOUND', 'stagingId 无效')+ : fail('LIBRARY_UNAVAILABLE', 'staging tombstone 不可读');+ }+ let parsed: { version?: unknown; stagingId?: unknown; released?: unknown };+ try {+ parsed = JSON.parse(raw.content) as { version?: unknown; stagingId?: unknown; released?: unknown };+ } catch {+ return fail('LIBRARY_UNAVAILABLE', 'staging tombstone 不可读');+ }+ if (parsed.version !== 1 || parsed.stagingId !== stagingId || parsed.released !== true) {+ return fail('LIBRARY_UNAVAILABLE', 'staging tombstone 字段非法');+ }+ return { ok: true, stagingId };+ }++ private findByTask(taskId: string, sourceRevision: string): DurableRecord | UploadRecord | undefined {+ const id = this.byTask.get(taskKey(taskId, sourceRevision));+ if (!id) return undefined;+ return this.durables.get(id) ?? this.uploads.get(id);+ }++ private durableFromIdentity(identity: TaskIdentity): DurableRecord {+ return {+ stagingId: identity.stagingId,+ taskId: identity.taskId,+ sourceRevision: identity.sourceRevision,+ sha256: identity.sha256,+ bytes: identity.bytes,+ mime: identity.mime,+ recovery: identity.recovery,+ };+ }++ private expectedIdentity(upload: UploadRecord, hashed: { sha256: string; bytes: number }): TaskIdentity {+ return {+ stagingId: upload.stagingId,+ ghostId: this.ghostId,+ ownerScopeKey: this.ownerScopeKey,+ taskId: upload.taskId,+ sourceRevision: upload.sourceRevision,+ sha256: hashed.sha256,+ bytes: hashed.bytes,+ mime: upload.mime,+ recovery: upload.recovery,+ };+ }++ private async hashMatchesIdentity(identity: TaskIdentity): Promise<LibraryStagingResult<{ record: DurableRecord }>> {+ const hashed = await this.vault.hashFile(blobPath(identity.stagingId));+ if (!hashed.ok) return fail('LIBRARY_UNAVAILABLE', 'staging 原件缺失或不可读');+ if (hashed.sha256 !== identity.sha256 || hashed.bytes !== identity.bytes) {+ return fail('LIBRARY_UNAVAILABLE', 'staging 原件与声明身份不一致');+ }+ return { ok: true, record: this.durableFromIdentity(identity) };+ }++ private async recoverDurableFromDisk(+ stagingId: string,+ hasIntent: boolean,+ ): Promise<LibraryStagingResult<{ record: DurableRecord }>> {+ const raw = await this.vault.read({ path: manifestPath(stagingId), encoding: 'utf8' });+ if (!raw.ok) return fail('LIBRARY_UNAVAILABLE', 'staging manifest 不可读');+ const parsed = parseManifest(raw.content, stagingId, this.ghostId, this.ownerScopeKey);+ if ('errorCode' in parsed) return parsed;+ if (hasIntent) {+ const intentRaw = await this.vault.read({ path: intentPath(stagingId), encoding: 'utf8' });+ if (!intentRaw.ok) return fail('LIBRARY_UNAVAILABLE', 'staging intent 不可读');+ const intent = parseIntent(intentRaw.content, stagingId, this.ghostId, this.ownerScopeKey);+ if ('errorCode' in intent) return intent;+ if (!identityMatches(parsed, intent)) {+ return fail('LIBRARY_UNAVAILABLE', 'staging intent 与 manifest 冲突');+ }+ }+ return this.hashMatchesIdentity(parsed);+ }++ private async recoverDurableFromIntent(stagingId: string): Promise<LibraryStagingResult<{ record: DurableRecord }>> {+ const raw = await this.vault.read({ path: intentPath(stagingId), encoding: 'utf8' });+ if (!raw.ok) return fail('LIBRARY_UNAVAILABLE', 'staging intent 不可读');+ const intent = parseIntent(raw.content, stagingId, this.ghostId, this.ownerScopeKey);+ if ('errorCode' in intent) return intent;+ const matched = await this.hashMatchesIdentity(intent);+ if (!matched.ok) return matched;+ const promoted = await this.writeManifestUnlocked(intent);+ if (promoted) return promoted;+ return { ok: true, record: matched.record };+ }++ private async writeIntentUnlocked(identity: TaskIdentity): Promise<LibraryStagingFailure | null> {+ const marker: IntentMarker = { ...identity, version: 1, intent: true };+ const written = await this.vault.write({+ path: intentPath(identity.stagingId),+ content: JSON.stringify(marker),+ ifNotExists: true,+ });+ if (!written.ok && written.errorCode !== 'ALREADY_EXISTS') return vaultFail(written);+ if (!written.ok) {+ const raw = await this.vault.read({ path: intentPath(identity.stagingId), encoding: 'utf8' });+ if (!raw.ok) return fail('LIBRARY_UNAVAILABLE', 'staging intent 不可读');+ const existing = parseIntent(raw.content, identity.stagingId, this.ghostId, this.ownerScopeKey);+ if ('errorCode' in existing) return existing;+ if (!identityMatches(existing, identity)) {+ return fail('ALREADY_EXISTS', 'staging intent 与当前任务身份冲突');+ }+ }+ const synced = await this.fsyncDurablePath(identity.stagingId);+ if (synced) {+ const deleted = await this.vault.delete({ path: intentPath(identity.stagingId) });+ if (!deleted.ok && deleted.errorCode !== 'NOT_FOUND') return vaultFail(deleted);+ return synced;+ }+ return null;+ }++ private async writeManifestUnlocked(identity: TaskIdentity): Promise<LibraryStagingFailure | null> {+ const manifest: DurableManifest = { ...identity, version: 1, durable: true };+ const written = await this.vault.write({+ path: manifestPath(identity.stagingId),+ content: JSON.stringify(manifest),+ ifNotExists: true,+ });+ if (!written.ok && written.errorCode !== 'ALREADY_EXISTS') return vaultFail(written);+ let created = written.ok;+ if (!written.ok) {+ const adopted = await this.adoptExistingManifest(identity);+ if (adopted.error) return adopted.error;+ created = false;+ }+ const journalSync = await this.fsyncDurablePath(identity.stagingId);+ if (journalSync) {+ if (created) {+ const deleted = await this.vault.delete({ path: manifestPath(identity.stagingId) });+ if (!deleted.ok && deleted.errorCode !== 'NOT_FOUND') return vaultFail(deleted);+ }+ return journalSync;+ }+ return null;+ }++ private async adoptExistingManifest(+ expected: TaskIdentity,+ ): Promise<{ error: LibraryStagingFailure | null }> {+ const raw = await this.vault.read({ path: manifestPath(expected.stagingId), encoding: 'utf8' });+ if (!raw.ok) return { error: fail('LIBRARY_UNAVAILABLE', 'staging manifest 不可读') };+ const parsed = parseManifest(raw.content, expected.stagingId, this.ghostId, this.ownerScopeKey);+ if ('errorCode' in parsed) return { error: parsed };+ if (!identityMatches(parsed, expected)) {+ return { error: fail('ALREADY_EXISTS', '已有 manifest 与当前任务身份冲突') };+ }+ return { error: null };+ }++ private async finishReleaseUnlocked(stagingId: string): Promise<LibraryStagingFailure | null> {+ const blob = await this.vault.delete({ path: blobPath(stagingId) });+ if (!blob.ok && blob.errorCode !== 'NOT_FOUND') return vaultFail(blob);+ const manifest = await this.vault.delete({ path: manifestPath(stagingId) });+ if (!manifest.ok && manifest.errorCode !== 'NOT_FOUND') return vaultFail(manifest);+ const intent = await this.vault.delete({ path: intentPath(stagingId) });+ if (!intent.ok && intent.errorCode !== 'NOT_FOUND') return vaultFail(intent);+ await this.vault.delete({ path: tombstonePath(stagingId) }).catch(() => {});+ return null;+ }++ async begin(req: {+ ghostId: string;+ taskId: unknown;+ sourceRevision: unknown;+ totalBytes: unknown;+ sha256: unknown;+ mime: unknown;+ recovery: unknown;+ }): Promise<LibraryStagingResult<{ stagingId: string }>> {+ return this.runSerialized(async () => {+ const ready = await this.requireReady();+ if (ready) return ready;+ if (req.ghostId !== this.ghostId) return fail('PATH_INVALID', 'ghostId 与当前 staging 根不一致');+ const taskId = parseBoundedString(req.taskId, 'taskId', TASK_ID_MAX);+ if (typeof taskId !== 'string') return taskId;+ const sourceRevision = parseBoundedString(req.sourceRevision, 'sourceRevision', TASK_ID_MAX);+ if (typeof sourceRevision !== 'string') return sourceRevision;+ const mime = parseBoundedString(req.mime, 'mime', MIME_MAX);+ if (typeof mime !== 'string') return mime;+ const sha256 = parseSha256(req.sha256);+ if (typeof sha256 !== 'string') return sha256;+ if (typeof req.totalBytes !== 'number' || !Number.isInteger(req.totalBytes) || req.totalBytes < 0) {+ return fail('PATH_INVALID', 'totalBytes 必须是非负整数');+ }+ if (req.totalBytes > this.limits.maxTaskBytes) {+ return fail('TOO_LARGE', `分块流总大小超上限(${this.limits.maxTaskBytes} 字节)`);+ }+ const parsedRecovery = parseRecovery(req.recovery, this.limits.maxRecoveryMetadataBytes);+ if (!parsedRecovery.ok) return parsedRecovery;+ const existing = this.findByTask(taskId, sourceRevision);+ if (existing) {+ const same = 'durable' in existing === false+ && 'streamId' in existing+ && existing.mime === mime+ && existing.totalBytes === req.totalBytes+ && existing.sha256Declared === sha256+ && sameRecovery(existing.recovery, parsedRecovery.recovery);+ const sameDurable = this.durables.get((existing as DurableRecord).stagingId)+ && (existing as DurableRecord).mime === mime+ && (existing as DurableRecord).bytes === req.totalBytes+ && (existing as DurableRecord).sha256 === sha256+ && sameRecovery((existing as DurableRecord).recovery, parsedRecovery.recovery);+ if (same || sameDurable) {+ if (this.requireOwner()) return fail('OWNER_CHANGED', '账号已切换,staging 操作已取消');+ return { ok: true as const, stagingId: existing.stagingId };+ }+ return fail('ALREADY_EXISTS', '同一 task/revision 已有不同元数据的原件');+ }+ await this.sweepIdleUploadsUnlocked();+ if (this.closedTmpStale) {+ const residue = await this.refreshClosedTmp();+ if (residue) return residue;+ this.closedTmpStale = false;+ }+ if (this.uploads.size >= this.limits.maxConcurrentWrites) {+ return fail('STAGING_BUSY', '并发上传已达上限,请稍后重试');+ }+ if (this.quotaBytes() + req.totalBytes > this.limits.maxTotalBytes) {+ return fail('STAGING_QUOTA', 'staging 总容量不足,请在确认归档后释放再试');+ }+ const disk = await this.checkDiskReserveUnlocked(req.totalBytes);+ if (disk) return disk;+ const stagingId = randomUUID();+ const identity: TaskIdentity = {+ stagingId,+ ghostId: this.ghostId,+ ownerScopeKey: this.ownerScopeKey,+ taskId,+ sourceRevision,+ sha256,+ bytes: req.totalBytes,+ mime,+ recovery: parsedRecovery.recovery,+ };+ const intentFail = await this.writeIntentUnlocked(identity);+ if (intentFail) return intentFail;+ if (this.requireOwner()) {+ await this.vault.delete({ path: intentPath(stagingId) }).catch(() => {});+ return fail('OWNER_CHANGED', '账号已切换,staging 操作已取消');+ }+ const begin = await this.vault.writeBegin({+ path: blobPath(stagingId),+ totalBytes: req.totalBytes,+ sha256,+ });+ if (this.requireOwner()) {+ if (begin.ok) await this.vault.writeAbort({ streamId: begin.streamId }).catch(() => {});+ return fail('OWNER_CHANGED', '账号已切换,staging 操作已取消');+ }+ if (!begin.ok) {+ await this.vault.delete({ path: intentPath(stagingId) }).catch(() => {});+ return vaultFail(begin);+ }+ this.uploads.set(stagingId, {+ stagingId,+ streamId: begin.streamId,+ taskId,+ sourceRevision,+ totalBytes: req.totalBytes,+ sha256Declared: sha256,+ mime,+ recovery: parsedRecovery.recovery,+ nextSeq: 1,+ lastChunk: null,+ lastAt: this.now(),+ written: 0,+ commitPending: false,+ });+ this.byTask.set(taskKey(taskId, sourceRevision), stagingId);+ return { ok: true as const, stagingId };+ });+ }++ async chunk(req: {+ ghostId: string;+ stagingId: unknown;+ seq: unknown;+ content: unknown;+ encoding?: unknown;+ }): Promise<LibraryStagingResult<{ accepted: number }>> {+ return this.runSerialized(async () => {+ const ready = await this.requireReady();+ if (ready) return ready;+ if (req.ghostId !== this.ghostId) return fail('PATH_INVALID', 'ghostId 与当前 staging 根不一致');+ const stagingId = parseStagingId(req.stagingId);+ if (typeof stagingId !== 'string') return stagingId;+ if (req.encoding !== undefined && req.encoding !== 'base64') {+ return fail('PATH_INVALID', 'encoding 只支持 "base64"');+ }+ const upload = this.uploads.get(stagingId);+ if (!upload) {+ if (this.durables.has(stagingId)) return fail('STREAM_INVALID', '已提交的原件不能再写分块');+ return fail('NOT_FOUND', 'stagingId 无效');+ }+ if (typeof req.seq !== 'number' || !Number.isInteger(req.seq) || req.seq < 1) {+ return fail('STREAM_INVALID', 'seq 必须从 1 起连续');+ }+ const decoded = decodeStrictBase64(req.content, this.limits.maxChunkBytes);+ if (!Buffer.isBuffer(decoded)) return decoded;+ if (req.seq === upload.nextSeq - 1 && upload.lastChunk && upload.lastChunk.equals(decoded)) {+ if (this.requireOwner()) return fail('OWNER_CHANGED', '账号已切换,staging 操作已取消');+ return { ok: true as const, accepted: decoded.byteLength };+ }+ const chunk = await this.vault.writeChunk({+ streamId: upload.streamId,+ seq: req.seq,+ content: decoded.toString('base64'),+ encoding: 'base64',+ });+ if (this.requireOwner()) return fail('OWNER_CHANGED', '账号已切换,staging 操作已取消');+ if (!chunk.ok) return vaultFail(chunk);+ upload.nextSeq = req.seq + 1;+ upload.lastChunk = decoded;+ upload.lastAt = this.now();+ upload.written += decoded.byteLength;+ return { ok: true as const, accepted: chunk.accepted };+ });+ }++ async commit(req: { ghostId: string; stagingId: unknown }): Promise<LibraryStagingResult<LibraryStagingReceipt>> {+ return this.runSerialized(async () => {+ const ready = await this.requireReady();+ if (ready) return ready;+ if (req.ghostId !== this.ghostId) return fail('PATH_INVALID', 'ghostId 与当前 staging 根不一致');+ const stagingId = parseStagingId(req.stagingId);+ if (typeof stagingId !== 'string') return stagingId;+ const durable = this.durables.get(stagingId);+ if (durable) {+ if (this.requireOwner()) return fail('OWNER_CHANGED', '账号已切换,staging 操作已取消');+ return { ok: true as const, ...receiptOf(durable) };+ }+ const upload = this.uploads.get(stagingId);+ if (!upload) return fail('NOT_FOUND', 'stagingId 无效');+ if (!upload.commitPending) {+ upload.commitPending = true;+ const committed = await this.vault.writeCommit({ streamId: upload.streamId });+ if (this.requireOwner()) return fail('OWNER_CHANGED', '账号已切换,staging 操作已取消');+ if (!committed.ok) {+ this.uploads.delete(stagingId);+ this.byTask.delete(taskKey(upload.taskId, upload.sourceRevision));+ const residue = await this.refreshClosedTmp();+ const leftover = await this.vault.stat({ path: blobPath(stagingId) });+ if (leftover.ok && leftover.kind === 'file') this.orphanBlobBytes += leftover.bytes;+ if (residue) return residue;+ return vaultFail(committed);+ }+ }+ const hashed = await this.vault.hashFile(blobPath(stagingId));+ if (!hashed.ok || hashed.sha256 !== upload.sha256Declared || hashed.bytes !== upload.totalBytes) {+ return fail('STREAM_INVALID', 'sha256 校验失败(声明值与实际字节不一致)');+ }+ const blobSync = await this.fsyncDurablePath(stagingId);+ if (blobSync) return blobSync;+ const identity = this.expectedIdentity(upload, hashed);+ const written = await this.writeManifestUnlocked(identity);+ if (written) return written;+ const record = this.durableFromIdentity(identity);+ this.uploads.delete(stagingId);+ this.durables.set(stagingId, record);+ this.durableBytes += hashed.bytes;+ if (this.requireOwner()) return fail('OWNER_CHANGED', '账号已切换,staging 操作已取消');+ return { ok: true as const, ...receiptOf(record) };+ });+ }++ async list(req: {+ ghostId: string;+ cursor?: unknown;+ limit?: unknown;+ }): Promise<LibraryStagingResult<{ items: LibraryStagingListItem[]; hasMore: boolean; nextCursor: string | null }>> {+ return this.runSerialized(async () => {+ const ready = await this.requireReady();+ if (ready) return ready;+ if (req.ghostId !== this.ghostId) return fail('PATH_INVALID', 'ghostId 与当前 staging 根不一致');+ const limit = req.limit === undefined+ ? this.limits.defaultListLimit+ : (typeof req.limit === 'number' && Number.isInteger(req.limit) && req.limit >= 1 && req.limit <= this.limits.maxListLimit+ ? req.limit+ : null);+ if (limit === null) return fail('PATH_INVALID', `limit 必须是 1..${this.limits.maxListLimit}`);+ if (req.cursor !== undefined && (typeof req.cursor !== 'string' || req.cursor.length === 0)) {+ return fail('PATH_INVALID', 'cursor 必须是非空字符串');+ }+ const committed = [...this.durables.values()].sort((a, b) => a.stagingId.localeCompare(b.stagingId));+ let start = 0;+ if (typeof req.cursor === 'string') {+ const cursor = req.cursor;+ start = committed.findIndex((record) => record.stagingId > cursor);+ if (start < 0) start = committed.length;+ }+ const slice = committed.slice(start, start + limit);+ const hasMore = start + slice.length < committed.length;+ if (this.requireOwner()) return fail('OWNER_CHANGED', '账号已切换,staging 操作已取消');+ return {+ ok: true as const,+ items: slice.map((record) => ({ ...receiptOf(record), recovery: record.recovery })),+ hasMore,+ nextCursor: hasMore ? slice[slice.length - 1]!.stagingId : null,+ };+ });+ }++ async read(req: {+ ghostId: string;+ stagingId: unknown;+ offset?: unknown;+ length?: unknown;+ }): Promise<LibraryStagingResult<{ stagingId: string; content: string; encoding: 'base64'; bytes: number; sha256: string }>> {+ return this.runSerialized(async () => {+ const ready = await this.requireReady();+ if (ready) return ready;+ if (req.ghostId !== this.ghostId) return fail('PATH_INVALID', 'ghostId 与当前 staging 根不一致');+ const stagingId = parseStagingId(req.stagingId);+ if (typeof stagingId !== 'string') return stagingId;+ if (!this.durables.has(stagingId)) return fail('NOT_FOUND', 'stagingId 无效');+ const offset = req.offset === undefined ? 0 : req.offset;+ const length = req.length === undefined ? this.limits.maxChunkBytes : req.length;+ if (typeof offset !== 'number' || !Number.isInteger(offset) || offset < 0) {+ return fail('PATH_INVALID', 'offset 必须是非负整数');+ }+ if (typeof length !== 'number' || !Number.isInteger(length) || length < 0) {+ return fail('PATH_INVALID', 'length 必须是非负整数');+ }+ if (length > this.limits.maxChunkBytes) {+ return fail('TOO_LARGE', `读取长度超上限(${this.limits.maxChunkBytes} 字节)`);+ }+ const read = await this.vault.read({+ path: blobPath(stagingId),+ encoding: 'base64',+ offset,+ length,+ });+ if (this.requireOwner()) return fail('OWNER_CHANGED', '账号已切换,staging 操作已取消');+ if (!read.ok) return vaultFail(read);+ return {+ ok: true as const,+ stagingId,+ content: read.content,+ encoding: 'base64' as const,+ bytes: read.bytes,+ sha256: read.sha256,+ };+ });+ }++ async abort(req: { ghostId: string; stagingId: unknown }): Promise<LibraryStagingResult<{ aborted: boolean }>> {+ return this.runSerialized(async () => {+ const ready = await this.requireReady();+ if (ready) return ready;+ if (req.ghostId !== this.ghostId) return fail('PATH_INVALID', 'ghostId 与当前 staging 根不一致');+ const stagingId = parseStagingId(req.stagingId);+ if (typeof stagingId !== 'string') return stagingId;+ const upload = this.uploads.get(stagingId);+ if (!upload) {+ if (this.durables.has(stagingId)) return fail('STREAM_INVALID', '已提交的原件不能 abort');+ return { ok: true as const, aborted: false };+ }+ if (upload.commitPending) {+ return fail('STREAM_INVALID', '已提交的原件不能 abort');+ }+ const aborted = await this.vault.writeAbort({ streamId: upload.streamId });+ this.uploads.delete(stagingId);+ this.byTask.delete(taskKey(upload.taskId, upload.sourceRevision));+ const intentDeleted = await this.vault.delete({ path: intentPath(stagingId) });+ if (!intentDeleted.ok && intentDeleted.errorCode !== 'NOT_FOUND') return vaultFail(intentDeleted);+ const residue = await this.refreshClosedTmp();+ if (this.requireOwner()) return fail('OWNER_CHANGED', '账号已切换,staging 操作已取消');+ if (!aborted.ok) return vaultFail(aborted);+ if (residue) return residue;+ return { ok: true as const, aborted: aborted.aborted };+ });+ }++ async dispose(): Promise<void> {+ await this.runSerialized(async () => {+ for (const upload of [...this.uploads.values()]) {+ await this.vault.writeAbort({ streamId: upload.streamId }).catch(() => {});+ }+ this.uploads.clear();+ this.byTask.clear();+ await this.vault.invalidate().catch(() => {});+ });+ }++ async release(req: {+ ghostId: string;+ stagingId: unknown;+ ack: LibraryStagingAck;+ /** Recheck Library session/epoch and re-hash the unique original before irreversible staging delete. */+ confirmLibrary?: () => LibraryStagingFailure | null | Promise<LibraryStagingFailure | null>;+ }): Promise<LibraryStagingResult<{ stagingId: string; released: boolean }>> {+ return this.runSerialized(async () => {+ const ready = await this.requireReady();+ if (ready) return ready;+ if (req.ghostId !== this.ghostId) return fail('PATH_INVALID', 'ghostId 与当前 staging 根不一致');+ const stagingId = parseStagingId(req.stagingId);+ if (typeof stagingId !== 'string') return stagingId;+ if (req.ack.ok !== true) return req.ack;+ const confirm = async (): Promise<LibraryStagingFailure | null> => {+ const owner = this.requireOwner();+ if (owner) return owner;+ return (await req.confirmLibrary?.()) ?? null;+ };+ const rollbackTombstone = async (): Promise<LibraryStagingFailure | null> => {+ const deleted = await this.vault.delete({ path: tombstonePath(stagingId) });+ if (!deleted.ok && deleted.errorCode !== 'NOT_FOUND') return vaultFail(deleted);+ return null;+ };+ const record = this.durables.get(stagingId);+ if (!record) {+ const blocked = await confirm();+ if (blocked) return blocked;+ const tomb = await this.readTombstone(stagingId);+ const blockedAfter = await confirm();+ if (blockedAfter) return blockedAfter;+ if (!tomb.ok) {+ return tomb.errorCode === 'NOT_FOUND'+ ? { ok: true as const, stagingId, released: false }+ : tomb;+ }+ const cleaned = await this.finishReleaseUnlocked(stagingId);+ if (cleaned) return cleaned;+ return { ok: true as const, stagingId, released: false };+ }+ if (req.ack.sha256 !== record.sha256 || req.ack.bytes !== record.bytes) {+ return fail('ACK_MISMATCH', 'Library ACK 与 staging 原件不一致,原件已保留');+ }+ const blocked = await confirm();+ if (blocked) return blocked;+ const stone = await this.vault.write({+ path: tombstonePath(stagingId),+ content: JSON.stringify({ version: 1, stagingId, released: true }),+ ifNotExists: true,+ });+ const blockedAfterWrite = await confirm();+ if (blockedAfterWrite) {+ return await rollbackTombstone() ?? blockedAfterWrite;+ }+ if (!stone.ok && stone.errorCode !== 'ALREADY_EXISTS') return vaultFail(stone);+ const markerSync = await this.fsyncDurablePath(stagingId);+ if (markerSync) {+ return await rollbackTombstone() ?? markerSync;+ }+ const blockedAfterSync = await confirm();+ if (blockedAfterSync) {+ return await rollbackTombstone() ?? blockedAfterSync;+ }+ const cleaned = await this.finishReleaseUnlocked(stagingId);+ if (cleaned) return cleaned;+ this.durables.delete(stagingId);+ this.byTask.delete(taskKey(record.taskId, record.sourceRevision));+ this.durableBytes = Math.max(0, this.durableBytes - record.bytes);+ return { ok: true as const, stagingId, released: true };+ });+ }+}diff --git a/apps/desktop/src/main/cindy-brain/libraryVault.ts b/apps/desktop/src/main/cindy-brain/libraryVault.tsindex 03d856425a..b257259417 100644--- a/apps/desktop/src/main/cindy-brain/libraryVault.ts+++ b/apps/desktop/src/main/cindy-brain/libraryVault.ts@@ -148,7 +148,8 @@ export interface LibraryVaultDeps {realPathAtGrant: string;identity: { dev: number; ino: number } | null;};- log?: {+ /** false = binding already created this ghost tree; MISSING must not init an empty replacement. */+ allowCustomInit?: boolean; log?: {info: (msg: string, meta?: Record<string, unknown>) => void;warn: (msg: string, meta?: Record<string, unknown>) => void;};@@ -318,6 +319,8 @@ export class LibraryVault {private opened = false;private invalidated = false;+ /** Absolute parent dirs created by recursive mkdir of a missing root; fsync these before claiming durable. */+ private createdAncestorDirs: string[] = [];private state: LibraryState = 'ready';private unavailableReason: string | null = null;private readonlyReason: string | null = null;@@ -361,6 +364,79 @@ export class LibraryVault {return fsFailure(err, 'INTERNAL', message);}+ /** mkdir -p that records newly created ancestor dirs (deepest first) so their parent entries can be fsynced. */+ private async mkdirRecordingCreated(absDir: string): Promise<string[]> {+ const target = path.resolve(absDir);+ const created: string[] = [];+ let cursor = target;+ const missing: string[] = [];+ for (;;) {+ try {+ const st = await fs.promises.lstat(cursor);+ if (st.isSymbolicLink() || !st.isDirectory()) {+ throw Object.assign(new Error('mkdir target is not a directory'), { code: 'ENOTDIR' });+ }+ break;+ } catch (err) {+ if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;+ missing.push(cursor);+ const parent = path.dirname(cursor);+ if (parent === cursor) break;+ cursor = parent;+ }+ }+ for (const dir of missing.reverse()) {+ await fs.promises.mkdir(dir);+ created.push(dir);+ }+ return created;+ }++ private async fsyncAbsDir(absDir: string): Promise<LibraryResult<{ fsynced: boolean }>> {+ const st = await this.lstatTarget(absDir);+ if (!st) return fail('NOT_FOUND', '目录不存在');+ if (st.isSymbolicLink() || !st.isDirectory()) {+ return fail('PATH_INVALID', 'fsyncDir 目标必须是普通目录');+ }+ if (process.platform === 'win32') {+ return { ok: true as const, fsynced: false };+ }+ try {+ const fh = await fs.promises.open(absDir, 'r');+ try {+ await fh.sync();+ } finally {+ await fh.close();+ }+ return { ok: true as const, fsynced: true };+ } catch (err) {+ return this.tmpFailure(err, '目录 fsync 失败');+ }+ }++ /**+ * Fsync parents of directories created when open() first minted this root.+ * Syncing the root inode is not the same as syncing the parent directory entry.+ * Windows still reports fsynced:false after the same path checks.+ */+ async fsyncCreatedAncestors(): Promise<LibraryResult<{ fsynced: boolean }>> {+ if (!this.opened) return fail('LIBRARY_UNAVAILABLE', 'Library 未打开(先调用 open)');+ if (this.createdAncestorDirs.length === 0) {+ return { ok: true as const, fsynced: true };+ }+ let anyUnsynced = false;+ const parents = new Set<string>();+ for (const created of this.createdAncestorDirs) {+ parents.add(path.dirname(created));+ }+ for (const parent of parents) {+ const synced = await this.fsyncAbsDir(parent);+ if (!synced.ok) return synced;+ if (synced.fsynced !== true) anyUnsynced = true;+ }+ if (process.platform !== 'win32' && !anyUnsynced) this.createdAncestorDirs = [];+ return { ok: true as const, fsynced: !anyUnsynced };+ }/** Custom roots must not recreate a vanished or replaced user-selected parent. keep files stay in the renamed-away directory. */private customRootUnavailable(reason: 'disk-missing' | 'binding-moved' = 'disk-missing',@@ -467,7 +543,11 @@ export class LibraryVault {this.meta = existing.meta;if (existing.usage) customUsage = existing.usage;} else if (existing.code === 'MISSING') {- const tree = await (this.deps.initCustomTree ?? initCustomLibraryTree)({+ // Same vault already had a live custom tree, or binding says this+ // ghost dir was created before: do not mkdir an empty replacement.+ if (this.meta || this.deps.allowCustomInit === false) {+ return this.customRootUnavailable('disk-missing');+ } const tree = await (this.deps.initCustomTree ?? initCustomLibraryTree)({parentFd: parentHandle.fd,ghostId: dirSeg,metaJson,@@ -505,7 +585,7 @@ export class LibraryVault {}}} else {- await fs.promises.mkdir(this.root, { recursive: true });+ this.createdAncestorDirs = await this.mkdirRecordingCreated(this.root);await fs.promises.mkdir(this.tmpDir, { recursive: true });await fs.promises.mkdir(path.join(this.metaDir, 'backups'), { recursive: true });}@@ -1074,6 +1154,69 @@ export class LibraryVault {});}+ /** Active writeBegin reservations (declared totalBytes). Staging uses this for hard 8GiB accounting. */+ pendingStreamReservationBytes(): number {+ let total = 0;+ for (const stream of this.streams.values()) total += stream.totalBytes;+ return total;+ }++ /** Leftover .cindy-library/tmp files. ENOENT = 0; permission/corrupt/symlink fail closed. */+ async tmpResidueBytes(): Promise<LibraryResult<{ bytes: number }>> {+ let entries: fs.Dirent[];+ try {+ entries = await fs.promises.readdir(this.tmpDir, { withFileTypes: true });+ } catch (err) {+ if ((err as NodeJS.ErrnoException).code === 'ENOENT') {+ return { ok: true as const, bytes: 0 };+ }+ return this.tmpFailure(err, 'staging 残片目录不可读');+ }+ const activeTmp = new Set(Array.from(this.streams.values()).map((stream) => stream.tmpAbs));+ let bytes = 0;+ for (const entry of entries) {+ const full = path.join(this.tmpDir, entry.name);+ if (activeTmp.has(full)) continue;+ let st: fs.Stats;+ try {+ st = await fs.promises.lstat(full);+ } catch (err) {+ if ((err as NodeJS.ErrnoException).code === 'ENOENT') continue;+ return this.tmpFailure(err, 'staging 残片不可读');+ }+ if (st.isSymbolicLink()) {+ return fail('LIBRARY_UNAVAILABLE', 'staging 残片含符号链接');+ }+ if (st.isFile()) bytes += st.size;+ }+ return { ok: true as const, bytes };+ }++ /**+ * Fsync a library-relative directory after durable rename.+ * Reuses resolveTarget identity (symlink/root guard). POSIX failure is not durable.+ * Windows cannot open a directory fd — returns fsynced:false after the same path checks.+ */+ async fsyncDir(relPath: unknown = ''): Promise<LibraryResult<{ fsynced: boolean }>> {+ if (!this.opened) return fail('LIBRARY_UNAVAILABLE', 'Library 未打开(先调用 open)');+ const rel = relPath === '' || relPath === undefined || relPath === null ? '' : String(relPath);+ let target: string;+ if (rel === '') {+ try {+ target = await fs.promises.realpath(this.root);+ } catch {+ return fail('LIBRARY_UNAVAILABLE', 'Library 根目录不可访问');+ }+ } else {+ const reason = validateLibraryRelPath(rel, this.limits);+ if (reason) return fail('PATH_INVALID', reason);+ const resolved = await this.resolveTarget(rel);+ if (!('target' in resolved)) return resolved;+ target = resolved.target;+ }+ return this.fsyncAbsDir(target);+ }+async writeAbort(req: { streamId: unknown }): Promise<LibraryResult<{ aborted: boolean }>> {const stream = typeof req.streamId === 'string' ? this.streams.get(req.streamId) : undefined;if (!stream) return { ok: true as const, aborted: false }; // 幂等@@ -1141,7 +1284,7 @@ export class LibraryVault {});}- async list(req: { path?: unknown; recursive?: unknown; cursor?: unknown; limit?: unknown }): Promise<LibraryResult<{ entries: Array<{ path: string; kind: 'file' | 'dir'; bytes: number; mtime: number }>; hasMore: boolean; nextCursor: string | null }>> {+ async list(req: { path?: unknown; recursive?: unknown; cursor?: unknown; limit?: unknown; strict?: unknown }): Promise<LibraryResult<{ entries: Array<{ path: string; kind: 'file' | 'dir'; bytes: number; mtime: number }>; hasMore: boolean; nextCursor: string | null }>> {if (!this.opened) return fail('LIBRARY_UNAVAILABLE', 'Library 未打开(先调用 open)');const sub = req.path === undefined || req.path === '' ? '' : String(req.path);if (sub !== '') {@@ -1152,6 +1295,7 @@ export class LibraryVault {const listRoot = sub === '' ? base : path.join(base, ...sub.split('/'));if (!isInsideDir(base, listRoot)) return fail('PATH_INVALID', 'path 越界');const recursive = req.recursive === true;+ const strict = req.strict === true;const limit = Math.min(typeof req.limit === 'number' && Number.isInteger(req.limit) && req.limit > 0 ? req.limit : this.limits.listPageSize,this.limits.listPageSize,@@ -1189,10 +1333,17 @@ export class LibraryVault {let st: fs.Stats;try {st = await fs.promises.lstat(full);- } catch {+ } catch (err) {+ if (strict && (err as NodeJS.ErrnoException).code !== 'ENOENT') {+ return this.tmpFailure(err, '目录条目不可读');+ }continue;}const rel = path.relative(base, full).split(path.sep).join('/');+ if (st.isSymbolicLink()) {+ if (strict) return fail('LIBRARY_UNAVAILABLE', '目录含符号链接');+ continue;+ }if (st.isFile()) {if (!push(rel, 'file', st.size, Math.round(st.mtimeMs))) break;} else if (st.isDirectory()) {@@ -1448,6 +1599,44 @@ export class LibraryVault {* 相对路径 → 已存在普通文件的绝对路径。路径纪律与 read 同源;任何校验* 不过(越界/symlink/不存在/是目录)返回 null,调用方统一折叠 404。*/+ /** Stream the whole file for hash+size; never slurps 8GiB into memory. */+ async hashFile(relPath: string): Promise<LibraryResult<{ path: string; bytes: number; sha256: string }>> {+ if (!this.opened) return fail('LIBRARY_UNAVAILABLE', 'Library 未打开(先调用 open)');+ const reason = validateLibraryRelPath(relPath, this.limits);+ if (reason) return fail('PATH_INVALID', reason);+ const resolved = await this.resolveTarget(relPath);+ if (!('target' in resolved)) return resolved;+ const expected = await this.lstatIdentityForRead(resolved.target);+ if (!expected) return fail('NOT_FOUND', `文件不存在:${relPath}`);+ if (!expected.isFile()) return fail('PATH_INVALID', `不是文件:${relPath}`);+ const flags = fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0);+ let handle: LibraryReadHandle | null = null;+ try {+ handle = await this.openReadHandle(resolved.target, flags);+ const opened = await handle.stat();+ if (!opened.isFile()) return fail('PATH_INVALID', `不是文件:${relPath}`);+ if (!isSameLibraryFileObject(expected, opened)) {+ return fail('INTERNAL', '读取身份校验失败(目标 identity 不一致)');+ }+ const size = Number(opened.size);+ const hash = crypto.createHash('sha256');+ const buf = Buffer.alloc(Math.min(1024 * 1024, Math.max(size, 1)));+ let pos = 0;+ while (pos < size) {+ const { bytesRead } = await handle.read(buf, 0, buf.length, pos);+ if (bytesRead === 0) break;+ hash.update(buf.subarray(0, bytesRead));+ pos += bytesRead;+ }+ if (pos !== size) return fail('INTERNAL', '读取不完整');+ return { ok: true as const, path: relPath, bytes: size, sha256: hash.digest('hex') };+ } catch (err) {+ return this.tmpFailure(err, '读取失败(主机 IO 错误)');+ } finally {+ if (handle) await handle.close().catch(() => {});+ }+ }+async resolveExistingFile(relPath: string): Promise<string | null> {const reason = validateLibraryRelPath(relPath, this.limits);if (reason) return null;diff --git a/apps/desktop/src/shared/ghost.ts b/apps/desktop/src/shared/ghost.tsindex 36dc2c338c..e5354ed307 100644--- a/apps/desktop/src/shared/ghost.ts+++ b/apps/desktop/src/shared/ghost.ts@@ -8228,6 +8228,13 @@ export const GHOST_LIBRARY_OPS = ['reveal','saveAs','clipboardWrite',+ 'staging.begin',+ 'staging.chunk',+ 'staging.commit',+ 'staging.list',+ 'staging.read',+ 'staging.release',+ 'staging.abort',] as const;export type GhostLibraryOp = (typeof GHOST_LIBRARY_OPS)[number];@@ -8235,9 +8242,30 @@ export type GhostLibraryOp = (typeof GHOST_LIBRARY_OPS)[number];export const GHOST_LIBRARY_CAPABILITY_OPERATIONS = ['clipboardWrite', 'saveAs'] as const;export type GhostLibraryCapabilityOperation = (typeof GHOST_LIBRARY_CAPABILITY_OPERATIONS)[number];+export const GHOST_LIBRARY_STAGING_OPERATIONS = [+ 'staging.begin',+ 'staging.chunk',+ 'staging.commit',+ 'staging.list',+ 'staging.read',+ 'staging.release',+ 'staging.abort',+] as const;+export type GhostLibraryStagingOperation = (typeof GHOST_LIBRARY_STAGING_OPERATIONS)[number];++export const GHOST_LIBRARY_STAGING_LIMITS_V1 = {+ version: 1 as const,+ maxTaskBytes: 8 * 1024 * 1024 * 1024,+ maxTotalBytes: 8 * 1024 * 1024 * 1024,+ maxConcurrentWrites: 4,+ maxChunkBytes: 16 * 1024 * 1024,+ reserveBytes: 1024 * 1024 * 1024,+};+export const GHOST_LIBRARY_CAPABILITIES_V1 = {version: 1 as const,- operations: GHOST_LIBRARY_CAPABILITY_OPERATIONS,+ operations: [...GHOST_LIBRARY_CAPABILITY_OPERATIONS, ...GHOST_LIBRARY_STAGING_OPERATIONS] as const,+ staging: GHOST_LIBRARY_STAGING_LIMITS_V1,};/** 宿主实际操作的稳定失败类别;TIMEOUT / TRANSPORT_ERROR 由插件查询层本地分类,不从 message 猜测。 */@@ -8314,6 +8342,16 @@ export interface GhostPipeLibraryRequest {length?: number;/** saveAs: 另存为建议文件名(仅 basename)。 */name?: string;+ /** staging: 插件任务身份 / 源版本 / MIME / 恢复元数据。 */+ taskId?: string;+ sourceRevision?: string;+ mime?: string;+ recovery?: Record<string, unknown>;+ stagingId?: string;+ /** staging.release: Library ACK 字节数(不是 begin 的 totalBytes)。 */+ bytes?: number;+ libraryIdentity?: string;+ libraryGeneration?: number;}/**@@ -8394,9 +8432,57 @@ export type GhostPipeLibraryResult =op: 'capabilities';capabilities: {version: 1;- operations: GhostLibraryCapabilityOperation[];+ operations: ReadonlyArray<GhostLibraryCapabilityOperation | GhostLibraryStagingOperation>;+ staging?: {+ version: 1;+ maxTaskBytes: number;+ maxTotalBytes: number;+ maxConcurrentWrites: number;+ maxChunkBytes: number;+ reserveBytes: number;+ };};}+ | { ok: true; op: 'staging.begin'; stagingId: string }+ | { ok: true; op: 'staging.chunk'; accepted: number }+ | {+ ok: true;+ op: 'staging.commit';+ stagingId: string;+ taskId: string;+ sourceRevision: string;+ sha256: string;+ bytes: number;+ mime: string;+ durable: true;+ }+ | {+ ok: true;+ op: 'staging.list';+ items: Array<{+ stagingId: string;+ taskId: string;+ sourceRevision: string;+ sha256: string;+ bytes: number;+ mime: string;+ durable: true;+ recovery: Record<string, unknown>;+ }>;+ hasMore: boolean;+ nextCursor: string | null;+ }+ | {+ ok: true;+ op: 'staging.read';+ stagingId: string;+ content: string;+ encoding: 'base64';+ bytes: number;+ sha256: string;+ }+ | { ok: true; op: 'staging.release'; stagingId: string; released: boolean }+ | { ok: true; op: 'staging.abort'; aborted: boolean }| { ok: false; errorCode: string; message: string; reason?: GhostLibraryErrorReason };/** Library 概览(ghosts:library-overview IPC 载荷;设置页插件详情消费)。 */diff --git a/docs/dev-rules/plugin-library-storage.md b/docs/dev-rules/plugin-library-storage.mdindex c2ece161e0..1e1a2bf77c 100644--- a/docs/dev-rules/plugin-library-storage.md+++ b/docs/dev-rules/plugin-library-storage.md@@ -21,6 +21,7 @@| per-plugin worker 入口 | `apps/desktop/src/main/cindy-brain/libraryDbWorker.ts` || 主进程 RPC 服务(发送前语句门 / dispose 收口) | `apps/desktop/src/main/cindy-brain/librarySqlService.ts` || 协议分派(资格审 / binding 根解析 / owner scope 复核) | `apps/desktop/src/main/cindy-brain/librarySlot.ts` |+| owner-scoped staging(独立于可迁移 Library 根) | `apps/desktop/src/main/cindy-brain/libraryStaging.ts` || 随时迁移状态机 | `apps/desktop/src/main/cindy-brain/libraryMigrate.ts` || 回收站删除通道 | `apps/desktop/src/main/cindy-brain/libraryTrash.ts` || 管子协议类型(`library-request`) | `apps/desktop/src/shared/ghost.ts`(`GhostPipeLibraryRequest/Result`) |@@ -34,7 +35,8 @@owners/<ownerKey>/├── libraries/<ghostId>/ # 系统管理默认根├── libraries-binding.json # 自定义位置持久 binding(原子写)-└── libraries-trash/<ghostId>-<ts>/ # 删除通道的 30 天回收站+├── libraries-trash/<ghostId>-<ts>/ # 删除通道的 30 天回收站+└── library-staging/<ghostId>/ # H1 上传 staging(不可随 Library 根迁移)```自定义根 = `<用户所选父目录>/<ghostId>`(binding 记录 realpath 快照 + 文件@@ -113,8 +115,14 @@ backups)对插件不可达——路径语法段首不许点,协议层天然13. **只读操作能力合同(capabilities)**:`{op:'capabilities'}` 在资格审与 op 合法性校验之后、会话创建之前返回,不捕获 owner、不解析库根、不 open vault、不弹窗、不碰剪贴板、不泄漏 owner 或绝对库路径。成功形态固定为- `{ok:true, op:'capabilities', capabilities:{version:1, operations:['clipboardWrite','saveAs']}}`。+ `{ok:true, op:'capabilities', capabilities:{version:1, operations:[...clipboardWrite/saveAs, staging.*], staging:{version:1,...limits}}}`。`operations` 只表达**实现支持**,不等于此刻有窗口、已授权或库可用。+ staging 操作与 capabilities 在 Library open/root/authorizedReadonly 门之前分派,+ 仍验当前 owner 与已启用 library 能力;只有 `staging.release` 核验当前 Library ACK。+ `disposeGhost` / `disposeAll` 先置 `relocating` 再排空该 ghost 在途 `staging.release`(tombstone/fsync 期间 Library 会话保持稳定),新的 release 在闸上拒绝;bind/unbind/relocate/delete 都先置 relocating 再 dispose,不把 owner mutation lease 当迁库锁。首次 mint staging 根时,耐久还要 fsync 新建根在其父目录中的 entry,只 fsync 根 inode 不算。Windows 仍报 `fsynced:false`。+ staging 根按 owner×ghost 捕获后不漂移;坏/不可读 manifest 返回 `LIBRARY_UNAVAILABLE`,不得报空或释放对应空间。+ 新原件在 blob 就位前经 Vault 写下 `intent.json`(owner/ghost/id/task/revision/hash/bytes/mime/recovery);崩溃后 new Store 只从这份可信 intent 校验 bytes/hash 再补 `manifest.json`+dirfsync,不从 blob 猜归属。不完整或冲突 fail-closed 并保留源。本 PR 新原件必有 intent;历史无 intent 的 orphan blob 只隔离计费,不 TTL 删除、不声称可恢复。原件只在 Library ACK 且调用者已保存画布后释放。+ 恢复与 release 走流式 hash,禁止 `readFile` 整文件入内存。null owner 拒。消费规则:仅 `version===1` 且 `operations` 为字符串数组才有效;额外字段忽略,未知operation 忽略,已知项保留;有效 v1 清单缺少某项才是 unsupported;缺字段、错类型、`version` 非 1、或旧宿主 unknown-op 一律 unknown。旧插件无需重装或重授权。