docs: say that nothing binds a job to a thread #626

Merged

coilyco-ops merged 1 commit from docs/say-what-the-job-thread-does-claude into main

2026-08-13 17:29:32 +00:00

coilyco-ops commented

2026-08-13 17:28:51 +00:00

Member

Part of #620. Deliberately the lesser half, and it closes none of that issue's four items — it removes the property that made them invisible.

#620's acceptance offers two routes per item: "reachable from production, or its doc corrected to describe what the service actually does." The first needs a product call. The second needs nobody.

What the docs claimed

sirens-echo-commands.md:

job-status and job-cancel take an optional job id and fall back to the binding, so a follow-up inside the thread repeats nothing.

sirens-echo-jobs-telemetry.md:

When a thread is bound to the job, updates go there instead of the channel.

Both describe current behaviour. Neither can happen: BindJobToThread is the only writer of Origin.ThreadID and nothing calls it. The resolver and the record are built and correct; the write side was never wired.

So the id-less fallback never resolves, job updates always land in the channel, and a member following the documentation is told a command works that cannot.

Why this is worth a change on its own

Unused code shows up in a grep. Documentation promising behaviour the runtime cannot perform does not — it reads exactly like documentation of working behaviour, which is why four of these survived unnoticed. Same shape as #592.

What this does not do

The member-facing symptom is untouched. A job command inside a thread still reports no referent, and it will until someone answers whether a job gets its own thread. BindJobToThread, Origin.ThreadID, and the call graph are not touched.

ward exec gate green, and commands.md stays inside the 80-line cap — my first draft put it at 81, so the addition is trimmed rather than someone else's prose.

Part of #620. **Deliberately the lesser half**, and it closes none of that issue's four items — it removes the property that made them invisible. #620's acceptance offers two routes per item: *"reachable from production, or its doc corrected to describe what the service actually does."* The first needs a product call. **The second needs nobody.** ## What the docs claimed `sirens-echo-commands.md`: > `job-status` and `job-cancel` take an optional job id and fall back to the binding, so a follow-up inside the thread repeats nothing. `sirens-echo-jobs-telemetry.md`: > When a thread is bound to the job, updates go there instead of the channel. Both describe current behaviour. Neither can happen: **`BindJobToThread` is the only writer of `Origin.ThreadID` and nothing calls it.** The resolver and the record are built and correct; the write side was never wired. So the id-less fallback never resolves, job updates always land in the channel, and a member following the documentation is told a command works that cannot. ## Why this is worth a change on its own Unused code shows up in a grep. **Documentation promising behaviour the runtime cannot perform does not** — it reads exactly like documentation of working behaviour, which is why four of these survived unnoticed. Same shape as #592. ## What this does not do The member-facing symptom is untouched. A job command inside a thread still reports no referent, and it will until someone answers whether a job gets its own thread. `BindJobToThread`, `Origin.ThreadID`, and the call graph are not touched. `ward exec gate` green, and `commands.md` stays inside the 80-line cap — my first draft put it at 81, so the addition is trimmed rather than someone else's prose.

coilyco-ops added 1 commit

2026-08-13 17:28:51 +00:00

docs: say that nothing binds a job to a thread

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

Details

ci / test (pull_request) Successful in 37s

Details

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

Details

ci / publish-observed (pull_request) Has been skipped

Details

7e624659d1

Two documents describe a job bound to its thread as current behaviour. The
resolver and the record exist and are correct, but BindJobToThread is the only
writer of Origin.ThreadID and no production path calls it. So the id-less
fallback never resolves, job updates always land in the channel, and a member
following the documentation is told a command works that cannot.

Documentation that promises more than the runtime does is the failure this
sweep found hardest to see, because unlike unused code it does not show up in
a grep.

This deliberately does not wire anything. Whether a job gets a thread of its
own is a product question and it stays open. What changes is that a reader is
no longer told it already happens.

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

coilyco-ops requested review from coilysiren

2026-08-13 17:28:51 +00:00

coilyco-ops merged commit 78df02a525 into main

2026-08-13 17:29:32 +00:00

coilyco-ops referenced this pull request from a commit

2026-08-13 17:29:33 +00:00

Merge pull request 'docs: say that nothing binds a job to a thread' (#626) from docs/say-what-the-job-thread-does-claude into main