docs(website): settle the module loader's trigger and its collision check #127

wtclaude · 2026-08-10T19:37:04Z

wtclaude commented

2026-08-10 19:37:04 +00:00

The docs half of RunicGateway/website#129 (phase 2, PR 2 — the module loader). Records what the implementation decided against the two things MODULE_API.md explicitly left open for Phase 2.

§7.6 → settled: an explicit load(). app.js calls modules.load(tierRouters) once, and the accessors throw until it has run. A require-time scan was the stated alternative and was rejected for two reasons worth keeping: the loader needs the tier routers handed to it for the §4.3 check, which a require-time side effect cannot receive; and it would enforce the ordering constraint by where a require sits rather than by an argument that is missing when it is wrong.

§4.1 and §4.3 gain the mechanics that fall out — where the call must sit in app.js and why in both directions (after /api so core's prefixes are on the tier routers and first-match-wins protects them; before the /api 404 so a module route reaches its handler), that mounting is a second pass after validation, and that core's prefix ownership is probed on the live tier routers with express's layer.match() instead of a declared table that was already stale in the spike.

§2.7 records PR 2 as done, with what it deliberately does not contain.

No contract member changed, so MODULE_API_VERSION stays 1.0.0.

AI-assisted: written with Claude Code (Opus 5), reviewed before opening.

The docs half of RunicGateway/website#129 (phase 2, PR 2 — the module loader). Records what the implementation decided against the two things `MODULE_API.md` explicitly left open for Phase 2. **§7.6 → settled: an explicit `load()`.** `app.js` calls `modules.load(tierRouters)` once, and the accessors throw until it has run. A require-time scan was the stated alternative and was rejected for two reasons worth keeping: the loader needs the tier routers *handed to it* for the §4.3 check, which a require-time side effect cannot receive; and it would enforce the ordering constraint by where a `require` sits rather than by an argument that is missing when it is wrong. **§4.1 and §4.3** gain the mechanics that fall out — where the call must sit in `app.js` and why in both directions (after `/api` so core's prefixes are on the tier routers and first-match-wins protects them; before the `/api` 404 so a module route reaches its handler), that mounting is a **second pass** after validation, and that core's prefix ownership is probed on the live tier routers with express's `layer.match()` instead of a declared table that was already stale in the spike. **§2.7** records PR 2 as done, with what it deliberately does not contain. No contract member changed, so `MODULE_API_VERSION` stays `1.0.0`. --- - [x] AI-assisted: written with Claude Code (Opus 5), reviewed before opening.

wtclaude added 1 commit 2026-08-10 19:37:06 +00:00

docs(website): settle the module loader's trigger and its collision check 9355f2aec4

Records what phase 2 PR 2 decided against the two things MODULE_API.md
left open for it.

7.6 is settled as an explicit modules.load(tierRouters) call in app.js
rather than a require-time scan: the loader needs the tier routers handed
to it for the 4.3 check, which a require-time side effect cannot receive,
and a require's position enforces an ordering constraint invisibly.

4.1 and 4.3 gain the mechanics that fall out -- where the call must sit
in app.js and why in both directions, that mounting is a second pass
after validation, and that core's prefix ownership is probed on the live
tier routers with express's layer.match() rather than declared in a table
that was already stale in the spike.

2.7 records PR 2 as done.

Co-Authored-By: Claude <noreply@anthropic.com>

whitlocktech merged commit 510d10b297 into main

2026-08-10 21:30:54 +00:00

whitlocktech deleted branch docs/module-loader

2026-08-10 21:30:55 +00:00

whitlocktech referenced this issue from a commit

2026-08-10 21:30:56 +00:00

Merge pull request 'docs(website): settle the module loader's trigger and its collision check' (#127) from docs/module-loader into main

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/docs#127