The documentation half of Phase 11a (website#177, Module-uo#22). Three files,
each carrying one obligation from 6.0b's Phase 11a row.
**MODULE_API.md -> 1.8.0.** A seventh audience ceiling, `admin`, as a child of
`staff`. One addition, no removal, so minor -- every declaration valid under
1.7.0 is valid now and no stored value changes. 2.4's ceiling bullet now names
seven values rather than six, and says the thing a module author actually needs:
`admin` is the ONLY pair in the whole lattice with real containment, so
`permits('staff','admin')` holds and it is the only place `permits` is true
between two values below `authenticated`.
Also corrects two 2.3 rows that were stale rather than wrong: `ctx.inbox.push`
has not thrown since Phase 7, and both members now name the consumer that
actually calls them.
**modules/uo/API.md gains 5**, the full trigger catalogue -- which 6.0b asked for
in as many words ("the full trigger catalogue, its audiences and its ceilings,
not one entry"). The 24 triggers grouped by ceiling with the reason for each
ceiling; the four rows that deliberately do NOT ship with their recorded reasons;
the two that need a patch tier or a v5 overlay; the three things a rule cannot
express and are therefore done in the mapper; the three registered audiences; and
the ingest ORDERING, which is load-bearing rather than incidental.
**BACKEND_DESIGN.md -- the news publish path.** It described a direct
`pushDispatch.publish('news.post', ...)` from the create/publish-post path. That
call is gone: it is an emit through the engagement engine now, so news push rides
a rule, and core seeds that rule disabled. The note says so as an operator-visible
upgrade step, names the separate one-shot settings key and states what did NOT
change -- the announce legs and the post hooks still fire exactly as they did.
Co-Authored-By: Claude <noreply@anthropic.com>
Two corrections from the org lead on the transport rewrite.
It is an OXIDE plugin, not "a mod loaded by the server's mod framework". Oxide is
what modded Rust servers run, and naming it is the difference between a design a
reader can start from and one they have to go and pick a framework for.
And the architecture is ONE SERVER, ONE SIDECAR - not one sidecar fronting a
community's several servers, which is the arrangement a UO-shaped reading reaches
for and which this document had. Rust servers in practice sit on separate VMs, so
a shared sidecar would have to be reached across a network by plugins that are
supposed to talk to it over loopback: it trades the invariant that makes the
design safe for a saving in process count.
The cost lands on the module, which is the right place for it - it holds one
client per configured server rather than one client to an aggregator - and it
makes the Team provider's `complete` answerable rather than vague, since "every
team there is" now means every team on THIS server. Five of six sidecars
reachable is `complete` left off, and core adds and updates without archiving.
Recorded as a reevaluable assumption rather than a principle, because that is
what it is. Nothing in the contract objects either way: core is not in this
conversation at all, which finding 2 now says.
Co-Authored-By: Claude <noreply@anthropic.com>
Overruled by the org lead: RCON is not used. Rust gets the same three-part shape
UO has - a plugin inside the game that dials out, a sidecar that persists before
it forwards, a module that talks only to the sidecar - and the plugin is a mod
loaded by the server's mod framework, exposing data through hooks.
The document had RCON as its premise, so the correction reaches further than the
transport paragraph:
- The reason Rust is a good second game changes. It was "its server speaks a
protocol nobody has to write". It is now "its server is a BINARY" - the
opposite of ServUO, which is source a shard owner compiles - so the way in is
a published mod API and the shard-dials-out invariant has to survive that
change of footing. It does, unchanged, which is a stronger result than the
one the document originally claimed.
- The announce leg sends a command down the socket the mod already holds,
rather than calling rcon.say.
- The provider refuses when no mod is connected, not when RCON is unreachable.
- Two hooks answer questions UO had to work for: a wipe arrives as an event, and
membership is real-time - so this module's Team provider is event-driven with
a baseline on connect rather than sweep-driven. The provider contract does not
change by a line, which is the part worth keeping: core never needed to know
how the data arrives.
The 2026-08-12 correction block stays and a second one is added beside it rather
than editing the history out - this document's own convention, and the thing that
makes it worth reading twice. It also records what the correction COSTS: this
project no longer has a worked example of "a game that already speaks a
remote-control protocol, so its sidecar is thin".
Co-Authored-By: Claude <noreply@anthropic.com>
The kit's README sends a reader here FIRST - it is the shortest honest picture of
the whole job - and it predated Teams, so it taught a second game to build its
teams as private module data and never mentioned the provider. The two places the
contract changed since it was written are now in it, and nothing else moved:
all four findings stand, including the identity gap, which is still the one a
real second module hits first.
What Rust adds that UO does not, and why it was worth revisiting rather than
noting:
- externalId must survive a rename and a Rust team HAS no name - it is a numeric
team id in the save. The right answer, and the one a designer is least likely
to reach for.
- `complete` is per SERVER, not per community. Six servers are six team spaces,
so a provider that can reach five must leave `complete` off or core archives
every team on the sixth.
- A wipe empties every team, so { ok: true, complete: true, teams: [] } is TRUE
once a month and core archiving all of them is correct - which is exactly why
an unreachable RCON must answer { ok: false } instead. The two states are one
API call apart and only the module can tell them apart.
- The team route carries a server id as well as a team id, so the external id is
<serverId>:<teamId>. Core stores that and never parses it; an external id is
opaque to core by design, and this is the case that shows why.
Also: rust_teams stays the module's table and core's teams stays core's, which is
the boundary worth stating in the one document where both appear; and the kit is
nine members now, not seven.
Co-Authored-By: Claude <noreply@anthropic.com>
Only the Gitea release workflow carries the publishing placeholders. The report
said both flavours; the GitHub one uses GITHUB_REPOSITORY and friends and has
nothing to rename. Found while fixing it in the kit (Integration-kit#4), which is
where the single checklist row landed.
Also records what that implies about a run like this: every finding was
re-derived before being acted on, and it was not ceremony — this one was wrong in
a detail and F5 understated its problem in a way that changed the fix. A cold
agent's report is evidence, not a verdict, which is the standard the rest of the
plan already applies to a passing suite.
Separate PR because #147 was already merged; a push to a merged branch is silent.
Co-Authored-By: Claude <noreply@anthropic.com>
Slice 3 of Phase 5 (MODULE_SYSTEM.md 2.11.1), and the phase's last slice.
docs/modules/kit-acceptance.md is decision 5's deliverable: a cold agent given the
Integration Kit and the documents it links to — never core's source, never
module-uo — built a working module for a second game, which was then installed
into a real core and taken through MODULE_API.md 7.7's browser smoke. Verdict
recorded whichever way it went, and it went **yes, with caveats**: one pass, no
core source, and three of the four normative documents never opened.
The finding that justifies the two-stage shape is the one the agent structurally
could not reach, because it had no core to render against. A module page built
exactly as the kit teaches renders OUTSIDE the site: PublicLayout supplies the
chrome and not the body, and the `shell-... page-body` wrapper every core public
page writes for itself is two class names that appear in no contract. That is
3.4's own stated failure — "a module page that does not look like the site it is
installed in" — reached by following 3.4.
Fixed in core rather than documented at the reader, so the class names stay
core's private business and the theming workstream keeps its freedom to rename
them: PublicLayout takes an opt-in `shell` width, MODULE_API_VERSION 1.5.0
(website#148, merges first).
- MODULE_API.md 1.1: 1.5.0's entry, and a new bump-table row — adding an
OPTIONAL prop or argument is minor. "A member's signature changes" is major
because a call already written changes meaning, and an optional prop changes
none; the table now says what it means rather than leaving it to be argued.
- MODULE_API.md 3.4: the shell prop, why a module names a width and never a
class, and the eight-vs-seven miscount the run also turned up — the kit had
faithfully carried it out of the contract into the template, which is the
never-re-specify rule working exactly as designed on a wrong input.
- rust-dryrun.md: coreApi ^1.3.0 -> ^1.5.0, as a dated correction per decision 33.
It is the only complete module.json in the kit's reading path and nothing
checks a JSON block inside a Markdown file, which is the reusable half.
- MODULE_SYSTEM.md 2.11.1: slice 3 recorded, plus the third finding worth
generalising — a check whose failure message asserts a diagnosis has to be
right about it. `check:swagger` failed on a pristine template on Windows
(CRLF) while blaming the routes, green on the Linux runner forever.
- Decision 34: core owns the page body as well as the chrome.
The banner does not come off. Decision 32 makes that a person's to remove, this
run exercised the website-module half only (the module has no sidecar, so
chapters 3 and 4 were never tested), and an agent does not skim or give up.
Co-Authored-By: Claude <noreply@anthropic.com>
Phase 4 closed; this is the plan for Phase 5, the Integration Kit, settled with
the org lead on six decisions.
MODULE_SYSTEM.md
- §2.11.1 (new): Phase 5's shape — measured starting state, the six decisions,
the four slices, the acceptance mechanism.
- §2.11: layer 2 rewritten. The sidecar is the default and only path to a game,
and it is a non-blocking dumb forwarder that persists before it forwards. A
game that already ships a remote-control surface gets a thin sidecar, not none.
- §2.10: a MODULE_API_VERSION bump now carries a pass over the kit.
- Part 3: decisions 28–33.
- The Phase 5 line in Part 2's phase list: STARTED 2026-08-12.
MODULE_API.md
- §2.7 gains one prohibition: a module does not open a connection to a game
server from the website process — a game socket, RCON, a query port, an
engine admin API — with the three reasons it exists (the website is the
internet-facing process, the sidecar owns the durable copy, neither side can
stall the other). Normative prose with no CI behind it, stated so that every
second module does not re-decide it.
- §1.1: the 1.4.0 entry. No member changed; minor deliberately.
modules/rust-dryrun.md
- §2 "Talking to the game" rewritten from "No sidecar" to a thin RCON sidecar,
with a dated Correction note recording what the exercise originally concluded
and why it was overruled. Corrected in view rather than silently rewritten.
Pairs with website#… (the 1.4.0 bump, into edge); either order.
Co-Authored-By: Claude <noreply@anthropic.com>
Phase 4 slice 4. BACKEND_DESIGN.md had never been de-UO'd: Phase 3 rewrote core's
code and README, but §5.2's identifier check reads code, not prose, so nothing
ever looked at the design document. It still described 27 shard_* tables, 20 UO
route rows and the shard visibility ladder as core's, a phase after core stopped
being able to serve any of them.
Moved, text unchanged:
BACKEND_DESIGN §3 six shard_* schema sections (226 lines) → modules/uo/SCHEMA.md
BACKEND_DESIGN §4 13 public + 7 admin UO route rows → modules/uo/API.md
BACKEND_DESIGN §6.5 the audience ladder (70 lines) → modules/uo/API.md §4
Core keeps the seam and gains the eight /admin/modules routes it had never
documented. §6.5 becomes "Module-owned audience boundaries": core's security
boundary ends at authentication, roles and the session, and a module that serves
game data brings its own.
Also fixed on the way: users.router.js was still listed as 15 routes (it is 9 —
six went to the extension slot), and the push section still promised
config/shardStreams.js "moves out with it" four slices after it left.
The acceptance table now carries results. Criterion 2 was proved for real against
module-uo v0.3.0 on an empty database, which turned up the uninstall ordering
defect fixed in website#146.
AI disclosure: this contribution was AI-assisted (Claude Code).
Co-Authored-By: Claude <noreply@anthropic.com>
Records the slice that closes the extraction, and adds the two documents phase 3
owed: docs/modules/uo/ and the module-rust dry run.
**The slice found an obligation neither repo had built.** MODULE_API.md §2.8 and
§6.1a settle the OpenAPI fragment in detail — a module ships one, core merges the
fragments of started modules into /api/docs.json. Neither half existed, so the 72
URLs module-uo serves were in no spec at all. §2.8 and §6.1a now record what was
built, including the four things settled while building it: the filename is fixed
rather than declared, a module namespaces what it DEFINES and references core's
shared schemas by core's name, the generator derives its prefixes from the
module's own register() call, and swagger-autogen's diagnostics have to be
captured because it reports a broken annotation and then prints Success.
**§5.3 gains the design decision the frozen manifest actually made:** it is a
SUBTRACTION, not a prefix filter. Generating the manifest without the module and
then with it answers "what does the module serve" AND "did core lose anything",
and the second is the one §1.2 promises to the shipped Android app. A module that
shadowed a core route cannot appear as an addition anywhere.
**BACKEND_DESIGN.md §4.0.1** is new: /api/docs.json is assembled per request, the
two generated artifacts are core's alone, and the route count was still 228.
**docs/modules/** is new, per §2.10 (module documentation aggregates here, not in
module repos): docs/modules/uo/README.md orients a reader on what module-uo
serves, owns and needs from an operator, and links out to the feature docs that
already existed rather than restating them.
**docs/modules/rust-dryrun.md** is phase 3's fourth acceptance criterion. A
written, deliberately unimplemented module for Rust — chosen because it wipes
monthly, runs several servers rather than one shard, identifies by Steam, and
ships RCON so there is no sidecar to write. The contract generalises: same
manifest, same seven registration calls, same schema rules, and six of the UI
kit's seven members wanted by a game with nothing in common with the one the kit
was curated from.
It found one real gap — **a module cannot register an identity provider**, and
"Sign in with Steam" is what a Rust community expects. Recorded as the first
candidate for a future MODULE_API_VERSION bump rather than bolted on: an identity
provider participates in session creation, and §2.7's link-only SSO policy has to
survive it.
Also: website-README.md refreshed from the repo (it was several changes stale),
and three settled decisions added (18-20).
Pairs with Module-uo#6 and website#141.
Co-Authored-By: Claude <noreply@anthropic.com>
