docs(events): detail is a real envelope member now #227

wtclaude · 2026-09-08T23:51:57Z

wtclaude commented

2026-09-08 23:51:57 +00:00

Follows the finding docs#226 recorded, which you merged while this was being written — so it is a fresh branch rather than a second commit on that one.

The finding, restated

§H told a module the revert contract accepts a detail on its envelope. classify() reads ok, retry, error, await, holdFor, resources and participants and had never read a detail. module-uo believed §H twice since Phase 12b — uo.item.grant answers { granted, missed, why } and uo.world.save answers { started: true } — and both were writing into nothing.

The grant is the one that mattered: a grant reaches the players a run's participation ledger holds, and which of them missed out is knowable only to the module, so an operator saw a step marked done and never learned four of twelve got nothing.

Fixed by making the member real, not by deleting the reporting

§H's sentence was right; only its example was wrong. website#197 carries the code; this documents it.

Where	What changed
`MODULE_API.md` §1.1, 1.10.0	`detail` as a third envelope member beside Phase 10's two — optional, on both success shapes, objects only, 4KB, dropped-and-logged rather than failing the step
`MODULE_API.md` §2.4	the contract rule: core reads no key out of it, because a switch on known keys anywhere in core would be core learning one module's vocabulary
`EVENTS.md` §F	the finding and the fix, including the half that is easy to miss — the run console's `describeLogLine` default returns a kind word, so the new line would have rendered as the literal string `step.detail`: the channel existing and showing nothing
`EVENTS.md` §H	the wipes row no longer claims `detail` is unread, and no longer spells a successful revert with one

Two rules are worth reading in §F rather than here, because they are the ones a later phase will be tempted to relax: anything wrong with a detail is dropped and logged rather than failing the step — a step that did what it was asked must not be re-run because its module's commentary was malformed, which is a world write repeated for a log line — and the failure channel is unchanged and is still error alone.

module-uo needed no change: the code it already shipped started working. MODULE_API_VERSION stays 1.10.0, amended in place — still on edge.

AI-assisted: written with Claude Code (Claude Opus 5).

🤖 Generated with Claude Code

https://claude.ai/code/session_016wDDVXWMDz82WqE1i969r4

Follows the finding docs#226 recorded, which you merged while this was being written — so it is a fresh branch rather than a second commit on that one. ## The finding, restated §H told a module the revert contract accepts a `detail` on its envelope. `classify()` reads `ok`, `retry`, `error`, `await`, `holdFor`, `resources` and `participants` and had **never** read a `detail`. `module-uo` believed §H twice since Phase 12b — `uo.item.grant` answers `{ granted, missed, why }` and `uo.world.save` answers `{ started: true }` — and both were writing into nothing. The grant is the one that mattered: a grant reaches the players a run's participation ledger holds, and **which of them missed out is knowable only to the module**, so an operator saw a step marked `done` and never learned four of twelve got nothing. ## Fixed by making the member real, not by deleting the reporting §H's sentence was right; only its example was wrong. **website#197** carries the code; this documents it. | Where | What changed | | --- | --- | | `MODULE_API.md` §1.1, 1.10.0 | `detail` as a third envelope member beside Phase 10's two — optional, on both success shapes, objects only, 4KB, dropped-and-logged rather than failing the step | | `MODULE_API.md` §2.4 | the contract rule: core reads **no key** out of it, because a switch on known keys anywhere in core would be core learning one module's vocabulary | | `EVENTS.md` §F | the finding and the fix, including the half that is easy to miss — the run console's `describeLogLine` default returns a kind *word*, so the new line would have rendered as the literal string `step.detail`: the channel existing and showing nothing | | `EVENTS.md` §H | the wipes row no longer claims `detail` is unread, and no longer spells a successful revert with one | Two rules are worth reading in §F rather than here, because they are the ones a later phase will be tempted to relax: **anything wrong with a `detail` is dropped and logged rather than failing the step** — a step that did what it was asked must not be re-run because its module's commentary was malformed, which is a world write repeated for a log line — and **the failure channel is unchanged and is still `error` alone**. **`module-uo` needed no change**: the code it already shipped started working. `MODULE_API_VERSION` stays **1.10.0, amended in place** — still on `edge`. - [x] AI-assisted: written with Claude Code (Claude Opus 5). 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_016wDDVXWMDz82WqE1i969r4

wtclaude added 1 commit 2026-09-08 23:52:00 +00:00

docs(events): detail is a real envelope member now ec55e66720

Follows the finding recorded a commit ago: §H told a module the revert contract
accepts a `detail`, `classify()` had never read one, and `module-uo` had been
answering one since Phase 12b — so `uo.item.grant`'s report of which recipients
missed out was written into nothing.

Fixed in `website#197` by making the member real rather than by deleting the
reporting, because §H's sentence was right and only its example was wrong.

  * **§1.1, 1.10.0** gains `detail` as a third envelope member beside Phase
    10's two: optional, on both SUCCESS shapes, carried and never interpreted,
    objects only, 4KB, dropped-and-logged rather than failing the step.
  * **§2.4** gains the contract rule — core reads no key out of it, because a
    switch on known keys anywhere in core would be core learning one module's
    vocabulary.
  * **EVENTS.md §F** records the fix, including the half that is easy to miss:
    the run console's `describeLogLine` default returns a kind WORD, so the new
    line would have rendered as the literal string "step.detail" — the channel
    existing and showing nothing.
  * **§H's wipes row** no longer claims `detail` is unread.

MODULE_API stays 1.10.0, amended in place — still on `edge`. The failure
channel is unchanged and is still `error` alone.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016wDDVXWMDz82WqE1i969r4

whitlocktech merged commit 8cb4cb3e01 into edge

2026-09-09 00:22:16 +00:00

whitlocktech deleted branch docs/events-module-detail

2026-09-09 00:22:17 +00:00

whitlocktech referenced this issue from a commit

2026-09-09 00:22:19 +00:00

Merge pull request 'docs(events): `detail` is a real envelope member now' (#227) from docs/events-module-detail into edge

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/docs#227

docs(events): detail is a real envelope member now #227

The finding, restated

Fixed by making the member real, not by deleting the reporting

docs(events): `detail` is a real envelope member now #227