Files
docs/modules
wtclaude dbc0455490 docs(modules): a second contract pass over MODULE_API.md, member by member
Section 7 audited the plan against the Integration Kit and the template. This
pass reads MODULE_API.md itself and enumerates every member rather than grepping
for registration names. It found one regression, one mispriced decision, one
missing declaration, and a set of ctx members the plan had never mentioned.

THE REGRESSION. ctx.events.reconcile() and an action's reconcile() appear
nowhere in the document. The twelve-phase first draft had them - phase 6,
reconcile and the boot-id watch - and the rewrite to twenty phases lost them.
That is a regression in the plan, not a decision. It matters MORE for Rust than
for the game the contract was written against: the kit rates reconcile the one
omission that is merely a lower standard rather than a broken promise, but that
assumes a world which persists. Rust wipes monthly and a wipe invalidates every
ledgered resource for that server at once, and core cannot tell a wedged sidecar
from a game that rebooted and lost everything - it sees ok:false retry:true
either way. It asks once at its own boot and otherwise waits to be told.
ctx.events.reconcile() is being told, and the trigger is a watch on the game's
boot id changing, which is also the only way to tell a game restart from a
sidecar reconnect. Restored to phase 13.

R9 WAS MISPRICED. It says the map's per-layer switches work through the existing
visibility framework, which reads as reuse. It is not reuse: section 6.3 records
shardVisibility as module-owned, and the tree confirms it - the util, both
models, the admin controller and its tests all live under module-uo/server/ and
there is nothing by that name left in website/server. Section 2.7 forbids a
module requiring outside its own directory, so module-rust cannot import a line
of it and builds its own. Not a reason to change the decision; phase 14 now
carries a visibility layer of its own rather than a configuration of somebody
else's.

A MISSING DECLARATION. R13 claims two extension slots and never says where they
are declared. module.json has an extensions array and the dry run's own manifest
carried it. Like mounts it is a statement of surface the loader holds against
reality, so phase 1 adds it.

THE CTX MEMBERS. ctx has 29 members and the plan named a handful. The ones that
change work: secretBox, because each configured server's sidecar token is a
secret at rest and core already has the posture for it; middleware.rateLimit,
which is the mechanism R1 asked for without naming; uploads, which is where R9's
map image actually lands - the plan described fetching it and never said where
it goes; activity.log, which both R2 and R18 owe an audit trail to; the three
ctx.teams calls, since Teams is more than the provider; ctx.posts behind the
announce leg and post hook; and the three send paths section 10's catalogue
implies.

Also records section 6.8, a constraint on phase 10 and on purge: a trigger, a
rule and an audience outlive the module that declared them.
engagement_rules.trigger_id is a plain VARCHAR with no foreign key and no
cascade, so a module can be removed and reinstalled without destroying an
operator's rules - and a rule whose trigger or audience is unregistered shows
DORMANT, never an error and never auto-deleted. An audience resolving to the
empty set is not the same answer as resolved to nobody and must not be rendered
as if it were. The failure that prevents is exact: an id that stops resolving
must never silently become a send to a different set of people.

And the two client lists in full, since section 7 said UI kit discipline without
saying what is in it; plus one confirmation for R10, that
/api/v1/public/modules returns only started modules with no state and no failure
reason, so a Rust module that failed to boot makes the app render a site without
those screens rather than one advertising screens that 503.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016wDDVXWMDz82WqE1i969r4
2026-09-15 12:46:36 -05:00
..