[fazxes]

Description

world-local names a stream chunk chnk_<ULID> when streams.write() is called, before any await, then writes it to a temporary file and renames that into place. Readers order a stream's chunks by name, and a live reader delivers each chunk it has not had after the ones it already delivered. So a write that stalls between the two, as one does when its process is frozen, or when its file write is slow, lands under a name that sorts ahead of every chunk other writers landed meanwhile:

• a live reader that already had those chunks gets the late one after them;
• every read from index 0 gets it before them, so each of those chunks moves one index on, and a reader that resumes from an index (get(name, startIndex), a getChunks cursor) repeats one chunk or misses one.

Two writers of one stream is what happens when a process stalls and another takes its work over. libfx runs durable sessions on world-local and numbers each line of a session's stream by its index, so a reader that reconnects from a line's cursor depends on indexes never moving. libfx's crash campaign on world-local hits this when it freezes a worker with a stream write on its way: the frozen worker's line lands ahead of lines the replacing worker wrote, which a reader in another process already had, and nine later lines change index. The new test below reproduces it without timing: held just before its rename, a chunk minted before two other writers' chunks lands ahead of them.

This change names a chunk as it lands, in the new src/stream-chunk-place.ts:

• The name is the next one. A chunk's name is the successor, in the ULID alphabet, of the stream's newest chunk id, and the chunk is linked into place with link(), which never replaces a file. The chunk lands only if no other chunk has that name, so it lands after every chunk already in the stream.
• A writer that stalled after naming its chunk takes the next name. Its link() fails with EEXIST once another writer landed under that name. It lists the stream and tries after the newest. No lock is needed, and none would do: a lock held by a frozen process would hold every writer of the stream until it went stale, and the frozen holder would still land under its old name when it woke.
• One streamer's writes land in the order they were called, as they did when each chunk was named then. Each write takes its turn in its stream before any await, and lands only after the turns before it, so the guarantee the promise runId test pins is kept. writeMulti still writes its chunks in parallel and lands them in order.
• No listing in the common case. A streamer remembers the last chunk it landed in each stream and tries the next name first. It lists the stream for its first write to it and after a failed link.
• A stream's first chunk is chnk_0…01, the successor of the tombstone a zero-retention purge leaves, which still sorts first.
• A file system that makes no hard links (link() fails with ENOTSUP, EOPNOTSUPP, ENOSYS, EXDEV, or EPERM outside Windows) renames the chunk into place as before, under a name minted as it lands. That narrows the window from the whole write to the moment between naming and renaming.

Why a landed chunk always sorts after every chunk already in the stream: every name a writer creates is the successor of a name that existed, or the first id, so the names after a stream's older chunks have no gap. A link() to the successor of the id a writer knows succeeds only while that successor is free, and with no gap, that means the id it knows is the stream's newest. A writer whose id is out of date fails and lists the stream. Each failure moves its id forward, so the loop ends.

Compatibility:

• Readers and the file format are unchanged. Names are still chnk_ and 26 ULID characters, sorted as text, and a stream written by an older world-local goes on after its newest chunk.
• A chunk id no longer carries the time of its write: ids count on from the stream's newest chunk. Nothing in world-local reads that time; streamer.test.ts decodes it only to print the chunks when a test fails.
• An older world-local writing the same stream at the same time still names its chunks when the write is called, so its own late chunk can still land ahead. Its names carry the current time, while this change's ids count on from an older one, so a streamer with this change that kept the newest id it landed can also land a chunk ahead of one the older version landed since. Either needs both versions writing one stream.

Out of scope: fs.readdir lists a large directory in several system calls, so a reader whose listing runs while two chunks land can see the second without the first, and deliver them out of order. That needs a change on the reader side (wait for the next poll when the next name is not the successor of the last), and is the same before and after this change.

How did you test your changes?

• New src/stream-chunk-place.test.ts, 7 tests:
  • chunkSuccessor counts up in the ULID alphabet and carries, and refuses what is not a chunk id and the last one;
  • newestChunkId reads the newest chunk of any tag or format and ignores temporary and other files;
  • a chunk whose writer stalled after naming it (held at the link() that lands it, or the rename() that did before this change) lands after the chunks another writer landed meanwhile, the other writer took the name it chose, and a reader in its own streamer gets what a read from index 0 gets;
  • writers in four other processes (src/stream-chunk-place.child.mjs, run with Node's type stripping like in-band-fence.child.mjs), each writing 40 chunks to one stream, land every chunk once, each writer's in its order, and a live reader gets them in the order a read from index 0 does;
  • one streamer's writes land in the order they were called, with the first waiting on its runId promise and a batch whose first chunk is the largest, and the stream's first chunk is chnk_0…01;
  • on a file system that makes no hard links, chunks from two streamers land in order and leave no temporary file, and a streamer with links goes on after them.
• With streamer.ts back at 5.1.1, the four placement tests fail. The stalled chunk is read before the other writer's: [ 'a1', 'a2', 'b1', 'b2', 'b3' ] where [ 'a1', 'b1', 'b2', 'a2', 'b3' ] is expected. The live reader of the racing processes disagrees with a read from 0. A write lands before the one called earlier. And link is never called.
• vitest run src in packages/world-local: 28 files, 678 tests pass on 5.1.1 with the change, and 682 on main with it. tsc --noEmit passes. biome check on the changed files reports only the three existing complexity warnings in streamer.ts.
• End to end, through libfx, which bundles world-local:
  • a model of the stream (TLA+, a takeover with a write on its way) that TLC checks, walked against the code with each chunk's landing held: 40 walks, 656 steps, on world-local with this change, and the walk fails at its third path with 5.1.1, where the stalled chunk is read ahead of the other writer's;
  • libfx's crash scenarios that freeze a worker and let another take its session over, with this change built into world-local: 80 runs, and the reader's view matched a read from 0 in every one. In 6 of them the frozen worker's chunk was on its way when it froze, and it landed after the other worker's. libfx's 60-trial crash campaign on world-local and libfx's bundled copy held every invariant.
• Cost: on a Mac, a sequential write() takes about 0.6 ms instead of 0.3 ms (the link(), the unlink() of the temporary name, and write()'s own temporary rename), and a streamer's first write to a stream of 2,000 chunks lists it in 2 to 4 ms.

PR Checklist - Required to merge

• 📦 pnpm changeset was run to create a changelog for this PR
  • Use the correct semver bump type: patch for bug fixes, minor for new features, major for breaking changes.
  • Use pnpm changeset --empty if you are changing documentation or workbench apps
• 🔒 DCO sign-off passes (run git commit --signoff on your commits)
• 📝 Ping @vercel/workflow in a comment once the PR is ready, and the above checklist is complete

[changeset-bot]

🦋 Changeset detected

Latest commit: 617f7d7

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 19 packages

Name	Type
@workflow/world-local	Patch
@workflow/cli	Patch
@workflow/core	Patch
@workflow/vitest	Patch
@workflow/web	Patch
@workflow/world-postgres	Patch
workflow	Patch
@workflow/world-testing	Patch
@workflow/builders	Patch
@workflow/next	Patch
@workflow/nitro	Patch
@workflow/web-shared	Patch
@workflow/astro	Patch
@workflow/nest	Patch
@workflow/rollup	Patch
@workflow/sveltekit	Patch
@workflow/vite	Patch
@workflow/nuxt	Patch
@workflow/world-vercel	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

@fazxes is attempting to deploy a commit to the Vercel Labs Team on Vercel.

A member of the Team first needs to authorize it.

[VaguelySerious]

(AI) Preliminary review: AI review: no blocking issues

[VaguelySerious]

AI Review: Note

Two things about the no-hard-links fallback:

1. It looks unreachable in practice. Every event write already goes through writeExclusive() in fs.ts, which link()s a temp into place and has no fallback. On a file system without hard links, world-local fails at the run's first event, before any stream gets written.
2. It isn't safe across processes. Say process A lands T|R and B, in the same millisecond, lists T|R and mints T|R' with R' < R. B then takes chunkSuccessor(T|R). A's next write in that millisecond lists T|R too, and its monotonic factory mints T|R+1, which is the same name. Both rename() into chnk_T|R+1, and the second one silently replaces the first's chunk. Before this PR, ids minted in different processes never collided like this.

I'd drop the fallback, along with mint and the monotonicUlid source, and let link() errors surface the way writeExclusive does. If you keep it, a comment noting the overwrite risk would help. Not blocking.

[VaguelySerious]

AI Review: Note

Addressed in 4caefdc: the fallback is gone.

• renamedInto, NO_HARD_LINKS, the hardLinks flag and the mint option are removed from stream-chunk-place.ts, and the monotonicUlid source (with its ulid and @workflow/utils imports) is removed from streamer.ts.
• A link() that fails with anything other than EEXIST, or ENOENT once the directory is recreated, now fails the write. This matches writeExclusive(). The temp file is still cleaned up.
• The no-hard-links test is replaced by one where link() fails once with ENOTSUP: that write rejects, it leaves no temporary file, and the next write lands as chnk_0…02 right after chnk_0…01.
• The module comment now says why there is no fallback.

world-local tests pass (679 passed, 4 skipped), tsc --noEmit is clean, and the multi-process SIGSTOP/SIGCONT stress run still holds: the live reader matches a read from 0, and indexes never move.

[github-actions]

Backport PR opened against stable: #5188. Merge conflicts were resolved by AI — please review carefully. (backport job run)