feat: the module skeleton and every bundle seam

module-rust, id 'rust', built from the Integration Kit's template. Phase 1's job
is the kit's own argument: get every seam working at once with almost nothing in
them, so that afterwards you break exactly one at a time.

What is here:

* /rust on all three tiers, because the loader holds module.json's mounts against
  what is registered in BOTH directions -- so the declaration and the
  registration land together or not at all. The player tier is honestly thin: it
  answers the server list on the authenticated tier, delegating to the same model
  the public tier uses so the two cannot drift while they are meant to be the
  same. It is the address the app will call, registered now rather than moved
  later.
* Two tables. rust_servers is configuration an operator writes; rust_server_state
  is what a sidecar reported. Separate tables because they have different
  writers, lifetimes and audiences -- and because purging observed state while
  keeping the configuration is a thing an operator will want.
* Per-server sidecar tokens through ctx.secretBox, write-only in the API. The
  admin list reports hasToken and never the credential, and an empty token on a
  save leaves the stored one alone -- a form that posts its own blank field would
  otherwise erase a credential every time somebody renamed a server.
* A real sidecar client. It never throws: every call answers {ok, status, data},
  and the status is what tells a wrong URL from a wrong token from a mismatched
  protocol -- all three present as 'the site says my server is offline' and each
  has a different fix.
* The five guards, green: check:imports, check:swagger, check:externals, and both
  suites.

What is deliberately NOT registered: the Team provider, triggers, audiences,
engagement seeds, notification streams, the four event catalogues, and the two
extension slots. Each arrives with the phase that has something real to put in
it, and a test asserts their absence so that removing it is deliberate. A
declared trigger nothing emits and a declared slot nothing fills are both
surfaces an operator can configure and then wait on, which is worse than an
absent one because the absence is visible.

Two corrections to the kit's template, both feedback for a later phase:

* registration.test.js read one page BY NAME to check declared slots are
  rendered, so a module declaring none dies on ENOENT before reaching the loop
  that would have been empty. It now scans every file under src/routes.
* test/_fakes.js supplied validator: {}. An admin router that builds validation
  chains at file scope cannot be required with that, so the fake holds the real
  express-validator -- for the same reason it holds a real express Router.

The kit was right about noGameConnection.test.js: its header predicts that a
module adding a sidecar client will see the check go red, names sidecarClient.js
as the file to allow, and says narrow it rather than delete it. That is exactly
what happened on the first run, and the fix was the one line the header names.

Installed into a real core and verified: the module reaches 'started', publishes
its capability, serves its chunk, and renders a server whose server.hello
originated in a live Rust server.

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

server/scripts/checkImports.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+// ── §5.1 — zero internal imports ───────────────────────────────────────────
+//
+// The acceptance test for the whole module contract. A module that reaches into
+// core's tree still works — right up until core moves a file — and the boundary
+// this workstream exists to build is worth exactly as much as this check is.
+//
+// MODULE_API.md §5.1 sketches it as a grep for `../../`. That is the shape of
+// the violation but not the rule, and the difference matters in both directions:
+// a grep says nothing about `require('../../../../etc/passwd')` from a deeply
+// nested file (which it catches by accident) and false-alarms on a legitimate
+// `require('../module.json')` from `server/` (which it catches wrongly). So this
+// RESOLVES each specifier against the file that wrote it and asks whether the
+// result is still inside the module root — the actual rule, stated once.
+//
+// Bare specifiers are checked too, and against a stricter list than "is it
+// installed": core hands the module express, express-validator, the database and
+// the logger on `ctx` precisely so the module never resolves them, and Node's
+// resolver cannot reach core's `node_modules` from here anyway. A bare
+// `require` that is not a Node builtin is therefore a module that will fail to
+// load on a real install, with a message about a missing package rather than
+// about the rule it broke.
+//
+// **That second check applies to SHIPPED code only.** `test/` and `scripts/`
+// never run inside core's process — the fakes in `test/_fakes.js` build a real
+// `express` router precisely so the module's routers are exercised for real —
+// so they may use devDependencies. The containment check applies everywhere,
+// because a test that reaches into core's tree is a test that passes on this
+// machine and nowhere else.
+//
+// Run over the SERVER half. The client half's equivalents are its Vite build,
+// which fails if a shared dependency resolves into node_modules, and
+// client/scripts/checkExternals.js, which asks the built chunk whether any bare
+// specifier survived.
+
+const fs = require('fs')
+const path = require('path')
+// Node's own answer, not a list reconstructed from `builtinModules`. That list
+// omits `test` on Node 20 and includes it on Node 24, so a suite that requires
+// `node:test` passed locally and failed in CI on the very first run — reported
+// as the module boundary being broken, which it was not. `isBuiltin` is the
+// authoritative check and handles the `node:` prefix itself.
+const { isBuiltin } = require('module')
+
+const MODULE_ROOT = path.resolve(__dirname, '..', '..')
+const SERVER_ROOT = path.join(MODULE_ROOT, 'server')
+
+// Packages the SHIPPED half may resolve for itself: this package's declared
+// `dependencies`, and nothing else. Read from package.json rather than listed
+// here, so adding one is a visible, reviewable edit to the manifest that also
+// changes what CI installs and what the release tarball carries.
+//
+// Adding a dependency is a real decision. §2.7 permits a module its own, and the
+// release tarball carries `server/node_modules` because an operator never builds
+// — so every entry is weight in the artifact and a package the operator's
+// deployment now runs. Anything core already owns must come from `ctx` instead:
+// a second express is a second Router prototype, a second express-rate-limit is
+// a second store, and a limit enforced by two independent counters is not the
+// limit either of them states.
+
+const SKIP_DIRS = new Set(['node_modules', 'coverage', '.git'])
+
+// Directories whose contents never run inside core's process, and may therefore
+// resolve this package's devDependencies.
+const NOT_SHIPPED = [path.join(SERVER_ROOT, 'test'), path.join(SERVER_ROOT, 'scripts')]
+const isShipped = (file) => !NOT_SHIPPED.some((d) => file.startsWith(d + path.sep))
+
+const manifest = JSON.parse(fs.readFileSync(path.join(SERVER_ROOT, 'package.json'), 'utf8'))
+const dependencies = new Set(Object.keys(manifest.dependencies || {}))
+const devDependencies = new Set(Object.keys(manifest.devDependencies || {}))
+
+// `require('x')`, `from 'x'`, `import('x')`. Deliberately textual: parsing would
+// need a dependency, and a specifier this pattern misses is a specifier written
+// to be missed, which review catches and a stricter regexp would not.
+const SPECIFIER = /(?:require\(|from\s+|import\()\s*['"]([^'"]+)['"]/g
+
+/**
+ * Blank out comments and template literals before scanning.
+ *
+ * Not a nicety — without it this file fails on ITSELF, because the comments
+ * above name `require('../../../../etc/passwd')` as an example of what to
+ * catch, and index.js explains in prose why it must never `require('express')`.
+ * A boundary check that cannot survive being described is a check people stop
+ * writing comments around.
+ *
+ * A character walk rather than a regexp, because the two get in each other's
+ * way: `'https://x'` contains a line-comment opener inside a string, and
+ * `// don't` contains a quote inside a comment. Tracking the state is shorter
+ * than the regexp that would almost handle it. Content is replaced with spaces
+ * rather than removed so nothing else has to care.
+ */
+function stripCommentsAndTemplates(src) {
+  let out = ''
+  let i = 0
+  const keep = (n) => { out += src.slice(i, i + n); i += n }
+  const blank = (end) => { out += src.slice(i, end).replace(/[^\n]/g, ' '); i = end }
+  while (i < src.length) {
+    const two = src.slice(i, i + 2)
+    if (two === '//') {
+      const nl = src.indexOf('\n', i)
+      blank(nl === -1 ? src.length : nl)
+    } else if (two === '/*') {
+      const end = src.indexOf('*/', i + 2)
+      blank(end === -1 ? src.length : end + 2)
+    } else if (src[i] === '"' || src[i] === "'") {
+      // Strings are KEPT — they are where the specifiers live.
+      const quote = src[i]
+      keep(1)
+      while (i < src.length && src[i] !== quote) keep(src[i] === '\\' ? 2 : 1)
+      keep(1)
+    } else if (src[i] === '`') {
+      // Template literals are blanked: nothing may `require` a template, and a
+      // template holding SQL or HTML is a rich source of false positives.
+      i += 1
+      out += ' '
+      while (i < src.length && src[i] !== '`') {
+        if (src[i] === '\\') { out += '  '; i += 2 } else { out += src[i] === '\n' ? '\n' : ' '; i += 1 }
+      }
+      i += 1
+      out += ' '
+    } else {
+      keep(1)
+    }
+  }
+  return out
+}
+
+function* walk(dir) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (!SKIP_DIRS.has(entry.name)) yield* walk(path.join(dir, entry.name))
+    } else if (/\.(js|mjs|cjs)$/.test(entry.name)) {
+      yield path.join(dir, entry.name)
+    }
+  }
+}
+
+/**
+ * Every boundary violation under `root`, resolved against `moduleRoot`.
+ *
+ * Exported so `test/checkImports.test.js` can point it at fixtures. A check that
+ * has never been shown to fail is a check nobody knows the state of — and this
+ * one guards the acceptance criterion for the whole contract.
+ */
+function scan(root, moduleRoot = MODULE_ROOT, { shipped = isShipped, deps = dependencies, dev = devDependencies } = {}) {
+  const violations = []
+  for (const file of walk(root)) {
+    const source = stripCommentsAndTemplates(fs.readFileSync(file, 'utf8'))
+    for (const [, specifier] of source.matchAll(SPECIFIER)) {
+      if (specifier.startsWith('.')) {
+        const resolved = path.resolve(path.dirname(file), specifier)
+        if (resolved !== moduleRoot && !resolved.startsWith(moduleRoot + path.sep)) {
+          violations.push({ file, specifier, why: 'escapes the module root' })
+        }
+      } else if (path.isAbsolute(specifier)) {
+        violations.push({ file, specifier, why: 'absolute path' })
+      } else {
+        const pkg = specifier.startsWith('@')
+          ? specifier.split('/').slice(0, 2).join('/')
+          : specifier.split('/')[0]
+        const allowed = deps.has(pkg) || (!shipped(file) && dev.has(pkg))
+        // The `node:` prefix can only ever name a builtin, so it never reaches
+        // node_modules and is safe whatever this Node version enumerates.
+        const builtin = isBuiltin(specifier) || specifier.startsWith('node:')
+        if (!builtin && !allowed) {
+          violations.push({ file, specifier, why: 'undeclared bare specifier — should this come from ctx?' })
+        }
+      }
+    }
+  }
+  return violations
+}
+
+module.exports = { scan, stripCommentsAndTemplates, SERVER_ROOT, MODULE_ROOT }
+
+// Required by a test, or run as the check? Only the second one exits.
+if (require.main !== module) return
+
+const violations = scan(SERVER_ROOT)
+
+if (violations.length) {
+  console.error(`\n${violations.length} import(s) break the module boundary (MODULE_API.md §5.1):\n`)
+  for (const v of violations) {
+    console.error(`  ${path.relative(MODULE_ROOT, v.file)}\n    "${v.specifier}" — ${v.why}`)
+  }
+  console.error('')
+  process.exit(1)
+}
+
+console.log(`OK — no import escapes the module root (${SERVER_ROOT}).`)

server/scripts/swaggerFragment.js

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+// ── §2.8 — the OpenAPI fragment ───────────────────────────────────────────
+//
+// Generates (or checks) `swagger-fragment.json` in the bundle root: the paths,
+// tags and schemas describing every route this module registers. Core merges the
+// fragments of *started* modules over its own committed spec at request time and
+// serves the result at `/api/docs.json` (MODULE_API.md §6.1a).
+//
+// ── Why a module has to ship this at all ──────────────────────────────────
+//
+// Core's own spec generation is STATIC analysis — swagger-autogen parses core's
+// `app.js` as text and follows the literal `app.use(...)` chain. Your module
+// arrives on a volume after core was built, is required by a filesystem loop, and
+// mounts through `api.registerRoutes()`. There is no literal mount for a parser to
+// follow, and core does not have your sources anyway. So nothing core can run
+// will ever describe your routes.
+//
+// The failure mode is the dangerous one: swagger-autogen reports success and
+// emits a spec with the routes simply absent. It happened twice inside core
+// before anyone noticed, and once to the first module — 417 annotations that
+// generated nothing at all, for two phases, because nobody had built the
+// fragment. If you take one thing from this file, take that a green build is not
+// evidence that anything was described.
+//
+// ── Where the prefixes come from ──────────────────────────────────────────
+//
+// swagger-autogen is pointed at one router file at a time, so its paths come out
+// relative to that router (`/status`, not `/api/v1/public/world/status`) —
+// nothing in the file says where it hangs. §6.1a requires fully-qualified paths,
+// because core merges the fragment verbatim and never re-derives a prefix.
+//
+// So this script **runs your own `register()`** against a recording `api` and
+// reads the mounts back out. Every prefix is therefore the prefix that router is
+// actually registered under — the same call an operator's core will make, rather
+// than a table beside it that drifts the first time a mount moves. Which file a
+// recorded router object came from is answered by `require.cache`: the module
+// whose `exports` IS that router.
+//
+// The tier base paths are the one thing that cannot be derived here, because they
+// are core's and not yours. They are §2.4's normative table, quoted below.
+
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+
+const swaggerAutogen = require('swagger-autogen')({ openapi: '3.0.0' })
+
+const { fakeCtx, fakeApi } = require('../test/_fakes')
+const doc = require('../swagger/doc')
+
+const MODULE_ROOT = path.resolve(__dirname, '..', '..')
+const SERVER_ROOT = path.join(MODULE_ROOT, 'server')
+const FRAGMENT = path.join(MODULE_ROOT, 'swagger-fragment.json')
+
+// MODULE_API.md §2.4. A router registered under a tier sits inside that tier's
+// router in core, behind its gate; the base path is core's and fixed.
+const TIER_BASE = {
+  public: '/api/v1/public',
+  admin: '/api/v1/admin',
+  player: '/api/v1/player',
+}
+
+/**
+ * Run `register()` with a recording api and return `[{ file, prefix, what }]`.
+ *
+ * The ctx is the test fakes' — the same one the suite proves the module runs
+ * against — because registration must not touch a database (§2.2), and this
+ * script is exactly the kind of no-database caller that rule exists for.
+ */
+function mountedRouters() {
+  const register = require('../index')
+  const api = fakeApi()
+  register(fakeCtx(), api)
+
+  const fileOf = (router) => {
+    for (const mod of Object.values(require.cache)) {
+      if (mod && mod.exports === router) return mod.filename
+    }
+    return null
+  }
+
+  const mounts = []
+  for (const [tier, byPrefix] of Object.entries(api.record.routes || {})) {
+    const base = TIER_BASE[tier]
+    if (!base) throw new Error(`swagger: registered under unknown tier "${tier}" — §2.4 has three`)
+    for (const [prefix, router] of Object.entries(byPrefix)) {
+      mounts.push({ router, prefix: base + prefix, what: `${tier}${prefix}` })
+    }
+  }
+
+  return mounts.map(({ router, prefix, what }) => {
+    const file = fileOf(router)
+    if (!file) {
+      // A router built inline in index.js rather than required from its own
+      // file. swagger-autogen needs a file to read, so there is nothing to
+      // generate from — put the router in its own module.
+      throw new Error(`swagger: cannot find the source file of the router for ${what}`)
+    }
+    return { file, prefix, what }
+  })
+}
+
+/**
+ * Run swagger-autogen over one router file. Paths come out router-relative.
+ *
+ * **swagger-autogen reports a broken annotation and then succeeds anyway** — it
+ * `console.error`s "Syntax error" or "out of structure", drops that one
+ * annotation, and prints `Success` in green. So its diagnostics are captured here
+ * and made fatal. Nothing else will tell you.
+ */
+async function fragmentFor(file) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'module-swagger-'))
+  const out = path.join(dir, 'fragment.json')
+
+  const complaints = []
+  const realError = console.error
+  console.error = (...args) => {
+    const line = args.map(String).join(' ')
+    if (/syntax error|out of structure/i.test(line)) complaints.push(line.trim())
+    else realError(...args)
+  }
+  try {
+    // A DEEP COPY per call, and that is not defensive style. swagger-autogen
+    // writes its result back into the object it was handed, so reusing one `doc`
+    // across several routers re-wraps the previous pass's output every time. The
+    // first module to hit this produced a 484 MB fragment from six routers.
+    await swaggerAutogen(out, [path.relative(SERVER_ROOT, file).split(path.sep).join('/')], {
+      ...JSON.parse(JSON.stringify(doc)),
+      info: { title: 'examplegame fragment', version: '0' },
+    })
+  } finally {
+    console.error = realError
+  }
+  if (complaints.length > 0) {
+    throw new Error(
+      `swagger: ${path.relative(MODULE_ROOT, file)} has ${complaints.length} annotation(s) ` +
+        `swagger-autogen could not parse — it drops them and reports success:\n  ${complaints.join('\n  ')}`,
+    )
+  }
+
+  const fragment = JSON.parse(fs.readFileSync(out, 'utf8'))
+  fs.rmSync(dir, { recursive: true, force: true })
+  return fragment
+}
+
+/**
+ * Re-root a router-relative fragment under the prefix it is mounted at.
+ *
+ * Express path params (`:id`) become OpenAPI's (`{id}`), and any param belonging
+ * to the PREFIX is moved to the front of each operation's parameter list —
+ * swagger-autogen orders parameters by where they appeared in the path it saw,
+ * which was only the tail.
+ */
+function prefixPaths(fragment, prefix) {
+  const oas = prefix.replace(/:([A-Za-z0-9_]+)/g, '{$1}').replace(/\/+$/, '')
+  const outer = [...oas.matchAll(/\{([A-Za-z0-9_]+)\}/g)].map((m) => m[1])
+  const paths = {}
+  for (const [p, item] of Object.entries(fragment.paths || {})) {
+    for (const operation of Object.values(item)) {
+      const params = operation && operation.parameters
+      if (!Array.isArray(params)) continue
+      const rank = (q) => {
+        const i = outer.indexOf(q && q.name)
+        return i === -1 ? outer.length : i
+      }
+      operation.parameters = params
+        .map((q, i) => ({ q, i }))
+        .sort((a, b) => rank(a.q) - rank(b.q) || a.i - b.i)
+        .map(({ q }) => q)
+    }
+    // `router.get('/')` under a prefix concatenates to a trailing slash, a URL no
+    // client calls. Core's generator normalises the same way.
+    paths[`${oas}${p}`.replace(/\/$/, '')] = item
+  }
+  return paths
+}
+
+/**
+ * Build the whole fragment: every mounted router, re-rooted and merged.
+ *
+ * Only `paths`, `tags` and `components.schemas` — the three sections §6.1a lets a
+ * fragment carry. `info`, `servers` and the security schemes belong to the merged
+ * document, which is to say to core.
+ */
+async function build() {
+  const spec = { paths: {}, tags: [], components: { schemas: {} } }
+  let shared = false
+
+  for (const { file, prefix, what } of mountedRouters()) {
+    const generated = await fragmentFor(file)
+    // Tags and schemas are the same on every pass — each was handed the same
+    // `doc` — so take them from whichever ran first. What lands in the fragment
+    // has to be what swagger-autogen PRODUCED and not what it was given: those
+    // two differ (see fragmentFor), and core merges this file verbatim into a
+    // spec whose own schemas went through the same mill.
+    if (!shared) {
+      spec.tags = generated.tags || []
+      spec.components.schemas = (generated.components || {}).schemas || {}
+      shared = true
+    }
+    const paths = prefixPaths(generated, prefix)
+    const count = Object.keys(paths).length
+    if (count === 0) {
+      // An empty result is precisely what the silent drop looks like, so it is a
+      // hard failure rather than a router that happens to declare no routes.
+      throw new Error(`swagger: ${what} (${path.relative(MODULE_ROOT, file)}) generated NO paths`)
+    }
+    for (const [p, item] of Object.entries(paths)) {
+      if (spec.paths[p]) throw new Error(`swagger: two of this module's routers both document ${p}`)
+      spec.paths[p] = item
+    }
+    process.stdout.write(`  ${String(count).padStart(3)} path(s)  ${prefix}  ← ${what}\n`)
+  }
+
+  // Sorted, because swagger-autogen emits router-traversal order: without this,
+  // moving a route between files rewrites most of a committed artifact even when
+  // the API is provably unchanged.
+  spec.paths = Object.fromEntries(Object.entries(spec.paths).sort(([a], [b]) => (a < b ? -1 : 1)))
+  return spec
+}
+
+async function main() {
+  const check = process.argv.includes('--check')
+  const spec = await build()
+  const json = `${JSON.stringify(spec, null, 2)}\n`
+
+  if (!check) {
+    fs.writeFileSync(FRAGMENT, json)
+    process.stdout.write(`\nwrote ${path.relative(MODULE_ROOT, FRAGMENT)} — ${Object.keys(spec.paths).length} paths\n`)
+    return
+  }
+
+  if (!fs.existsSync(FRAGMENT)) {
+    process.stderr.write('\nswagger-fragment.json is missing. Run `npm run swagger`.\n')
+    process.exit(1)
+  }
+  // Compared with line endings normalised, and that is not fussiness. A default
+  // Windows clone checks this file out as CRLF while the generator above writes
+  // LF, so a byte comparison failed on a PRISTINE template and told the reader
+  // their routes had changed — the kit's acceptance run lost ten minutes to it
+  // before reaching for `od -c` (docs/modules/kit-acceptance.md, F1). A check may
+  // only fail for the reason it names; this one names a diagnosis, so it has to
+  // be right about it. `.gitattributes` stops the CRLF from arriving in the first
+  // place, and this stops it mattering if it does.
+  const lf = (s) => s.replace(/\r\n/g, '\n')
+
+  if (lf(fs.readFileSync(FRAGMENT, 'utf8')) !== lf(json)) {
+    process.stderr.write(
+      '\nswagger-fragment.json is STALE — the routes or their annotations changed and it was not\n' +
+        'regenerated. Run `npm run swagger` and commit the result. Core merges this file verbatim,\n' +
+        'so a stale one documents a URL surface this module does not serve.\n',
+    )
+    process.exit(1)
+  }
+  process.stdout.write(`\nswagger-fragment.json is current — ${Object.keys(spec.paths).length} paths\n`)
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    process.stderr.write(`${err.stack}\n`)
+    process.exit(1)
+  })
+}
+
+module.exports = { mountedRouters, prefixPaths, build, TIER_BASE, FRAGMENT }