test(threads): the honest doc is the one nothing was keeping honest #641

Merged

coilyco-ops merged 1 commit from qa/pin-the-unwired-thread-binding into main

2026-08-13 17:43:41 +00:00

coilyco-ops commented

2026-08-13 17:42:03 +00:00

Member

#620 reports that documentation describes a job-thread binding the runtime never performs. The defect is real — BindJobToThread is the only writer of Origin.ThreadID and has no production caller, so jobstore.go:127 scans a field nothing sets and a member using a job command inside its own thread can never be resolved.

But threads.md is not the document at fault. Under a heading called "What is not here":

BindJobToThread and ResolveThreadJob exist and are still unwired, which is a separate piece of work.

That is true, and it is the only place that says so. commands.md has a Thread binding section describing the semantics in present tense, and jobs-telemetry.md implies it. The two disagree and the more detailed one is wrong.

So this pins the accurate one.

What it asserts

That BindJobToThread having no production caller, and threads.md saying so, stay true together — in both directions:

a production caller appears, doc unchanged    fails, and names commands.md
the doc stops saying unwired, still unwired   fails, the honest text is gone

Mutation checked both ways

wire the writer:
  BindJobToThread now has a production caller and docs/sirens-echo-threads.md
  still says it is unwired. Update that doc, and update the Thread binding
  section of docs/sirens-echo-commands.md, which already describes this as
  shipped.

remove the sentence:
  BindJobToThread has no production caller and docs/sirens-echo-threads.md no
  longer says so, so the only honest description of this feature is gone.

The first message is the point. Whoever wires this feature is told about the second document that is already wrong, at the moment they can fix it, rather than discovering it from a member.

Why a doc comment does not count as a caller

productionCallers skips the declaration and any line beginning //. That is the trap #618 records — its first census counted doc comments and missed StaffPosture entirely, and I hit the same one earlier today counting evaluation checks and published a false zero.

Deliberately not in this PR

Correcting commands.md. A doc that promises a behaviour is a product statement, and changing what it promises is not a test change. This is the half that keeps the accurate description accurate; the inaccurate one needs an owner.

Test-only. No production change.

Refs #620

https://forgejo.coilysiren.me/coilyco-gaming/sirens-echo/issues/620 reports that documentation describes a job-thread binding the runtime never performs. **The defect is real** — `BindJobToThread` is the only writer of `Origin.ThreadID` and has no production caller, so `jobstore.go:127` scans a field nothing sets and a member using a job command inside its own thread can never be resolved. **But `threads.md` is not the document at fault.** Under a heading called *"What is not here"*: > `BindJobToThread` and `ResolveThreadJob` exist and are **still unwired**, which is a separate piece of work. That is true, and it is the only place that says so. `commands.md` has a Thread binding section describing the semantics in present tense, and `jobs-telemetry.md` implies it. **The two disagree and the more detailed one is wrong.** So this pins the accurate one. ## What it asserts That `BindJobToThread` having no production caller, and `threads.md` saying so, stay true **together** — in both directions: ``` a production caller appears, doc unchanged fails, and names commands.md the doc stops saying unwired, still unwired fails, the honest text is gone ``` ## Mutation checked both ways ``` wire the writer: BindJobToThread now has a production caller and docs/sirens-echo-threads.md still says it is unwired. Update that doc, and update the Thread binding section of docs/sirens-echo-commands.md, which already describes this as shipped. remove the sentence: BindJobToThread has no production caller and docs/sirens-echo-threads.md no longer says so, so the only honest description of this feature is gone. ``` The first message is the point. **Whoever wires this feature is told about the second document that is already wrong**, at the moment they can fix it, rather than discovering it from a member. ## Why a doc comment does not count as a caller `productionCallers` skips the declaration and any line beginning `//`. That is the trap #618 records — its first census counted doc comments and missed `StaffPosture` entirely, and I hit the same one earlier today counting evaluation checks and published a false zero. ## Deliberately not in this PR **Correcting `commands.md`.** A doc that promises a behaviour is a product statement, and changing what it promises is not a test change. This is the half that keeps the accurate description accurate; the inaccurate one needs an owner. Test-only. No production change. Refs https://forgejo.coilysiren.me/coilyco-gaming/sirens-echo/issues/620

coilyco-ops added 1 commit

2026-08-13 17:42:03 +00:00

test(threads): the honest doc is the one nothing was keeping honest

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

Details

ci / test (pull_request) Successful in 38s

Details

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

Details

ci / publish-observed (pull_request) Has been skipped

Details

c11df60e0a

sirens-echo#620 reports that docs describe a job-thread binding the runtime
never performs. The defect is real: BindJobToThread is the only writer of
Origin.ThreadID and has no production caller, so jobstore.go:127 scans a field
nothing sets and commanddiscord.go can never resolve a job from its thread.

But threads.md is not the document at fault. Under a heading called "What is
not here" it says both functions are still unwired, which is true and is the
only place that says so. commands.md has a Thread binding section describing
the semantics in present tense, and jobs-telemetry.md implies it. The two
disagree and the more detailed one is wrong.

So this pins the accurate one. It asserts that BindJobToThread having no
production caller and threads.md saying so stay true together, in both
directions:

  a production caller appears, doc unchanged   fails, and names commands.md
  the doc stops saying unwired, still unwired  fails, the honest text is gone

Mutation checked both ways. Wiring the writer produces the first message
including the pointer to the second doc, so whoever lands the feature is told
about the section that is already wrong rather than discovering it later.

Deliberately not editing commands.md here. Correcting a doc that promises a
behaviour is a product change, and this is the test half.

Refs sirens-echo#620

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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:42:03 +00:00

coilyco-ops merged commit a7ac90f4e9 into main

2026-08-13 17:43:41 +00:00

coilyco-ops referenced this pull request from a commit

2026-08-13 17:43:42 +00:00

Merge pull request 'test(threads): the honest doc is the one nothing was keeping honest' (#641) from qa/pin-the-unwired-thread-binding into main

coilyco-ops referenced this pull request

2026-08-13 17:46:10 +00:00

Seventeen exported functions have no production caller, and the interesting ones are not the obvious ones #618

coilyco-ops referenced this pull request from a commit

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