feat(template): a module that builds and loads — Phase 5 slice 1

The kit's `template/`: a complete, minimal Runic Gateway module a reader copies,
renames, and runs before reading a chapter. Slice 0 landed the workflow that runs
it; this is the tree that workflow was written against, so the `template` job
arms itself with no edit to the guard.

Installed into a real core it adds one public page at `/examplegame/status`, a nav
row pointing at it, one API route described in an OpenAPI fragment core merges,
one table created by an idempotent schema fragment and dropped by a purge file,
and both lifecycle hooks. That is deliberately less than a real module does; what
it is complete about is the shape — every seam used once, with the reasoning next
to it.

Four decisions, settled with the org lead:

1. **Public tier only, plus the lifecycle hooks.** §2.11.1 d1's "one public route",
   plus enough to show the whole vertical seam once. Admin and player tiers become
   worked examples quoted from module-uo in chapter 2 rather than two thirds of a
   tree the reader deletes on day one.
2. **The release workflow ships as a file, in BOTH flavours** — `.gitea/` and
   `.github/`. Neither runs where it sits (a workflow is only read from a
   repository root) and each arms itself when the reader's copy is its own repo.
   Packaging is the part of a module that cannot be guessed at, and the kit's
   audience is outside this org, so assuming Gitea would have been assuming our
   own deployment. Core installs from a URL and does not care where the release
   lives — only that the host is on the operator's `MODULE_SOURCE_HOSTS`.
3. **A rename checklist that CI verifies**, not a rename script. `template/README.md`
   carries the table; `scripts/checkRenameSites.js` holds it against the tree in
   both directions — an unlisted file that still carries the placeholder fails, and
   so does a listed file that no longer does. The second half is the one usually
   left out and the more valuable: a row that has stopped matching reads as
   instructions to edit something that is not there. Same rule core's identifier
   check follows about its own exemptions. It has its own ten-test suite, run by
   CI as `node --test`, because a check that has never been shown to fail is a
   check nobody knows the state of.
4. **A neutral invented game.** One deviation from the literal answer, forced by
   decision 3: the id is `examplegame`, not `example`. The checklist check is a
   text search, and `example` occurs in ordinary English ("for example") all over
   prose that is not a rename site — a placeholder that cannot occur by accident is
   what makes the check answerable instead of a source of false alarms someone
   learns to ignore.

**The pin moves to the 1.4.0 bump** (website `edge` 1b692bf), which is what
`template/module.json` declares as `coreApi`. Slice 0 pinned its parent, before
1.4.0 existed, so `checkCoreApi.js` arms for the first time here — it asserts
EQUALITY, and its failing on the next contract bump is the system working.

Also in CI: the client tests now run AFTER the build (two of them read the built
chunk and skip without one — run first, the job reports green while asking nothing
about the artifact that ships), and `check:swagger` verifies the committed
fragment is current.

## The finding: an UPDATE that changes nothing does not touch ON UPDATE CURRENT_TIMESTAMP

Every suite passed, both guards passed, the chunk built, the module loaded into a
real core and the page rendered correctly. Two hours later the same page said the
world was offline, and it was wrong.

`updated_at` was declared `ON UPDATE CURRENT_TIMESTAMP`, and MariaDB fires that
only when an UPDATE actually CHANGES a value. The boot refresh writes the same
numbers every thirty seconds — which is exactly what a quiet game looks like — so
the timestamp froze at the first write, the row crossed the freshness window, and
the model correctly reported a stale row as offline. Verified against the live
database: two hours of refreshes, `updated_at` still the boot timestamp.

No test in this repo could see it. The model takes its clock as an argument, and
nothing in a suite runs the same UPDATE twice against a real database. It is only
visible as a page that was right when you looked at it and wrong an hour later.

The writer now sets `updated_at = CURRENT_TIMESTAMP` explicitly and the column
drops the clause that was not doing what it looked like it was doing; both carry
the reasoning. Re-verified end to end: the timestamp advances every interval and
the API reports fresh.

Falling out of the fix, the schema fragment gained the rule the reader hits next:
**changing a table is an ALTER, never an edit to its CREATE** — `CREATE TABLE IF
NOT EXISTS` does nothing when the table exists, so an edited column definition
takes effect on a fresh install and on no existing one, which is the worst
possible split because your development database is usually the fresh one.

## Verified

- 29 server tests, 18 client tests, 10 kit-script tests; `check:imports`,
  `check:externals`, `check:swagger` and `checkCoreApi` all green, run in CI's own
  order from a clean `npm ci`.
- Browser smoke (MODULE_API.md §7.7) against a real core built from the pinned
  ref: module `started`, published on `/api/v1/public/modules`, chunk served
  `no-cache` with the right MIME from the entry's directory while `module.json`
  and the server source 404, script tag injected after core's bundle, the page
  rendering inside core's own chrome, the nav row interleaved into the public
  header between Wiki and About, SPA navigation into it from another page, the
  module's path and schema and tag merged into `/api/docs.json`, and
  `[examplegame] registered against core API 1.4.0` in the console with no CSP
  report and no React error.

Refs: MODULE_SYSTEM.md §2.11.1 (slice 1), MODULE_API.md §2.x, §3.x, §5.1, §7.7.

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

template/server/test/_fakes.js

@@ -0,0 +1,107 @@
+// ── Test doubles for what core hands the module ───────────────────────────
+//
+// Your server half is testable WITHOUT core, and that is not a convenience — it
+// is the contract holding. Everything a module may touch arrives on `ctx`
+// (MODULE_API.md §2.3), so a `ctx` this file can build is a complete statement of
+// what your module depends on. **If a test ever needs something that is not here,
+// either your module reached past the boundary or §2.3 needs a new member.** Both
+// are worth stopping for.
+//
+// The fake mirrors §2.3 member for member — including the freezing, so a module
+// that assigns to `ctx.something` fails here the way it would in core.
+//
+// This file lives under `test/`, which `checkImports.js` treats as not-shipped —
+// which is why it may `require('express')` when the module's own routers may not.
+// It builds a REAL express Router on purpose: a fake Router would only ever test
+// the fake.
+
+const express = require('express')
+
+/** Records every call, so a test can assert what the module asked for. */
+function spy(returns) {
+  const fn = (...args) => {
+    fn.calls.push(args)
+    return typeof returns === 'function' ? returns(...args) : returns
+  }
+  fn.calls = []
+  return fn
+}
+
+function fakeLog() {
+  return { error: spy(), warn: spy(), info: spy(), debug: spy() }
+}
+
+function fakeCtx(overrides = {}) {
+  // `freeze: false` is a test seam for a suite that wants to adjust the ctx it
+  // installed. Core always freezes; the unfrozen variant is never a claim about
+  // what a module is handed in production.
+  const { freeze = true, ...rest } = overrides
+  const logs = []
+  const ctx = {
+    moduleId: 'examplegame',
+    paths: { moduleRoot: require('path').resolve(__dirname, '..', '..') },
+    express,
+    validator: {},
+    db: { query: spy(Promise.resolve([])), pool: {} },
+    log: (namespace) => {
+      const log = fakeLog()
+      logs.push({ namespace, log })
+      return log
+    },
+    auth: { getUserFromRequest: spy(null) },
+    middleware: {
+      requireAuth: (req, res, next) => next(),
+      requireRole: () => (req, res, next) => next(),
+      siteMode: (req, res, next) => next(),
+      validate: (req, res, next) => next(),
+      noindex: (req, res, next) => next(),
+      // The factory returns a pass-through rather than a real limiter: a test
+      // that tripped a rate limit would be a test whose result depended on how
+      // many times the suite had run.
+      rateLimit: (options) => Object.assign((req, res, next) => next(), { options }),
+      accountChangeLimiter: (req, res, next) => next(),
+    },
+    site: { baseUrl: 'http://localhost:5173' },
+    ...rest,
+  }
+  // Non-enumerable, and that is not tidiness. Core freezes every object value on
+  // `ctx` one level deep, so an enumerable recorder hung off it would be frozen
+  // by the loop below and every `log.info` would throw on push. Keeping it out of
+  // the enumeration also makes the fake more faithful: a module iterating `ctx`
+  // sees §2.3's members and nothing a test put there.
+  Object.defineProperty(ctx, 'logs', { value: logs, enumerable: false })
+  if (!freeze) return ctx
+  for (const value of Object.values(ctx)) {
+    if (value && typeof value === 'object') Object.freeze(value)
+  }
+  return Object.freeze(ctx)
+}
+
+/**
+ * The registration api, recording rather than mounting.
+ *
+ * Copies core's `once()` rule (§2.4: "calling twice is an error"), so a module
+ * that registers the same thing twice fails in its own suite rather than first on
+ * an operator's install.
+ */
+function fakeApi() {
+  const record = { routes: null, extensions: [], streams: null, legs: [], hooks: {} }
+  const called = new Set()
+  const once = (name) => {
+    if (called.has(name)) throw new Error(`${name}() called twice`)
+    called.add(name)
+  }
+  const api = {
+    registerRoutes(mounts) { once('registerRoutes'); record.routes = mounts },
+    registerExtension(slot, router) { record.extensions.push({ slot, router }) },
+    registerNotificationStreams(streams) { once('registerNotificationStreams'); record.streams = streams },
+    registerAnnounceLeg(leg) { record.legs.push(leg) },
+    registerPostHook(hook) { once('registerPostHook'); record.hooks.post = hook },
+    onBoot(fn) { once('onBoot'); record.hooks.onBoot = fn },
+    onShutdown(fn) { once('onShutdown'); record.hooks.onShutdown = fn },
+  }
+  api.record = record
+  return api
+}
+
+module.exports = { fakeCtx, fakeApi, spy }

template/server/test/checkImports.test.js

@@ -0,0 +1,149 @@
+// The boundary check, checked.
+//
+// `scripts/checkImports.js` is the acceptance test for the whole module contract
+// (MODULE_API.md §5.1), and a check that has never been shown to fail is a check
+// nobody knows the state of. These point it at fixtures that break each rule and
+// assert it says so — and at prose that merely *describes* breaking them, which
+// is what it got wrong the first time it was run.
+//
+// **Every fixture is a template literal, and that is load-bearing.** The scanner
+// reads the files in this directory too, so an ordinary quoted string holding
+// `require('../../x')` would make this file fail the very check it is testing.
+// Templates are blanked by the stripper for exactly this class of text: source
+// being composed as data is not source being imported.
+
+const test = require('node:test')
+const assert = require('node:assert')
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+
+const { scan, stripCommentsAndTemplates, SERVER_ROOT, MODULE_ROOT } = require('../scripts/checkImports')
+
+/** Write `files` into a throwaway module tree and scan it. */
+function scanFixture(files, { dev = new Set() } = {}) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'module-tpl-'))
+  const src = path.join(root, 'server')
+  for (const [name, source] of Object.entries(files)) {
+    const file = path.join(src, name)
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    fs.writeFileSync(file, source)
+  }
+  try {
+    return scan(src, root, { shipped: (f) => !f.startsWith(path.join(src, 'test') + path.sep), dev })
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true })
+  }
+}
+
+test('the real server half is clean', () => {
+  assert.deepStrictEqual(scan(SERVER_ROOT, MODULE_ROOT), [])
+})
+
+test('catches a relative path that escapes the module root', () => {
+  const found = scanFixture({ 'a.js': `require('../../server/src/utils/db')` })
+  assert.strictEqual(found.length, 1)
+  assert.strictEqual(found[0].why, 'escapes the module root')
+})
+
+test('allows a relative path that stays inside it, however deep', () => {
+  assert.deepStrictEqual(
+    scanFixture({ 'deep/nested/a.js': `require('../../../module.json')` }),
+    [],
+  )
+})
+
+test('catches an absolute path', () => {
+  const found = scanFixture({ 'a.js': `require('/etc/passwd')` })
+  assert.strictEqual(found[0].why, 'absolute path')
+})
+
+test('catches a bare specifier in shipped code, even a devDependency', () => {
+  // The rule that makes the boundary real: express arrives on ctx. A shipped
+  // file requiring it would fail on a real install, because a module lives
+  // outside core's server/ and never reaches core's node_modules.
+  const found = scanFixture({ 'a.js': `const express = require('express')` }, { dev: new Set(['express']) })
+  assert.strictEqual(found.length, 1)
+  assert.match(found[0].why, /should this come from ctx/)
+})
+
+test('allows a devDependency in test code, which never runs inside core', () => {
+  assert.deepStrictEqual(
+    scanFixture({ 'test/a.js': `const express = require('express')` }, { dev: new Set(['express']) }),
+    [],
+  )
+})
+
+test('allows node builtins anywhere, with or without the node: prefix', () => {
+  assert.deepStrictEqual(
+    scanFixture({ 'a.js': `require('path'); require('node:fs'); import crypto from 'node:crypto'` }),
+    [],
+  )
+})
+
+test('allows node:test, which older Node versions omit from builtinModules', () => {
+  // The first CI run failed on exactly this and on nothing else: `builtinModules`
+  // omits `test` on Node 20 and includes it on Node 24, so every test file in
+  // this suite was reported as breaking the module boundary. The check asks
+  // Node (`isBuiltin`) rather than rebuilding the list, and treats the `node:`
+  // prefix as sufficient on its own — a prefixed specifier can never resolve to
+  // a package, whatever the running version enumerates.
+  assert.deepStrictEqual(
+    scanFixture({ 'a.js': `require('node:test'); require('node:test/reporters')` }),
+    [],
+  )
+})
+
+test('catches ESM and dynamic forms, not only require()', () => {
+  const found = scanFixture({
+    'a.js': [`import db from '../../core/db.js'`, `const x = await import('../../core/other.js')`].join('\n'),
+  })
+  assert.strictEqual(found.length, 2)
+})
+
+test('ignores a violation that is only DESCRIBED in a comment', () => {
+  // The first run of this check failed on its own documentation, and on
+  // index.js's comment explaining why the module must never require('express').
+  // Prose about the rule must not trip the rule.
+  assert.deepStrictEqual(
+    scanFixture({
+      'a.js': [
+        `// Never write require("../../server/src/utils/db") - it escapes the module root.`,
+        `/* Nor import express from "express": core hands it over on ctx. */`,
+        `const path = require('path')`,
+      ].join('\n'),
+    }),
+    [],
+  )
+})
+
+test('ignores a specifier-shaped string inside a template literal', () => {
+  assert.deepStrictEqual(
+    scanFixture({ 'a.js': ['const sql = ', '`SELECT 1 -- require("../../x")`'].join('') }),
+    [],
+  )
+})
+
+test('a comment opener inside a string does not swallow the rest of the file', () => {
+  // The reason this is a character walk and not a regexp: a URL in a string
+  // contains `//`, and treating that as a comment would blank everything after
+  // it — turning the check into one that silently passes.
+  const found = scanFixture({
+    'a.js': [`const url = 'https://example.com/x'`, `require('../../escaped')`].join('\n'),
+  })
+  assert.strictEqual(found.length, 1, 'the specifier after a URL string was missed')
+})
+
+test('a quote inside a comment does not swallow the rest of the file', () => {
+  const found = scanFixture({
+    'a.js': [`// don't do this`, `require('../../escaped')`].join('\n'),
+  })
+  assert.strictEqual(found.length, 1)
+})
+
+test('stripping preserves line numbers', () => {
+  // Blanked rather than removed, so anything that later reports a line still
+  // reports the right one.
+  const src = ['/* a', 'b', 'c */', `require("x")`, ''].join('\n')
+  assert.strictEqual(stripCommentsAndTemplates(src).split('\n').length, src.split('\n').length)
+})

template/server/test/entry.test.js

@@ -0,0 +1,84 @@
+// ── The registration handshake ────────────────────────────────────────────
+//
+// The one suite every module should have, whatever else it does. Core validates
+// all of this at boot and refuses to mount a module that fails — so testing it
+// here is the difference between finding out in half a second and finding out on
+// an operator's install.
+
+const test = require('node:test')
+const assert = require('node:assert')
+
+const { fakeCtx, fakeApi } = require('./_fakes')
+const manifest = require('../../module.json')
+
+/** A fresh registration. `core.js` holds a module-level `ctx`, so reset it. */
+function register(ctx = fakeCtx()) {
+  require('../core')._reset()
+  const api = fakeApi()
+  require('../index')(ctx, api)
+  return { api, ctx }
+}
+
+test('registers exactly the mounts module.json declares', () => {
+  const { api } = register()
+
+  // Core compares these two and rejects a mismatch in EITHER direction: a prefix
+  // declared and never registered is as fatal as a route registered and never
+  // declared. Asserting it against the manifest rather than against a literal is
+  // what keeps the test true after you add a prefix.
+  assert.deepStrictEqual(
+    Object.keys(api.record.routes).sort(),
+    Object.keys(manifest.mounts).sort(),
+  )
+  for (const [tier, prefixes] of Object.entries(manifest.mounts)) {
+    assert.deepStrictEqual(Object.keys(api.record.routes[tier]).sort(), [...prefixes].sort())
+  }
+})
+
+test('every registered mount is a real express router', () => {
+  const { api } = register()
+  for (const byPrefix of Object.values(api.record.routes)) {
+    for (const [prefix, router] of Object.entries(byPrefix)) {
+      assert.strictEqual(typeof router, 'function', `${prefix} is not a router`)
+      assert.ok(router.stack, `${prefix} has no middleware stack`)
+    }
+  }
+})
+
+test('prefixes are one segment, lowercase, no parameters', () => {
+  // §2.4's rule, restated where a typo is cheap to find. Core enforces it, and a
+  // module that fails it does not mount at all.
+  for (const prefixes of Object.values(manifest.mounts)) {
+    for (const prefix of prefixes) {
+      assert.match(prefix, /^\/[a-z0-9][a-z0-9-]*$/, `illegal mount prefix ${prefix}`)
+    }
+  }
+})
+
+test('registration touches no database and awaits nothing', () => {
+  const ctx = fakeCtx()
+  register(ctx)
+
+  // §2.2's first rule. Core requires `app.js` with the pool pointed at a dead
+  // port in two build tools, so a query here would hang both — and the symptom
+  // is a build that never finishes rather than an error naming this module.
+  assert.deepStrictEqual(ctx.db.query.calls, [])
+})
+
+test('registers both lifecycle hooks', () => {
+  const { api } = register()
+  assert.strictEqual(typeof api.record.hooks.onBoot, 'function')
+  assert.strictEqual(typeof api.record.hooks.onShutdown, 'function')
+})
+
+test('the manifest declares what the loader requires', () => {
+  assert.match(manifest.id, /^[a-z][a-z0-9-]{1,31}$/)
+  assert.match(manifest.version, /^\d+\.\d+\.\d+/)
+  assert.ok(manifest.coreApi, 'coreApi is required — it is the version check')
+  // Declaring a schema without a purge is refused: a module that can create
+  // tables and cannot drop them leaves an operator with orphaned data.
+  if (manifest.schema) assert.ok(manifest.purge, 'a schema fragment requires a purge file')
+  // The chunk must be in a SUBDIRECTORY — the directory it sits in is what core
+  // serves, so an entry in the module root would publish the whole module.
+  if (manifest.client) assert.ok(manifest.client.entry.includes('/'), 'client.entry must be in a subdirectory')
+})

template/server/test/schema.test.js

@@ -0,0 +1,116 @@
+// ── The schema fragment, checked against §2.6's rules ─────────────────────
+//
+// Core validates the fragment at LOAD time and refuses to mount a module that
+// breaks a rule — with no tables created and no routes served. That is the right
+// behaviour and a slow way to find a typo, so the same rules are checked here.
+//
+// **This is also the suite that catches a half-finished rename.** Change the id
+// in `module.json` and forget a table name, and the prefix assertion below fails
+// immediately rather than at an operator's first boot.
+
+const test = require('node:test')
+const assert = require('node:assert')
+const fs = require('node:fs')
+const path = require('node:path')
+
+const manifest = require('../../module.json')
+
+const read = (rel) => fs.readFileSync(path.resolve(__dirname, '..', '..', rel), 'utf8')
+
+/**
+ * Split a SQL file into statements the way core does.
+ *
+ * Core's own splitter is shared code (`utils/sqlStatements.js`) used by both the
+ * loader and the schema replay — this is a small stand-in for a test, and it is
+ * deliberately simple because the fragment it reads is deliberately simple. If
+ * your schema grows a stored procedure or a string containing a semicolon, stop
+ * trusting this and read the fragment a different way.
+ */
+function statements(sql) {
+  return sql
+    .split('\n')
+    .filter((line) => !line.trim().startsWith('--'))
+    .join('\n')
+    .split(';')
+    .map((s) => s.trim())
+    .filter(Boolean)
+}
+
+const schema = statements(read(manifest.schema))
+const purge = statements(read(manifest.purge))
+
+// The allowlist core enforces. Note it is an ALLOWLIST and not a `DROP` denylist:
+// this file replays on every boot, so TRUNCATE or DELETE would empty a table on
+// every restart — which no denylist naming only DROP would have caught.
+const ALLOWED_VERBS = ['CREATE', 'ALTER', 'INSERT', 'UPDATE']
+
+test('every statement starts with an allowed verb', () => {
+  for (const statement of schema) {
+    const verb = statement.split(/\s+/)[0].toUpperCase()
+    assert.ok(ALLOWED_VERBS.includes(verb), `"${verb}" is not one of ${ALLOWED_VERBS.join(', ')}`)
+  }
+})
+
+test('every table is prefixed with the module id', () => {
+  for (const statement of schema) {
+    const match = /^CREATE\s+TABLE(?:\s+IF\s+NOT\s+EXISTS)?\s+`?([A-Za-z0-9_]+)`?/i.exec(statement)
+    if (!match) continue
+    assert.ok(
+      match[1].startsWith(`${manifest.id}_`),
+      `table "${match[1]}" is not prefixed "${manifest.id}_" — core will refuse to load this module`,
+    )
+  }
+})
+
+test('the fragment is idempotent — it replays on every boot', () => {
+  for (const statement of schema) {
+    if (/^CREATE\s+TABLE/i.test(statement)) {
+      assert.match(statement, /IF\s+NOT\s+EXISTS/i, 'CREATE TABLE without IF NOT EXISTS')
+    }
+    if (/^ALTER\s+TABLE/i.test(statement) && /ADD\s+COLUMN/i.test(statement)) {
+      assert.match(statement, /IF\s+NOT\s+EXISTS/i, 'ADD COLUMN without IF NOT EXISTS')
+    }
+    if (/^INSERT\s+INTO/i.test(statement)) {
+      // A plain INSERT succeeds once and then fails the whole replay on the next
+      // boot with a duplicate key — the classic "worked until I restarted it".
+      assert.ok(
+        /INSERT\s+IGNORE/i.test(statement) || /ON\s+DUPLICATE\s+KEY/i.test(statement),
+        'INSERT must be IGNORE or carry ON DUPLICATE KEY — it runs again every boot',
+      )
+    }
+  }
+})
+
+test('purge drops every table the schema creates', () => {
+  const created = schema
+    .map((s) => /^CREATE\s+TABLE(?:\s+IF\s+NOT\s+EXISTS)?\s+`?([A-Za-z0-9_]+)`?/i.exec(s))
+    .filter(Boolean)
+    .map((m) => m[1])
+  const dropped = purge
+    .map((s) => /^DROP\s+TABLE(?:\s+IF\s+EXISTS)?\s+`?([A-Za-z0-9_]+)`?/i.exec(s))
+    .filter(Boolean)
+    .map((m) => m[1])
+
+  for (const table of created) {
+    assert.ok(dropped.includes(table), `${table} is created but never dropped — purge would orphan it`)
+  }
+  for (const table of dropped) {
+    assert.ok(created.includes(table), `${table} is dropped but never created`)
+  }
+})
+
+test('purge drops in the reverse of creation order', () => {
+  // With one table this proves nothing; with a parent and its children it is the
+  // difference between a clean teardown and a purge that fails halfway, leaving
+  // exactly the orphaned data it exists to remove.
+  const created = schema
+    .map((s) => /^CREATE\s+TABLE(?:\s+IF\s+NOT\s+EXISTS)?\s+`?([A-Za-z0-9_]+)`?/i.exec(s))
+    .filter(Boolean)
+    .map((m) => m[1])
+  const dropped = purge
+    .map((s) => /^DROP\s+TABLE(?:\s+IF\s+EXISTS)?\s+`?([A-Za-z0-9_]+)`?/i.exec(s))
+    .filter(Boolean)
+    .map((m) => m[1])
+
+  assert.deepStrictEqual(dropped, [...created].reverse())
+})

template/server/test/worldStatus.test.js

@@ -0,0 +1,58 @@
+// ── The model, with no database ───────────────────────────────────────────
+//
+// The `.db.js` / `.model.js` split pays for itself here: the logic worth testing
+// is in the model, and the model's only dependency is a function that returns a
+// row. Stub that and there is nothing to stand up.
+
+const test = require('node:test')
+const assert = require('node:assert')
+
+const db = require('../model/worldStatus/worldStatus.db')
+const { getPublicStatus, STALE_AFTER_MS } = require('../model/worldStatus/worldStatus.model')
+
+const NOW = Date.parse('2026-08-12T12:00:00Z')
+
+/** Replace `getStatus` for one test and put it back afterwards. */
+function withRow(row, fn) {
+  const real = db.getStatus
+  db.getStatus = async () => row
+  return Promise.resolve(fn()).finally(() => { db.getStatus = real })
+}
+
+test('a fresh row reports the world online', () =>
+  withRow(
+    { online: 1, players: 12, worldName: 'Example World', updatedAt: new Date(NOW - 1000) },
+    async () => {
+      const status = await getPublicStatus(NOW)
+      assert.strictEqual(status.online, true)
+      assert.strictEqual(status.players, 12)
+      assert.strictEqual(status.worldName, 'Example World')
+      assert.strictEqual(status.stale, false)
+    },
+  ))
+
+test('a stale row is reported offline, whatever it says', () =>
+  withRow(
+    { online: 1, players: 12, worldName: 'Example World', updatedAt: new Date(NOW - STALE_AFTER_MS - 1) },
+    async () => {
+      const status = await getPublicStatus(NOW)
+      // The row claims the world is up. Nothing has written it in longer than the
+      // freshness window, so the claim is not evidence of anything.
+      assert.strictEqual(status.online, false)
+      assert.strictEqual(status.players, 0)
+      assert.strictEqual(status.stale, true)
+      // The name is still worth showing — it does not go stale the way a player
+      // count does.
+      assert.strictEqual(status.worldName, 'Example World')
+    },
+  ))
+
+test('no row at all is an answer, not an error', () =>
+  withRow(null, async () => {
+    // A fresh install whose first boot has not finished replaying the schema.
+    // The site must render; the next boot fixes it.
+    const status = await getPublicStatus(NOW)
+    assert.deepStrictEqual(status, {
+      online: false, players: 0, worldName: null, updatedAt: null, stale: true,
+    })
+  }))