Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

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.ts
index 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.ts
index 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.ts
index 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 '../libraryD
import { 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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_ch
open/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.ts
index 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 changes
const 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.ts
index 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.ts
index 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 Libr
import { 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.md
index 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。旧插件无需重装或重授权。