docs(events): detail is a real envelope member now
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
This commit is contained in:
@@ -225,6 +225,24 @@ field:
|
||||
leaves the ledger alone: **"I do not know" is never read as "it is gone"**, and a resource a module
|
||||
reports missing becomes `orphaned` rather than `reverted`, because nobody asked for it to go.
|
||||
|
||||
**A third joined in Phase 15, also on an envelope:**
|
||||
|
||||
- **`detail` on an action's SUCCESS envelope** (`EVENTS.md` §F). An optional object a module may
|
||||
answer with, carried to the run log as a `step.detail` line and **never interpreted by core** —
|
||||
nothing reads a key out of it in the dispatcher, the runner or the browser. It exists because a
|
||||
module knows things about its own verb core cannot compute and had no other way to say them:
|
||||
`uo.item.grant` reaches the players a run's participation ledger holds, and *which of them missed
|
||||
out* was reported nowhere at all. On both success shapes, like `resources` and `participants`,
|
||||
because `await: 'human'` is a success and a cue's confirm finishes the step without a second
|
||||
dispatch.
|
||||
|
||||
Objects only, 4KB of serialised JSON, dropped rather than truncated, and **anything wrong with it
|
||||
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 would be a world write repeated for
|
||||
a log line. It is additive and optional: a module that never answers one is behaving exactly as
|
||||
before. **Found by writing the integration kit's chapter 5** (`EVENTS_PLAN.md` Phase 15), whose
|
||||
template made the same mistake `module-uo` had — see §F.
|
||||
|
||||
**1.9.0 — a module may ship its own message bodies and rules: `api.registerEngagementSeeds(...)`**
|
||||
(`website/ENGAGEMENT.md` Phase 11b, decision 7). One addition and no removal, so minor; a module
|
||||
written against 1.8.0 keeps working and simply seeds nothing.
|
||||
@@ -1135,6 +1153,13 @@ rather than implementation and belong here:
|
||||
rule generalises past that one pairing — an action is the near end of a call with a far end, and
|
||||
the near end has to outlive it. This is why `uo.broadcast`, whose whole safety property is that it
|
||||
is attempted once, declares 15000.
|
||||
- **A module's `detail` is carried and never read.** An optional object on either success shape,
|
||||
bounded at the dispatcher and written to the run log verbatim beside the action id. Core reads no
|
||||
key out of it — a switch on known keys anywhere in core would be core learning one module's
|
||||
vocabulary, which is the thing this whole contract exists to prevent. It is the answer to *"what
|
||||
actually happened"* for a verb whose answer is neither a resource nor a participant, and before
|
||||
Phase 15 there was no such answer: `EVENTS.md` §H named the member, `classify()` had never read
|
||||
one, and a module that used it wrote into nothing.
|
||||
- **A module reports who took part on the envelope, and there is no other door.** `participants`
|
||||
rides back from `perform()` exactly as `resources` does, on both success shapes — including
|
||||
`await: 'human'`, because a cue's confirm finishes the step without a second dispatch and that is
|
||||
|
||||
Reference in New Issue
Block a user