docs(events): the Event System design of record and its phased plan #207

wtclaude · 2026-09-02T01:29:51Z

wtclaude commented

2026-09-02 01:29:51 +00:00

What & why

Two documents for a game-agnostic Event System — an engine for scheduled, bounded, audited changes to a live game world, driven by the staff who already run the site.

website/EVENTS.md is the design of record. It surveys what the eight repos already provide, records what they do not, and proposes the architecture: core owns the engine, a module owns the meaning, and the seam is declaration plus dispatch rather than a string core interprets.

website/EVENTS_PLAN.md is the plan of record. Seventeen phases (P0–P16): what lands in which PR, what each ships on its own merit, how each is proved, and the traps in each.

The three findings that shaped it

The differentiating feature is not the spawning. It is the tooling around it — series, recurrence, per-shard local time, participation, results, audit — none of which exists anywhere. The site→game direction this needs is modest: gates, props, NPCs, named creatures, announcements.
An event does not edit the world; it holds a lease. Baseline is what is true when no lease is held. The deadline ships to the game side, so the plugin restores baseline even if the website never comes home — a design that fails safe rather than open, which is what makes unattended scheduled world changes defensible at all. Restore is compare-and-set, so a GM's mid-event edit produces drifted rather than a silent revert of their change.
The generic half is nearly all already built — the staged registry, the ceiling lattice, the closed condition grammar, the compare-and-set outbox claim, the retry/classify leg dispatcher, the schema-driven admin form builder, and the spawn atlas, which already names every region, creature and landmark on the shard, offline.

Scope and gating

Fourteen of the seventeen phases reach the game only to announce, over verbs the write plane already carries, and need no decision beyond P0. Only P11 and P12 are gated on the ../link/ADMIN_CONTROLS.md §8 amendment.

This PR discharges the first half of P0. The decisions — N1 through N11, and the §8 amendment itself — remain, and they are the part that gates the two world-changing phases. EVENTS_PLAN.md's P0 says so in as many words rather than reading as though it were still entirely ahead of the reader.

Two documents that disagree with the code

Recorded rather than quietly resolved, per the survey's own rule:

website/ARCHITECTURE.md places the SSE fan-out inside the core backend. It is entirely module-uo's, and has been since the module-system Phase 3 cutover.
modules/rust-dryrun.md finding 4 asserts the Android app feature-detects against GET /api/v1/public/modules. It does not — ShardStreamClient.kt hardcodes api/v1/public/shard/stream, a module path, and no Kotlin source mentions capabilities.

Neither is fixed here; both are named so the fix has somewhere to start. The second is a prerequisite for P14 and the plan says so.

One operational note worth reading before P1

edge is free but stale in website, docs and module-uo — 0 commits ahead of main and several behind, because the engagement cutover merged it into main and nothing moved it afterwards. The first act of P1 is to reset each edge to its main; branching off it as it stands would silently revert the engagement retention work at the next cutover. The plan carries the two rev-list --count commands to verify this per repo.

How it was tested

Documentation only — no code, no CI in this repo. Checked mechanically:

Anchors — every in-document ](#…) link resolves against goldmark's slug algorithm (lowercase, strip punctuation, one hyphen per space). Caught one genuine break: plan: the collapses to a single hyphen, not a double.
Relative links — all seven (MODULE_API.md, MODULE_SYSTEM.md, ENGAGEMENT.md, ../link/ADMIN_CONTROLS.md, and the two files' cross-references) resolve from docs/website/.
Cross-document consistency — the 17 phase rows in EVENTS.md §M and the 17 phase headings in EVENTS_PLAN.md agree on number, order and repos-touched, verified by diff.
Code fences balanced; both mermaid blocks parse.
Ambiguity pass — bare "Phase 13"/"Phase 14" references meaning engagement's phases were qualified, now that Events has a P13 and P14 of its own.

Every codebase claim was read from the working trees on 2026-09-01 — including the ServUO checkout, where the 258 Config.Get call sites and their static readonly vs live-read split are the reason the lease catalog must be a plugin-verified allowlist rather than "any config key".

Checklist

I have read CONTRIBUTING.md.
The change builds and existing tests/checks pass locally.
I have added or updated tests/docs where it makes sense.
My commits are reasonably scoped with clear messages.

AI-assisted contributions (required)

AI tools were used. Tool(s): Claude Code (Opus 5). I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a Co-Authored-By trailer.

License

I agree that my contribution is licensed under this project's license (GNU GPL v3.0 or later), and I have the right to contribute it.

## What & why Two documents for a game-agnostic **Event System** — an engine for scheduled, bounded, audited changes to a live game world, driven by the staff who already run the site. **`website/EVENTS.md`** is the design of record. It surveys what the eight repos already provide, records what they do not, and proposes the architecture: core owns the engine, a module owns the meaning, and the seam is declaration plus dispatch rather than a string core interprets. **`website/EVENTS_PLAN.md`** is the plan of record. Seventeen phases (P0–P16): what lands in which PR, what each ships on its own merit, how each is proved, and the traps in each. ### The three findings that shaped it 1. **The differentiating feature is not the spawning.** It is the tooling around it — series, recurrence, per-shard local time, participation, results, audit — none of which exists anywhere. The site→game direction this needs is modest: gates, props, NPCs, named creatures, announcements. 2. **An event does not edit the world; it holds a *lease*.** Baseline is what is true when no lease is held. The deadline ships to the game side, so the plugin restores baseline even if the website never comes home — a design that fails *safe* rather than *open*, which is what makes unattended scheduled world changes defensible at all. Restore is compare-and-set, so a GM's mid-event edit produces `drifted` rather than a silent revert of their change. 3. **The generic half is nearly all already built** — the staged registry, the ceiling lattice, the closed condition grammar, the compare-and-set outbox claim, the retry/classify leg dispatcher, the schema-driven admin form builder, and the spawn atlas, which already names every region, creature and landmark on the shard, offline. ### Scope and gating Fourteen of the seventeen phases reach the game only to **announce**, over verbs the write plane already carries, and need no decision beyond P0. Only **P11 and P12** are gated on the `../link/ADMIN_CONTROLS.md` §8 amendment. **This PR discharges the first half of P0.** The decisions — N1 through N11, and the §8 amendment itself — remain, and they are the part that gates the two world-changing phases. `EVENTS_PLAN.md`'s P0 says so in as many words rather than reading as though it were still entirely ahead of the reader. ### Two documents that disagree with the code Recorded rather than quietly resolved, per the survey's own rule: - `website/ARCHITECTURE.md` places the SSE fan-out inside the core backend. It is entirely `module-uo`'s, and has been since the module-system Phase 3 cutover. - `modules/rust-dryrun.md` finding 4 asserts the Android app feature-detects against `GET /api/v1/public/modules`. It does not — `ShardStreamClient.kt` hardcodes `api/v1/public/shard/stream`, a module path, and no Kotlin source mentions `capabilities`. Neither is fixed here; both are named so the fix has somewhere to start. The second is a prerequisite for P14 and the plan says so. ### One operational note worth reading before P1 `edge` is **free but stale** in `website`, `docs` and `module-uo` — 0 commits ahead of `main` and several behind, because the engagement cutover merged it into `main` and nothing moved it afterwards. The first act of P1 is to **reset each `edge` to its `main`**; branching off it as it stands would silently revert the engagement retention work at the next cutover. The plan carries the two `rev-list --count` commands to verify this per repo. ## How it was tested Documentation only — no code, no CI in this repo. Checked mechanically: - **Anchors** — every in-document `](#…)` link resolves against goldmark's slug algorithm (lowercase, strip punctuation, one hyphen per space). Caught one genuine break: `plan: the` collapses to a single hyphen, not a double. - **Relative links** — all seven (`MODULE_API.md`, `MODULE_SYSTEM.md`, `ENGAGEMENT.md`, `../link/ADMIN_CONTROLS.md`, and the two files' cross-references) resolve from `docs/website/`. - **Cross-document consistency** — the 17 phase rows in `EVENTS.md` §M and the 17 phase headings in `EVENTS_PLAN.md` agree on number, order and repos-touched, verified by diff. - **Code fences** balanced; both mermaid blocks parse. - **Ambiguity pass** — bare "Phase 13"/"Phase 14" references meaning *engagement's* phases were qualified, now that Events has a P13 and P14 of its own. Every codebase claim was read from the working trees on 2026-09-01 — including the ServUO checkout, where the 258 `Config.Get` call sites and their `static readonly` vs live-read split are the reason the lease catalog must be a plugin-verified allowlist rather than "any config key". ## Checklist - [x] I have read [CONTRIBUTING.md](CONTRIBUTING.md). - [x] The change builds and existing tests/checks pass locally. - [x] I have added or updated tests/docs where it makes sense. - [x] My commits are reasonably scoped with clear messages. ## AI-assisted contributions (required) - [x] AI tools were used. Tool(s): `Claude Code (Opus 5)`. I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a `Co-Authored-By` trailer. ## License - [x] I agree that my contribution is licensed under this project's license (**GNU GPL v3.0 or later**), and I have the right to contribute it.

wtclaude added 1 commit 2026-09-02 01:29:53 +00:00

docs(events): the Event System design of record and its phased plan 0aeb54d9a0

Two documents for a game-agnostic Event System: an engine for scheduled,
bounded, audited changes to a live game world, driven by the staff who
already run the site.

EVENTS.md is the design of record. It surveys what the eight repos already
provide, records what they do not, and proposes the architecture: core owns
the engine, a module owns the meaning, and the seam is declaration plus
dispatch rather than a string core interprets. Two findings shape it. An
event does not edit the world, it holds a LEASE with a game-side deadline
and a compare-and-set restore, so baseline returns even if the website never
comes home. And a reward is an ordinary module action, optional per module,
whose reversibility is the module's business.

EVENTS_PLAN.md decides order: seventeen phases, what each ships on its own
merit, how each is proved, and the traps in each. Fourteen of them reach the
game only to announce, over verbs the write plane already carries, and need
no decision beyond P0; only P11 and P12 are gated on the ADMIN_CONTROLS.md
Section 8 amendment.

This discharges the first half of P0. The decisions -- N1 through N11, and
the Section 8 amendment itself -- remain, and they are the part that gates
the two world-changing phases.

Every codebase claim was read from the working trees on 2026-09-01. Where a
document and the code disagreed, both are recorded rather than quietly
resolved: ARCHITECTURE.md places the SSE fan-out in core when it is entirely
module-uo's, and rust-dryrun.md asserts the Android app feature-detects on
/public/modules when it hardcodes a module path instead.

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

whitlocktech merged commit cda5325ab4 into main

2026-09-02 01:32:53 +00:00

whitlocktech deleted branch docs/events-system

2026-09-02 01:32:53 +00:00

whitlocktech referenced this issue from a commit

2026-09-02 01:32:56 +00:00

Merge pull request 'docs(events): the Event System design of record and its phased plan' (#207) from docs/events-system into main

wtclaude referenced this pull request

2026-09-02 01:53:19 +00:00

docs(events): Phase 0 — the eleven decisions, and the two documents they reach into #208

Sign in to join this conversation.