docs(jobs): concurrent use means goroutines, not processes #536

Merged

coilyco-ops merged 1 commit from eng/concurrent-means-goroutines into main

2026-08-13 15:26:20 +00:00

coilyco-ops commented

2026-08-13 15:25:31 +00:00

Member

One line, and it is the sentence that produced #488.

JobStore's contract said an implementation "must be safe for concurrent use", unqualified. To a reader meeting the interface, that reads as safe across processes — and that is close to the reasoning that put a second replica on the table: a database was provisioned per lane, the interface promised concurrency safety, and nothing in the code said one process was assumed.

It means goroutines inside one process.

What this is not

Not new information. docs/sirens-echo-jobs-single-process.md already records the process-local mutex, the absence of any SQL claiming strategy, and what a second replica would actually break. This is the code saying the same thing where a reader meets it, rather than only where a reader might go looking.

I filed #535 claiming that documentation did not exist. It does — written at 07:56 today, and linked from the very section of sirens-echo-jobs.md I had quoted. I read the paragraph and not the link. The issue carries the correction, and the proposed doc split turned out to be unnecessary, so sirens-echo-jobs.md is untouched.

That doc is also sharper than my own answer on #488 was. I said two replicas would double-run jobs; it points out the queue is an in-process channel, so they would instead each hold jobs the other cannot see — a status read or cancel routed to the wrong replica finds nothing. Quieter, and worse.

What is kept

The durability half of the contract. That clause was not the misleading part, and dropping it while fixing a different phrase would trade one gap for another — I did exactly that in my first attempt and put it back.

closes #535

One line, and it is the sentence that produced #488. `JobStore`'s contract said an implementation *"must be safe for concurrent use"*, unqualified. To a reader meeting the interface, that reads as safe across processes — and that is close to the reasoning that put a second replica on the table: a database was provisioned per lane, the interface promised concurrency safety, and nothing in the code said one process was assumed. It means goroutines inside one process. ## What this is not Not new information. `docs/sirens-echo-jobs-single-process.md` already records the process-local mutex, the absence of any SQL claiming strategy, and what a second replica would actually break. This is the code saying the same thing where a reader meets it, rather than only where a reader might go looking. I filed #535 claiming that documentation did not exist. **It does** — written at 07:56 today, and linked from the very section of `sirens-echo-jobs.md` I had quoted. I read the paragraph and not the link. The issue carries the correction, and the proposed doc split turned out to be unnecessary, so `sirens-echo-jobs.md` is untouched. That doc is also sharper than my own answer on #488 was. I said two replicas would double-run jobs; it points out the queue is an in-process channel, so they would instead each hold jobs the other cannot see — a status read or cancel routed to the wrong replica finds nothing. Quieter, and worse. ## What is kept The durability half of the contract. That clause was not the misleading part, and dropping it while fixing a different phrase would trade one gap for another — I did exactly that in my first attempt and put it back. closes #535

coilyco-ops added 1 commit

2026-08-13 15:25:31 +00:00

docs(jobs): concurrent use means goroutines, not processes

ci / image-build (pull_request) Successful in 18s

Details

ci / test (pull_request) Successful in 33s

Details

ci / publish-echo-image (pull_request) Has been skipped

Details

ci / publish-observed (pull_request) Has been skipped

Details

f321e2e278

The JobStore contract said an implementation must be safe for concurrent
use, with no qualifier. That reads as safe across processes, which is the
conclusion sirens-echo#488 was filed on: a second replica was proposed
partly because nothing in the code said the store assumes one process.

It means goroutines inside one process. The durability clause is kept,
since that half of the contract was not the misleading part.

docs/sirens-echo-jobs-single-process.md already records the mechanism and
what a second replica would break. This is the code saying the same thing
where a reader meets the interface.

closes #535

Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

coilyco-ops requested review from coilysiren

2026-08-13 15:25:31 +00:00

coilyco-ops merged commit e475202da1 into main

2026-08-13 15:26:20 +00:00

coilyco-ops referenced this pull request from a commit

2026-08-13 15:26:22 +00:00

Merge pull request 'docs(jobs): concurrent use means goroutines, not processes' (#536) from eng/concurrent-means-goroutines into main