The attribution and grants docs describe three capabilities nothing calls, in the present tense #657

New issue

Closed

opened 2026-08-13 18:04:40 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

2026-08-13 18:04:40 +00:00

Member

Filed by Angie (ENG, claude seat) as the doc slice of #620, so a doc correction does not close a question about whether to build the thing.

620 asks for each of four capabilities to be either reachable from production or have its doc corrected. Wiring them carries decisions. Correcting the docs does not, and the docs are wrong now.

Two of the four are already handled

docs/sirens-echo-commands.md was corrected while I was working on it — the Thread binding section now ends with "Nothing binds a job to a thread today" and cites 620. docs/sirens-echo-jobs-telemetry.md likewise says "No production path binds one today". Neither needs anything.

docs/sirens-echo-threads.md was never wrong. I named it on 620 and @Quail corrected me: it already says both functions are "still unwired" under a heading called "What is not here". Editing it would make it worse.

The two that remain

docs/sirens-echo-attribution.md, under "What is attributable":

Any job. AttributeJob returns the requester from the record.

Any effect. AttributeEffects resolves a job's applied effects to the principal that caused them...

Present tense, and nothing calls either. AttributeEffects is worse than uncalled: it reads job.Effects, and the only writer is RecordEffect at jobsubmit.go:86, which nothing calls either. The map is empty for every job that has ever run, so the doc describes a join over data the runtime never records.

docs/sirens-echo-grants.md:

GrantedKinds also lists what a principal holds, so they can be told rather than discovering it by being refused.

No surface calls it, so today they discover it by being refused. The sentence describes the fix for a problem the service still has.

Verified rather than inherited

I re-derived all four call graphs before editing, because I got the citation wrong on 620 by reaching for the doc whose title matched instead of the doc that described the behaviour:

BindJobToThread   jobthread.go:13    declaration only
AttributeEffects  attribution.go:24  declaration only
AttributeJob      attribution.go:48  declaration only
GrantedKinds      grants.go:101      declaration only

Change

Three sentences. Each names what does not happen, keeps the intended shape, and points at 620. AttributeJob is marked as wiring rather than new data, because Principal is already on the record — that distinction is the difference between a small task and a design question, and a reader deciding what to pick up needs it.

Acceptance

No document in docs/ describes these three as current behaviour. 620 stays open with all four capabilities still unwired.

**Filed by Angie (ENG, claude seat) as the doc slice of https://forgejo.coilysiren.me/coilyco-gaming/sirens-echo/issues/620**, so a doc correction does not close a question about whether to build the thing. 620 asks for each of four capabilities to be *either* reachable from production *or* have its doc corrected. Wiring them carries decisions. Correcting the docs does not, and the docs are wrong now. ## Two of the four are already handled **`docs/sirens-echo-commands.md`** was corrected while I was working on it — the Thread binding section now ends with *"Nothing binds a job to a thread today"* and cites 620. **`docs/sirens-echo-jobs-telemetry.md`** likewise says *"No production path binds one today"*. Neither needs anything. **`docs/sirens-echo-threads.md`** was never wrong. I named it on 620 and @Quail corrected me: it already says both functions are *"still unwired"* under a heading called **"What is not here"**. Editing it would make it worse. ## The two that remain **`docs/sirens-echo-attribution.md`**, under *"What is attributable"*: > * **Any job.** `AttributeJob` returns the requester from the record. > * **Any effect.** `AttributeEffects` resolves a job's applied effects to the principal that caused them... Present tense, and nothing calls either. `AttributeEffects` is worse than uncalled: it reads `job.Effects`, and the only writer is `RecordEffect` at `jobsubmit.go:86`, which nothing calls either. **The map is empty for every job that has ever run**, so the doc describes a join over data the runtime never records. **`docs/sirens-echo-grants.md`**: > `GrantedKinds` also lists what a principal holds, so they can be told rather than discovering it by being refused. No surface calls it, so today they discover it by being refused. The sentence describes the fix for a problem the service still has. ## Verified rather than inherited I re-derived all four call graphs before editing, because I got the citation wrong on 620 by reaching for the doc whose title matched instead of the doc that described the behaviour: ``` BindJobToThread jobthread.go:13 declaration only AttributeEffects attribution.go:24 declaration only AttributeJob attribution.go:48 declaration only GrantedKinds grants.go:101 declaration only ``` ## Change Three sentences. Each names what does not happen, keeps the intended shape, and points at 620. **`AttributeJob` is marked as wiring rather than new data**, because `Principal` is already on the record — that distinction is the difference between a small task and a design question, and a reader deciding what to pick up needs it. ## Acceptance No document in `docs/` describes these three as current behaviour. 620 stays open with all four capabilities still unwired.

coilyco-ops referenced this issue from a pull request that will close it,

2026-08-13 18:05:47 +00:00

docs(attribution,grants): three capabilities described in the present tense that nothing calls #658

coilyco-ops referenced this issue

2026-08-13 18:06:06 +00:00

Four documented capabilities have no production caller, and one of them makes a shipped Discord command unable to succeed #620

coilyco-ops closed this issue

2026-08-13 18:07:30 +00:00

coilyco-ops referenced this issue

2026-08-18 20:39:11 +00:00

Epic: August 19 Temporal Vibe Check demo readiness, the work that is on camera #981

coilyco-ops referenced this issue