Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
fix(desktop): serialize zip entry lifecycles and reserve the limits atomically (R3-M2, R4-M1)
M144339c958cb
diff --git a/desktop-app/src/__tests__/gfsZipStream.test.ts b/desktop-app/src/__tests__/gfsZipStream.test.tsindex a78257ccd..b905a5854 100644--- a/desktop-app/src/__tests__/gfsZipStream.test.ts+++ b/desktop-app/src/__tests__/gfsZipStream.test.ts@@ -50,11 +50,12 @@ async function makeDeps(failDialog?: booleanopenFile?: ZipStreamDeps['openFile']} = {}-): Promise<ZipStreamDeps & { tempDir: string }> {+): Promise<ZipStreamDeps & { tempDir: string; savePath: string }> {const tempDir = await mkdtemp(join(tmpdir(), 'evenfire-zip-test-'))tempRoots.push(tempDir)return {tempDir,+ savePath,openFile: options.openFile,showSaveDialog: vi.fn(async () => {if (options.failDialog) throw new Error('save dialog failed')@@ -319,6 +320,218 @@ describe('gfs zipStream — streamed payload (R1-H2)', () => {})})+/**+ * R4-M1 / R3-M2 — CONCURRENCY. The writer used to serialize individual+ * WRITES, not complete ENTRY LIFECYCLES, so two concurrent appends could+ * interleave: the second entry's local header landed inside the first+ * entry's payload. The aggregate ceilings were likewise checked against+ * committed state only, so concurrent appends could collectively exceed+ * them.+ */+describe('gfs zipStream — concurrent entries (R4-M1, R3-M2)', () => {+ /** Yields to the event loop, so concurrent appends really do interleave. */+ const yieldToLoop = () => new Promise<void>(resolve => setTimeout(resolve, 0))++ it('keeps concurrent streaming appends from interleaving entries (R4-M1)', async () => {+ const savePath = join(tmpdir(), `concurrent-${Date.now()}.zip`)+ savedFiles.push(savePath)+ const deps = await makeDeps(savePath)+ const jobId = await openJob(OWNER, deps)++ const sources = [+ { name: 'a.txt', chunks: ['aaa-1', 'aaa-2', 'aaa-3'] },+ { name: 'b.txt', chunks: ['bbb-1', 'bbb-2', 'bbb-3'] },+ { name: 'c.txt', chunks: ['ccc-1', 'ccc-2', 'ccc-3'] },+ ]+ // All three appends are ACCEPTED before any of them completes.+ const results = await Promise.all(+ sources.map(source =>+ appendZipEntryStreaming(+ jobId,+ OWNER,+ source.name,+ async sink => {+ for (const chunk of source.chunks) {+ await sink.write(new TextEncoder().encode(chunk))+ await yieldToLoop()+ }+ },+ deps+ )+ )+ )+ expect(results.map(result => result.bytes)).toEqual([15, 15, 15])++ await finishZipJob(jobId, OWNER, 'Concurrent.zip', deps)++ // An INDEPENDENT reader sees three complete entries whose payloads are+ // exactly what the producers wrote.+ const { entries } = readZipArchive(new Uint8Array(await readFile(savePath)))+ expect(entries.map(entry => entry.name).sort()).toEqual(['a.txt', 'b.txt', 'c.txt'])+ for (const entry of entries) {+ const source = sources.find(candidate => candidate.name === entry.name)!+ expect(new TextDecoder().decode(entry.bytes)).toBe(source.chunks.join(''))+ expect(entry.crc).toBe(crc32(entry.bytes))+ }++ // The SYSTEM extractor agrees — a corrupted archive does not extract.+ const extracted = await extractWithSystemUnzip(savePath)+ if (extracted) {+ expect(extracted['a.txt']).toBe('aaa-1aaa-2aaa-3')+ expect(extracted['b.txt']).toBe('bbb-1bbb-2bbb-3')+ expect(extracted['c.txt']).toBe('ccc-1ccc-2ccc-3')+ }+ })++ it('keeps a failed concurrent append from corrupting its neighbours (R4-M1)', async () => {+ const savePath = join(tmpdir(), `concurrent-rollback-${Date.now()}.zip`)+ savedFiles.push(savePath)+ const deps = await makeDeps(savePath)+ const jobId = await openJob(OWNER, deps)++ const good = appendZipEntryStreaming(+ jobId,+ OWNER,+ 'good.txt',+ async sink => {+ await sink.write(new TextEncoder().encode('good-1'))+ await yieldToLoop()+ await sink.write(new TextEncoder().encode('good-2'))+ await yieldToLoop()+ },+ deps+ )+ const doomed = appendZipEntryStreaming(+ jobId,+ OWNER,+ 'doomed.txt',+ async sink => {+ await sink.write(new TextEncoder().encode('partial'))+ await yieldToLoop()+ throw new Error('producer failed mid-stream')+ },+ deps+ )++ await expect(doomed).rejects.toThrow(/producer failed/)+ await expect(good).resolves.toMatchObject({ name: 'good.txt', bytes: 12 })++ await finishZipJob(jobId, OWNER, 'ConcurrentRollback.zip', deps)+ const { entries } = readZipArchive(new Uint8Array(await readFile(savePath)))+ expect(entries.map(entry => entry.name)).toEqual(['good.txt'])+ expect(new TextDecoder().decode(entries[0]!.bytes)).toBe('good-1good-2')+ })++ it('reserves job slots atomically across concurrent starts (R3-M2)', async () => {+ const deps = await makeDeps(join(tmpdir(), 'batch.zip'))+ // Every start is fired WITHOUT awaiting, so they all race for the slots.+ // DIFFERENT owners race for the PROCESS-wide ceiling.+ const attempts = Array.from({ length: MAX_ACTIVE_ZIP_JOBS + 3 }, (_, index) =>+ startZipJob(`window-${index}`, deps).then(+ jobId => ({ ok: true as const, jobId }),+ error => ({ ok: false as const, error })+ )+ )+ const settled = await Promise.all(attempts)+ const opened = settled.filter(result => result.ok)+ const refused = settled.filter(result => !result.ok)+ // Register the opened jobs for cleanup BEFORE asserting, so a failing+ // expectation cannot leak a job into the next test.+ settled.forEach((result, index) => {+ if (result.ok) openJobs.push({ jobId: result.jobId, owner: `window-${index}`, deps })+ })++ expect(opened).toHaveLength(MAX_ACTIVE_ZIP_JOBS)+ expect(refused).toHaveLength(3)+ for (const result of refused) {+ expect((result as { error: Error }).error).toBeInstanceOf(ZipStreamLimitError)+ }+ })++ it('reserves per-window job slots atomically across concurrent starts (R3-M2)', async () => {+ const deps = await makeDeps(join(tmpdir(), 'owner-batch.zip'))+ // ONE window racing for its own ceiling.+ const attempts = Array.from({ length: MAX_ACTIVE_ZIP_JOBS_PER_OWNER + 3 }, () =>+ startZipJob(OWNER, deps).then(+ jobId => ({ ok: true as const, jobId }),+ error => ({ ok: false as const, error })+ )+ )+ const settled = await Promise.all(attempts)+ // Register the opened jobs for cleanup BEFORE asserting.+ for (const result of settled.filter(result => result.ok)) {+ openJobs.push({ jobId: result.jobId, owner: OWNER, deps })+ }+ expect(settled.filter(result => result.ok)).toHaveLength(MAX_ACTIVE_ZIP_JOBS_PER_OWNER)+ expect(settled.filter(result => !result.ok)).toHaveLength(3)+ for (const result of settled.filter(result => !result.ok)) {+ expect((result as { error: Error }).error).toBeInstanceOf(ZipStreamLimitError)+ }+ })++ it('reserves the payload budget atomically across concurrent appends (R3-M2)', async () => {+ const deps = await makeDeps(join(tmpdir(), 'budget.zip'))+ const jobId = await openJob(OWNER, { ...deps, limits: { maxTotalBytes: 64 } })++ // Three appends of 32 bytes each: only TWO fit in a 64-byte archive.+ const attempts = Array.from({ length: 3 }, (_, index) =>+ appendZipEntryStreaming(+ jobId,+ OWNER,+ `entry-${index}.bin`,+ async sink => {+ await sink.write(new Uint8Array(32).fill(index + 1))+ await yieldToLoop()+ },+ deps+ ).then(+ () => ({ ok: true as const }),+ error => ({ ok: false as const, error })+ )+ )+ const settled = await Promise.all(attempts)+ const accepted = settled.filter(result => result.ok)+ const refused = settled.filter(result => !result.ok)++ // The ceiling is not bypassed: the archive never exceeds 64 payload bytes.+ expect(accepted).toHaveLength(2)+ expect(refused).toHaveLength(1)+ expect((refused[0] as { error: Error }).error).toBeInstanceOf(ZipStreamLimitError)++ await finishZipJob(jobId, OWNER, 'Budget.zip', deps)+ const { entries } = readZipArchive(new Uint8Array(await readFile(deps.savePath)))+ const total = entries.reduce((sum, entry) => sum + entry.bytes.length, 0)+ expect(total).toBeLessThanOrEqual(64)+ })++ it('reserves the entry count atomically across concurrent appends (R3-M2)', async () => {+ const deps = await makeDeps(join(tmpdir(), 'entries.zip'))+ const jobId = await openJob(OWNER, { ...deps, limits: { maxEntries: 2 } })++ const attempts = Array.from({ length: 4 }, (_, index) =>+ appendZipEntryStreaming(+ jobId,+ OWNER,+ `entry-${index}.bin`,+ async sink => {+ await sink.write(new TextEncoder().encode('x'))+ await yieldToLoop()+ },+ deps+ ).then(+ () => ({ ok: true as const }),+ error => ({ ok: false as const, error })+ )+ )+ const settled = await Promise.all(attempts)+ expect(settled.filter(result => result.ok)).toHaveLength(2)+ expect(settled.filter(result => !result.ok)).toHaveLength(2)+ for (const result of settled.filter(result => !result.ok)) {+ expect((result as { error: Error }).error).toBeInstanceOf(ZipStreamLimitError)+ }+ })+})+describe('gfs zipStream — path safety (R3-M1)', () => {const unsafeNames = ['../outside.txt',diff --git a/desktop-app/src/gfs/zipStream.ts b/desktop-app/src/gfs/zipStream.tsindex 7a6ee312c..d44362e9b 100644--- a/desktop-app/src/gfs/zipStream.ts+++ b/desktop-app/src/gfs/zipStream.ts@@ -1,11 +1,11 @@/**- * File-backed ZIP assembly for the folder-zip export (R1-H2, spec: round-2- * extensions). The renderer walks the folder and hands each entry to the main- * process; entries (local header + payload) are appended to a temp file, only- * central-directory metadata stays in memory, and `finish` appends the- * directory + EOCD in place, then moves the temp file to the user-chosen save- * location. Peak renderer memory is independent of folder size; main keeps- * ~76 + name bytes per entry plus one chunk.+ * File-backed ZIP assembly for the folder-zip export (R1-H2, R3-M1, R3-M2,+ * R3-M3, R3-M5, R4-M1). The renderer walks the folder and hands each entry to+ * the main process; entries (local header + payload) are appended to a+ * temp file, only central-directory metadata stays in memory, and `finish`+ * appends the directory + EOCD in place, then moves the temp file to the+ * user-chosen save location. Peak renderer memory is independent of folder+ * size; main keeps ~76 + name bytes per entry plus one chunk.** The main process is the TRUST BOUNDARY, not a helper. A renderer is a web* page: it must not be able to write outside the directory the user chose, to@@ -16,17 +16,44 @@* - PATH SAFETY (R3-M1): every entry name is validated as a canonical* relative path BEFORE a byte of entry data is written.* - RESOURCE LIMITS (R3-M2): aggregate payload bytes, entry count, the ZIP32- * format bounds, job ownership and concurrency are all enforced here.+ * format bounds, job ownership and concurrency are all enforced here, and+ * every one of them is RESERVED ATOMICALLY before the asynchronous work+ * that consumes it.* - CLEANUP OWNERSHIP (R3-M3): the job owns its handle and its temp file until* the save has completed; every unsuccessful path closes the handle and* removes the file.* - STREAMED PAYLOAD (R1-H2): the payload is written chunk by chunk, so a* large file never materializes as one contiguous buffer.*+ * ## Concurrency (R4-M1)+ *+ * The writer serializes COMPLETE ENTRY LIFECYCLES, not individual WRITES.+ * An entry's local header, payload and CRC patch are written by ONE task, so+ * two concurrent appends can never interleave: the second entry's header+ * cannot land inside the first entry's payload. Finalization waits for every+ * accepted append to settle before the central directory is written, so an+ * in-flight entry can never land after the directory.+ *+ * ## Reservations (R3-M2)+ *+ * A ceiling that is CHECKED but not RESERVED is a ceiling two concurrent+ * operations can both slip past. Every limit below is therefore taken as a+ * reservation in ONE synchronous step, before the first `await`:+ *+ * - a job slot, held from before the temp file is opened until the job is+ * registered;+ * - an entry slot, held from admission until the entry commits or fails;+ * - payload bytes, held per chunk until the entry commits or fails.+ *+ * The reservations are taken against the COMMITTED state plus everything+ * other accepted appends already reserved, so the aggregate ceilings include+ * in-flight work. A rejected append releases everything it reserved and+ * changes nothing: not the file size, not the entry list, not the counters.+ ** Format reference: APPNOTE.TXT — local file header (4.3.7), central directory* (4.3.12), EOCD (4.3.19). Entries are STORED (see the renderer-era decision:- * already-encoded payloads, exact byte-budget reasoning); names are UTF-8 with- * general-purpose flag bit 11 set; DOS timestamps are zero (deterministic).+ * the payload is streamed, not compressed, so the CRC is computed over the+ * bytes as they are written).*/import { dialog } from 'electron'import { randomUUID } from 'node:crypto'@@ -97,28 +124,40 @@ interface ZipStreamJob {ownerId: stringtempPath: stringhandle: Awaited<ReturnType<typeof open>>- /** Serializes temp-file writes across append calls. Never rejects. */- writeChain: Promise<void>+ /**+ * Serializes COMPLETE ENTRY LIFECYCLES: one at a time, in acceptance+ * order. Never rejects.+ */+ lifecycleChain: Promise<void>+ /** The entries committed to the central directory. */entries: DirectoryEntry[]+ /**+ * Entry slots held by accepted appends that have not committed yet. Counted+ * against the entry ceiling together with the committed entries (R3-M2).+ */+ reservedEntries: numberallocator: ZipEntryNameAllocator/** Payload bytes committed to the archive (the archive's data size). */payloadBytes: number+ /**+ * Payload bytes reserved by accepted appends that have not committed yet.+ * Counted against the payload ceiling together with the committed bytes+ * (R3-M2).+ */+ reservedPayloadBytes: number/** Bytes written to the temp file: payload + local headers. */byteCount: number/** The archive's ceilings, resolved when the job was opened. */limits: ZipStreamLimits- /** Appends currently in flight for this job. */+ /** Appends accepted and not yet finished (queued or running). */inFlight: number- closed: boolean+ /** The archive is being finalized: no further append is accepted. */+ finishing: boolean+ /** The job is dead: no further lifecycle may start. */destroyed: boolean-}--/** An entry whose local header has been written and whose payload follows. */-interface PreparedEntry {- plan: PlannedEntryName- nameBytes: Uint8Array- header: Uint8Array- localHeaderOffset: number+ /** The handle and the temp file have been released. */+ cleaned: boolean+ closed: boolean}export interface ZipStreamLimits {@@ -151,6 +190,14 @@ export const MAX_ACTIVE_ZIP_JOBS_PER_OWNER = 2export const MAX_CONCURRENT_APPENDS_PER_JOB = 4const jobs = new Map<string, ZipStreamJob>()+/**+ * Jobs being opened RIGHT NOW. Their slot is held from before the temp file+ * is opened until the job is registered, so two concurrent starts cannot+ * both observe the same free capacity (R3-M2).+ */+let pendingJobStarts = 0+/** The same, per window, so one window cannot bypass its own ceiling. */+const pendingJobStartsByOwner = new Map<string, number>()/** The entry name is unsafe: it could escape the extraction directory. */export class ZipStreamNameError extends Error {@@ -188,13 +235,17 @@ function requireJob(jobId: string, ownerId: string): ZipStreamJob {}/**- * Serializes one write onto the job's chain. A failed write belongs to the- * append that caused it: the chain stays usable so a later append is not- * silently skipped, and the job's cleanup path owns the broken handle.+ * Runs one complete entry lifecycle, strictly in acceptance order.+ *+ * The WHOLE lifecycle — local header, payload, CRC patch — runs inside ONE+ * task, so an entry's bytes are always contiguous and never interleaved with+ * another entry's (R4-M1). A failed lifecycle belongs to the append that+ * caused it: the chain stays usable so a later append is not silently+ * skipped.*/-function enqueue<T>(job: ZipStreamJob, task: () => Promise<T>): Promise<T> {- const result = job.writeChain.then(task, task)- job.writeChain = result.then(+function enqueueLifecycle<T>(job: ZipStreamJob, task: () => Promise<T>): Promise<T> {+ const result = job.lifecycleChain.then(task, task)+ job.lifecycleChain = result.then(() => undefined,() => undefined)@@ -202,15 +253,63 @@ function enqueue<T>(job: ZipStreamJob, task: () => Promise<T>): Promise<T> {}/**- * Closes the handle and removes the temp file, and drops the job. The job+ * Reserves an entry slot and its payload bytes, in ONE synchronous step,+ * BEFORE any asynchronous work (R3-M2).+ *+ * The check and the reservation are not separated by an `await`, so two+ * concurrent appends cannot both observe the same free capacity and+ * collectively exceed a ceiling. Everything reserved here is released again+ * when the append fails.+ */+function reserveAppend(job: ZipStreamJob, payloadBytes: number): void {+ const maxEntries = Math.min(job.limits.maxEntries, ZIP32_MAX_ENTRIES)+ if (job.entries.length + job.reservedEntries >= maxEntries) {+ throw new ZipStreamLimitError(+ `A ZIP archive holds at most ${maxEntries} entries, which this archive would exceed`+ )+ }+ if (job.payloadBytes + job.reservedPayloadBytes + payloadBytes > job.limits.maxTotalBytes) {+ throw new ZipStreamLimitError(+ `The archive would exceed the ${job.limits.maxTotalBytes}-byte folder-zip limit`+ )+ }+ job.reservedEntries += 1+ job.reservedPayloadBytes += payloadBytes+}++/**+ * Reserves one payload chunk against the archive's ceilings, in ONE+ * synchronous step (R3-M2).+ *+ * The aggregate ceiling includes the bytes other accepted appends already+ * reserved, so in-flight work counts against the budget.+ */+function reservePayload(job: ZipStreamJob, bytes: number): void {+ if (job.payloadBytes + job.reservedPayloadBytes + bytes > job.limits.maxTotalBytes) {+ throw new ZipStreamLimitError(+ `The archive would exceed the ${job.limits.maxTotalBytes}-byte folder-zip limit`+ )+ }+ if (job.byteCount + bytes > ZIP32_MAX_BYTES) {+ throw new ZipStreamLimitError('The archive would exceed the ZIP32 size limit')+ }+ job.reservedPayloadBytes += bytes+}++/**+ * Releases the handle and removes the temp file, and drops the job. The job* OWNS both resources until the save completes, so this is the single place* that releases them (R3-M3).+ *+ * This does NOT wait for the lifecycle chain: it is called from INSIDE a+ * lifecycle when a rollback fails, and awaiting the chain from within the+ * chain would deadlock.*/async function destroyJob(job: ZipStreamJob, deps: ZipStreamDeps): Promise<void> {jobs.delete(job.jobId)- if (job.destroyed) returnjob.destroyed = true- await job.writeChain.catch(() => undefined)+ if (job.cleaned) return+ job.cleaned = trueif (!job.closed) {job.closed = trueawait job.handle.close().catch(() => undefined)@@ -219,36 +318,54 @@ async function destroyJob(job: ZipStreamJob, deps: ZipStreamDeps): Promise<void>}export async function startZipJob(ownerId: string, deps: ZipStreamDeps = {}): Promise<string> {- if (jobs.size >= MAX_ACTIVE_ZIP_JOBS) {- throw new ZipStreamLimitError('Too many ZIP jobs are already open')- }+ // ── ADMISSION (synchronous, atomic) ─────────────────────────────────────+ // The slot is taken BEFORE the first await, so two concurrent starts+ // cannot both observe the same free capacity and collectively exceed the+ // ceiling (R3-M2).+ const pendingOwned = pendingJobStartsByOwner.get(ownerId) ?? 0let owned = 0for (const job of jobs.values()) if (job.ownerId === ownerId) owned += 1- if (owned >= MAX_ACTIVE_ZIP_JOBS_PER_OWNER) {+ if (jobs.size + pendingJobStarts >= MAX_ACTIVE_ZIP_JOBS) {+ throw new ZipStreamLimitError('Too many ZIP jobs are already open')+ }+ if (owned + pendingOwned >= MAX_ACTIVE_ZIP_JOBS_PER_OWNER) {throw new ZipStreamLimitError('This window already has too many ZIP jobs open')}- const jobId = randomUUID()- const tempPath = join(deps.tempDir ?? tmpdir(), `evenfire-zip-${jobId}.part`)- const handle = await (deps.openFile ?? open)(tempPath, 'w', 0o600)- jobs.set(jobId, {- jobId,- ownerId,- tempPath,- handle,- writeChain: Promise.resolve(),- entries: [],- allocator: new ZipEntryNameAllocator(),- payloadBytes: 0,- byteCount: 0,- limits: {- maxTotalBytes: deps.limits?.maxTotalBytes ?? ZIP_MAX_TOTAL_BYTES,- maxEntries: deps.limits?.maxEntries ?? ZIP_MAX_ENTRIES,- },- inFlight: 0,- closed: false,- destroyed: false,- })- return jobId+ pendingJobStarts += 1+ pendingJobStartsByOwner.set(ownerId, pendingOwned + 1)+ try {+ const jobId = randomUUID()+ const tempPath = join(deps.tempDir ?? tmpdir(), `evenfire-zip-${jobId}.part`)+ const handle = await (deps.openFile ?? open)(tempPath, 'w', 0o600)+ jobs.set(jobId, {+ jobId,+ ownerId,+ tempPath,+ handle,+ lifecycleChain: Promise.resolve(),+ entries: [],+ reservedEntries: 0,+ allocator: new ZipEntryNameAllocator(),+ payloadBytes: 0,+ reservedPayloadBytes: 0,+ byteCount: 0,+ limits: {+ maxTotalBytes: deps.limits?.maxTotalBytes ?? ZIP_MAX_TOTAL_BYTES,+ maxEntries: deps.limits?.maxEntries ?? ZIP_MAX_ENTRIES,+ },+ inFlight: 0,+ finishing: false,+ destroyed: false,+ cleaned: false,+ closed: false,+ })+ return jobId+ } finally {+ pendingJobStarts -= 1+ const current = pendingJobStartsByOwner.get(ownerId) ?? 1+ if (current <= 1) pendingJobStartsByOwner.delete(ownerId)+ else pendingJobStartsByOwner.set(ownerId, current - 1)+ }}function localHeader(nameBytes: Uint8Array, crc: number, size: number): Uint8Array {@@ -270,22 +387,18 @@ function localHeader(nameBytes: Uint8Array, crc: number, size: number): Uint8Arr}/**- * Validates the entry and reserves its name, WITHOUT touching the archive.+ * Validates the entry and plans its name, WITHOUT touching the archive and+ * WITHOUT reserving anything.*- * Every check here runs before the caller writes a byte, so a rejected append- * leaves the file size, the entry list and the byte counters exactly as they- * were (R3-M2).+ * The name is planned INSIDE the entry lifecycle, so it is planned against+ * the names already committed: two concurrent appends of the same name get+ * two different names, never one duplicated entry.*/function prepareEntry(job: ZipStreamJob, rawName: string): PlannedEntryName {const rejection = validateZipEntryPath(rawName)if (rejection) throw new ZipStreamNameError(rawName, rejection)const plan = job.allocator.plan(rawName)if (!plan.fits) throw new ZipStreamNameTooLongError(plan.name)- if (job.entries.length >= Math.min(job.limits.maxEntries, ZIP32_MAX_ENTRIES)) {- throw new ZipStreamLimitError(- `A ZIP archive holds at most ${Math.min(job.limits.maxEntries, ZIP32_MAX_ENTRIES)} entries, which this archive would exceed`- )- }return plan}@@ -302,39 +415,53 @@ export async function appendZipEntry(): Promise<string> {const job = requireJob(jobId, ownerId)const data = new Uint8Array(bytes)- const plan = prepareEntry(job, rawName)- if (job.payloadBytes + data.byteLength > job.limits.maxTotalBytes) {- throw new ZipStreamLimitError(- `The archive would exceed the ${job.limits.maxTotalBytes}-byte folder-zip limit`- )- }- const nameBytes = new TextEncoder().encode(plan.name)- const header = localHeader(nameBytes, 0, 0)- if (job.byteCount + header.length + data.byteLength > ZIP32_MAX_BYTES) {- throw new ZipStreamLimitError('The archive would exceed the ZIP32 size limit')+ // ── ADMISSION (synchronous, atomic) ─────────────────────────────────────+ if (job.finishing) throw new Error('The ZIP archive is being finalized')+ if (job.inFlight + 1 > MAX_CONCURRENT_APPENDS_PER_JOB) {+ throw new ZipStreamLimitError('Too many ZIP appends are in flight for this job')}- const localHeaderOffset = job.byteCount+ reserveAppend(job, data.byteLength)+ job.inFlight += 1try {- await enqueue(job, async () => {- await job.handle.write(header, 0, header.length, localHeaderOffset)- await job.handle.write(data, 0, data.byteLength, localHeaderOffset + header.length)- const crc = crc32(data)- const patch = new Uint8Array(12)- const view = new DataView(patch.buffer)- view.setUint32(0, crc, true)- view.setUint32(4, data.byteLength, true)- view.setUint32(8, data.byteLength, true)- await job.handle.write(patch, 0, patch.length, localHeaderOffset + 14)- job.allocator.commit(plan)- job.entries.push({ nameBytes, crc, size: data.byteLength, localHeaderOffset })- job.payloadBytes += data.byteLength- job.byteCount = localHeaderOffset + header.length + data.byteLength+ return await enqueueLifecycle(job, async () => {+ let localHeaderOffset: number | undefined+ try {+ if (job.destroyed) throw new Error('The ZIP job was destroyed')+ const plan = prepareEntry(job, rawName)+ const nameBytes = new TextEncoder().encode(plan.name)+ const header = localHeader(nameBytes, 0, 0)+ if (job.byteCount + header.length + data.byteLength > ZIP32_MAX_BYTES) {+ throw new ZipStreamLimitError('The archive would exceed the ZIP32 size limit')+ }+ localHeaderOffset = job.byteCount+ await job.handle.write(header, 0, header.length, localHeaderOffset)+ await job.handle.write(data, 0, data.byteLength, localHeaderOffset + header.length)+ const crc = crc32(data)+ const patch = new Uint8Array(12)+ const view = new DataView(patch.buffer)+ view.setUint32(0, crc, true)+ view.setUint32(4, data.byteLength, true)+ view.setUint32(8, data.byteLength, true)+ await job.handle.write(patch, 0, patch.length, localHeaderOffset + 14)+ job.byteCount = localHeaderOffset + header.length + data.byteLength+ job.allocator.commit(plan)+ job.entries.push({ nameBytes, crc, size: data.byteLength, localHeaderOffset })+ job.payloadBytes += data.byteLength+ job.reservedPayloadBytes -= data.byteLength+ job.reservedEntries -= 1+ return plan.name+ } catch (error) {+ job.reservedPayloadBytes -= data.byteLength+ job.reservedEntries -= 1+ if (localHeaderOffset !== undefined) {+ await rollBackEntry(job, localHeaderOffset, deps)+ }+ throw error+ }})- } catch (error) {- await rollBackEntry(job, localHeaderOffset, deps)- throw error+ } finally {+ job.inFlight -= 1}- return plan.name}/**@@ -343,6 +470,9 @@ export async function appendZipEntry(* the job can still serve the next one. A failed rollback means the handle is* no longer trustworthy, so the job is destroyed (its handle closed and its* temp file removed).+ *+ * This runs INSIDE the failing entry's own lifecycle, so no other entry can+ * be written between the failure and the truncation (R4-M1).*/async function rollBackEntry(job: ZipStreamJob,@@ -350,10 +480,8 @@ async function rollBackEntry(deps: ZipStreamDeps): Promise<void> {try {- await enqueue(job, async () => {- await job.handle.truncate(localHeaderOffset)- job.byteCount = localHeaderOffset- })+ await job.handle.truncate(localHeaderOffset)+ job.byteCount = localHeaderOffset} catch {await destroyJob(job, deps)}@@ -380,6 +508,9 @@ export interface ZipStreamEntryResult {* CRC and writes it straight to the temp file. The local header is written* first with placeholder CRC/size fields and patched in place once the* payload is complete, so the entry stays a valid STORED entry.+ *+ * The WHOLE entry — header, payload, patch — is one lifecycle, so a+ * concurrent append cannot interleave with it (R4-M1).*/export async function appendZipEntryStreaming(jobId: string,@@ -389,77 +520,80 @@ export async function appendZipEntryStreaming(deps: ZipStreamDeps = {}): Promise<ZipStreamEntryResult> {const job = requireJob(jobId, ownerId)+ // ── ADMISSION (synchronous, atomic) ─────────────────────────────────────+ if (job.finishing) throw new Error('The ZIP archive is being finalized')if (job.inFlight + 1 > MAX_CONCURRENT_APPENDS_PER_JOB) {throw new ZipStreamLimitError('Too many ZIP appends are in flight for this job')}+ reserveAppend(job, 0)job.inFlight += 1- let preparedEntryOffset: number | undefinedtry {- const prepared: PreparedEntry = await enqueue(job, async () => {- const plan = prepareEntry(job, rawName)- const nameBytes = new TextEncoder().encode(plan.name)- const header = localHeader(nameBytes, 0, 0)- if (job.byteCount + header.length > ZIP32_MAX_BYTES) {- throw new ZipStreamLimitError('The archive would exceed the ZIP32 size limit')- }- const localHeaderOffset = job.byteCount- preparedEntryOffset = localHeaderOffset- await job.handle.write(header, 0, header.length, localHeaderOffset)- job.byteCount = localHeaderOffset + header.length- return { plan, nameBytes, header, localHeaderOffset }- })-- let crc = CRC32_INIT- let size = 0- const sink: ZipEntrySink = {- write: async (chunk: Uint8Array) => {- if (chunk.byteLength === 0) return- if (job.payloadBytes + size + chunk.byteLength > job.limits.maxTotalBytes) {- throw new ZipStreamLimitError(- `The archive would exceed the ${job.limits.maxTotalBytes}-byte folder-zip limit`- )- }- if (job.byteCount + chunk.byteLength > ZIP32_MAX_BYTES) {+ return await enqueueLifecycle(job, async () => {+ let localHeaderOffset: number | undefined+ let reservedPayload = 0+ try {+ if (job.destroyed) throw new Error('The ZIP job was destroyed')+ const plan = prepareEntry(job, rawName)+ const nameBytes = new TextEncoder().encode(plan.name)+ const header = localHeader(nameBytes, 0, 0)+ if (job.byteCount + header.length > ZIP32_MAX_BYTES) {throw new ZipStreamLimitError('The archive would exceed the ZIP32 size limit')}- size += chunk.byteLength- crc = crc32Update(crc, chunk)- await enqueue(job, async () => {- await job.handle.write(chunk, 0, chunk.byteLength, job.byteCount)- job.byteCount += chunk.byteLength- })- },- }-- await produce(sink)+ localHeaderOffset = job.byteCount+ await job.handle.write(header, 0, header.length, localHeaderOffset)+ job.byteCount = localHeaderOffset + header.length++ let crc = CRC32_INIT+ let size = 0+ const sink: ZipEntrySink = {+ write: async (chunk: Uint8Array) => {+ if (chunk.byteLength === 0) return+ // ATOMIC reservation: the chunk's bytes are claimed before the+ // write, against the aggregate ceiling that includes every other+ // accepted append's reservation (R3-M2).+ reservePayload(job, chunk.byteLength)+ reservedPayload += chunk.byteLength+ size += chunk.byteLength+ crc = crc32Update(crc, chunk)+ await job.handle.write(chunk, 0, chunk.byteLength, job.byteCount)+ job.byteCount += chunk.byteLength+ },+ }- const finalCrc = (crc ^ CRC32_INIT) >>> 0- await enqueue(job, async () => {- const patch = new Uint8Array(12)- const view = new DataView(patch.buffer)- view.setUint32(0, finalCrc, true)- view.setUint32(4, size, true)- view.setUint32(8, size, true)- await job.handle.write(patch, 0, patch.length, prepared.localHeaderOffset + 14)- })- job.allocator.commit(prepared.plan)- job.entries.push({- nameBytes: prepared.nameBytes,- crc: finalCrc,- size,- localHeaderOffset: prepared.localHeaderOffset,+ await produce(sink)++ const finalCrc = (crc ^ CRC32_INIT) >>> 0+ const patch = new Uint8Array(12)+ const view = new DataView(patch.buffer)+ view.setUint32(0, finalCrc, true)+ view.setUint32(4, size, true)+ view.setUint32(8, size, true)+ await job.handle.write(patch, 0, patch.length, localHeaderOffset + 14)++ job.allocator.commit(plan)+ job.entries.push({+ nameBytes,+ crc: finalCrc,+ size,+ localHeaderOffset,+ })+ job.payloadBytes += size+ job.reservedPayloadBytes -= reservedPayload+ job.reservedEntries -= 1+ return { name: plan.name, bytes: size }+ } catch (error) {+ // The entry is incomplete. Release everything it reserved and roll it+ // back so the archive stays a valid sequence of complete entries and+ // the job can still serve the next one; a failed rollback destroys the+ // job instead of leaving an unowned resource behind (R3-M3).+ job.reservedPayloadBytes -= reservedPayload+ job.reservedEntries -= 1+ if (localHeaderOffset !== undefined) {+ await rollBackEntry(job, localHeaderOffset, deps)+ }+ throw error+ }})- job.payloadBytes += size- return { name: prepared.plan.name, bytes: size }- } catch (error) {- // The entry is incomplete. Roll it back so the archive stays a valid- // sequence of complete entries and the job can still serve the next one;- // a failed rollback destroys the job (its handle closed, its temp file- // removed) instead of leaving an unowned resource behind (R3-M3).- if (preparedEntryOffset !== undefined) {- await rollBackEntry(job, preparedEntryOffset, deps)- }- throw error} finally {job.inFlight -= 1}@@ -477,6 +611,11 @@ export interface FinishZipJobResult {* The job stays REGISTERED until the save has completed: the cleanup* ownership must not end while the temp file is still on disk, or a failure* here would leave an unowned `.part` file behind (R3-M3).+ *+ * No further append is accepted once the archive is being finalized, and the+ * central directory is written only after every ACCEPTED append has settled+ * — otherwise an in-flight entry could land after the directory and produce+ * an invalid archive (R4-M1).*/export async function finishZipJob(jobId: string,@@ -485,58 +624,61 @@ export async function finishZipJob(deps: ZipStreamDeps = {}): Promise<FinishZipJobResult> {const job = requireJob(jobId, ownerId)+ // No further append is accepted from here on.+ job.finishing = true+ // Wait for every accepted append to settle before the directory is built.+ await job.lifecycleChain.catch(() => undefined)+const entryCount = job.entries.lengthtry {- await enqueue(job, async () => {- const centralDirectoryOffset = job.byteCount- const parts: Uint8Array[] = []- for (const entry of job.entries) {- const record = new Uint8Array(46 + entry.nameBytes.length)- const view = new DataView(record.buffer)- view.setUint32(0, CENTRAL_DIRECTORY_SIGNATURE, true)- view.setUint16(4, VERSION_NEEDED, true) // made by- view.setUint16(6, VERSION_NEEDED, true) // needed- view.setUint16(8, UTF8_FLAG, true)- view.setUint16(10, STORED_METHOD, true)- view.setUint16(12, 0, true) // mod time- view.setUint16(14, 0, true) // mod date- view.setUint32(16, entry.crc, true)- view.setUint32(20, entry.size, true)- view.setUint32(24, entry.size, true)- view.setUint16(28, entry.nameBytes.length, true)- view.setUint16(30, 0, true) // extra length- view.setUint16(32, 0, true) // comment length- view.setUint16(34, 0, true) // disk start- view.setUint16(36, 0, true) // internal attributes- view.setUint32(38, 0, true) // external attributes- view.setUint32(42, entry.localHeaderOffset, true)- record.set(entry.nameBytes, 46)- parts.push(record)- }- const centralDirectorySize = parts.reduce((sum, part) => sum + part.length, 0)- const eocd = new Uint8Array(22)- const view = new DataView(eocd.buffer)- view.setUint32(0, END_OF_CENTRAL_DIRECTORY_SIGNATURE, true)- view.setUint16(4, 0, true)- view.setUint16(6, 0, true)- view.setUint16(8, job.entries.length, true)- view.setUint16(10, job.entries.length, true)- view.setUint32(12, centralDirectorySize, true)- view.setUint32(16, centralDirectoryOffset, true)- view.setUint16(20, 0, true)- parts.push(eocd)- // Every write carries an EXPLICIT position: the writer must survive a- // rollback that truncates the file, and a truncated file leaves the- // handle's own position pointing past the new end.- let writeOffset = job.byteCount- for (const part of parts) {- await job.handle.write(part, 0, part.length, writeOffset)- writeOffset += part.length- }- job.byteCount = writeOffset- await job.handle.close()- job.closed = true- })+ const centralDirectoryOffset = job.byteCount+ const parts: Uint8Array[] = []+ for (const entry of job.entries) {+ const record = new Uint8Array(46 + entry.nameBytes.length)+ const view = new DataView(record.buffer)+ view.setUint32(0, CENTRAL_DIRECTORY_SIGNATURE, true)+ view.setUint16(4, VERSION_NEEDED, true) // made by+ view.setUint16(6, VERSION_NEEDED, true) // needed+ view.setUint16(8, UTF8_FLAG, true)+ view.setUint16(10, STORED_METHOD, true)+ view.setUint16(12, 0, true) // mod time+ view.setUint16(14, 0, true) // mod date+ view.setUint32(16, entry.crc, true)+ view.setUint32(20, entry.size, true)+ view.setUint32(24, entry.size, true)+ view.setUint16(28, entry.nameBytes.length, true)+ view.setUint16(30, 0, true) // extra length+ view.setUint16(32, 0, true) // comment length+ view.setUint16(34, 0, true) // disk start+ view.setUint16(36, 0, true) // internal attributes+ view.setUint32(38, 0, true) // external attributes+ view.setUint32(42, entry.localHeaderOffset, true)+ record.set(entry.nameBytes, 46)+ parts.push(record)+ }+ const centralDirectorySize = parts.reduce((sum, part) => sum + part.length, 0)+ const eocd = new Uint8Array(22)+ const view = new DataView(eocd.buffer)+ view.setUint32(0, END_OF_CENTRAL_DIRECTORY_SIGNATURE, true)+ view.setUint16(4, 0, true)+ view.setUint16(6, 0, true)+ view.setUint16(8, job.entries.length, true)+ view.setUint16(10, job.entries.length, true)+ view.setUint32(12, centralDirectorySize, true)+ view.setUint32(16, centralDirectoryOffset, true)+ view.setUint16(20, 0, true)+ parts.push(eocd)+ // Every write carries an EXPLICIT position: the writer must survive a+ // rollback that truncates the file, and a truncated file leaves the+ // handle's own position pointing past the new end.+ let writeOffset = job.byteCount+ for (const part of parts) {+ await job.handle.write(part, 0, part.length, writeOffset)+ writeOffset += part.length+ }+ job.byteCount = writeOffset+ await job.handle.close()+ job.closed = true} catch (error) {await destroyJob(job, deps)throw error@@ -580,6 +722,10 @@ export async function abortZipJob(if (job.ownerId !== ownerId) {throw new Error(`ZIP job ${jobId} belongs to another window`)}+ // A queued append must not start against a closing handle.+ job.destroyed = true+ // Wait for the in-flight entry to settle, so no write races the close.+ await job.lifecycleChain.catch(() => undefined)await destroyJob(job, deps)}